PDBLib User’s Manual

Portable Data Base Library

Stewart A. Brown


Introduction

PDBLib Design Philosophy
PDBLib API Overview
PDBLib and Index Ordering
PDBLib and Index Offsets
Compiling and Loading
Memory Management Considerations
PDB Universal Data Locators
Binary and Text Data
PDB Syntax
PDBLib Rules
PDB File Format
Terms
Data Conversion and Compression

Using PDBLib

Functions in each group are listed in functional order.
o indicates functions that are mandatory or nearly so
o indicates functions for optional use

Opening, Creating, Closing, and Controlling PDB Files
o PD_SET_BUFFER_SIZE
o PD_TARGET
o PD_OPEN
o PD_ACTIVATE_CKSUM
o PD_VERIFY
o PD_AUTOFIX_DENORM
o PD_FIX_DENORM
o PD_SET_FORMAT_VERSION
o PD_SET_MAJOR_ORDER
o PD_SET_MAX_FILE_SIZE
o PD_SET_OFFSET
o PD_FAMILY
o PD_FLUSH
o PD_CLOSE
o PD_REMOVE_ENTRY
Writing Data to PDB Files
o PD_WRITE
o PD_WRITE_ALT
o PD_WRITE_AS
o PD_WRITE_AS_ALT
o PD_APPEND
o PD_APPEND_ALT
o PD_APPEND_AS
o PD_APPEND_AS_ALT
Reserving Space for Future Write
o PD_DEFENT
o PD_DEFENT_ALT
Reading Data from PDB Files
o PD_READ
o PD_READ_ALT
o PD_READ_AS
o PD_READ_AS_ALT
Defining New Data Types
o PD_CAST
o PD_DEFIX
o PD_DEFLOAT
o PD_DEFNCV
o PD_DEFSTR
o PD_DEFSTR_ALT
o PD_TYPEDEF
Defining Attributes
o PD_DEF_ATTRIBUTE
o PD_GET_ATTRIBUTE
o PD_REM_ATTRIBUTE
o PD_SET_ATTRIBUTE
Queries
o PD_GET_BUFFER_SIZE
o PD_GET_ERROR
o PD_GET_FILE_LENGTH
o PD_GET_FILE_NAME
o PD_GET_FORMAT_VERSION
o PD_GET_MAX_FILE_SIZE
o PD_GET_MAJOR_ORDER
o PD_GET_MODE
o PD_GET_OFFSET
o PD_QUERY_ENTRY
o PD_GET_ENTRY_INFO
o PD_FREE_ENTRY_INFO
o PD_INQUIRE_TYPE
o PFIMBR
Using Pointers
o PD_GET_TRACK_POINTERS
o PD_SET_TRACK_POINTERS
o PD_RESET_PTR_LIST
o PD_FREE
Using Directories
o PD_CD
o PD_LN
o PD_LS
o PD_LS_ALT
o PD_MKDIR
o PD_PWD
o PD_ISDIR
Parallel Programming with PDB
o PD_INIT_THREADS
o PD_INIT_MPI
o PD_TERM_MPI
o PD_MP_OPEN
o PD_MP_CREATE
Special Purpose I/O
o PD_PUT_IMAGE
o PD_PUT_MAPPING
o PD_PUT_SET
o PD_MAKE_IMAGE
o PD_REL_IMAGE
o PFWRAN

Data Structures in PDBLib

DATA_ALIGNMENT
DATA_STANDARD
DEFSTR
DIMDES
MEMDES
PDBFILE
SYMENT

PDBLib by Example

Working with PDB files
Writing Data to PDB files
Reading Data from PDB files
Appending Data to PDB file variables
Inquiries in PDBLib
Browsing PDB files
Writing PM_mappings with PFWMAP
Writing PM_mappings with PFWSET and PFWRAN
SMP Parallel Example
MPI Parallel Example

Related Documentation


Introduction

PDBLib is a small library of file management routines useful for storing and retrieving binary data in a portable format. It is intended to supply a flexible means of managing binary databases without the user having to be concerned with the machines on which they are written or read. Please note that PACT headers MUST be included before all other headers. See the SCORE introduction for more information.

The specific goals for this library are:

PDBLib Design Philosophy

Perhaps the most fundamental element in the design of PDBLib is the concept of modularity through abstraction barriers. In essence, the functionality is broken down into modular units and abstraction barriers are used to preserve the integrity of the units.

An abstraction barrier is simply a technique or device which allows a section of code to be written assuming other functions or routines are defined and that their internal workings are irrelevant to their use. In this way a routine or module can be changed without any other part of the code which uses it being affected (so long as the definition of its function does not change). Abstraction barriers are most effectively created by a careful choice of the basic functional units and by the interfaces between them.

For example, if all variables in the code were global there would be little or no chance of having any abstraction barriers at all. Similarly, monolithic functions which are defined to `solve the worlds problems' do not lend themselves to the more easy maintenance that abstraction barriers afford a program. For a good discussion of the principles and applications of these ideas see Abelson and Sussman's marvelous book, The Structure and Interpretation of Computer Programs.

The main functional units in the PDBLib system are: the hash package which controls the maintenance of the data in both the symbol table and structure chart; the conversion package which handles all data format conversions; the data reading routine which is defined to bring data in from the disk, perform any necessary conversion, and store it in the specified location(s) of memory; and the data writing routine which does the reverse of the reading routine.

These units are put together in such a way that they are used over and over again in the process of doing any of the high level functions. In this way the code size was kept relatively small. Again this is one of the rewards of modularity.

Overview of PDBLib API

The functional PDBLib interface was designed as a minimal extension of the standard C library binary I/O interface. The relevant C library functions are fopen, fclose, fwrite, and fread. The extensions are driven mainly by some missing features in C. Because C doesn't handle data types as types, PDBLib must be told the type of a variable when it is written to a file. Because C variables don't know about their dimensions, PDBLib must be given the dimensions when a variable is written out. On the other hand, because PDBLib knows both type and dimension information about file variables, PDBLib requires less information from the programmer when reads are done.

Since C doesn't have the needed type handling facilities, data structures must be described to PDBLib. Therefore, in addition to the basic I/O functions mentioned above, there is a function in PDBLib to be used when a C data structure or a FORTRAN common block must be described in a file.

Next, to give the user the most flexibility and efficiency regarding data conversions, PDBLib has a function which lets the user specify the binary data format of the file. In this way, a file can be targeted for a particular machine type. A common use for this might be when a powerful machine produces some data which is going to be reprocessed on a less powerful machine. The more powerful machine which writes the file might target the file for the less powerful one so that the conversions are done by the faster machine and not the slower one.

In some applications with structures, some members of a structure may be pointers, and the actual type to which a pointer points may be changed by a cast depending on some other member's value. PDBLib supports the notion of a "cast" in that it can be told to ignore the type of a structure member and get the actual type from another member when it writes out the structure.

There are also routines to manage data attributes. An attribute table will be created for a PDB file the first time PD_def_attribute is called. The attribute table is kept in the PDBfile structure. Variables can be added to PDB files solely for their attribute values. Attributes can be given to entire variables or any part of them. This works because the attribute table is a separate hash table, like the symbol table, which associates names with attribute values. It also is used to manage the attributes themselves. It is not exactly clear why one should use these attributes. Most of the utility of attributes is already inherent in the structures or records which can by built with PDBLib's mechanism for defining derived types. Since the structure handling mechanisms are much more efficient, the reason for using attributes instead of structures should be very clear in the mind of the application programmer.

Because all of the information about files and their contents is contained in PDBLib structures and hash tables, the C API (Application Program Interface) has no inquiry functions. Users can extract information directly from the PDBfile structure and they can use the hash table lookup function, SC_def_lookup, to get access to the syment and defstr structures which describe variables and types, respectively.

The FORTRAN API to PDBLib has most of the same functions as the C API. There are some differences due to the differences in the languages.

SX, a version of the SCHEME programming language with extensions for PACT, has a PDBLib API. In fact, PDBView is largely an SX program which means that it is immanently suited to user customization. The SX interface to PDBLib is largely documented here. More documentation may be found in other PACT manuals.

A Python module is also available to access PDBLib's functionality.

PD_GET_FORMAT_VERSION

C Binding:   void PD_get_format_version(int v)
F77 Binding: integer PFGFMV(integer v)
SX Binding:  (format-version)
Python Binding:  XXX - missing

Get the format version to be used when creating new PDB files to v. See the section PDB File Format for a discussion of the PDB file formats.

Input to this function is: v, an integer in which to return the format version.

In the C binding return the value of the format version. In the FORTRAN binding return 1 if successful, 0 otherwise.


C Example
       int v;
             .
             .
             .

       PD_get_format_version(v);
             .
             .
             .

Fortran Example
       integer pfgfmv
       integer v
             .
             .
             .

       v = 3
       if (pfgfmv(v) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (format-version)
             .
             .
             .

Python Example
             .
             .
             .

PDBLib and Index Ordering

Languages such as C and FORTRAN differ about the major ordering of arrays. For example, C is row major and FORTRAN is column major. To accommodate the use of PDB files among applications in different languages, each PDB file contains a flag that says which ordering to use.

The C header file #define's two constants:

   #define ROW_MAJOR_ORDER     101
   #define COLUMN_MAJOR_ORDER  102
These values define how PDB treats index expressions when reading and writing data. PDB does NOT transpose arrays when reading or writing, it transposes the index expressions.

By default PDB files created via the C interface are set with ROW_MAJOR_ORDER and files created via the FORTRAN interface are set with COLUMN_MAJOR_ORDER. Applications can query or change the value at any time after the file is opened/created. See the functions PD_SET_MAJOR_ORDER and PD_GET_MAJOR_ORDER.

Using PDBView you can check the mode of a given file using the file command.

We recommend that when you know that you will be using files between applications in different languages that you use column major ordering consistently. There is no deep reason for this. It simply helps you to be consistent and to have an expectation of how to think about your files.

PDBLib and Index Offsets

Languages such as C and FORTRAN differ about the default value for the first index value in an array. For example, C uses 0 based indexing and FORTRAN uses 1 based indexing. To accommodate the use of PDB files among applications in different languages, each PDB file contains a flag that specifies the default offset.

The offset determines how PDB treats index expressions when reading and writing data. It doesn't affect the number of items specified by a dimension. It only affects the range of index values.

By default PDB files created via the C interface are set with a default offset of 0 and files created via the FORTRAN interface have a default offset of 1. Applications can query or change the value at any time after the file is opened/created. The value can be set to any integer value so it is more general than would be strictly necessary if there were only C and FORTRAN. See the functions PD_SET_OFFSET and PD_GET_OFFSET.

Using PDBView you can check the default offset of a given file using the file command.

Compiling and Loading

To compile your C programs you must use

 #include <pdb.h>
in the source files which deal with the library.

To link your application you must use the following libraries in the order specified.

-lpdb -lpml -lscore [-lm ...]
Although this is expressed as if for a UNIX linker, the order would be the same for any system with a single pass linker. The items in [] are optional or system dependent.

Each system has different naming conventions for its libraries and the reader is assumed to understand the appropriate naming conventions as well as knowing how to tell the linker to find the installed PACT libraries on each system that they use.

Memory Management Considerations

PDBLib is capable of correctly handling data that is indirectly referenced through arbitrary levels of pointers. In order to do this it is necessary to put an extra layer of memory management over the standard C library routines. The basic requirement is that given a pointer, one would like to know how many bytes of data it points to. The functions, SC_alloc, SC_realloc, SC_strsave, SC_free, and SC_arrlen, built on top of the standard C library functions, malloc and free, provide this capability. For C programmers, macros are provided which offer a nice and intuitive way of using these functions (they also provide an abstraction barrier against the details of any memory management scheme). These functions and macros are documented in the SCORE User's Manual.

A brief discussion of the procedure for writing and reading indirectly referenced data follows. Although the discussion will use integers as an example, the ideas apply to all data types, primitive or derived.

Consider the following:

int a[10], *b;

b = MAKE_N(int, 10);

Both a and b are pointers to 10 integers (macro MAKE_N is used to allocate the necessary space). The difference as far as an application is concerned is that the space that a points to was set aside by the compiler at compile time (for all practical purposes) while the space the b points to is created at run time. There is no possibility, given the definition of the C language, of asking the pointer a how many bytes it points to. On the other hand, since b is dynamically allocated, an extra layer of memory management could be provided so that a function, SC_arrlen, could be defined to return the number of bytes that a dynamically allocated space has. In particular,

SC_arrlen(a) => -1 (indicating an error)

SC_arrlen(b)/sizeof(int) => 10

SC_arrlen(b+5) => -1 (indicating an error)

These functions and macros can be found in SCORE. The general utility of something like SC_arrlen made it desirable to put it in the lowest possible level library. This could be used, for example, to implement some dynamic array bound checking.

PDBLib uses this idea to be able to trace down arbitrary layers of indirection and obtain at each level the exact number of bytes to write out to a file. Of course, it also writes this information out so that the correct amount of space can be allocated by read operations as well as re-creating the correct connectivity of data structures.

Great care must be taken that pointers to fixed arrays not be embedded in a chain of indirects unless their dimension specifications are included either in the I/O request or the definition of a structure. This point cannot be over-emphasized! The extra memory management layer may fail to detect a statically allocated array and return an erroneous byte count. This in turn will cause very obscure incorrect behavior (in the worst of circumstances) or a direct crash (the best outcome possible).

Also, note that subsets of dynamically allocated arrays cannot know how many bytes they contain and hence care should be taken in their use.

The example on the following page shows the different ways that statically allocated arrays, dynamically allocated arrays, statically allocated arrays of pointers, and dynamically allocated arrays of pointers are handled by PDBLib. Note: The function SC_strsave invokes the MAKE_N macro.

 /* define variables in pairs - one to write and one to read into */
    PDBfile *strm;
    char *a, *b;
    char c[10], d[10];
    char *e[3], *f[3];
    char **s, **t;

    s = MAKE_N(char *, 2);

/* fill statically and dynamically allocated arrays */
    strcpy(c, "bar");
    a = SC_strsave("foo");

/* fill statically and dynamically allocated arrays of pointers */
    e[0] = SC_strsave("Foo");
    e[1] = NULL;
    e[2] = SC_strsave("Bar");
    s[0] = SC_strsave("Hello");
    s[1] = SC_strsave("world");

/* write these variables out
 * note the dimension specifications and the type
 */
    PD_write(strm, "c(10)", "char", c);
    PD_write(strm, "a", "char *", &a);
    PD_write(strm, "e(3)", "char *", e);
    PD_write(strm, "s", "char **", &s);

/* read the file variables into fresh memory spaces
 * note that the pointers to the pointers are passed in since the
 * space is to be allocated and the value of the pointer here must
 * be set to point to the new space
 */
    PD_read(strm, "c", d);
    PD_read(strm, "a", &b);
    PD_read(strm, "e", f);
    PD_read(strm, "s", &t);

PDB Universal Data Locators

As of PDB version 22, PDBLib can access data from a variety of sources. For example, PDBLib can access PDB files in TAR files and AR archives. In conjunction with the translation spokes, PDBLib can access various other data formats such as HDF and mySQL.

In order to make sense of all the possible data sources, PDBLib is using a Uniform Data Locator modelled after the URL used in the World Wide Web. The UDL syntax is as follows:

   [<proto>://<host>/]<path>[@<addr>][,<attr>]*

   <proto>     := http | https | ftp |  (via curl)
                  mysql                 (via mysql)
                  webdav
   <path>      := <file> | <container> '~' <file>
   <file>      := full or relative path to file
                  relative means relative to $HOME or
                  whatever the base path is as determined by
                  the server or container in question
   <container> := tar | ar
   <addr>      := offset into the file - allows accessing
                  remote files without having to download
                  them in toto
   <attr>      := key/value pair specifications
                  e.g. tgt=ieee96 or tgt=txt
Calls to PD_open, PD_create, and so on now take a UDL in the place of the file name. Based on the UDL, the appropriate data source or destination is used.

Some examples are:

   "/home/you/a.pdb"        full path to a.pdb
   "a.pdb"                  file a.pdb in current directory
   "b.tar~a.pdb"            file a.pdb in TAR file b.tar in current directory
   "a.pdb,tgt=txt"          write a.pdb in TXT mode
   "mysql://server/data"    MySQL database 'data' on host 'server'
Note that access to some data sources depends on whether various libraries are available on the system on which PACT is installed. The following data sources/destinations have such dependencies:
   HDF5      hdf5.h, libhdf5.a
   mySQL     mysql.h, libmysqlclient.a
   SQLite    sqlite3.h, libsqlite3.a
The C macro can be PD_get_file_type can be used to query a PDBfile structure returned by PD_open regarding the type of file actually opened. The standard kinds of files have the following types:

TypeType Name
PDBPDBfile
HDF5HDF5file
SQLSQLdatabase
XMLXMLfile

Binary and Text Data

For all of its history up to version 22, PDBLib dealt only with binary files. As of version 22, PDBLib can write and read a text version of data. The capability is new and there are important restrictions.

First of all PDBLib has considered ASCII characters as binary data which might need to be converted to other character formats such as the wchar or various internationalizations. None of those conversions have been implemented, merely provided for.

Now a text or TXT mode, means that the entire data file is represented in printable characters. You can look at the data with a text editor. With restrictions you can edit a text mode file with a text editor and read it back in.

In text mode each primitive data type has fixed number of bytes to represent it. For example, a short requires 7 bytes - a leading space, a sign, and 5 decimal digits to represent values from -32768 to 32767.

The editing restrictions are that the you cannot violate the field width, i.e. the number of characters to represent each primitive type. You may change the values in the field, but not the field width.

In practice this capability is rather unrefined at this point. Future improvements with be made to increase flexibility and user friendliness.

PDB Syntax

This section contains discussion of some PDB concepts that are used elsewhere in this manual.

In the following discussion and elsewhere in the manual a BNF style notation is used. In such places the following constructs are used:

| or
[] items between the brackets are optional
[]* zero or more instances of the items between the brackets
[]+ one or more instances of the items between the brackets
"x" literal x Since a data entry can be of a structured type, in general, a data entry is a tree. A part of the data tree is specified by a path to that part. A path specification is of the form:

path := node_spec | path.node_spec
node_spec := name["[" index_expr "]"]* | name["(" index_expr ")"]*
name := entry-name | member-name

The last node specified is referred to as the terminal node.

PDBLib Rules

There are a few crucial rules to be followed with PDBLib. If they are not obeyed, PDBLib may crash or the results desired will not occur.

Rule #1

The following reserved characters or sequences are not allowed in variable names or defstr member names:
'.',  '(',  ')', '[',  ']'  and  '->'.
They are reserved by the grammar of the data description language which follows some C and some FORTRAN conventions. It is recommended that you try to be somewhat conservative in choosing identifier names. Some punctuation characters are perfectly legal to use but may cause confusion when browsing files or reading your own code.

Rule #2

In each read and write operation, the type of the argument corresponding to the variable to be written or read must be a pointer to an object of the type specified for the entry. For example,

     int *a, *b;
            .
            .
     PD_write(strm, "a", "integer *", &a);
     PD_read(strm, "a", &b);
            .
            .

Rule #3

When using pointers and dynamically allocated memory with PDBLib, use SC_alloc, SC_realloc, SC_strsave, MAKE, MAKE_N, REMAKE, or REMAKE_N to allocate memory. These functions and macros are documented in the SCORE User's Manual.

Rule #4

When reading or writing part of a variable, especially a structured variable, the terminal node must be of primitive type or a structure containing no indirections and whose descendant members contain no indirections. Furthermore, the path to the desired part must contain one array reference for each level of indirection traversed. For example,
     char **s, c;
 
 /* fill s so that s[0] = "Hello" and s[1] = "World" */
            .
            .
     PD_write(strm, "s", "char **", &s);
 
 /* read the `o' in "Hello" */
     PD_read(strm, "s[0][4]", &c);
 
 /* read the `o' in "World" */
     PD_read(strm, "s[1][1]", &c);
            .
            .

PDB File Format

Up until PDBLib version 19 the file format has gone through only one major revision. These two formats were deeply connected to the internal workings of PDBLib itself. As such those file formats were not documented. Over the years certain problems and experience have led to the design of a next generation PDB file format. This is the third file format version for PDB. Its design addresses three main goals:

1) Total separation of data and metadata.

Earlier versions of the PDB file format had metadata at the beginning and end of the file. If pointers were written, there was metadata interspersed amidst the data itself.

With the new format, all PDB metadata is concatenated at the end of the file, including pointer metadata. This means that PDB metadata can be attatched to the end of any file rendering it a valid PDB file. A simple extension of this will permit the metadata to exist in a separate file. This design strategy opens the door to greater flexibility in using PDBLib to access arbitrary data files. It also promises benefits in dealing with data files in parallel applications.

2) More efficient operation.

The organization of the metadata improves on the scheme used in earlier versions. Earlier versions introduced a metadata section seperate from the structure chart and symbol table called the extras. The extras provide a means to accrete new features into PDBLib without invalidating existing files.

Several extras dealt with extentions to the description of the data types. This led to a requirement that the extras had to be read in order to interpret the data types correctly. The new format generalizes this idea to make the description of data types more extensible and remove any data type description elements from the extras. In effect, this gives data types their own independent extras. This in turn means that the interpretation of the type metadata is self contained and in a way that can be extended in the future.

The structure chart has been broken down into two distinct sections for: primitive types and compound types. The syntax of these sections has been refined for their respective needs.

The new design for handling pointers improves I/O performance by reducing the amount of seeking around on disk to find the pointer metadata. All of the pointer metadata is contained in the /&ptrs directory of the symbol table. As such the pointers are able to be processed using more of the general PDBLib functionality and require less specialized coding.

3) Human readable and editable.

The new design of the metadata section features 100% ASCII representation of the information. A syntax for the metadata was chosen to make the metadata more human readable. Also, where possible the elements of C language syntax were used in order to make the metadata more intuitive to users familiar with that language.

Occassionally, file system errors corrupt data files. By redesigning the metadata section to be both ASCII and as human readable as possible, the goal is to make it as easy as possible for a user, program or shell script to repair files which have damaged metadata.

Also to fully realize the potential of having separated the metadata into a single, complete section, it makes sense to have it human readable. A person has a higher probability of composing a description of some pure binary file and turning it into a PDB file with this design. A script or a program to do this becomes relatively simple in comparison to the previous PDB formats. By emphasizing the human readability and comprehensibility of the metadata, the entire PDBLib machinery becomes even more accessible for a wider range of applications.

In order to meet these goals (especially goal 3) it is imperative that the format of the metadata be documented. You can also use a text editor such as emacs to look at a PDB file. If you peruse the end of a format version I or II file you will recognize some elements of those formats. If you look at the end of a format version III file you will plainly see the metadata spelled out.

The current default is to write format version II files. This is a transitional measure to allow users to become familiar with format version III. An application can select which format version to use when creating new PDB files. See the PD_set_format_version routine for details.

Format Version III Syntax

A) PrimitiveTypes

The primitive data types are perhaps the most fundamental of all the metadata. The compound types are defined in terms of primitive types and other compound types. The symbol table cannot be interpreted without understanding the types.

The metadata section for the primitive types starts with a line containing only the tag, "PrimitiveTypes:". Each primitive type is defined by a single line of the form:

      <type> <Nbytes> <alignment> <attributes>;
where
      <type>       := the name of the data type, e.g. int
      <Nbytes>     := the length in bytes of an instance of the type
      <alignment>  := the byte alignment of the type
      <attributes> := <attribute>[|<attribute>]*
      <attribute>  := <order> | FIX | <float> | NO-CONV | UNSGNED |
                      <typedef> | ONESCMP
      <order>      := ORDER(<ord-spec>)
      <ord-spec>   := big | little | <Nbytes comma delimited integers>
      <float>      := FLOAT(<float-spec>)
      <float-spec> := #bits,#exponent-bits,#mantiss-bits,offset-sign-bit,
                      offset-exponent-field,offset-mantisssa-field,
                      leading-bit-flag,exponent-bias
      <typedef>    := TYPEDEF(<type>)
Three other fundamental pieces of information exist with the primitive types:
      StructAlignment    - additional alignment for structs
      DefaultIndexOffset - the value of the default array index offset
                           typically 0 for C codes and 1 for Fortran
      MajorOrder         - the major ordering for multi-dimensional arrays
                         - typically "row" for C and "column" for Fortran
The following excerpt from an actual file illustrates:
      PrimitiveTypes:
         *          4   4  ORDER(little)|FIX;
         char       1   1  NO-CONV|FIX;
         int        4   4  ORDER(little)|FIX;
         u_int      4   4  ORDER(little)|FIX|UNSGNED;
         double     8   8  ORDER(little)|FLOAT(64,11,52,0,1,12,0,1023);
         REAL       8   8  ORDER(little)|FLOAT(64,11,52,0,1,12,0,1023)|TYPEDEF(double);
         function   4   4  ORDER(little)|FIX;
         Directory  1   0  NO-CONV|FIX;

      StructAlignment: 0
      DefaultIndexOffset: 0
      MajorOrder: row
B) CompoundTypes

Compound types are constructed from primitive types and other compound types. This section begins with a line containing just the tag, "CompoundTypes:". Each compound type begins with a line of the form:


      <type> (<Nbytes>)
where
      <type>   := the name of the compound type
      <Nbytes> := the number of bytes required to represent one
                  instance of <type> on disk
The members of the compound type are specified one per line. The syntax is:
       {<member>
        <member>
           .
           .
           .
        <member>};
where
      <member> := <type> <name> [<- <cast>];
      <type>   := the name of the type of the member
      <name>   := the name of the member
      <cast>   := the name of the member whose true type
                  this member contains (this member must
                  have <type> "char *")
The following example illustrates:
      CompoundTypes:
         pcons (16)
            {char *car_type;
             char *car <- car_type;
             char *cdr_type;
             char *cdr <- cdr_type;};
C) SymbolTable

The symbol table associates a name with the information describing an object written to the file. This section begins with a line containing just the tag, "SymbolTable:". Each entry is described in a single line of the form:

     <type> <name>[<dimensions>] @ <address> (<Nitems>);
where
     <type>       := is the name of the type of the data
     <name>       := is the name of the entry
                     all names are fit into a hierarchy on the
                     model of a file system and as such begin
                     with '/'
     <dimensions> := <dim_start><dimension>[,<dimension>]*<dim_end>
     <dim_start>  := '(' | '['
     <dimension>  := <length> | <min>:<max>
     <dim_end>    := ')' | ']'
The following example illustrates some of the syntax:
      SymbolTable:
         Directory / @ 0 (1);
         Directory /&ptrs/ @ 1 (1);
         integer /ia[0:4] @ 41 (5);
         float /fa2[0:3,0:2] @ 61 (12);
         double /da[0:3] @ 109 (4);
         char /ca[0:9] @ 21 (10);
         integer /is @ 5 (1);
         short /sa[0:4] @ 31 (5);
         char * /cap[0:2] @ 141 (3);
         st62 /d71 @ 2 (1);
         double /&ptrs/ia_2 @ 98 (10);
         double /&ptrs/ia_1 @ 10 (10);
D) Extras

Certain metadata does not specifically describe symbol table entries or data types. Also, from time to time extra information is added to PDB files to adapt to new requirements. This information is placed in the extras table. The data in the extras table is optional and PDBLib has default values for each piece of information which permit backwards compatibility to the greatest possible degree.

The extras appear after the symbol table. The syntax of the entries varies according to the needs of the data, but as a rule of thumb the syntax is:

     <key>: <value>
The following example illustrates some of the syntax:
      UseItags: 0
      Version: 19 (Fri Apr 28 14:04:36 2006)
E) Addresses and Trailer

The last three elements of version III syntax are the addresses of the structure chart (beginning with the PrimitiveTypes section), the symbol table, and a tag which identifies the file as being a PDB file using format version III.

The following example illustrates this syntax:

      StructureChartAddress: 40247
      SymbolTableAddress: 41442
      !<<PDB:3>>!
F) Blocks

PDBLib supports notions like PD_append which allow applications to add more data to an entry in the file. In order to do this with the greatest flexibility and economy of disk space, PDBLib allows a variable to be stored in discontiguous blocks of space in the file. Logically, the variable is contiguous, only the underlying storage pattern is discontiguous.

If a variable is completely contiguous, its symbol table entry in the file has a complete specification. If a variable has discontiguous parts, its symbol table entry in the file completely describes the first continguous part (this makes non-PDB readers able to make sense of at least some of the data). The remainder of the variable is described by a list of blocks in the extras section of the file.

By virtue of the fact the PDB only allows extending the most slowly increasing dimension, it is sufficient that a block specify the number of items in the discontiguous piece and its starting address.

A section in the extras part of the file which begins with the tag "Blocks:" contains all of the block information for all variables in the file. Each entry has the form:

       <name> <n-blocks>
           <addr> <n-items>          n-blocks pairs
where
       <name>     := the name of the variable
       <n-blocks> := the number of block specifcations
                     to follow
       <addr>     := the starting address of the data
                     for the block
       <n-items>  := the number of items in the block
G) Checksums

PDBLib supports per variable checksumming. In practice, since checksumming works with PD_append, it is actually per block checksumming (see the above Blocks section).

Because checksumming is independent of having blocks the per variable checksum information has its own extras section and tag, "Checksums:". Each entry has the form:

       <name> <n-blocks> <n-entries>
           <block-n> <block-checksum>        n-entries 
where
       <name>            := the name of the variable
       <n-blocks>        := the number of block specifcations to follow
       <n-entries>       := the number of checksum specifcations to follow
       <block-n>         := the index of the block whose checksum follow
       <block-checksum>  := the checksum for the specified block
The checksums are laid out this way because it is possible to reserve a block of data with PD_defent and not write to it. Consequently, a variable can have blocks with no checksum and entries are made only for blocks possessing a valid checksum at the time the file is closed.

H) Hidden Directories

PDBLib has the notion of a directory (after the file system model used by most operating systems). All variables are entered in the symbol table as a "full path". This means all symbol table entry names begin with '/'.

PDBLib stores some of its metadata using PDBLib API calls such as PD_write. This has several advantages: minimizes special coding for metadata; and exposes some metadata to generic PDB file browsers such as PDBView.

In order to make plain which information is data and which metadata, PDBLib uses a convention that root level directories whose name begins with '&' contain metadata. By default, such directories will not be listed by PDBView which has earned them the nickname "hidden directories".

Current hidden directories are:

      /&ptrs
      /&etc
I) Pointers

With regard to the handling of pointers, earlier versions of PDBLib did not write the actual pointers into the file (and struct members that were pointers were simply copied unconverted to the file). They wrote a simplified version of a symbol table entry called an ITAG, into the file at the start of the pointee's data. This had the bad effect of mingling data and metadata in the file.

Starting with format version III, PDBLib offers a new model which converts pointers to integer indices that are used to make symbol table entries for the pointees which are then entered in the /&ptrs directory. The pointers are therefore not ignored as they were previously. They are simply another kinds of data which has a well defined conversion algorithm, just as floats or integers do.

With this model it is not necessary to read from the disk to ascertain the location, type, and number information which describe the pointees. That resides in the symbol table which is kept in memory. As a result the performance of PDBLib when handling pointers is much improved.

Pointers are assigned an index, more or less, in the order in which they are written. So as the Nth pointer is written to the file, the number N is what the pointer is converted to and the pointee gets an entry in the symbol table /&ptrs/ia_N.

J) Attributes

The metadata supporting PDBLib's attribute handling is written out in the /&etc hidden directory. The pointers in the attribute table are not written in the /&ptrs directory, but in /&etc along with the attribute table itself.

NOTE: It is PDBLib policy that files with all prior format versions will be readable by all subsequent PDBLib versions. Current PDBLib design allows applications to select the format version they wish to use when creating new files (except for version I - current PDBLib cannot create a version I file any longer). We actively test this in our regression test suite.

Terms

A few definitions must be given first to keep the following summary concise. Some of these will be elaborated upon in the next section.

PDBfile: for the purposes of a program this is a collection of all the relevant information about one of these data files (in the actual coding it is a C struct). See the section on Data Structures for more information.

ENTRY: for the purposes of a program this is a collection of all the relevant information about a variable written to a PDB file.

DEFSTR: for the purposes of a program this is a collection of all the relevant information about a data type in a PDB file.

ASCII: a string

VOID: any data type

TRUE: a value of 1 (defined by PDBLib)

FALSE: a value of 0 (defined by PDBLib)

C context

LAST: a pointer to 0 (declared and defined by PDBLib)

FORTRAN context

LAST: the value 0

REAL*8: an eight byte floating point number.

SX context

TRUE: #t or anything that it not #f or nil.

FALSE: #f or nil.

Data Conversion and Compression

PDBLib has a quasi-universal data translation capability. It is called Parametrized Data Conversion (PDC). A set of parameters which characterizes a large set of integer and floating point formats was developed. It describes the byte size and order of integer types. For floating point data it describes the bit location and width of the sign, exponent, and mantissa field as well as the byte size and order of the data. Using this information a single integer conversion routine and a single floating point conversion routine handle all of the data conversions in PDBLib. An advantage of this approach is that there is no increase in the size of the library for each port to a new environment. Furthermore, it will allow future releases to auto-configure themselves to the machines on which they run. Another benefit is that a data representation may be targeted without regard to its implementation. This provides a vehicle for developing data representations, evaluating them, or using them in a highly abstract manner. One drawback of this approach is that it makes assumptions about the representation of data in computers. While the assumptions are general and the result of incorporating data representations outside these assumptions is more work on the library itself, it is philosophically unsatisfying to make any assumptions about how things are to be done or data to be represented. Another drawback is that by being general purpose the conversion routines are slightly slower than specific ones. This is more than made up for in the saving in library size and ease of porting the library.

Alternative data conversion strategies are either hub and spoke (such as Sun's XDR) or specific format to format. The latter suffers from an N2 growth in the number of conversion routines where N is the number of machine/architectures which the library supports. On the other hand, hub and spoke strategies necessitate a conversion on each read or write operation.

PDC prevents the conversion problem from being N2. At worst, the PDC method should grow like N in the number of parameter sets required. In practice, it is even better than that. Most computer systems today are based on a handful of CPU's which are the most constraining factor in binary data formats. For the convenience of the users of PDBLib, several data_standard's and data_alignment's are predefined by the library itself.

A significant advantage to PDC is that a class of data compression algorithms is implicit in the method. By simply describing a format which describes data in the correct range (up to a possible overall offset for each type), PDBLib can do all of the work to store and retrieve the data in a compressed form.

Using the PDBLib API

There is a hierarchy of routines in PDBLib from high to low level. The high level routines form the API while the lower level routines are modularized to perform the actual work. It should be noted that the lower level routines are sufficiently well modularized so as to make it possible to build entirely different API's for PDBLib.

Comments on the C API

The high level PDBLib routines have a strict naming convention. All high level routines begin with `PD_'. Some routines have several related forms. These are referred to as families of functions. For example the PD_write family.

Most routines maintain a thread of control's error message variable. The value of the error message can be retrieved through a call to PD_get_error. The error messages include the name of the routine in which they are made thus eliminating the need for error codes which must be cross referenced with some other document. In this way application programs can check for error conditions themselves and decide in what manner to use the PDBLib error messages instead of having error messages printed by the system routines. An error message variable is maintained per thread for multi-threaded applications. Error messages are not stacked and must be processed by the application before any other PDBLib calls are made in order to avoid potential overwrites. See the descriptions of individual routines for more information about error handling and messages.

Programs written in C must include a header which makes certain declarations and definitions needed to use the library. Much in the same spirit as one includes stdio.h to use printf and others, include pdb.h as follows:

  #include "pdb.h"
The file pdb.h #include's some other files which must either be in your directory space or pointed to in some manner which your compiler can recognize. The auxiliary #include files are schash.c, scstd.h, and score.h. These files are a part of the SCORE package which you must have to use PDBLib.

Comments on the FORTRAN API

The high level PDBLib routines have a strict naming convention. All routines in the FORTRAN API begin with `PF'.

Note: many of these functions return integer values. The implicit typing convention in FORTRAN would indicate that they return real values. Application programs must explicitly type these functions as integers.

When an error condition is detected by PDBLib it saves a message in a global C character string. FORTRAN programs can access this error message by invoking function PFGERR. The message contains the name of the function in which the error occurred thus eliminating the need for a cross reference document on error codes. In this way applications programs can check for error conditions themselves and decide in what manner to use the PDBLib error messages instead of having error messages printed by the system routines. Error messages are not stacked and must be processed by the application before any other PDBLib calls are made in order to avoid potential overwrites. See the FORTRAN API section for more information about which routines return error messages.

Opening, Creating, Closing, and Controlling PDB Files

These are the most fundamental operations involving PDBLib. The function PD_open is used to either open an existing file or create a new one. PD_close is used to close a PDB file so that it can be recognized by PDBLib for future operations.

PDBLib allows applications to specify the binary format in which a newly created file will be written. PD_target does this work. It is not necessary to invoke PD_target before creating a new PDB file. In this case the binary format is that appropriate for the host system.

During the run of an application code, PDBLib can complete the information in an open PDB file so that in the event of a code crash, the file will be a valid PDB file. This functionality is provided by PD_flush.


PD_SET_BUFFER_SIZE

C Binding:   int PD_set_buffer_size(int v)
F77 Binding: integer PFSBFS(integer v)
SX Binding:  (pd-set-buffer-size! v)
Python Binding:  XXX - missing

Set the buffer size which PDBLib will use for all PDB files to v.

The arguments to this function are: v, an integer value for the buffer size in bytes.

Return the integer value of the buffer size in bytes.


C Example
       int v;
             .
             .
             .

       PD_set_buffer_size(v);
             .
             .
             .

Fortran Example
       integer pfsbfs
       integer v, sz
             .
             .
             .

       sz = pfsbfs(v)
             .
             .
             .

SX Example
             .
             .
             .

       (pd-set-buffer-size! 4096)
             .
             .
             .

Python Example


PD_TARGET

C Binding:   int PD_target(data_standard *std, data_alignment *align)
F77 Binding: integer PFTRGT(integer is, integer ia)
SX Binding:  (target is ia)
Python Binding:  XXX - missing

Write the next PDB file according to the specified data standard and alignment. PDBLib has a general binary data conversion mechanism called parametrized data conversion (PDC). An integer type is described by one set of parameters and a floating point type is described by another. A general purpose conversion routine takes the description of the input type and a description of the desired output type and does the conversion. In this way, PDBLib avoids an N2 increase in data conversion routines as it ports to new machines. In fact, the number of data standards and alignments grows more slowly than N because many machines share common formats.

An additional advantage to PDC is that by specifying a format involving the minimal number of bits to represent the data for a file, PDBLib can carry out a large class of data compressions.

Available data standards are:

C Fortran Byte Order S/I/L/LL F/D
IEEEA_STD 1 NORMAL_ORDER 2,4,4,8 4,8
IEEEB_STD 2 NORMAL_ORDER 2,2,4,4 4,12
IEEEC_STD 3 NORMAL_ORDER 2,4,4,4 4,12
INTELA_STD 4 REVERSE_ORDER 2,2,4,4 4,8
INTELB_STD 5 REVERSE_ORDER 2,4,4,8 4,8
VAX_STD 6 REVERSE_ORDER 2,4,4,8 4,8
CRAY_STD 7 NORMAL_ORDER 8,8,8,8 8,8
IEEED_STD 8 NORMAL_ORDER 2,4,8,8 4,8
IEEEE_STD 9 REVERSE_ORDER 2,4,8,8 4,8
NOTE: S/I/L/LL - short/int/long/longlong  byte sizes
      F/D      - float/double byte sizes

Available data alignments are:

C Fortran C/P/S/I/L/LL/F/D/Str
M68000_ALIGNMENT 1 1,2,2,2,2,2,2,2,0
SPARC_ALIGNMENT 2 1,4,2,4,4,4,4,8,0
MIPS_ALIGNMENT 3 1,4,2,4,4,8,4,8,0
INTEL_ALIGNMENT 4 1,2,2,2,2,2,2,2,0
DEF_ALIGNMENT 5 1,4,4,4,4,4,4,4,0
CRAY_ALIGNMENT 6 4,8,8,8,8,8,8,8,8
UNICOS_ALIGNMENT 7 4,8,8,8,8,8,8,8,8
RS6000_ALIGNMENT 8 1,4,2,4,4,8,4,4,0
NOTE: C/P/S/I/L/LL/F/D/Str - char/pointer/short/int/long/longlong/float/double/struct

In the FORTRAN API, these structures are placed in two arrays and the indices into these arrays are passed into PFTRGT to specify the binary format to be targeted.

Some common configurations are:

Platform C Method Fortran SX Method
Intel 80x86 UNIX PD_target(&INTELB_STD, &INTEL_ALIGNMENT) PFTRGT(5, 4) (target 5 4)
SPARC PD_target(&IEEEA_STD, &SPARC_ALIGNMENT) PFTRGT(1, 2) (target 1 2)
MIPS, SGI PD_target(&IEEEA_STD, &MIPS_ALIGNMENT) PFTRGT(1, 3) (target 1 3)
IBM RS6000 PD_target(&IEEEA_STD, &RS6000_ALIGNMENT) PFTRGT(1, 8) (target 1 8)
Mac/Think C PD_target(&IEEEB_STD, &M68000_ALIGNMENT) PFTRGT(2, 1) (target 2 1)
DEC 3100 PD_target(&INTELB_STD, &MIPS_ALIGNMENT) PFTRGT(5, 3) (target 5 3)
UNICOS Cray PD_target(&CRAY_STD, &UNICOS_ALIGNMENT) PFTRGT(7, 7) (target 7 7)
Motorola PD_target(&IEEEA_STD, &M68000_ALIGNMENT) PFTRGT(1, 1) (target 1 1)
DEC Vax PD_target(&VAX_STD, &DEF_ALIGNMENT) PFTRGT(6, 5) (target 6 5)
Mac/MPW PD_target(&IEEEC_STD, &M68000_ALIGNMENT) PFTRGT(3, 1) (target 3 1)
DOS PD_target(&INTELA_STD, &INTEL_ALIGNMENT) PFTRGT(4, 4) (target 4 4)

The arguments to this function are: std, a pointer to a data_standard structure; is, an index corresponding one of the data_standards; align, a pointer to a data_alignment structure; and ia, an index corresponding to one of the data_alignment structures above. See the section on Data Structures.

The return value is TRUE, if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: DATA_STANDARD and DATA_ALIGNMENT .


C Example
 #include "pdb.h"
 
 void test_target(tgt, base, n, fname, datfile)
    char *tgt, *base;
    int n;
    char *fname, *datfile;
    {if (tgt != NULL)
 
 /* for DOS machines */
        {if (strcmp(tgt, "dos") == 0)
            PD_target(&INTEL_STD, &INTEL_ALIGNMENT);
 
 /* for CRAY computers */
         else if (strcmp(tgt, "cray") == 0)
            PD_target(&CRAY_STD, &UNICOS_ALIGNMENT);
 
 /* for DEC VAX machines */
         else if (strcmp(tgt, "vax") == 0)
            PD_target(&VAX_STD, &DEF_ALIGNMENT);
 
 /* for MIPS based machines */
         else if (strcmp(tgt, "mips") == 0)
            PD_target(&IEEEA_STD, &MIPS_ALIGNMENT);
 
 /* for standard M68000 machines */
         else if (strcmp(tgt, "sun3") == 0)
            PD_target(&IEEEA_STD, &M68000_ALIGNMENT);
 
 /* for SPARC machines */
         else if (strcmp(tgt, "sun4") == 0)
            PD_target(&IEEEA_STD, &SPARC_ALIGNMENT);
 
 /* for Macintosh */
         else if (strcmp(tgt, "mac") == 0)
            PD_target(&IEEEB_STD, &M68000_ALIGNMENT);
 
         sprintf(fname, "%s-%s.rs%d", base, tgt, n);
         sprintf(datfile, "%s-%s.db%d", base, tgt, n);}
     else
        {sprintf(fname, "%s-nat.rs%d", base, n);
         sprintf(datfile, "%s-nat.db%d", base, n);};
 
     return;}

Fortran Example
       integer pftrgt
       integer is, ia
             .
             .
             .

 c ... set target architecture (MIPS, SGI)
 c ... IEEEA_STD
       is = 1
 c ... MIPS_ALIGNMENT
       ia = 3
       if (pftrgt(is, ia) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

 ; set target architecture (MIPS, SGI)
 ; IEEEA_STD is 1 and MIPS_ALIGNMENT is 3
     (target 1 3)
             .
             .
             .

PD_OPEN

C Binding:   PDBfile *PD_open(char *filename, char *mode)
F77 Binding: integer PFOPEN(integer nchr, character name, character mode)
SX Binding:  (open-pdbfile name mode)
Python Binding:  pact.pdb.open(name, mode='r')

Open an existing PDB file or create a new PDB file. Depending on the value of the mode argument, PDBLib attempts to open the file filename in read-only binary mode, open the file in append binary mode, or create a new file in read-write binary mode. Any string which begins with "r" causes the file to be opened in read-only mode, any string beginning with "a" causes the file to be opened in append mode, and any string beginning with "w" causes a file to be created in read-write mode. Next the beginning of the file is searched for the header which identifies the file as having been generated by PDBLib. The addresses of the structure chart and symbol table are then sought.

The structure chart from the file is read in. The structure chart contains information about data types (e.g. floats), their sizes in bytes and their structures if any. By default there are six primitive data types that PDBLib knows about: short integers, integers, long integers, floating point numbers, double precision floating point numbers, characters, and pointers. The sizes of these types vary from machine to machine, but PDBLib hides this from the user.

The symbol table from the file is read in. The symbol table contains the list of variables in the file, their types as defined in the structure chart, and dimensioning information for arrays. Each read from the file first consults the symbol table to see if the requested variable is present in the PDB file.

Both the structure chart and the symbol table are implemented as hash tables, although their shapes are different. This makes lookups as efficient as possible given an unknown amount of data in the file.

The arguments to PD_open() are:
nchr - the number of characters in filename;
filename - an ASCII string, which is the name of the file to be created or opened;
mode - an ASCII string, which is the mode (either "w" for create/write, "r" for read-only or "a" for append).

In the C binding the function returns a pointer to a PDBfile. In the FORTRAN binding the function returns an integer identifier for the PDBfile opened/created. In the Python binding the funtion returns a PDBfile object. This PDBfile identifies the particular file to PDBLib. As such, if it is overwritten, the file is lost. The number of PDB files which can be open simultaneously is machine or operating system dependent, but each open file has a unique PDBfile associated with it.

If any aspect of the PDB file opening process fails, a NULL pointer is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
           .
           .
           .

    if ((file = PD_open("filename", "r")) == NULL)
       printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfopen
       integer fileid
             .
             .
             .

       fileid = pfopen(8, 'file.pdb', 'r')
       if (fileid .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (define file (open-pdbfile "foo.pdb" "w"))
             .
             .
             .

Python Example
    import pact.pdb
             .
             .
             .

    file = pact.pdb.open("foo.pdb" "w")
             .
             .
             .

PD_SET_MAJOR_ORDER

C Binding:   void PD_set_major_order(PDBfile *file, int v)
F77 Binding: integer PFSMJO(integer fileid, integer v)
SX Binding:  (major-order file v)
Python Binding:  XXX - missing

Set the major order for PDB file fileid to v. The major order refers to the order of data in multidimensional arrays. See the discussion of this topic in the section PDBLib and Index Ordering.

Input to this function is: fileid, an integer PDBfile identification number, v, an integer value for the major order.

In the C binding return the value of the major order. In the FORTRAN binding return 1 if successful, 0 otherwise.


C Example
       PDBfile *file;
             .
             .
             .

       PD_set_major_order(file, COLUMN_MAJOR_ORDER);
             .
             .
             .

Fortran Example
       integer pfsmjo
       integer fileid, v
             .
             .
             .

       v = 102
       if (pfsmjo(fileid, v) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (major-order file "column-major-order")
             .
             .
             .

Python Example
             .
             .
             .

    file.major_order = "column-major-order"
             .
             .
             .

PD_SET_FORMAT_VERSION

C Binding:   void PD_set_format_version(int v)
F77 Binding: integer PFSFMV(integer v)
SX Binding:  (format-version v)
Python Binding:  XXX - missing

Set the format version to be used when creating new PDB files to v. See the section PDB File Format for a discussion of the PDB file formats.

Input to this function is: v, an integer value for the format version.

In the C binding return the value of the format version. In the FORTRAN binding return 1 if successful, 0 otherwise.


C Example
             .
             .
             .

       PD_set_format_version(3);
             .
             .
             .

Fortran Example
       integer pfsfmv
       integer v
             .
             .
             .

       v = 3
       if (pfsfmv(v) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (format-version 3)
             .
             .
             .

Python Example
             .
             .
             .

PD_SET_MAX_FILE_SIZE

C Binding:   PD_set_max_file_size(PDBfile *file, int v)
F77 Binding: integer PFSMXS(integer fileid, integer v)
SX Binding:  (set-maximum-file-size! file v)
Python Binding:  XXX - missing

Set the maximum file size for PDB file fileid to v. This is used to allow applications to make families of related PDB files and to control the size of the members of the family.

Input to this function is: fileid, an integer PDBfile identification number. Output from this function is: v, an integer value for the maximum file size.

In the C binding return the new integer value of the maximum file size. In the FORTRAN binding return 1 if successful, 0 otherwise.

See also: PD_family .


C Example
       PDBfile *file
             .
             .
             .

       PD_set_max_file_size(fileid, 2000000);
             .
             .
             .

Fortran Example
       integer pfsmxs
       integer fileid, v, sz
             .
             .
             .

       if (pfsmxs(fileid, sz) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

     (set-maximum-file-size! file 100000000)
             .
             .
             .

Python Example
             .
             .
             .

     file.maximum_size = 100000000
             .
             .
             .

PD_SET_OFFSET

C Binding:   void PD_set_offset(PDBfile *file, int v)
F77 Binding: integer PFSOFF(integer fileid, integer v)
SX Binding:  (default-offset file v)
Python Binding:  XXX - missing

Set the default offset for PDB file fileid to v. The default offset refers to the minimum value of a dimension index. PDBLib allows dimensions to be specfied either in "min:max" form, in which case the minimum value is explicit, or in "max" form, in which case the minimum value or offset is assumed. See the discussion in PDBLib and Index Offsets for more details.

Input to this function is: fileid, an integer PDBfile identification number,

Output from this function is: v, an integer value for the default offset.

In the C binding return the value of the offset. In the FORTRAN binding return 1 if successful, 0 otherwise.


C Example
       PDBfile *file;
             .
             .
             .

       PD_set_offset(file, 1);
             .
             .
             .

Fortran Example
       integer pfsoff
       integer fileid, v, sz
             .
             .
             .

       if (pfsoff(fileid, sz) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (default-offset file 0)
             .
             .
             .

Python Example
             .
             .
             .

    file.default-offset = 0
             .
             .
             .

PD_FAMILY

C Binding:   PDBfile *PD_family(PDBfile *file, int flag)
F77 Binding: integer pffami(integer fileid, integer flag)
SX Binding:  (family-file file flag)
Python Binding:  XXX - missing

This function checks to see whether the specified file has exceeded it size limit as set by PD_set_max_file_size. If it has then a new file is opened and returned. If not the given file pointer is returned. The flag is set to TRUE if you want PD_family to close the file it is given. Otherwise the application is responsible for closing the file.

In order to make a family of files the file name is constrained to follow a form that clearly identifies the sequence of files in the family. The name of the file in the original PD_open must be of the form:

          base.[a-zA-Z]dd
where
          d = [0-9a-zA-Z]
This is a 3 digit base 36 integer and permits upto 46656 files in a family.

The arguments to this function are: file, the pointer to the PDBfile structure returned by a previous call to PD_open; fileid, an integer file identifier returned by a previous call to PFOPEN; and flag, an integer value (either TRUE or FALSE).

In the C binding this function returns a pointer to a PDBfile. In the FORTRAN binding this function returns an integer file identifier.

See also: PD_set_max_file_size .


C Example
 #include "pdb.h"
 
    PDBfile *old, *new;
            .
            .

     PD_set_max_file_size(old, 10000000);
            .
            .
            .

     new = PD_family(old, FALSE);
     if (new != old)
        {PD_close(old);
              .
              .
              .

         old = new;};
            .
            .
            .

Fortran Example
    integer old, new
    integer pffami
            .
            .
            .

     new = pffami(old, 0)
     if (new .ne. old) then
        pfclos(old)
              .
              .
              .

        old = new
     endif
            .
            .
            .

SX Example
            .
            .
            .

     (set! old (family-file old #t))
            .
            .
            .

PD_FIX_DENORM

C Binding:  int PD_fix_denorm(data_standard* std, char *type, long len, void *vr)
F77 Binding: integer PFDNRM(integer istd, integer nc, character type,
                 integer len, void vr)

This function checks to see whether the floating point values pointed to by var are denormalized, and if so, sets all denormalized values to 0.0 (zero).

The arguments to this function are: std, the pointer to a data_standard (if NULL the data standard for the current platform will be used); istd, integer id of the data_standard (if -1 the data standard for the current platform will be used); nc, an integer number of characters in the type string; type, the type of values pointed to by var (either "float" or "double"); len, the number of values pointed to by var; and vr, a pointer to the floating point values.

Available data standards are:

C Fortran Byte Order S/I/L/LL F/D
IEEEA_STD 1 NORMAL_ORDER 2,4,4,8 4,8
IEEEB_STD 2 NORMAL_ORDER 2,2,4,4 4,12
IEEEC_STD 3 NORMAL_ORDER 2,4,4,4 4,12
INTELA_STD 4 REVERSE_ORDER 2,2,4,4 4,8
INTELB_STD 5 REVERSE_ORDER 2,4,4,8 4,8
VAX_STD 6 REVERSE_ORDER 2,4,4,8 4,8
CRAY_STD 7 NORMAL_ORDER 8,8,8,8 8,8
IEEED_STD 8 NORMAL_ORDER 2,4,8,8 4,8
IEEEE_STD 9 REVERSE_ORDER 2,4,8,8 4,8
NOTE: S/I/L/LL - short/int/long/longlong  byte sizes
      F/D      - float/double byte sizes

This function returns 1 on success and 0 on failure.

See also: DATA_STANDARD and DATA_ALIGNMENT .


C Example
 #include "pdb.h"
 
    PDBfile *file;
    float* fvalue;
    double* dvalue;

    fvalue = MAKE_N(float, 3);
    dvalue = MAKE_N(double, 1);
            .
            .
            .

    PD_fix_denorm(file->std, "float", 3, fvalue);
    PD_fix_denorm(NULL, "double", 1, dvalue);
            .
            .
            .


Fortran Example
 #include "pdb.h"
       integer pfdnrm
       integer is
       doubleprecision d(100)
             .
             .
             .

       is = -1
       if (pfdnrm(is, 6, "double", 100, d) .eq. 0)
      &   call errproc
             .
             .
             .


PD_FLUSH

C Binding:   int PD_flush(PDBfile *file)
F77 Binding: integer PFFLSH(integer fileid)
SX Binding:  (flush-pdbfile file)
Python Binding:  file.flush()

This function writes out the information which describes the contents of the PDB file specified. Normally, PD_close calls this routine, but applications that want to protect themselves from system failures or other problems may chose to periodically use this function. After a successful return and until or unless more data is written to the file or space reserved for future writes, the PDB file is valid in the sense that if the application terminates unexpectedly before calling PD_close, the file can be PD_open'd successfully.

NOTE: this call does NOT obviate PD_close!

The argument to this function is: file, the pointer to the PDBfile structure returned by a previous call to PD_open; or fileid, the pointer to the PDBfile structure returned by a previous call to PFOPEN.

This function returns TRUE if successful and FALSE is returned and FORTRAN programs may retrieve an error message by invoking function PFGERR.


C Example
 #include "pdb.h"
 
    PDBfile *file;
            .
            .
            .

     if (PD_flush(file) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfflsh
       integer fileid
             .
             .
             .

       if (pfflsh(fileid) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

     (flush-pdbfile file)
             .
             .
             .

Python Example
             .
             .
             .

     file.flush()
             .
             .
             .

PD_CLOSE

C Binding:   int PD_close(PDBfile *file)
F77 Binding: integer PFCLOS(integer fileid)
SX Binding:  (close-pdbfile file)
Python Binding:  file.close()

Close a PDB file.

After all data is written to the PDB file, the structure chart and symbol table must be written out to the file and their disk addresses recorded in the file header. Without these operations the file cannot be read back in by PDBLib and all data is lost. All open PDB files must be closed with PD_close() before exiting the program.

The arguments to PD_close() are:
file - a pointer to a PDBfile;
fileid - an integer file identifier

The function returns TRUE if the PDB file is correctly written and closed;
otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
            .
            .
            .

     if (PD_close(file) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfclos
       integer fileid
             .
             .
             .

       if (pfclos(fileid) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

     (close-pdbfile file)
             .
             .
             .

Python Example
             .
             .
             .

     file.close()
             .
             .
             .

PD_REMOVE_ENTRY

C Binding:   int PD_remove_entry(PDBfile *file, char *name)
F77 Binding: integer PFRENT(integer fileid, char name)
SX Binding:  (remove-entry file name)

Remove an entry from the symbol table of a PDB file.

This function only removes an entry from the symbol table of the file. It does not do anything about the space which the entry took up in the file.

If the unused regions of the file on disk is a problem, then the file could be copied by opening a new file, reading each variable found in the symbol table, and writing it to the new file. The resulting file would be compact. PDBView has just such a copy command.

The arguments to PD_remove_entry() are:
file - a pointer to a PDBfile;
fileid - an integer file identifier name - a string containing the name of the entry to remove

The function returns TRUE if the entry is successfully removed;
otherwise, FALSE is returned.


C Example
 #include "pdb.h"
 
    PDBfile *file;
            .
            .
            .

     if (PD_remove_entry(file, "foo") == FALSE)
        printf("Cannot remove 'foo'\n");
            .
            .
            .

Fortran Example
       integer pfrent
       integer fileid
             .
             .
             .

       if (pfrent(fileid, 'foo') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

     (remove-entry file "foo")
             .
             .
             .

Writing Data to PDB Files

The following paragraphs describe a sequence of increasingly more elaborate output operations for PDB files. They are all compatible with one another so users can select the ones which match their needs best. The most straightforward operations are first.

There are two forms for the most basic data writing operations. These have to do with how the application wants to handle the dimension specifications. The two functions are PD_write and PD_write_alt.

PDBLib supports the notion of writing data of one type out into a file as another type. More precisely, an integer type of data can be written to a file in the format of any other integer type, and similarly for floating point types. The application must take all responsibility for ensuring the appropriateness of this type of conversion (e.g. underflows and overflows). The functions which support this are PD_write_as and PD_write_as_alt.

PDBLib allows applications to append data to existing entries. This is handy in situations where the total amount of data is not known in advance, but a logical ordering of the data is apparent which matches the order in which data will be written. The functions which do this are the PD_append family of functions.

Finally, PDBLib allows applications to reserve space on disk and then let subsequent writes fill in that space with values. This is handy in instances where an application knows a logical structure for a data set but needs to write it out in smaller pieces and not necessarily in the order implied by its logical structure. The functions which let applications reserve space are PD_defent and PD_defent_alt. Reserved spaces may be written to with any of the PD_write family of commands.


PD_WRITE

C Binding:   int PD_write(PDBfile *file, char *name,
                          char *type, void *var)
F77 Binding: integer PFWRTA(integer fileid, integer nchr, character name,
                            integer ntype, character type, void space)
SX Binding:  (write-pdbdata file (type dimension) data)
                    (write-pdbdata file pdbdata)
Python Binding:  file.write(name, var, [outtype, ind])

Write data to a PDB file.

If an entry already exists in the file, the data overwrites the specified file data; otherwise, before writing data to the PDB file an entry is prepared for the symbol table consisting of the name, the type, the dimension information, the disk address to which the data will be written, and the total number of bytes as computed with the help of the structure chart. After the entry is installed in the symbol table the data from memory is converted (only if the target machine type is different from the current machine type) and then written out to disk starting at the current disk address.

The primitive data types which the PDBLib system knows about by default are: "short", "integer", "long", "float", "double", and "char" for short integer, integer, long integer, floating point or real number, double precision floating point number, and character or single byte respectively. Additional types may be added using PD_defstr().

PDBLib supports arbitrary levels of indirections. This means that all types of pointers (except function pointers) can be traced down to the actual data to which they point and that data will be written out into the PDB file in such a way that the read operations can reconstruct the data as it exists prior to the write operation. There is one crucial restriction. That is that the memory associated with any pointer must have been allocated using a SCORE memory management function or macro. See the memory management section near the beginning of this document.

Rationale: When writing out scalar variables (i.e. non-dimensioned variables - structured variables are scalars unless specifically dimensioned) this function is the most convenient to use since it involves no variable argument list and hence no worries about terminating the list. Another situation, which is more common than expected, in which PD_write() would be preferred is when it is desirable to make entries in a PDB file which do not correspond to any variables in the application program. Since string manipulations might be involved in preparing the name under which to write the data, coding in the dimensional information is not any less efficient.

Dimensions can be given in two ways. If the default offset value for the PDB file can be taken as the minimum value for the range which a dimension index can legally run, the maximum value may be specified alone. Alternatively, the minimum value, maximum value, and stride (separated by colons) may be specified. The stride is optional and defaults to 1. For example:

    PD_write(file, "u[30,1:10]", "float", u);

    pfwrta(pid, 10, 'u(30,1:10)', 5, 'float', u)
The arguments to PD_write() are:
file - a pointer to a PDBfile which designates the PDB file to which to attempt to write;
fileid - an integer identifier which designates the PDB file to which to write;
nchr - an integer number of characters in the name string;
name - an ASCII string containing the name of the variable to install in the symbol table;
ntype - an integer number of characters in the type string;
type - an ASCII string specifying the variable type;
var - a pointer to the data to be written. This pointer must be consistent with the type specified, that is it must be a pointer to data with type type. For example:

   char **s, **t;
   int *u;

   PD_write(file, "s", "char **", &s);

   PD_write(file, "t(3)", "char *", t);

   PD_write(file, "u(30,1:10)", "integer", u);
The dimension information is encoded in the ASCII string name, as if in a FORTRAN dimension statement.

Note: PDBLib can only write part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When writing part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

The return value is TRUE if successful;
otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

pdbdata is described in the PDB section of: Python Bindings .

Troubleshooting: Rules and Pointers

See also: PD_write_alt and PD_defent .


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float x[20];
           .
           .
           .

     if (!PD_write(file, "x(20)", "float", x))
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfwrta
       integer fileid
       real x(20)
       common /abc/ a(2), b, c(2,2:4)
       real a, b, c
             .
             .
             .

 c ... write array x
       if (pfwrta(fileid, 5, `x(20)', 5, `float', x) .eq. 0)
      &   call errproc
 
 c ... write entire structure abc (previous defined with pfdefs)
       if (pfwrta(fileid, 3, `abc', 3, `abc', a) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (define file (open-pdbfile "foo.pdb" "w"))

; write various kinds of integer variables
    (write-pdbdata file "cn" (type "integer" 10) 1 2 3 4 5 6 7 8 9 10))
    (write-pdbdata file "an" (type "integer *") '(1 2 3 4)))
    (write-pdbdata file "en" (type "integer *" 3) '(-1 -2 -3) '(4 5 6) '(7 8 9)))
    (write-pdbdata file "sn" (type "integer **") '((1 2 3 4 5) (6 7 8 9))))

; create pdbdata objects c, a, s, and e
    (define c (write-pdbdata nil "c" (type "char" 10) "bar"))
    (define a (write-pdbdata nil "a" (type "char *") "foo"))
    (define e (write-pdbdata nil "e" (type "char *" 3) "Foo" () "Bar"))
    (define s (write-pdbdata nil "s" (type "char **") '("Hello" "world")))

; write pdbdata objects c, a, s, and e
    (write-pdbdata file "c" c)
    (write-pdbdata file "a" a)
    (write-pdbdata file "e" e)
    (write-pdbdata file "s" s)
             .
             .
             .

Python Example
    import pact.pdb
             .
             .
             .

    file = pact.pdb.open( "/tmp/foo.pdb", "w" )

# Write various kinds of simple integers directly.
    file.write("prime",  9973, "integer")
    file.write("cn",  [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], "integer")

# Create pdbdata nested integer objects an, en and sn.
    an = pact.pdb.pdbdata( [1, 2, 3, 4], "integer *" )
    en = pact.pdb.pdbdata( [[-1, -2, -3], [4, 5, 6], [7, 8, 9]], "integer *[3]" )
    sn = pact.pdb.pdbdata( [[1, 2, 3, 4, 5], [6, 7, 8, 9]], "integer **" )

# Write pdbdata nested integer objects an, en and sn.
    file.write( "an", an )
    file.write( "en", en )
    file.write( "sn", sn )

# Create pdbdata nested string objects c, a, s, and e.
    c = pact.pdb.pdbdata( "bar", "char[3]" )
    a = pact.pdb.pdbdata( "foo", "char *" )
    e = pact.pdb.pdbdata( [ "Foo", None, "Bar" ], "char *[3]" )
    s = pact.pdb.pdbdata( [ "Hello", "world" ], "char **" )

# Write pdbdata nested string objects c, a, s, and e.
    file.write("c", c)
    file.write("a", a)
    file.write("e", e)
    file.write("s", s)
             .
             .
             .
    file.close()

PD_WRITE_ALT

C Binding:   int PD_write_alt(PDBfile *file, char *name, char *type,
                              void *var, int nd, long *ind)
F77 Binding: integer PFWRTD(integer fileid,
                            integer nchr, character name,
                            integer ntype, character type,
                            void vr, integer nd, integer ind)
SX Binding:  none
Python Binding:  none

Write data to a PDB file. This is an alternate form to PD_write. If an entry already exists in the file, the data overwrites the specified file data; otherwise, before writing data to the PDB file an entry is prepared for the symbol table consisting of the name, the type, the dimension information, the disk address to which the data will be written, and the total number of bytes as computed with the help of the structure chart. After the entry is installed in the symbol table the data from memory is converted (only if the target machine type is different from the current machine type) and then written out to disk starting at the current disk address.

The primitive data types which the PDBLib system knows about by default are: "short", "integer", "long", "float", "double", and "char" for short integer, integer, long integer, floating point or real number, double precision floating point number, and character or single byte respectively. Additional types may be added using PD_defstr.

PDBLib supports arbitrary levels of indirections. This means that, subject to the restrictions spelled out in the section on rules, pointers (except function pointers) can be traced down to the actual data to which they point and that data will be written out into the PDB file in such a way that the read operations can reconstruct the data as it exists prior to the write operation. There is one crucial restriction. That is that the memory associated with any pointer must have been allocated by a SCORE memory management function or macro. See the Memory Management section near the beginning of this document.

The rationale for this function is that in some situations, it is desirable to be able to specify the dimensions without building them into an ASCII string.

The arguments to PD_write_alt are: file, a pointer to a PDBfile which designates the PDB file to which to attempt to write; fileid, an integer identifier which designates the PDB file to which to write; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable to install in the symbol table; ntype, an integer number of characters in the type string; type, an ASCII string specifying the variable type; var, a pointer to the data to be written; nd, then number of dimensions for the variable; and ind, an array of long integers containing (min, max, stride) triples specifying the ranges and strides of the dimensions. The pointer, var, must be consistent with the type specified, that is it must be a pointer to data with type, type. For example:

   char **s, **t;
   int *u;

   PD_write_alt(file, "s", "char **", &s, ...);

   PD_write_alt(file, "t", "char *", t, ...);

   PD_write_alt(file, "u", "integer", u, ...);
Note: PDBLib can only write part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When writing part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

The return value is TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

Troubleshooting: Rules and Pointers


C Example
 #include "pdb.h"
 
     PDBfile *file;
     long ind[6];
     float x[20][5];
           .
           .
           .

     ind[0] = 0L;
     ind[1] = 19L;
     ind[2] = 1L;
     ind[3] = -2L;
     ind[4] = 2L;
     ind[5] = 1L;
     if (!PD_write_alt(file, "x", "float", x, 2, ind))
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfwrtd
       integer fileid, nd, ind(6)
       real c(2,2:4)
             .
             .
             .

 c ... write array c
       nd = 2
       ind(1) = 1
       ind(2) = 2
       ind(3) = 1
       ind(4) = 2
       ind(5) = 4
       ind(6) = 1
       if (pfwrtd(fileid, 1, `c', 5, `float', c, nd, ind) .eq. 0)
      &   call errproc
             .
             .
             .

PD_WRITE_AS

C Binding:   int PD_write_as(PDBfile *file, char *name,
                             char *intype, char *outtype, void *var)
F77 Binding: integer PFWRAS(integer fileid,
                            integer nchr, character name,
                            integer ntypin, character intype,
                            integer ntypout, character outtype, void vr)
SX Binding:  none
SX Python:  none

Write the data pointed to by var under name and with intype in PDB file file as data of outtype.

The rationale for this function is that in some situations, it is desirable to not only convert the formats of data of a specified type, but to convert between types. An example that occurs in practice often enough is converting a 32 bit int to a 32 bit long on a machine which only has a 16 bit int.

Input to PD_write_as is: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file to which to write; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable in the PDB file; ntypin, an integer number of characters in the intype string; intype, an ASCII string containing the type of the variable; ntypout, an integer number of characters in the outtype string; outtype, an ASCII string containing the output type of the variable; and var, a pointer to the location where the data is to be stored in memory.

Note: PDBLib can only write part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When writing part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

PD_write_as returns TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

Troubleshooting: Rules and Pointers

See also: PD_write_as_alt and PD_defent_alt .


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float x[20];
           .
           .
           .
     if (!PD_write_as(file, "x(20)", "float", "double", x))
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfwras
       integer fileid
       real*8 x(20)
             .
             .
             .

 c ... write array x of type double as type float
       if (pfwras(fileid, 5, `x(20)', 6, `double', 
      &                               5, `float', x) .eq. 0)
      &   call errproc
             .
             .
             .

PD_WRITE_AS_ALT

C Binding:   int PD_write_as_alt(PDBfile *file,
                                 char *name, char *intype, char *outtype,
                                 void *var, int nd, long *ind)
F77 Binding: integer PFWRAD(integer fileid,
                            integer nchr, character name,
                            integer ntypin, character intype,
                            integer ntypout, character outtype,
                            void vr, integer nd, integer ind)
SX Binding:  none
Python Binding:  none

Write the data pointed to by var under name and with intype in PDB file file as data of outtype. This is an alternate form of PD_write_as.

The rationale for this function is:
    1) that in some situations, it is desirable to not only convert the formats of data of a specified type, but to convert between types. An example that occurs in practice often enough is converting a 32 bit int to a 32 bit long on a machine which only has a 16 bit int.
    2) that in some situations, it is desirable to be able to specify the dimensions without building them into an ASCII string.

Input to PD_write_as_alt is: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file to which to write; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable in the PDB file; ntypin, an integer number of characters in the intype string; intype, an ASCII string containing the type of the variable; ntypout, an integer number of characters in the outtype string; outtype, an ASCII string containing the output type of the variable; var, a pointer to the location where the data is to be stored in memory; nd, an integer number of dimensions; and ind, an array of long integers specifying the ranges of each dimension (min, max, stride).

Note: PDBLib can only write part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When writing part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

PD_write_as_alt returns TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

Troubleshooting: Rules and Pointers


C Example
 #include "pdb.h"
 
     PDBfile *file;
     long ind[6];
     float x[20][5];
           .
           .
           .

     ind[0] = 0L;
     ind[1] = 19L;
     ind[2] = 1L;
     ind[3] = -2L;
     ind[4] = 2L;
     ind[5] = 1L;
     if (!PD_write_as_alt(file, "x", "float", "double", x, 2, ind))
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfwrad
       integer fileid, nd, ind(6)
       real*8 c(2,2:4)
             .
             .
             .

 c ... write array c of type double as type float
       nd = 2
       ind(1) = 1
       ind(2) = 2
       ind(3) = 1
       ind(4) = 2
       ind(5) = 4
       ind(6) = 1
       if (pfwrad(fileid, 1, `c', 6, `double',
      &                           5, `float', c, nd, ind) .eq. 0)
      &   call errproc
             .
             .
             .

PD_APPEND

C Binding:   int PD_append(PDBfile *file, char *name, void *vr)
F77 Binding: integer pfappa(integer fileid, integer nchr,
                            character name, void vr)
SX Binding:  none
Python Binding:  XXX - none

Append data to an entry in the specified file. The type is taken to be the same as for the original entry. The dimensions of the appended data are specified in name. They must match the original entry except for the most slowly varying one. The specification of the most slowly varying dimension must be one of the following:

   min:max => new dimension is old_min:old_max+(max-min+1)
              if min is the default_offset for the file
or
   min:max => new dimension is old_min:max
              if min is old_max+1

The rationale for this function is that some data sets are of unknown size until they are completely written. PDBLib permits any entry to reside in discontiguous blocks of disk space. The library is responsible for reading and writing data correctly across these blocks.

The shape or dimensional information of the entry is a part of the name string. In this respect PD_append behaves just like PD_write.

Input to this function is: file, a pointer to a PDBfile, fileid, an integer identifier for a PDBfile, nchr, an integer character length for the name argument, name, an ASCII string containing the name of the variable and any dimensional information, and vr, a pointer to the data to be appended.

This function returns TRUE, if successful; otherwise, FALSE and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_append_alt, PD_append_as, PD_append_as_alt, PD_defent, PD_defent_alt, PD_write, PD_write_alt, PD_write_as, and PD_write_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float *fv;
           .
           .
           .

     if (PD_append(file, "x(20)", fv)) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .
Compare this with the example of PD_write.


Fortran Example
       integer pfappa, pfwrta
       integer fileid
       real y(10)
             .
             .
             .

 c ... append to x
       if (pfappa(fileid, 7, `x(1:10)', y) .eq. 0)
      &   call errproc
             .
             .
             .

PD_APPEND_ALT

C Binding:   int PD_append_alt(PDBfile *file, char *name,
                               void *vr, int nd, long *ind)
F77 Binding: integer pfappd(integer fileid,
                            integer nchr, character name,
                            void vr, integer nd, integer ind)
SX Binding:  none
Python Binding:  none

Append data to an entry in the specified file. The type is taken to be the same as for the original entry. The dimensions of the appended data are specified in the ind array. They must match the original entry except for the most slowly varying one. The specification of the most slowly varying dimension must be one of the following:

   min:max => new dimension is old_min:old_max+(max-min+1)
              if min is the default_offset for the file
or
   min:max => new dimension is old_min:max
              if min is old_max+1
The rationale for this function is that some data sets are of unknown size until they are completely written. PDBLib permits any entry to reside in discontiguous blocks of disk space. The library is responsible for reading and writing data correctly across these blocks.

The shape or dimensional information of the entry is specified in nd and ind. In this respect PD_append_alt behaves just like PD_write_alt.

Input to this function is: file, a pointer to a PDBfile; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable; vr, a pointer to the data to be appended; nd, an integer number of dimensions; and ind, an array of longs with triples (start, stop, step) defining dimension information.

This function returns TRUE, if successful; otherwise, FALSE and an ASCII string error message can be retrieved through a call to PD_get_error. For FORTRAN programs an error message may be retrieved by invoking the function PFGERR.

See also: PD_append, PD_append_as, PD_append_as_alt, PD_defent, PD_defent_alt, PD_write, PD_write_alt, PD_write_as, and PD_write_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float *fv;
     long ind[3]
           .
           .
           .

     ind[0] = 0L;
     ind[1] = 20L;
     ind[2] = 1L;
     if (PD_append_alt(file, "x", fv, 1, ind)) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .
Compare this with the example of PD_write_alt.


Fortran Example
      integer pfappd
      integer fileid, ind(3)
      real y(20)
            .
            .
            .

c ... append to x
      ind(1) = 1
      ind(2) = 20
      ind(3) = 1
      if (pfappd(fileid, 1, `x', y, 1, ind) .eq. 0)
     &   call errproc
            .
            .
            .

PD_APPEND_AS

C Binding:   int PD_append_as(PDBfile *file
                              char *name,
                              char *intype,
                              void *vr)
F77 Binding: integer PFAPAS(integer fileid,
                              integer nchr,
                              character name,
                              integer ntype,
                              character intype,
                              void vr)
SX Binding:  none
Python Binding:  none

Append data to an entry in the specified file. The output type is taken to be the same as for the original entry. The dimensions of the appended data are specified in the name. They must match the original entry except for the most slowly varying one. The specification of the most slowly varying dimension must be one of the following:

   min:max => new dimension is old_min:old_max+(max-min+1)
              if min is the default_offset for the file
or
   min:max => new dimension is old_min:max
              if min is old_max+1
The rationale for this function is that some data sets are of unknown size until they are completely written. PDBLib permits any entry to reside in discontiguous blocks of disk space. The library is responsible for reading and writing data correctly across these blocks.

The shape or dimensional information of the entry is a part of the name string. In this respect PD_append_as behaves just like PD_write_as.

Input to this function is: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file to which to write; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable and any dimensional information; ntype, an integer number of characters in the intype string; intype, an ASCII string specifying the type of the data to which vr points; and vr, a pointer to the data to be appended.

This function returns TRUE, if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error. For FORTRAN applications an error message can be retrieved by invoking the function PFGERR.

See also: PD_append, PD_append_alt, PD_append_as_alt, PD_defent, PD_defent_alt, PD_write, PD_write_alt, PD_write_as, and PD_write_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     double *dv;
           .
           .
           .

     if (PD_append_as(file, "x(20)", "double", dv)) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .
Compare this with the example of PD_write_as.


Fortran Example
      integer fileid
      real*8 y(10)
      integer pfapas
            .
            .
            .

c ... append to x
      if (pfapas(fileid, 7, `x(1:10)', 6, `double', y) .eq. 0)
     &   call errproc
            .
            .
            .
Compare this with the example of PFWRAS.


PD_APPEND_AS_ALT

C Binding:   int PD_append_as_alt(PDBfile *file char *name,
                                  char *intype, void *vr,
                                  int nd, long *ind)
F77 Binding: integer PFAPAD(integer fileid,
                            integer nchr, character name,
                            integer ntype, character intype,
                            void vr, integer nd, integer ind)
SX Binding:  none
Python Binding:  none

Append data to an entry in the specified file. The output type is taken to be the same as for the original entry. The dimensions of the appended data are specified in the ind array. They must match the original entry except for the most slowly varying one. The specification of the most slowly varying dimension must be one of the following:

   min:max => new dimension is old_min:old_max+(max-min+1)
              if min is the default_offset for the file
or
   min:max => new dimension is old_min:max
              if min is old_max+1
The rationale for this function is that some data sets are of unknown size until they are completely written. PDBLib permits any entry to reside in discontiguous blocks of disk space. The library is responsible for reading and writing data correctly across these blocks.

The shape or dimensional information of the entry is specified in nd and ind. In this respect PD_append_as_alt behaves just like PD_write_alt.

Input to this function is: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDBfile; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable; ntype, an integer number of characters in the intype string; intype, an ASCII string specifying the type of data to which vr points; vr, a pointer to the data to be appended; nd, an integer number of dimensions; and ind, an array of longs with triples (start, stop, step) defining dimension information.

This function returns TRUE, if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error. For FORTRAN applications an error message can be retrieved by invoking the function PFGERR.

See also: PD_append, PD_append_alt, PD_append_as, PD_defent, PD_defent_alt, PD_write, PD_write_alt, PD_write_as, and PD_write_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float *fv;
     long ind[3]
           .
           .
           .

     ind[0] = 0L;
     ind[1] = 20L;
     ind[2] = 1L;
     if (PD_append_as_alt(file, "x", "float", fv, 1, ind)) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .
Compare this with the example of PD_write_as_alt.


Fortran Example
      character*8 intype
      integer pfapad, pfwrtd
      integer fileid, ntype, nd, ind(3)
      real x(20) 
      real*8 y(10)
            .
            .
            .

c ... append to x
      ind(2) = 10
      if (pfapad(fileid, 1, `x', 6, `double', y, 1, ind) .eq. 0)
     &     call errproc
            .
            .
            .
Compare this with the example of PFWRAD.


Reserving Space for Future Writes

In some applications one knows the size and shape of a variable in advance of having the data to write. PDBLib permits the user to reserve space (including 0 sized space) for a variable and then later write all or parts of it using one or more PD_write calls.

This is different from appending to a variable which PDBLib also supports. See the discussion of the PD_append family of functions.


PD_DEFENT

C Binding:   syment *PD_defent(PDBfile *file,
                               char *name, char *outtype)
F77 Binding: integer PFDEFA(integer fileid,
                            integer nc, char *name,
                            integer nt, char *type)
SX Binding:  none
Python Binding:  none

Define an entry in the symbol table of the PDB file specified by file. This function reserves space on disk but writes no data. The data can be written with later calls to PD_write, PD_write_alt, PD_write_as, or PD_write_as_alt.

The shape or dimensional information of the entry is a part of the name string. In this respect it behaves as PD_write.

The size of the space reserved can be zero. What this means is that a symbol table entry will be setup, but no space on disk will be set aside. In this case the application must use one of the PD_append family of functions instead of one of the PD_write family.

The rationale for this function is to block out space in a PDB file corresponding to some logical layout of a piece of data. The data may not exist at the time the space is reserved or for some reason it may be desirable to write out the data in pieces. In any case if the type and shape of a variable is known at some point, an entry may be made in the PDB file without writing any data. The space may filled with other PDBLib calls at some later time.

Input to this function is: file, a pointer to a PDBfile, fileid, an integer identifier which designates the PDB file in which to define an entry; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable and any dimensional information, and outtype, an ASCII string specifying the type of data in the file.

In the C binding this function returns a symbol table entry (syment) pointer, if successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error. In the FORTRAN binding the return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.

See also: PD_defent_alt, PD_write, PD_write_alt, PD_write_as, and PD_write_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     syment *ep;
           .
           .
           .

     if ((ep = PD_defent(file, "x(20)", "float")) == NULL)
        printf("%s", PD_get_error());
           .
           .
           .
Compare this with the example of PD_write.


Fortran Example

       integer pfdefa
       integer fileid
             .
             .
             .

 c ... define and reserve array x
 c ... declaration for x would be: real x(20)
 
       if (pfdefa(fileid, 5, `x(20)', 5, `float') .eq. 0)
      &   call errproc
             .
             .
             .
Compare this with the example of PFWRTA.


PD_DEFENT_ALT

C Binding:   syment *PD_defent_alt(PDBfile *file, char *name,
                                   char *outtype, int nd, long *ind)
F77 Binding: integer PFDEFD(integer fileid,
                            integer nc, char *name,
                            integer nt, char *outtype,
                            integer nd, integer ind)
SX Binding:  none
Python Binding:  none

Define an entry in the symbol table of the PDB file specified by file. This function reserves space on disk but writes no data. The data can be written with later calls to PD_write, PD_write_alt, PD_write_as, or PD_write_as_alt.

This is an alternate form of PD_defent. The difference is that the dimension information is supplied via the nd and ind arguments instead of being a part of the name string. In this respect it behaves as PD_write_alt does.

The size of the space reserved can be zero. What this means is that a symbol table entry will be setup, but no space on disk will be set aside. In this case the application must use one of the PD_append family of functions instead of one of the PD_write family.

The rationale for this function is to block out space in a PDB file corresponding to some logical layout of a piece of data. The data may not exist at the time the space is reserved or for some reason it may be desirable to write out the data in pieces. In any case if the type and shape of a variable is known at some point, an entry may be made in the PDB file without writing any data. The space may filled with other PDBLib calls at some later time.

Input to this function is: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file in which to define an entry; nchr, an integer number of characters in the name string; name, an ASCII string containing the name of the variable only; ntype, an integer number of characters in the outtype string; outtype, an ASCII string specifying the type of data in the file; nd, an integer specifying the number of dimensions; and ind, an array of long integers containing the minimum and maximum values of the index for each dimension pairwise.

In the C binding this function returns a symbol table entry (syment) pointer, if successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error. In the FORTRAN binding the return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.

See also: PD_defent, PD_write, PD_write_alt, PD_write_as, and PD_write_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     syment *ep;
     long ind[4];
           .
           .
           .

     ind[0] = 0L;
     ind[1] = 19L;
     ind[2] = -2L;
     ind[3] = 2L;
     if ((ep = PD_defent_alt(file, "x", "float", 2, ind)) == NULL)
        printf("%s", PD_get_error());
           .
           .
           .
Compare this with the example of PD_write_alt and note the absence of a two dimensional array in this call.


Fortran Example
       integer pfdefd
       integer fileid, nd, ind(4)
             .
             .
             .

 c ... define and reserve array c
 c ... declaration for c would be: real c(2,2:4)
       nd = 2
       ind(1) = 1
       ind(2) = 2
       ind(3) = 2
       ind(4) = 4
       if (pfdefd(fileid, 1, `c', 5, `float', nd, ind) .eq. 0)
      &   call errproc
             .
             .
             .
Compare with the example for PFWRTD.


Reading Data from PDB Files

Since data in a file has a definite size and shape, the reading operations in PDBLib are somewhat simpler than the writing operation. The PD_read family of operations which is the counterpart of the PD_write family does all of the work in reading data from files.


PD_READ

C Binding:   int PD_read(PDBfile *file, char *name, void *var)
F77 Binding: integer PFREAD(integer fileid,
                            integer nchr, character name, void var)
SX Binding:  (read-pdbdata file name)
Python Binding:  file.read(name)

Read all or part of a data entry from an open PDB file.

The symbol table of the given PDB file is searched for the given name and if it is found the information there is used to read the proper number of bytes from the file, do any conversions, and put the result in memory pointed to by var.

The arguments to PD_read are:
file - a pointer to a PDBfile which designates the PDB file from which to attempt the read;
fileid - an integer identifier which designates the PDB file from which to attempt the read;
nchr - an integer number of characters in the name string;
name - an ASCII string containing the specification of data to be read;
var - a pointer to the location where the data is to be placed.

Note: In each PD_read operation, the type of var must be a pointer to the type of the variable name.

Note: PDBLib can only read part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When reading part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

The return value is the number of items successfully read.
An ASCII string error message can be retrieved through a call to PD_get_error if 0 items were read.

Troubleshooting: Rules and Pointers

pdbdata is described in the PDB section of: Python Bindings .

See also: PD_read_alt, PD_read_as, and PD_read_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float x[20];
           .
           .
           .
     if (PD_read(file, "x", x) == 0)
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfread
       integer fileid
       real x(20)
       common /abc/ a(2), b, c(2,2:4)
       real a, b, c
       common /jkl/ j, k, l
       integer j, k, l
             .
             .
             .

 c ... read array x
       if (pfread(fileid, 1, 'x', x) .eq. 0)
      &   call errproc
 
 c ... read first element of member c of structure abc
       if (pfread(fileid, 10, 'abc.c(1,2)', c) .eq. 0)
      &   call errproc
 
 c ... read entire structure jkl
       if (pfread(fileid, 3, 'jkl', j) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (define file (open-pdbfile "foo.pdb"))
    (define c1 (read-pdbdata file "c"))
    (define a1 (read-pdbdata file "a"))
    (define e1 (read-pdbdata file "e"))
    (define s1 (read-pdbdata file "s"))
             .
             .
             .

Python Example
    import pact.pdb
             .
             .
             .

    file = pact.pdb.open("foo.pdb")
    c1 = file.read("c")
    a1 = file.read("a")
    e1 = file.read("e")
    s1 = file.read("s")
             .
             .
             .

PD_READ_ALT

C Binding:   int PD_read_alt(PDBfile *file, char *name,
                             void *var, long *ind)
F77 Binding: integer PFPTRD(integer fileid,
                            integer nchr, character name,
                            void var, integer ind)
SX Binding:  none
Python Binding:  none

Read all or part of a data entry from an open PDB file. The symbol table of the given PDB file is searched for the given name and if it is found the information there is used to read the proper number of bytes from the file, do any conversions, and put the result in memory pointed to by var.

The arguments to PD_read_alt are: file, a pointer to a PDBfile which designates the PDB file from which to attempt the read; fileid, an integer identifier which designates the PDB file from which to attempt the read; nchr, an integer number of characters in the name string; name, an ASCII string containing the specification of the data to be read; var, a pointer to the location where the data is to be placed; and ind, an array of long integers consisting of three indexes (start, stop, and step) for each dimension of the entry.

Note: In each PD_read_alt operation, the type of var must be a pointer to the type of the variable name.

Note: PDBLib can only read part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When reading part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

The return value is the number of items successfully read. An ASCII string error message can be retrieved through a call to PD_get_error if 0 items were read.

Troubleshooting: Rules and Pointers

See also: PD_read, PD_read_as, and PD_read_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     long ind[3];
     float x[20];
           .
           .
           .

     ind[0] = 3;
     ind[1] = 18;
     ind[2] = 2;
     if (PD_read_alt(file, "x", x, ind) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfptrd
       integer fileid, ind(3)
       real xodd(10)
             .
             .
             .

 c ... read the first 10 odd elements of x into array xodd
       ind(1) = 1
       ind(2) = 20
       ind(3) = 2
       if (pfptrd(fileid, 1, 'x', xodd, ind) .eq. 0)
      &   call errproc
             .
             .
             .

PD_READ_AS

C Binding:   int PD_read_as(PDBfile *file,
                            char *name, char *intype, void *var)
F77 Binding: integer PFRDAS(integer fileid,
                            integer nchr, character name,
                            integer ntype, character intype, void var)
SX Binding:  none.
Python Binding:  none, but see example.

Read data from an open PDB file.

The symbol table of the given PDB file is searched for the given name. If the name is found, the information there is used with the type specified by type to read the proper number of bytes from the file, do any conversions, and put the result in memory pointed to by var. If it is not found, a zero is returned and the error message will indicate "MISSING ENTRY". The type specified overrides the type in the symbol table entry as far as deciding on data conversions goes.

This function is generally used to read floats as doubles and so on. However with sufficient care and understanding of both the file data and C data structuring, it can be used to transmute structured data.

The arguments to PD_read_as are:
file - a pointer to a PDBfile which designates the PDB file from which to attempt the read;
fileid - an integer identifier which designates the PDB file from which to attempt the read;
nchr - an integer number of characters in the name string;
name - an ASCII string containing the specification for the data to be read;
ntype - an integer number of characters in the intype string;
intype - an ASCII string containing the type of the data desired;
var - a pointer to the location where the data is to be placed.

Note: In each PD_read_as operation, the type of var must be a pointer to the type specified by type.

Note: PDBLib can only read part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When reading part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

The return value is the number of items successfully read.
An ASCII string error message can be retrieved through a call to PD_get_error if 0 items were read.

Troubleshooting: Rules and Pointers

See also: PD_read, PD_read_alt, and PD_read_as_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     float x[20];
           
           .
           .

 /* x is a double in the file */
     if (PD_read_as(file, "x", "float", x) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfrdas
       integer fileid
       real*8  xx(20)
       integer ierror
       character*128 errmsg
             .
             .
             .

 c     Read array x into array xx as type double.
       if (pfrdas(fileid, 1, 'x', 6, 'double', xx) .eq. 0) then
           ierror = pfgerr( 128, errmsg )
           print *, errmsg
           call exit ( -1 )
       endif
             .
             .
             .

Python Example
# There is no Python binding for PD_read_as() 
# but it can be faked by using the Python conversion methods
# int(), long(), float() and complex(). 

    import pact.pdb
             .
             .
             .

    file = pact.pdb.open( "foo.pdb", "r" )

# Read the variables as is.
    int1     = file.read( "int0" )
    long1    = file.read( "long0" )
    float1   = file.read( "float0" )
    double1  = file.read( "double0" )

# Coerce them into floats.
    x_int    = float( int1 )
    x_long   = float( long1 )
    x_float  = float( float1 )
    x_double = float( double1 )
             .
             .
             .

PD_READ_AS_ALT

C Binding:   int PD_read_as_alt(PDBfile *file,
                                char *name, char *type,
                                void *var, long *ind)
F77 Binding: integer PFRDAD(integer fileid,
                            integer nchr, character name,
                            integer ntype, character intype,
                            void var, integer ind)
SX Binding:  none
Python Binding:  none

Read all or part of a data entry from an open PDB file. The symbol table of the given PDB file is searched for the given name and if it is found the information there is used with the type specified by type to read the proper number of bytes from the file, do any conversions, and put the result in memory pointed to by var. The type specified overrides the type in the symbol table entry as far as deciding on data conversions goes.

This function is generally used to read floats as doubles and so on. However with sufficient care and understanding of both the file data and C data structuring, it can be used to transmute structured data.

The arguments to PD_read_as_alt are: file, a pointer to a PDBfile which designates the PDB file from which to attempt the read; fileid, an integer identifier which designates the PDB file from which to attempt the read; nchr, an integer number of characters in the name string; name, an ASCII string containing the specification of the data to be read; type, an ASCII string containing the type of the data desired; var, a pointer to the location where the data is to be placed; and ind, an array of long integers consisting of three indexes (start, stop, and step) for each dimension of the entry.

Note: In each PD_read_as_alt operation, the type of var must be a pointer to the type specified by type.

Note: PDBLib can only read part of an entry if the type of the terminal node is primitive or a structure which contains no indirections and whose descendant members contain no indirections.

Note: When reading part of a variable, especially a structured variable, the path to the desired part must contain one array reference for each level of indirection traversed.

The return value is the number of items successfully read. An ASCII string error message can be retrieved through a call to PD_get_error if 0 items were read.

Troubleshooting: Rules and Pointers

See also: PD_read, PD_read_as, and PD_read_alt.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     long ind[3];
     float x[20];
           .
           .
           .

 /* x is a double in the file */
     ind[0] = 2;
     ind[1] = 10;
     ind[2] = 2;
     if (PD_read_as_alt(file, "x", "float", x, ind) == FALSE)
        printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfrdad
       integer fileid, ind(3)
       real*8 xdd(10)
             .
             .
             .

 c ... read the first 10 elements of float x into array xdd 
 c ... as type double
       ind(1) = 1
       ind(2) = 10
       ind(3) = 1
       if (pfrdad(fileid, 1, 'x', 6, `double', xdd, ind) .eq. 0)
      &   call errproc
             .
             .
             .

Defining New Data Types

To aid application developers in using structured data PDBLib lets applications define new data types in a PDBfile. New data types may either be derived from other existing data types or they may be primitive (integer types, floating point types, or byte sequences). To define derived types applications should use PD_defstr or PD_defstr_alt. To define primitive types use PD_defix, PD_defloat, or PD_defncv.

Since PDBLib supports pointered data types, it is often the case that a pointer in a derived type may point to data of any kind. In C, casts are used to control this behavior. PDBLib permits a member of a struct which is of type "char *" specify the actual type of another pointered member. The function PD_cast is used to set up this behavior.


PD_CAST

C Binding:   int PD_cast(PDBfile *file, char *type,
                         char *memb, char *contr)
F77 Binding: none
SX Binding:  (make-cast file type memb contr)
Python Binding:  XXX - missing

Dynamically change the type of a structure member. PDBLib supports an extended data typing mechanism called a structure. A structure is a set of declarations of members. Each member is in turn a data type known to the system. In some applications, a structure member is used to point to data of a type which is specified by another member. In the C coding a cast is used to obtain a pointer to the desired data type.

PDBLib supports this same practice by allowing the programmer to override the type of a member as given in the structure definition (see PD_defstr) by supplying the name of a member, whose type must be "char *", which will contain an ASCII string specifying the actual type of the data to which the first member points.

The arguments to PD_cast are: file, a pointer to a PDBfile; type, an ASCII string containing the name of the data structure type in the PDB file; memb, an ASCII string containing the name of the member whose type is to be overridden; and contr, an ASCII string containing the name of the member (whose type must be "char *") which will provide the actual type for memb.

The return value is a TRUE if the cast is successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    struct sample
       {char *type;
        int *a;};
          .
          .
          .

     PD_defstr(file, "sample", "char *type", "int *a", LAST);
     PD_cast(file, "sample", "a", "type");
          .
          .
          .

SX Example
          .
          .
          .

    (make-cast file "sample" "char *type" "int *a")
          .
          .
          .

PD_DEFIX

C Binding:   defstr *PD_defix(PDBfile *file, char *name,
                              long bytespitem, int align, int flg)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Define a primitive integral type (fixed point type) in the PDB file specified by file.

Input to PD_defix is: file, a pointer to a PDBfile; name, an ASCII string containing the name of the new data type; bytespitem, the number of bytes required for 1 item of the new type; align, the byte alignment for the type; and flg, a flag indicating whether the byte ordering of the type is normal or reverse ordered.

PDBLib supplies two #define'd constants which define the two ordering schemes used for fixed point types: NORMAL_ORDER and REVERSE_ORDER. NORMAL_ORDER means that the byte ordering from lowest to highest address as occurs on most CPU's. REVERSE_ORDER means that the byte order goes from highest to lowest address as happens with INTEL and other CPU's.

Compare this information with that found in the discussion of data conversion later in this manual.

A pointer to the new type's defstr is returned if the call is successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    defstr *ptr;
           .
           .
           .

     ptr = PD_defix(file, "int40", 5, 1, NORMAL_ORDER);
           .
           .
           .

PD_DEFLOAT

C Binding:   defstr *PD_defloat(PDBfile *file, char *name,
                                long bytespitem, int align, int *ordr,
                                long expb, long mantb, long sbs, long sbe,
                                long sbm, long hmb, long bias)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Define a new floating point type to the PDB file specified by file.

Input to PD_defloat is: file, a pointer to a PDBfile; name, an ASCII string containing the name of the variable in the PDB file; bytespitem, the number of bytes required for an item of the new type; align, the byte alignment for this type; ordr, an array of bytespitem integers specifying the byte order; expb, the number of exponent bits; mantb, the number of mantissa bits; sbs, the position of the sign bit; sbe, the starting bit of the exponent; sbm, the starting bit of the mantissa; hmb, the value of the high order mantissa bit; and bias, the bias of the exponent.

Compare this information with that found in the discussion of data conversion later in this manual.

A pointer to the new type's defstr is returned if the call is successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
 int ord_int24[] = {1, 3, 2};
 
    PDBfile *file;
    defstr *ptr;
           .
           .
           .

     ptr = PD_defloat(file, "fp24", 3, 1, ord_int24,
                      7L, 16L, 0L, 1L, 8L, 0L, 0x3F)
           .
           .
           .

PD_DEFNCV

C Binding:   defstr *PD_defncv(PDBfile *file, char *name,
                               long bytespitem, int align)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Define a primitive type that will not undergo format conversion from platform to platform in the PDB file specified by file. Certain data types commonly defined in C programs are used as flags or character holders. With such data types the actual bit pattern contains the meaningful information. This information would be lost under a data conversion operation. This function provides users with a means to define primitive types which will not be converted under any circumstances and therefore preserve the meaningful bit patterns which constitute the intended data.

Input to PD_defncv is: file, a pointer to a PDBfile; name, an ASCII string containing the name of the new data type; bytespitem, the number of bytes required for 1 item of the new type; and align, the byte alignment for the type.

Compare this information with that found in the discussion of data conversion later in this manual.

A pointer to the new type's defstr is returned if the call is successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    defstr *ptr;
           .
           .
           .
 /* define a type like the FORTRAN character*8 */
     ptr = PD_defncv(file, "char_8", 8, 1);
           .
           .
           .

PD_DEFSTR

C Binding:   defstr *PD_defstr(PDBfile *file,
                               char *name,
                               char *mem1, ..., memn,
                               int *LAST)
F77 Binding: integer PFDEFS(integer fileid,
                            integer nchr,
                            character name,
                            integer ncm1, character mem1,
                                  ...,
                            integer ncmn, character memn,
                            integer LAST)
SX Binding:  (make-defstr name mem1 ... memn)
             (make-defstr* name mem1 ... memn)
Python Binding:  pact.pdb.defstr(name, (mem1, ..., memn), file=vif)
                 file.defstr(name, (mem1, ..., memn))

Define a data structure for a PDB file. As a matter of programming efficiency and clarity it is useful to be able to refer to more complex structural units than the primitive types: short integers, integers, long integers, floating point numbers, double precision floating point numbers, and characters. Arrays do this in a very simple-minded way. Many modern languages support extended types or structures which allow the programmer to group diverse types of data together in a very sophisticated way.

PDBLib supports an extended data typing mechanism called a structure. A structure is a set of declarations of members. Each member is in turn a data type known to the system. Much of the style and usage of structures comes from the C struct. Note: for FORTRAN versions which do not define any kind of pointer (e.g. ANSI FORTRAN 77) structures defined with this function should not contain pointered members. Because of the memory management features upon which PDBLib now depends, even members whose types are pointers are allowed. The only restrictions on member types are that they not be function pointers and that they be expressible without parentheses. Again any member which is a pointer must have its memory allocated by a SCORE memory management function or macro. See the Memory Management section near the beginning of this manual.

PD_defstr defines structures to the PDB system so that they can be read and written as a whole in a single statement. The members of the structure are processed and an entry in the structure chart is made. Then subsequent references to the new structure type are processed using information from the structure chart. The syntax by which members of a structure are specified is like that for C structs. The formal definition is given below ([ ] enclose optional elements). Self-referential structures are allowed providing the reference is through pointers (like C). The actual type name is used in the reference since PDBLib checks that all member types are already known or are the type being defined.

    <;member>         := <;type> [*...*]<;member name>[(<;dimensions>)]
    <;type>           := <;primitive type> | <;derived type>
    <;member name>    := an ASCII string representing the name of the member
    <;primitive type> := short | integer | long | float | double | char
    <;derived type>   := any PD_defstr'd type
    <;dimensions>     := <;integer> |
                        <;integer : integer> |
                        <;integer>, <;dimensions> |
                        <;integer : integer> <;dimensions>

Dimensions can be given in two ways. If the default offset value for the PDB file can be taken as the minimum value for the range which a dimension index can legally run, the maximum value may be specified alone. Alternatively, the minimum value followed by a colon and the maximum value may be specified. For example,

    integer a(30,1:10)

The arguments to PD_defstr are: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file to which to write; nchr, the integer number of characters in the name string; name, an ASCII string containing the name of the data structure type in the PDB file; and memi, a list of ASCII strings each representing the declaration of a member of a structure are defined above. LAST must terminate the list of members.

In the C binding the return value is a pointer to the entry made in the structure chart if the call is successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error. In the FORTRAN binding the return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    defstr *ptr;
    struct sample
       {float x[20];
        float y[20];
        int number;};
           .
           .
           .

     ptr = PD_defstr(file, "sample", "float x(20)", "float y(20)",
                           "int number", LAST);
           .
           .
           .

Fortran Example
       parameter(LAST = 0)
       integer pfdefs
       integer fileid
       common /abc/ j, a(2), b, c(2,2:4)
       real a, b, c
       integer j
             .
             .
             .

       if (pfdefs(fileid,
      &           3,  'abc',
      &           9,  'integer j',
      &           10, 'float a(2)',
      &           7,  'float b',
      &           14, 'float c(2,2:4)',
      &           LAST) .eq. 0)
      &     call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (make-defstr* file "abc" (def-member integer i)
                             (def-member char c 10) 
                             (def-member integer *i1)
                             (def-member char *a)
                             (def-member char **s)
                             (def-member float f))
             .
             .
             .

Python Example
             .
             .
             .


    file.make_defstr("abc", ['integer i',
                             'char c(10)',
                             'integer *i1',
                             'char *a',
                             'char **s',
                             'float f])
             .
             .
             .

PD_DEFSTR_ALT

C Binding:   defstr *PD_defstr_alt(PDBfile *file,
                                   char *name,
                                   int nmemb,
                                   char **members)
F77 Binding: integer PFDEFT(integer fileid,
                            integer nchr,
                            character name,
                            integer nmemb,
                            integer nc(2*nm),
                            character *memb)
SX Binding:  none
Python Binding:  none

Define a data structure for a PDB file. As a matter of programming efficiency and clarity it is useful to be able to refer to more complex structural units than the primitive types: short integers, integers, long integers, floating point numbers, double precision floating point numbers, and characters. Arrays do this in a very simple-minded way. Many modern languages support extended types or structures which allow the programmer to group diverse types of data together in a very sophisticated way.

PDBLib supports an extended data typing mechanism called a structure. A structure is a set of declarations of members. Each member is in turn a data type known to the system. Much of the style and usage of structures comes from the C struct. Because of the memory management features upon which PDBLib now depends, even members whose types are pointers are allowed. The only restrictions on member types are that they not be function pointers and that they be expressible without parentheses. Again any member which is a pointer must have its memory allocated by a SCORE memory management function or macro. See the Memory Management section near the beginning of this manual.

PD_defstr defines structures to the PDB system so that they can be read and written as a whole in a single statement. The members of the structure are processed and an entry in the structure chart is made. Then subsequent references to the new structure type are processed using information from the structure chart. The syntax by which members of a structure are specified is like that for C structs. The formal definition is given below ([ ] enclose optional elements). Self-referential structures are allowed providing the reference is through pointers (like C). The actual type name is used in the reference since PDBLib checks that all member types are already known or are the type being defined.

    <;member>         := <;type> [*...*]<;member name>[(<;dimensions>)]
    <;type>           := <;primitive type> | <;derived type>
    <;member name>    := an ASCII string representing the name of the member
    <;primitive type> := short | integer | long | float | double | char
    <;derived type>   := any PD_defstr'd type
    <;dimensions>     := <;integer> |
                        <;integer : integer> |
                        <;integer>, <;dimensions> |
                        <;integer : integer> <;dimensions>

Dimensions can be given in two ways. If the default offset value for the PDB file can be taken as the minimum value for the range which a dimension index can legally run, the maximum value may be specified alone. Alternatively, the minimum value followed by a colon and the maximum value may be specified. For example,

    integer a(30,1:10)

The arguments to PD_defstr are: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file to which to write; nchr, the integer number of characters in the name string; name, an ASCII string containing the name of the data structure type in the PDB file; nmemb, an integer number of strings in the members array; nc, an array of integer pairs specifying the 0 based offset into the memb array and the number of characters for each member; members, an array of ASCII strings each representing the declaration of a member of a structure are defined above; and memb, an array of characters containing the member specifications.

In the C binding the return value is a pointer to the entry made in the structure chart if the call is successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error. In the FORTRAN binding the return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    defstr *ptr;
    char **members;
    struct sample
       {float x[20];
        float y[20];
        int number;};
           .
           .
           .

     members = MAKE_N(char *, 3);
     members[0] = SC_strsave("float x[20]");
     members[1] = SC_strsave("float y[20]");
     members[2] = SC_strsave("integer number");
     ptr = PD_defstr_alt(file, "sample", 3, members);
 
     SFREE(members[0]);
     SFREE(members[1]);
     SFREE(members[3]);
     SFREE(members);
           .
           .
           .
Compare with the example for PD_defstr.


Fortran Example
       integer pfdeft
       integer fileid, nc(6)
       character*8 nm(4)
       common /abc/ a(2), b, c(2,2:4)
             .
             .
             .

       nc(1) = 0
       nc(2) = 10
       nc(3) = 10
       nc(4) = 7
       nc(5) = 17
       nc(6) = 14
       nm(1) = `float a('
       nm(2) = `2)float '
       nm(3) = `bfloat c'
       nm(4) = `(2,2:4) '
       if (pfdeft(fileid, 3, `abc', 3, nc, nm) .eq. 0)
      &    call errproc
             .
             .
             .
Compare with the example for PFDEFS.


PD_TYPEDEF

C Binding:   defstr *PD_typedef(PDBfile *file, char *oname, char *tname)
F77 Binding: none
SX Binding:  (make-typedef file oname tname)
Python Binding:  XXX - missing

Define a an alternate name for an existing type. The intended use of this function is to allow users to make their PDB data types match their C types as closely as possible. It does this by mimicking the C typedef mechanism in a limited way. More accurately it provides an aliasing capability. This can be used in conjunction with either PD_defix or PD_defloat to install a definition of a data type in the host chart (PD_defix and PD_defloat define their types to the file chart only).

Input to PD_typedef is: file, a pointer to a PDBfile; oname, an ASCII string containing the name of the original data type; tname, an ASCII string containing the name of the alias.

A pointer to the original type's defstr is returned if the call is successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    defstr *ptr;
           .
           .
           .

 /* define "enum" as an alias for "integer" */
     ptr = PD_typedef(file, "integer", "enum");
           .
           .
           .

SX Example
           .
           .
           .

    (make-typedef file "integer" "enum")
           .
           .
           .

Defining Attributes

PDBLib supports a general mechanism for managing a class of data which is variously referred to as attributes or meta data. In a great many cases, the careful design of data structures obviates the need for this kind of data. Nevertheless, PDBLib supplies four functions to manage attributive data: PD_def_attribute, PD_rem_attribute, PD_get_attribute, PD_set_attribute.


PD_DEF_ATTRIBUTE

C Binding:   int PD_def_attribute(PDBfile *file, char *attr, char *type)
F77 Binding: integer PFDATT(integer fileid,
                            integer na, char *attr,
                            integer nt, char *type)
SX Binding:  (def-attribute file name type)
Python Binding:  XXX - missing

Define an attribute to the given PDB file. The model of an attribute in PDBLib is an entity that has a name and type. The two supported operations on attributes are to create them and to remove them. An entity in a PDB file can be assigned an attribute value simply by making a call which specifies the entity name, the attribute name, and the attribute value (which is determined by the type). The only association between an entry in a PDB file and any attribute is made by the name in the attribute table and the entry in the symbol table. In particular, this mechanism allows the application developer to define and use entities in a PDB file solely in terms of attributes.

The arguments to this function are: file, a pointer to a PDBfile; na, an integer number of characters in the attr string; attr, an ASCII string containing the name of the attribute being defined; nt, an integer number of characters in the type string; and type, an ASCII string containing the name of the data type in the PDB file.

The return value is TRUE, if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error. FORTRAN programs may retrieve an error message by invoking the function PFGERR.

See also: PD_rem_attribute, PD_set_attribute, and PD_get_attribute.


C Example
 #include "pdb.h"
 
    PDBfile *file;
            .
            .
            .

     if (PD_def_attribute(file, "date", "char *") == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfdatt
       integer fileid
             .
             .
             .

       if (pfdatt(fileid, 4, `date', 6, `char *') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (def-attribute file "date" "char *")
             .
             .
             .

PD_GET_ATTRIBUTE

C Binding:   void *PD_get_attribute(PDBfile *file,
                                    char *vr, char *attr)
F77 Binding: integer PFGVAT(integer fileid,
                            integer nv, char *vr,
                            integer na char *attr,
                            void value)
SX Binding:  (get-attribute-value file vr attr)
Python Binding:  XXX - missing

Return the value of the specified attribute for the named entity.

The model of an attribute in PDBLib is an entity that has a name and type. The two supported operations on attributes are to create them and to remove them. An entity in a PDB file can be assigned an attribute value simply by calling PD_set_attribute. The only association between an entry in a PDB file and any attribute is made by the name in the attribute table and the entry in the symbol table. In particular, this mechanism allows the application developer to define and use entities in a PDB file solely in terms of attributes.

Attribute values are always assigned by reference and PD_get_attribute returns them the same way. The application may have to make a cast on the returned pointer.

The arguments to this function are: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file from which to get the attribute; nv, an integer number of characters in the var string; vr, an ASCII string containing the name of an entity in the PDB file; na, an integer number of characters in the attr string; attr, an ASCII string containing the name of the attribute being sought; and value, into which the attribute value will be copied.

The return value is a pointer to the value of the attribute if one exists; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_def_attribute, PD_rem_attribute, and PD_set_attribute.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    char *dt;
            .
            .
            .

     dt = (char *) PD_get_attribute(file, "foo", "date");
     if (dt == NULL)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfgvat
       integer fileid
       character*8 dt(10)
             .
             .
             .

       if (pfgvat(fileid, 3, `foo', 4, `date', dt) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
            .
            .
            .

    (define dt (get-attribute-value file "foo" "date"))
            .
            .
            .

PD_REM_ATTRIBUTE

C Binding:   int PD_rem_attribute(PDBfile *file, char *attr)
F77 Binding: integer PFRATT(integer fileid, integer na, char *attr)
SX Binding:  (rem-attribute file attr)
Python Binding:  XXX - missing

Remove the specified attribute. Any entities which have a value for this attribute will have it removed by PDBLib.

The model of an attribute in PDBLib is an entity that has a name and type. The two supported operations on attributes are to create them and to remove them. An entity in a PDB file can be assigned an attribute value simply by calling PD_set_attribute. The only association between an entry in a PDB file and any attribute is made by the name in the attribute table and the entry in the symbol table. In particular, this mechanism allows the application developer to define and use entities in a PDB file solely in terms of attributes.

The arguments to this function are: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file from which to remove the attribute; na, an integer number of characters in the attr string; and attr, an ASCII string containing the name of the attribute being removed.

The return value is TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_def_attribute, PD_get_attribute, and PD_set_attribute.


C Example
 #include "pdb.h"
 
    PDBfile *file;
            .
            .
            .

     if (PD_rem_attribute(file, "date") == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfratt
       integer fileid
             .
             .
             .

       if (pfratt(fileid, 4, `date') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
            .
            .
            .

    (rem-attribute file "date")
            .
            .
            .

PD_SET_ATTRIBUTE

C Binding:   int PD_set_attribute(PDBfile *file,
                                  char *vr, char *attr, void *vl)
F77 Binding: integer PFSVAT(integer fileid,
                            integer nv, char *vr,
                            integer na char *attr, void vl)
SX Binding:  (set-attribute-value! file vr attr vl)
Python Binding:  XXX - missing

Set the value of the specified attribute for the named entity. Attribute values are always assigned by reference.

The model of an attribute in PDBLib is an entity that has a name and type. The two supported operations on attributes are to create them and to remove them. An entity in a PDB file can be assigned an attribute value simply by calling PD_set_attribute. The only association between an entry in a PDB file and any attribute is made by the name in the attribute table and the entry in the symbol table. In particular, this mechanism allows the application developer to define and use entities in a PDB file solely in terms of attributes.

The arguments to this function are: file, a pointer to a PDBfile; fileid, an integer identifier which designates the PDB file in which the attribute is being set; nv, an integer number of characters in the var string; vr, an ASCII string containing the name of an entity in the PDB file; na, an integer number of characters in the attr string; attr, an ASCII string containing the name of the attribute being set; and vl, a pointer to data whose type matches the attribute type.

The return value is TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_def_attribute, PD_rem_attribute, and PD_get_attribute.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    char *dt;
            .
            .
            .

     dt = SC_strsave("Mon March 23, 1921");
     if (PD_set_attribute(file, "foo", "date", dt) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfsvat
       integer scftcs
       integer fileid
       character*80 dt
             .
             .
             .

       scftcs(dt, `Mon March 27, 1921', 18)
       if (pfsvat(fileid, 3, `foo', 4, `date', dt) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

       (set-attribute-value! file "foo" "date" "Mon 3/27/21")
             .
             .
             .

Queries


PD_GET_BUFFER_SIZE

C Binding:   int PD_get_buffer_size
F77 Binding: integer PFGBFS()
SX Binding:  (pd-get-buffer-size)
Python Binding:  XXX - missing

Get the current buffer size which PDBLib uses for all PDB files and return it.

This function has no arguments.

Return the current buffer size in bytes, if previously set; otherwise, return -1.


C Example
       int sz;
             .
             .
             .

       sz = PD_get_buffer_size;
             .
             .
             .

Fortran Example
       integer pfgbfs
       integer nb
             .
             .
             .

       nb = pfgbfs()
       if (nb .eq. -1)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

       (define sz (pd-get-buffer-size))
             .
             .
             .

PD_GET_ERROR

C Binding:   char *PD_get_error(void)
F77 Binding: integer PFGERR(integer nchr, character err)
SX Binding:  (pd-error-message)
Python Binding:  XXX - missing

Get the current PDBLib error message. Return the length of the error message in nchr and the actual message in err. The space for err should be 255 characters long.

The arguments to this function are: nchr, the length of the error message; and err, an ASCII string into which the message is copied.

In the C binding this function returns a pointer to the error message. In the FORTRAN binding this function returns 1 if successful, 0 otherwise.


C Example
       char *err;
             .
             .
             .

       err = PD_get_error();
             .
             .
             .

Fortran Example
       integer pfgerr
       integer ierr
       character*128 err
             .
             .
             .

       ierr = pfgerr(128, err)
             .
             .
             .

SX Example
             .
             .
             .

       (define err (pd-error-message))
             .
             .
             .

PD_GET_FILE_LENGTH

C Binding:   off_t PD_get_file_length(PDBfile *file)
F77 Binding: integer PFGFLN(integer fileid,
                            integer len)
SX Binding:  
Python Binding:  XXX - missing

Return the length of the specified PDB file.

The arguments to PFGFLN are: file, PDBfile designating the desired file; len, the integer byte length of the PDB file in question.

In the C binding returns the byte length of the file. In the FORTRAN binding return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.


C Example
       PDBfile *file;
       off_t ln;
             .
             .
             .

       ln = PD_get_file_length(file);
             .
             .
             .

Fortran Example
       integer pfgfln
       integer fileid, ln
             .
             .
             .

       if (pfgfln(fileid, ln) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

        none currently
             .
             .
             .

PD_GET_FILE_NAME

C Binding:   char *PD_get_file_name(PDBfile *file)
F77 Binding: integer PFGFNM(integer fileid,
                            integer nchr, character name)
SX Binding:  (file-info file "name")
Python Binding:  file.name

Return the name of the specified PDB file. The nchr argument contains the length of the buffer on input and the length of the file name on output. If the buffer is not long enough, the length of the file name is returned in nchr and a value of 0 is returned.

The arguments to PFGFNM are: file, PDBfile designating the desired file; fileid, an integer identifier which designates the PDB file in question; nchr, on input an integer number of characters in the name string, on output the length of the actual file name string; name, an ASCII string which will contain the file name upon successful completion.

In the C binding returns the name of the file. In the FORTRAN binding return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.


C Example
       PDBfile *file;
       char *nm;
             .
             .
             .

       nm = PD_get_file_name(file);
             .
             .
             .

Fortran Example
       integer pfgfnm
       integer fileid, nc
       character*32 name
             .
             .
             .

       nc = len(name)
       if (pfgfnm(fileid, nc, name) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (define name (file-info file "name"))
             .
             .
             .

Python Example
             .
             .
             .

    name = file.name
             .
             .
             .

PD_GET_MAJOR_ORDER

C Binding:   int PD_get_major_order(PDBfile *file)
F77 Binding: integer PFGMJO(integer fileid, integer val)
SX Binding:  (file-info file "major-order")
Python Binding:  file.major_order

Get the major order for PDB file fileid to v. The major order refers to the order of data in multidimensional arrays. See the discussion of this topic in the section PDBLib and Index Ordering.

Input to this function is: fileid, an integer PDBfile identification number.

Output from this function is: val, an integer major order.

In the FORTRAN API TRUE is returned if successful and FALSE otherwise.


C Example
       PDBfile *file;
       int mjo;
             .
             .
             .

       mjo = PD_get_major_order(file);
             .
             .
             .

Fortran Example
       integer pfgmjo
       integer mjo, fileid
             .
             .
             .

       mjo = pfgmjo(fileid)
             .
             .
             .

SX Example
             .
             .
             .

    (define mjo (file-info file "major-order"))
             .
             .
             .

PD_GET_MAX_FILE_SIZE

C Binding:   int PD_get_max_file_size(PDBfile *file)
F77 Binding: integer PFGMXS(integer fileid)
SX Binding:  (file-info file "maximum-size")
Python Binding:  XXX - missing

Get the current maximum file size of PDB file fileid in bytes.

The arguments to this function are: fileid, an integer PDBfile identification number.

Return the integer value of the current maximum file size.


C Example
       PDBfile *file;
             .
             .
             .

       sz = PD_get_max_file_size(file);
             .
             .
             .

Fortran Example
       integer pfgmxs
       integer sz, fileid
             .
             .
             .

       sz = pfgmxs(fileid)
             .
             .
             .

SX Example
             .
             .
             .

    (define size (file-info file "maximum-size"))
             .
             .
             .

Python Example
             .
             .
             .

    size = file.maximum_size
             .
             .
             .

PD_GET_MODE

C Binding:   int PD_get_mode(PDBfile *file)
F77 Binding: integer PFGMOD(integer fileid)
SX Binding:  (file-info file "mode")
Python Binding:  file.mode

Get the current mode of PDB file fileid: 2 (append - 'a'), 3 (open - 'r'), 4 (create - 'w').

The arguments to this function are: fileid, an integer PDBfile identification number.

Return the integer value of the current mode.


C Example
       PDBfile *file;
       int md;
             .
             .
             .

       md = PD_get_mode(file);
             .
             .
             .

Fortran Example
       integer pfgmod
       integer md, fileid
             .
             .
             .

       md = pfgmod(fileid)
             .
             .
             .

SX Example
             .
             .
             .

    (define mode (file-info file "mode"))
             .
             .
             .

Python Example
             .
             .
             .

    mode = file.mode
             .
             .
             .

PD_GET_OFFSET

C Binding:   int PD_get_offset(PDBfile *file)
F77 Binding: integer PFGOFF(integer fileid)
SX Binding:  (file-info file "default-offset")
Python Binding:  file.default_offset

Get the current default offset for PDB file fileid. See the discussion in PDBLib and Index Offsets for more details.

The arguments to this function are: fileid, an integer PDBfile identification number.

Return the integer value of the default offset.


C Example
       PDBfile *file;
       int off;
             .
             .
             .

       off = PD_get_offset(file);
             .
             .
             .

Fortran Example
       integer pfgoff
       integer off, fileid
             .
             .
             .

       off = pfgoff(fileid)
             .
             .
             .

SX Example
             .
             .
             .

    (define offs (file-info file "default-offset"))
             .
             .
             .

Python Example
             .
             .
             .

    offs = file.default_offset
             .
             .
             .

PD_query_entry

C Binding:   syment *PD_query_entry(PDBfile *file, char *name, char *fullname)
F77 Binding: none
SX Binding:  (read-syment file name)
Python Binding:  XXX - 

Inquire about variable name in the specified PDB file. This lookup can be done with an absolute path or relative to the current directory (in the specified PDB file).

Input to this function is:
file - a pointer to a PDBfile;
name - an ASCII string containing the path to the variable (absolute or relative to the current directory);
fullname - a character string which will hold the full path to the variable upon output (use NULL if not desired).

Output from this function is:
In the C binding, return a pointer to a syment (a symbol table entry structure) if successful;
otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.
fullname will contain the full path to this variable.


C Example
       PDBfile  *file;                      /* PDB file pointer */
       char     *path;                      /* the name of the variable */
       char     fullpath[MAXLINE];          /* full path to the variable */
       syment   *ep;                        /* symbol table entry pointer */
       long     size;                       /* no. of elements in variable */
       dimdes   *dims;                      /* array of dims; (max,min) pairs */
       char     *type;                      /* variable type in ASCII */
       long     addr;                       /* address of variable */
             .
             .
             .

       path = "abc";
       ep = PD_query_entry(file, path, fullpath);
       if (ep == NULL)
           printf("%s", PD_get_error());
       else
          {printf( "fullpath (output) = %s\n", fullpath );
           size = PD_entry_number(ep);
           dims = PD_entry_dimensions(ep);
           type = PD_entry_type(ep);
           addr = PD_entry_address(ep);}
             .
             .
             .  
       ep = PD_query_entry(file, "./xyz", fullpath);
       ep = PD_query_entry(file, "/top_dir/docs/xyz_doc", NULL);

SX Example
             .
             .
             .

     (define ep (read-syment file "abc"))

; el will contain (type dimensions number address)
     (define el (pdb->list ep))
             .
             .
             .

PD_get_entry_info

C Binding:   int PD_get_entry_info(syment *ep, char **type, long *size,
                                   int *ndims, long **dims)
F77 Binding: integer PFIVAR(integer fileid,
                            integer nchr, character name,
                            integer ntype, character type,
                            integer size, integer ndims, integer dims)
SX Binding:  none
Python Binding:  none

Extract the descriptive information about a variable. In the C binding, a symbol table entry (possibly obtained by PD_query_entry ) is the input. However, in the FORTRAN binding the name is used.

The C binding deals in dynamically allocated spaces which must be freed by a call to PD_free_entry_info.

Input to this function is:
ep - a symbol table entry;
fileid - an integer PDBfile identification number;
nchr - the number of characters in name;
name - an ASCII string containing the name of the variable.

The function returns 1 if successful, 0 otherwise and an ASCII string error message can be retrieved through a call to PD_get_error.

Output from this function is:
ntype - the number of characters in type;
type - an ASCII string containing the type of the variable;
size - the number of elements in the variable;
ndims - the number of dimensions which the variable has;
dims - an array of the dimensions given as (min, max) pairs.


C Example
       PDBfile  *file;
       char     path[MAXLINE];
       syment   *ep;
       char     *type;
       long     ni;
       int      nd;
       long     *dims;
       int      rv;
       int      ii;
             .
             .
             .

       ep = PD_query_entry(file, "abc", path);
       rv = PD_get_entry_info(ep, &type, &ni, &nd, &dims);
       if (!rv)
          printf("%s", PD_get_error());
       else 
          {printf("Variable type:  %s\n", type);
           printf("Number of elements:  %ld\n", ni);
           printf("Number of dimensions:  %d\n", nd);
           for ( ii = 0; ii < nd; ii++ )
               printf("    Dimension:  %ld:%ld\n", dims[2*ii], dims[2*ii+1]);
             .
             .
             .

           PD_free_entry_info(type, dims);}


Fortran Example
       integer pfivar
       integer fileid, sz, al, ind
             .
             .
             .

       if (pfivar(fileid, 3, `abc', 5 `float',
      &           sz, nd, dims) .eq. 0)
      &   call errproc
             .
             .
             .

PD_free_entry_info

C Binding:   void PD_free_entry_info(char *type, long *dims)
F77 Binding:  XXX - missing
SX Binding:  XXX - missing
Python Binding:  XXX - missing

Deallocate the space pointed to by type and dims, previously allocated by a successful call to PD_get_entry_info.

See PD_get_entry_info for examples.


PD_INQUIRE_TYPE

C Binding:   defstr *PD_inquire_type(PDBfile *file, char *type)
              defstr *PD_inquire_host_type(PDBfile *file, char *type)
F77 Binding: integer PFITYP(integer fileid,
                            integer ntype, character type,
                            void size, integer align, integer ind)
SX Binding:  (read-defstr file type)
Python Binding:  XXX - missing

Inquire about type type in the specified PDB file. PD_inquire_type and PFITYP do the lookup in the file chart in order to give information about data in the file rather than the host chart which would give information about the data type in the hardware on which the application is running. Instead PD_inquire_host_type does the lookup in the host chart to give information about the data type in the hardware on which the application is running.

The input for this function is: file, a PDBfile; fileid, an integer PDBfile identification number; ntype, the number of characters in type; type, an ASCII string containing the name of the type.

In the C binding return a pointer to a defstr which contains the description of the data type. In the FORTRAN binding return 1 if successful, 0 otherwise.

In the FORTRAN binding output for this function is: size, the number of bytes necessary to represent the type; align, the alignment of type in bytes; ind, the number of members which are pointers if type is a derived type.


C Example
       PDBfile *file;
       long sz;
       int al, ind;
       memdes *md;
             .
             .
             .

       dp = PD_inquire_type(file, "float");
       if (dp != NULL)
          {sz  = dp->size;
           al  = dp->alignment;
           ind = dp->n_indirects;
           md  = dp->members;};
             .
             .
             .

Fortran Example
       integer pfityp
       integer fileid, sz, al, ind
             .
             .
             .

       if (pfityp(fileid, 5, `float', sz, al, ind) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

     (define dp (read-defstr file "float"))

; dl will contain (type size members)
     (define dl (pdb->list dp))
             .
             .
             .

PFIMBR

C Binding:   none
F77 Binding: integer PFIMBR(integer fileid, integer ntype, char *type,
                            integer n, integer size, char *space)
SX Binding:  none

Inquire about the nth member of the type type in PDB file fileid. Return the description of the member in the character buffer, space. On input size is the number of characters in the buffer space. If the member description requires more space, size is set to the number of bytes required and 0 is returned.

Input to this function is: fileid, an integer PDBfile identification number; ntype, the number of characters in type; type, an ASCII string containing the name of the type; n, an integer specifying the member; size, an integer character size of the space buffer; and space, an character buffer to hold the member description.

Output from this function is: size, the number of characters in the member description; and space, the member description.

The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.

See also: PD_defstr and PD_defstr_alt .


Fortran Example
       integer pfimbr
       integer fileid
       character*8 type(10), desc(10), bdesc(100)
             .
             .
             .

       size = 80
       if (pfimbr(fileid, 3, `foo', 4, size, desc) .eq. 0) then
          if (size .le. 800) then
             if (pfimbr(fileid, 3, `foo', 4, size, bdesc) .eq. 0) then
      &         call errproc
             endif
          endif
       endif
             .
             .
             .

Using Pointers

The ability to use pointers with PDBLib is very powerful. It is unfortunate perhaps that it can also be a little bit tricky. Application developers should be aware of a key issue when using pointers with PDBLib. In general, when you want to write a data tree, you want to faithfully reproduce the connectivity of the tree. That means that if many pointers refer to the same chunk of memory then the file will exhibit that same pattern. To do this, PDBLib remembers the pointers that it has written and if handed a pointer that it has already written it does NOT write that memory into the file again. It instead makes note of the connection to an already existing region of disk. These same considerations apply to reading with the requisite changes in sense.

The difference between files and memory is that data trees may be created, destroyed, and pointers recycled. For instance, an application may wish to allocate an array, write it as an indirect, change it contents in memory, and write it out again under another name. This is a very common pattern of usage. If PDBLib remembers the pointers, only the first write will put any data on disk. Now PDBLib has no way of knowing what the application wants.

By default PDBLib tracks pointers in order to preserve connectivity patterns in data trees. Applications can exert two kinds of control over the default behavior. First, they can turn off the pointer tracking on a per file basis. Second, they can tell PDBLib to remove or reset its lists of remembered pointers (again on a per file basis).


PD_GET_TRACK_POINTERS

C Binding:   void PD_get_track_pointers(PDBfile *file)
F77 Binding: integer PFGTPT(integer fileid)
SX Binding:  (file-info file "track-pointers")
Python Binding:  XXX - missing

Get the track pointer flag for PDB file fileid. If the track pointer flag is set to FALSE, PDBLib will not record pointers and disk addresses as described above. This obviates the need for calls to PD_reset_ptr_list.

Input to this function is: fileid, an integer PDBfile identification number,

Return the value of the flag.


C Example
       PDBfile *file;
       int fl;
             .
             .
             .

       fl = PD_get_track_pointers(file);
             .
             .
             .

Fortran Example
       integer pfgtpt
       integer fileid, fl
             .
             .
             .

       fl = pfgtpt(fileid)
             .
             .
             .

SX Example
             .
             .
             .

    (define trk (file-info file "track-pointers"))
             .
             .
             .

PD_SET_TRACK_POINTERS

C Binding:   void PD_set_track_pointers(PDBfile *file, int v)
F77 Binding: integer PFSTPT(integer fileid, integer v)
SX Binding:  (set-track-pointers! file v)
Python Binding:  XXX - missing

Set the track pointer flag for PDB file fileid to v. If the track pointer flag is set to FALSE, PDBLib will not record pointers and disk addresses as described above. This obviates the need for calls to PD_reset_ptr_list.

Input to this function is: fileid, an integer PDBfile identification number,

Output from this function is: v, an integer value for the track pointer flag.

In the C binding return the value of the flag. In the FORTRAN binding return 1 if successful, 0 otherwise.


C Example
       PDBfile *file;
             .
             .
             .

       PD_set_track_pointers(file, TRUE);
             .
             .
             .

Fortran Example
       integer pfstpt
       integer fileid
             .
             .
             .

       if (pfstpt(fileid, 1) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (set-track-pointers! file #t)
             .
             .
             .

PD_RESET_PTR_LIST

C Binding:   int PD_reset_ptr_list(PDBfile *file)
F77 Binding: integer PFRSPL(integer fileid)
SX Binding:  (reset-pointer-list! file)
Python Binding:  XXX - missing

Free the list of pointers which the PDB file file knows about. This includes both pointers in memory acquired during write operations and pointers in the file acquired during read operations.

Rationale: When reading or writing indirectly referenced data, PDBLib, maintains an array of pointers encountered in write operations and an array of pointers encountered in read operations. This is done on a per file basis. These arrays are the basis on which PDBLIb can determine how to preserve the connectivity of data trees when they are moved between memory and files. Because of the difference between memory and disk files, it is important for applications to be able to clear out these arrays and start over. See the discussion on Using Pointers earlier in the manual.

The argument to this function is: file a pointer to a PDBfile.

The return value is TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
            .
            .
            .

     if (PD_reset_ptr_list(file) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pfrspl
       integer fileid
             .
             .
             .

       if (pfrspl(fileid) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (reset-pointer-list! file)
             .
             .
             .

PD_FREE

C Binding:   int PD_free(PDBfile *file, char *type, void *var)
F77 Binding: integer PFREE(integer fileid,
                            integer nchr, character type, void var)
SX Binding: 
Python Binding: 

Free memory which was allocated by PDBLib when reading pointers.

Rationale: When reading a variable from a file which has pointers, PDBLib allocates space to hold the actual data. When it comes time to release the memory, the application could walk the data tree which was read by PDBLib for the variable and free any dynamically allocated spaces. PDBLib is also capable of doing this since it understands the structure of the data. Consequently, this function has been included as a convenience for application developers. See the discussion on Using Pointers earlier in the manual.

The argument to this function is: file a pointer to a PDBfile. type the type of the data pointed to by var. var a variable previously read by PDBLib.

The return value is TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    foo vr;
            .
            .
            .

     if (PD_write(file, "bar", "foo", &vr) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

     if (PD_read(file, "bar", &vr) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

     if (PD_free(file, "foo", &vr) == FALSE)
        printf("%s", PD_get_error());
            .
            .
            .

Fortran Example
       integer pffree
       integer fileid
             .
             .
             .

 c ... read array x
       if (pfread(fileid, 3, 'bar', a) .eq. 0)
      &   call errproc
             .
             .
             .

 c ... free array x
       if (pffree(fileid, 3, 'foo', a) .eq. 0)
      &   call errproc
             .
             .
             .

Using Directories


PD_CD

C Binding:   int PD_cd(PDBfile *file, char *dir)
F77 Binding: integer PFCD(integer fileid,
                          integer nchr, char *dir)
SX Binding:  (change-directory file dir)
Python Binding:  file.cd(dir)

Change the current directory in the specified PDB file.

PDBLib supports an optional hierarchical directory structure inside PDB files. A directory or a variable in a directory may be specified by either a relative path or an absolute path. Slashes separate nodes in a path name. Absolute paths begin with a slash. Nodes consisting of two periods, "..", refer to the next higher level directory.

The arguments to PD_cd are:
file - a pointer to a PDBfile;
fileid - an integer file identifier;
nchr - an integer number of characters in string dir;
dir - an ASCII string containing the path name of the directory to change to.

If dir is NULL or an empty string or a slash, it refers to the top level or root directory.

The return value is TRUE if successful;
otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_ln, PD_ls, PD_mkdir, and PD_pwd.


C Example
 #include "pdb.h"
 
    PDBfile *file;
          .
          .
          .

     if (PD_cd(file, "") == FALSE)
        printf("%s", PD_get_error());
     if (PD_cd(file, "/animals/mammals") == FALSE)
        printf("%s", PD_get_error());
          .
          .
          .

     if (PD_cd(file, "../reptiles") == FALSE)
        printf("%s", PD_get_error());
          .
          .
          .

     if (PD_cd(file, NULL) == FALSE)
        printf("%s", PD_get_error());

Fortran Example
       integer pfcd
       integer fileid
             .
             .
             .

       if (pfcd(fileid, 16, `/animals/mammals') .eq. 0)
      &   call errproc
             .
             .
             .

       if (pfcd(fileid, 11, `../reptiles') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (change-directory file "/animals/mammals")
             .
             .
             .

Python Example
             .
             .
             .

    file.cd( None )
    file.cd( "/animals/mammals" )
             .
             .
             .

    file.cd( "../reptiles" )
             .
             .
             .

    file.cd( "/" )

PD_LN

C Binding:   int PD_ln(PDBfile *file,
                       char *var, char *link)
F77 Binding: integer PFLN(integer fileid,
                          integer nvar, char *var,
                          integer nlink, char *link)
SX Binding:  (create-link file var link)
Python Binding:  file.ln(var, link)

Create a link to a variable in the specified PDB file.

PDBLib supports an optional hierarchical directory structure inside PDB files. A directory or a variable in a directory may be specified by either a relative path or an absolute path. Slashes separate nodes in a path name. Absolute paths begin with a slash. Nodes consisting of two periods, "..", refer to the next higher level directory.

The arguments to PD_ln are: file, a pointer to a PDBfile; fileid, an integer file identifier; nvar, an integer number of characters in string var; var, an ASCII string containing the path name of an existing variable; nlink, an integer number of characters in string link; and link, an ASCII string containing the path name of the new link.

The return value is a TRUE if successful; otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_cd, PD_ls, PD_mkdir, and PD_pwd.


C Example
 #include "pdb.h"
 
    PDBfile *file;
          .
          .
          .

     if (PD_ln(file, "/animals/mammals/chimpanzee", "/chimp") == FALSE)
        printf("%s", PD_get_error());
          .
          .
          .

Fortran Example
       integer pfln
       integer fileid
             .
             .
             .

       if (pfln(fileid, 27, `/animals/mammals/chimpanzee',
      &                  6, `/chimp') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (create-link file "/animals/mammals/chimpanzee" "/chimp")
             .
             .
             .

Python Example
             .
             .
             .

    file.ln("/animals/mammals/chimpanzee", "/chimp")
             .
             .
             .

PD_LS

C Binding:   char **PD_ls(PDBfile *file,
                          char *path, char *type, int *num)
F77 Binding: integer PFLST(integer fileid,
                           integer npath, char *path,
                           integer ntype, char *type, integer num)
             integer PFGLS(integer n,
                           integer nchr, char *name)
             integer PFDLS()
SX Binding:  (list-variables file path type)
Python Binding:  file.ls()

Return a list of names of entries (variables and directories) in PDB file file that are of type type and that are in the directory and match the variable name pattern specified by path.

In FORTRAN applications use PFLST to generate an internal table of names of entries (variables and/or directories) in a PDB file that are of a specified type and that are in the directory and match the variable name pattern specified. Then use PFGLS to get the name of the nth entry in the internal table generated by PFLST. Once done with the list use PFDLS to release the internal table.

PDBLib supports an optional hierarchical directory structure inside PDB files. A directory or a variable in a directory may be specified by either a relative path or an absolute path. Slashes separate nodes in a path name. Absolute paths begin with a slash. Nodes consisting of two periods, "..", refer to the next higher level directory.

The arguments to PD_ls are: file, a pointer to a PDBfile; fileid, an integer file identifier; npath, an integer number of characters in string path; path, an ASCII string containing the path name of the directory to search and/or the variable name pattern to match; ntype, an integer number of characters in string type; type, an ASCII string containing the type of entries to return; and num, a pointer to an integer to contain the number of entries returned.

The arguments to PFGLS are: n, an integer ordinal index into the internal table; nchr, an integer to contain the number of characters returned in string name; and name, an ASCII string to contain the returned entry name.

If path is NULL, the contents of the current directory are listed. If type is NULL, all types are returned.

PFGLS copies the name of a symbol table entry into the name, if successful. The application must ensure that name is large enough to contain the longest name in the symbol table (although PDBLib permits names of arbitrary length, 256 characters would probably be more than enough).

The terminal node of path may contain meta characters "*" and "?". Each "*" matches any zero or more characters and each "?" matches any single character.

For the sake of efficiency, the returned names are not duplicated. That is, the caller should not free the space associated with each of the individual strings, but should free the char ** pointer. This should be done using the SFREE macro as shown in the example.

The return value is a pointer to an array of strings, if successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_cd, PD_ln, PD_mkdir, and PD_pwd.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    char **list;
    int num;
          .
          .
          .

 /* get a list of all directories in the current directory */
     list = PD_ls(file, NULL, "Directory", &num);
     if (list == NULL)
        printf("%s", PD_get_error());
          .
          .
          .

     SFREE(list);
          .
          .
          .

 /* get a list of the variables of type char * in directory animals */
     list = PD_ls(file, "animals", "char *", &num);
     if (list == NULL)
        printf("%s", PD_get_error());
          .
          .
          .

     SFREE(list);
          .
          .
          .

Fortran Example
       integer pflst, pfgls, pfdls
       integer fileid
       integer i, nvar, nchr
       character name(256)
             .
             .
             .

 c ... generate a table of all directories in the current directory
       if (pflst(fileid, 0, `', 9, `Directory', nvar) .eq. 0)
      &   call errproc

 c ... get the elements
       do 100 i = 1, nvar
          if (pfgls(i, nchr, name) .eq. 0)
      &      call errproc
             .
             .
             .

   100 continue

 c ... free the table
       if (pfdls() .eq. 0)
      &   call errproc

             .
             .
             .

 c ... generate a table of the variables of type char * in directory animals
       if (pflst(fileid, 7, `animals', 6, `char *', nvar) .eq. 0)
      &     call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (define vars (list-variables file "/animals"))
             .
             .
             .

Python Example
             .
             .
             .

    vars = file.ls("/animals")
             .
             .
             .

PFVART

C Binding:   none
F77 Binding: integer PFVART(integer fileid,
                            integer order, integer nvars)
                  integer PFGVAR(integer n, integer nchar, character name)
                  integer PFDVAR()
SX Binding:  none
Python Binding:  none

PFVART generates an internal table of variables in the specified PDB file. With subsequent calls to PFGVAR, each entry can be obtained one at a time by ordinal index. The table is sorted according to a specified scheme. The current choices are alphabetic and by disk address.

PFGVAR gets the name of the nth variable in the internal table generated by a previous call to PFVART. The table will have been sorted in a particular order and this function allows applications to access the variables in the sorted order, not the default hash ordering that would normally apply.

PFGVAR copies the name into the array name, if successful. The application must ensure that name is large enough to contain the longest name in the symbol table (although PDBLib permits names of arbitrary length, 256 characters would probably be more than enough).

Use PFDVAR to release the table created by PFVART.

Rationale: these functions are similar the PD_ls functions. The difference being in the ability to select the ordering criterion. The PD_lst functions sort solely by alphabetical order. It has no counterpart in the C or SX interface because those languages provide other means of accomplishing this capability.

The arguments to PFVART are: fileid, an integer which identifies the PDBfile; order, an integer specifying the sort ordering; and nvars, an integer in which the number of variables in the file is returned.

The choices for order are: 1, for an alphabetic sort; and 2, for a disk address order sort.

The arguments to PFGVAR are: n, an integer ordinal index into the internal sorted name table; nchr, an integer in which the number of characters in the name string is returned; name, an ASCII string which will contain the variable name upon successful completion.

The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.


Fortran Example
       integer pfvart, pfgvar, pfdvar
       integer i, n, nvar, nchar
       character vname(256)
       integer fileid, nvar, order
             .
             .
             .

 c ... create table of variable names in alphabetic order
       order = 1
       if (pfvart(fileid, order, nvar) .eq. 0)
      $   call errproc

 c ... print out the table of variable names created by pfvart
       write(6,700)
  700  format(/,'Alphabetic list of variables:')
       do 701 n = 1, nvar
          if (pfgvar(n, nchar, vname) .eq. 0)
      &        call errproc
          write(6,702) (vname(i), i=1,nchar)
  702     format('            ',256a1)
  701  continue

c ... release the table now
       if (pfdvar() .eq. 0)
      &   call errproc
             .
             .
             .

PD_MKDIR

C Binding:   int PD_mkdir(PDBfile *file, char *dir)
F77 Binding: integer PFMKDR(integer fileid, integer nchr, char *dir)
SX Binding:  (make-directory file dir flag)
Python Binding:  file.mkdir(dir)

Create a new directory in the specified PDB file.

PDBLib supports an optional hierarchical directory structure inside PDB files. A directory or a variable in a directory may be specified by either a relative path or an absolute path. Slashes separate nodes in a path name. Absolute paths begin with a slash. Nodes consisting of two periods, "..", refer to the next higher level directory.

The arguments to PD_mkdir are:
file - a pointer to a PDBfile;
fileid - an integer file identifier;
nchr - an integer number of characters in string dir;
dir - an ASCII string containing the path name of the new directory;
flag - if TRUE report an error if the directory cannot be created.

The root directory, "/", does not have to be created.

The return value is TRUE if successful;
otherwise, FALSE is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_cd, PD_ln, PD_ls, and PD_pwd.


C Example
 #include "pdb.h"
 
    PDBfile *file;
          .
          .
          .

     if (PD_mkdir(file, "/animals/mammals") == FALSE)
        printf("%s", PD_get_error());
          .
          .
          .

Fortran Example
       integer pfmkdr
       integer fileid
             .
             .
             .

       if (pfmkdr(fileid, 16, `/animals/mammals') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (make-directory file "/animals/mammals")
             .
             .
             .

Python Example
             .
             .
             .

    file.mkdir("/animals/mammals")
             .
             .
             .

PD_PWD

C Binding:   char *PD_pwd(PDBfile *file)
F77 Binding: integer PFPWD(integer fileid, integer nchr, char *dir)
SX Binding:  (current-directory file)
Python Binding:  file.pwd()

Return the current directory for the specified PDB file.

PDBLib supports an optional hierarchical directory structure inside PDB files. A directory or a variable in a directory may be specified by either a relative path or an absolute path. Slashes separate nodes in a path name. Absolute paths begin with a slash. Nodes consisting of two periods, "..", refer to the next higher level directory.

The arguments to PD_pwd are: file, a pointer to a PDBfile; fileid, an integer file identifier; nchr, an integer to contain the number of characters returned in string dir; and dir, an ASCII string to contain the path name of the current directory.

If no directory has been created, "/" is returned. In the FORTRAN binding this function copies the path name of a directory into the dir, if successful. The application must ensure that dir is large enough to contain the longest directory name (although PDBLib permits names of arbitrary length, 256 characters would probably be more than enough).

The return value is a pointer to a string containing the path name of the current directory if successful; otherwise, NULL is returned and an ASCII string error message can be retrieved through a call to PD_get_error.

See also: PD_cd, PD_ln, PD_ls, and PD_mkdir.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    char *dir;
          .
          .
          .

     if ((dir = PD_pwd(file)) == NULL)
        printf("%s", PD_get_error());
          .
          .
          .

Fortran Example
       integer pfpwd
       integer fileid, nchr
       character dir(256)
             .
             .
             .

       if (pfpwd(fileid, nchr, dir) .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (define dir (current-directory file))
             .
             .
             .

Python Example
             .
             .
             .

    dir = file.pwd()
             .
             .
             .

PD_ISDIR

C Binding:   int PD_isdir(PDBfile *file, char *dir)
F77 Binding: integer PFISDR(integer fileid, integer nchr, char *dir)
SX Binding:  (file-directory? file dir)
Python Binding:  file.isdir(dir)

Return TRUE if the specified path is a directory in the specified PDB file.

PDBLib supports an optional hierarchical directory structure inside PDB files. A directory or a variable in a directory may be specified by either a relative path or an absolute path. Slashes separate nodes in a path name. Absolute paths begin with a slash. Nodes consisting of two periods, "..", refer to the next higher level directory.

The arguments to PD_isdir are:
file - a pointer to a PDBfile;
fileid - an integer file identifier;
nchr - an integer number of characters in string dir;
dir - an ASCII string containing the path name of the new directory;

The return value is TRUE if successful;
otherwise, FALSE is returned.

See also: PD_mkdir, PD_cd, PD_ln, PD_ls, and PD_pwd.


C Example
 #include "pdb.h"
 
    PDBfile *file;
          .
          .
          .

     if (PD_isdir(file, "/animals/mammals") == FALSE)
        printf("%s", PD_get_error());
          .
          .
          .

Fortran Example
       integer pfmkdr
       integer fileid
             .
             .
             .

       if (pfisdr(fileid, 16, `/animals/mammals') .eq. 0)
      &   call errproc
             .
             .
             .

SX Example
             .
             .
             .

    (if (file-directory? file "/animals/mammals")
        (printf nil "/animals/mammals is a directory\n")
             .
             .
             .

Python Example
             .
             .
             .

    ok = file.isdir("/animals/mammals")
             .
             .
             .

Parallel Programming with PDB

PDBLib supports parallel programming on SMP systems using Pthreads or Sprocs and on distributed memory systems using MPI.

Parallel Programming on SMP Systems

When using the thread-safe version of PDBLib the application program must call the library's initialization routine, PD_init_threads, before making any other PDBLib calls. This routine will initialize PDB and SCORE thread specific data structures. With the exception of this one additional initialization call, PDBLib can be used similarly in threaded and serial programs. In multi-threaded applications care must be taken to make sure a file is opened before any read or write calls are issued. Applications must also be careful not to issue PD_close or PD_flush calls while other threads are actively reading or writing.

The thread-safe version of PDBLib can be used by applications to read or write the same file in parallel, or to operate on different files simultaneously. Reading and writing the same file in parallel is, of course, a risky thing to do.

Parallel Programming on Distributed Memory Systems

Applications using this distributed memory library must initialize the library for MPI by calling the routine, PD_init_mpi, before making any other PDBLib calls. This routine will initialize PDB and SCORE for MPI and will initialize the parallel file manager on the specified processor. After all other PDBLib activity is finished, applications must call the termination routine, PD_term_mpi, which will perform library clean-up, including terminating the parallel file manager.

In addition to the special initialization and termination routines, applications performing distributed parallel I/O must use the special MPI versions of the library open and create calls, PD_mp_open and PD_mp_create, in place of PD_open and PD_create when multiple processes will perform I/O to a common file. These routines have an additional argument, an intra-communicator. All participating processes must make the open or create calls, since the MPI-IO functions which provide the low-level I/O define these as collective operations. Each participating process will block on these calls until all processes have made the call. Care must be taken to avoid deadlock when utilizing these collective operations.

Other PDBLib routines that are collective operations include PD_flush, PD_close, and PD_defent. Each of these require that all participating processes make the call before any continue. PDBLib applications that make frequent calls to PD_flush when running in serial mode must examine their flush logic carefully to avoid deadlock when converting to MPI systems. Additionally, PD_flush is an expensive operation in parallel, so should be minimized in any case.

For applications that utilize "distributed arrays", that is, arrays that are decomposed across processes, it is possible to write these to a single array in the PDB file. The PD_defent routine is used to lay out the space in the file that will contain the whole array. The size must be known and specified in the PD_defent call. Subsequent calls to PD_write allow each process to contribute its piece of the distributed array to the file. Remember that since PD_defent is a collective call it must be made by each process and will be a synchronization point in the code.

On systems where threadsafe MPI libraries are available, such as the IBM systems, PDBlib calls to read and/or write can occur asynchronously (i.e. the calls will not block until all processes have made them). On other systems, such as the Compaqs and most others, the lack of threadsafe MPI implementations make it necessary for applications to run in "lock-step", and have all participating processes make the calls before proceeding. This is because on systems with threadsafe MPI PDBlib spawns a thread where the parallel file manager runs. On systems without threadsafe MPI the process designated as the master process in the initialization call will service the parallel file manager requests from other participating processes before returning from PDBlib calls to read or write.


PD_INIT_THREADS

C Binding:   int PD_init_threads(int np, void (*tid)(int *))
F77 Binding: integer PFINTH(integer np, external tid)
SX Binding:  none
Python Binding:  none

Initialize a set of threads for an SMP parallel application. A function, tid, may be supplied to identify the current thread in a parallel execution region. It takes a single integer pointer argument which is used to return a thread index between 0 and np-1. If tid is NULL the built in SCORE function will be used. In this way PDBLib will be able to know which thread it is working on when it is being used in a parallel execution sequence.

PDBLib can be safely used in threaded programs. PD_init_threads should be called before any other PDBLib calls are made so that the thread related PDB and SCORE data structures are properly initialized. Applications which use a thread pool to achieve their parallelism can safely pass a NULL value for the tid argument. The built in SCORE function for returning a thread index is designed to work in such situations. Applications that repeatedly create and destroy threads during the course of a run should provide a function that always sets its argument to a value between 0 and np-1.

The arguments to this function are: np, the number of threads to initialize; and tid, a function which identifies the current thread.

The return value is TRUE if successful; otherwise, FALSE is returned.


C Example
 #include "pdb.h"
 
    int np;
            .
            .
            .

     if (!PD_init_threads(np, NULL))
        printf("Couldn't initialize threads\n");
            .
            .
            .

Fortran Example
       integer pfinth
       integer np
             .
             .
             .

       if (pfinth(np, 0) .eq. 0)
      &   call errproc
             .
             .
             .

PD_INIT_MPI

C Binding:   int PD_init_mpi(int masterproc, int nthreads, void (*tid)(int *))
F77 Binding: integer PFINMP(integer masterproc, integer nthreads, external tid)

Initialize PDBLib for MPI use. The first argument, masterproc, should be the rank of the process that will spawn a control thread. For the current implementation nthreads and tid should be set to 1 and NULL, respectively. Future implementations will allow threads and MPI to coexist in the application.

The call to PD_init_mpi should precede any other PDBLib calls in the application.

The arguments to this function are: masterproc, the rank of the process where the control thread should run; nthreads, the number of threads the application will use (to be implemented, use 1 for now); and tid, a function which identifies the current thread (to be implemented).

The return value is TRUE if successful; otherwise, FALSE is returned.


C Example
 #include "pdb.h"
 
    int masterproc;
    int nthreads = 1;
            .
            .
            .

     if (!PD_init_mpi(masterproc, nthreads, NULL))
        printf("Couldn't initialize PDBLib for MPI\n");
            .
            .
            .

Fortran Example
       integer pfinmp
       integer masterproc, nthreads,
             .
             .
             .

       if (pfinmp(masterproc, nthreads, 0) .eq. 0)
      &   call errproc
             .
             .
             .

PD_TERM_MPI

C Binding:   void PD_term_mpi()
F77 Binding: integer PFTMMP()

Perform any clean-up operations necessary and terminate PDBLib in an MPI application. This call will terminate the PDBLib control thread and perform any other necessary activities when the application is finished using the library. No further PDBLib calls should be made after this call.

The arguments to this function are: none

There is no return value.


C Example
 #include "pdb.h"
 
            .
            .
            .

     PD_term_mpi();
            .
            .
            .

Fortran Example
             .
             .
             .

       call pftmmp()       
             .
             .
             .

PD_MP_OPEN

C Binding:   PDBfile *PD_mp_open(char *filename, char *mode, MPI_Comm comm)
F77 Binding: integer PFMPOP(integer nchr, character name, character mode, integer comm)

Open an existing PDB file in MP parallel mode. With the exception of the additional argument comm, the semantics of this call are identical to those of PD_open. The comm argument should be an MPI communicator which specifies the group of participating processes. The communicator must include the process where the control thread runs in the current implementation. This call is a collective call, therefore every participating process must make the call before any can proceed.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    MPI_Comm comm;
           .
           .
           .

    if ((file = PD_mp_open("filename", "r", comm)) == NULL)
       printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfmpop
       integer fileid
       integer comm
             .
             .
             .

       fileid = pfmpop(8, 'file.pdb', 'r', comm)
       if (fileid .eq. 0)
      &   call errproc
             .
             .
             .

PD_MP_CREATE

C Binding:   PDBfile *PD_mp_create(char *filename, SC_communicator *comm)

Create a PDB file in MP parallel mode. With the exception of the additional argument comm, the semantics of this call are identical to those of PD_create. The comm argument should be an MPI communicator which specifies the group of participating processes. The communicator must include the process where the control thread runs in the current implementation. This call is a collective call, therefore every participating process must make the call before any can proceed.


C Example
 #include "pdb.h"
 
    PDBfile *file;
    SC_communicator comm;
           .
           .
           .

    if ((file = PD_mp_open("filename", "r", comm)) == NULL)
       printf("%s", PD_get_error());
           .
           .
           .

Fortran Example
       integer pfmpop
       integer fileid
       integer comm
             .
             .
             .

       fileid = pfmpop(8, 'file.pdb', 'r', comm)
       if (fileid .eq. 0)
      &   call errproc
             .
             .
             .

Special Purpose I/O

PDBLib is frequently used in connection with visualization of scientific data. To facilitate this four special data structures have special functions dedicated to gathering and writing of this kind of data. The structures are: a curve, a set, a mapping, and an image. The latter three have representations in C structs in various parts of PACT.

If an application produces 1d data sets, writing curves into files would be the general intent. The PACT utility ULTRA can carry out analysis and visualization of such data.

If an application produces multi-dimensional data sets, writing mappings into files would the natural thing to do. Mappings include 1d datasets although they are represented differently than curves. The PACT utility PDBView can do analysis and visualization operations with such data.


PD_PUT_IMAGE

C Binding:   int PD_put_image(PDBfile *file, PD_image *image,
                              int index)
F77 Binding: integer PFWIMA(integer fileid,
                            integer nchr, character name,
                            integer pkn, integer pkx,
                            integer pln, integer plx,
                            real*8 data,
                            real*8 pxn, real*8 pxx,
                            real*8 pyn, real*8 pyx,
                            integer pim)
SX Binding:  none
Python Binding:  none

Build a PD_image structure out of the given input data and write it to a PDB file.

Rationale: The PD_image structure is a useful and general purpose representation of a raster image. The nature of the generalization is that the values in the raster are floating point numbers. So in addition to the standard data sets that can be rasterized, the PD_image can be used to display the computational matrix of some system of equations, for example. This function is a convenient way for FORTRAN programs to put out their data into PDB files as PD_image's for later visualization and processing by other programs. It allows a rectangular subset of a two dimensional array to be specified for the PD_image.

The calling application must keep track of how many PM_image's have been written to each file. PDBLib will write each PM_image under the name composed of the string, `Image', and the integer pim. For example if pim is 9, the PM_image will be written under the name `Image9'. If the application passes the same value for pim more than once only the last one will survive in the symbol table even though the data for each PM_image will persist in the file!

The arguments to PFWIMA are: file, PDBfile for writing; image, PD_image for writing; ind, integer index count; fileid, an integer identifier which designates the PDB file to which to attempt to write; nchr, an integer number of characters in name; name, an ASCII string containing the name of the image; pkn, the integer minimum column index of the data array; pkx, the integer maximum column index of the data array; pln, the integer minimum row index of the data array; plx, the integer maximum row index of the data array; data, an array of real*8 values containing the image data; pxn, a real*8 value specifying the minimum column index in image; pxx, a real*8 value specifying the maximum column index in image; pyn, a real*8 value specifying the minimum row index in image; pyx, a real*8 value specifying the maximum row index in image; and pim, a counter specifying the number of the image being written out.

The return value is 1, if successful; otherwise, 0 is returned and an ASCII string error message can be retrieved through a call to PD_get_error. For FORTRAN programs an error message may be retrieved by invoking function PFGERR.


C Example
       PDBfile *file;
       PD_image *image;
       static int count = 0;
             .
             .
             .

       if (!PD_put_image(file, image, count++))
          printf("%s", PD_get_error());
             .
             .
             .

Fortran Example
       integer pfwima
       integer fileid, k, l
 c ... these arguments to pfwima must have 8 byte element size
       double precision xmin, xmax, ymin, ymax, data(0:10,0:10)
             .
             .
             .

       xmin = 0.0
       xmax = 10.0
       ymin = 0.0
       ymax = 10.0
       do 100 l = 0, 10
          do 101 k = 0, 10
             data(k, l) = (k - 5)**2 + (l - 5)**2
  101     continue
  100  continue
 
       if (pfwima(fileid, 10, 'Test image', 0, 10, 0, 10,
      &           data, xmin, xmax, ymin, ymax, 1) .eq. 0)
      &   call errproc
             .
             .
             .

PD_PUT_MAPPING

C Binding:   int PD_put_mapping(PDBfile *file,
                                PM_mapping *mapping, int index)
F77 Binding: integer PFWMAP(integer fileid,
                            character dname, integer dp, real*8 dm,
                            character rname, integer rp, real*8 rm,
                            integer pim)
SX Binding:  none
Python Binding:  none

Build a PM_mapping structure out of the given input data and write it to a PDB file.

Rationale: The PM_mapping structure is a convenient medium of exchange between data production systems such as simulation codes, storage systems such as PDBLib, and visualization systems such as PDBView. This function is a convenient way for FORTRAN programs to put out their data into PDB files as PM_mapping's for later visualization and processing by other programs.

The PM_mapping is a structure with two main parts: a domain and a range. These two parts are in turn represented by a structure called a PM_set. Because they are both represented as the same type of data object, they are specified similarly in PFWMAP. For each of the domain and range sets the following information is given: a name; an array of integer quantities specifying such information as the dimensionality of the set, the dimensionality of the elements, the number of elements, and so on; and a linear array containing the elements of the set.

The entries in the arrays dp and rp are as follows:

1 the number of characters in the corresponding set name
2 the dimensionality of the set, nd
3 the dimensionality of the set elements, nde
4 the number of elements in the set, ne
5 thru 5+ nd-1 the sizes in each dimension
The layout of the set elements in dm and rm is:

1 thru ne values of the first component
ne+1 thru 2*ne values of the second component
... values of components
(nde-1)*ne+1 thru nde*ne values of the nde'th component
The calling application must keep track of how many PM_mapping's have been written to each file. PDBLib will write each PM_mapping under the name composed of the string, `Mapping', and the integer pim. For example if pim is 9, the PM_mapping will be written under the name `Mapping9'. If the application passes the same value for pim more than once only the last one will survive in the symbol table even though the data for each PM_mapping will persist in the file!

The arguments to PFWMAP are: file, PDBfile for writing; map, PM_mapping to write; ind, PM_mapping index; fileid, an integer identifier which designates the PDB file to which to attempt to write; dname, an ASCII string containing the name of the domain set; dp, an integer array of parameters defining the domain set; dm, an array of real*8 values containing the set elements component by component; rname, an ASCII string containing the name of the range set; rp, an integer array of parameters defining the range set; rm, an array of real*8 values containing the range elements component by component; and pim a counter specifying the number of the mapping being written out.

The return value is 1, if successful; otherwise, 0 is returned and an ASCII string error message can be retrieved through a call to PD_get_error. For FORTRAN programs an error message may be retrieved by invoking function PFGERR.


C Example
       PDBfile *file;
       PM_mapping *f;
       static int count = 0;
             .
             .
             .

       if (!PD_put_mapping(file, f, count++))
          printf("%s", PD_get_error());
             .
             .
             .

Fortran Example
       integer pfwmap
       integer fileid, dp(5), rp(5)
       double precision dm(0:99), rm(0:99)
             .
             .
             .

       dp(1) = 6
       dp(2) = 1
       dp(3) = 1
       dp(4) = 100
       dp(5) = 100
       rp(1) = 6
       rp(2) = 1
       rp(3) = 1
       rp(4) = 100
       rp(5) = 100
 
       do 100 i = 0, 99
          dm(i) = 6.28*float(i)/99.
          rm(i) = sin(6.28*float(i)/99.)
  100  continue
 
       if (pfwmap(fileid, `Domain', dp, dm, `Range', rp, rm, 0)
      &    .eq. 0)
      &   call errproc
             .
             .
             .

PFWRAN

C Binding:   none
F77 Binding: integer PFWRAN(integer fileid,
                            character dname, integer nchr,
                            character rname, integer rp, real*8 rm,
                            integer pim)
SX Binding:  none
Python Binding:  none

Build a PM_mapping structure out of the given input data and write it to a PDB file.

Rationale: The PM_mapping structure is a convenient medium of exchange between data production systems such as simulation codes, storage systems such as PDBLib, and visualization systems such as PDBView. This function is a convenient way for FORTRAN programs to put out their data into PDB files as PM_mapping's for later visualization and processing by other programs.

The PM_mapping is a structure with two main parts: a domain and a range. These two parts are in turn represented by a structure called a PM_set. In many cases a number of PM_mapping's share a common domain set. It is therefore more efficient to write the unique domain sets out separately and use PFWRAN to write out the PM_mapping's without their domains. Post processor codes such as PDBView (by definition) know how to put the full PM_mapping back together. Note: the domain name given for PFWRAN must be the same as the domain name passed to the corresponding PFWSET call.

For each range set the following information is given: a name; an array of integer quantities specifying such information as the dimensionality of the set, the dimensionality of the elements, the number of elements, and so on; and a linear array containing the elements of the set.

The entries in the array rp are as follows:

1 the number of characters in the corresponding set name
2 the dimensionality of the set, nd
3 the dimensionality of the set elements, nde
4 the number of elements in the set, ne
5 thru 5+ nd-1 the sizes in each dimension

The layout of the set elements in rm is:

1 thru ne values of the first component
ne+1 thru 2*ne values of the second component
... values of components
(nde-1)*ne+1 thru nde*ne values of the nde'th component
The calling application must keep track of how many PM_mapping's have been written to each file. PDBLib will write each PM_mapping under the name composed of the string, `Mapping', and the integer pim. For example if pim is 9, the PM_mapping will be written under the name `Mapping9'. If the application passes the same value for pim more than once only the last one will survive in the symbol table even though the data for each PM_mapping will persist in the file.

The arguments to PFWRAN are: fileid, an integer identifier which designates the PDB file to which to attempt to write; dname, an ASCII string containing the name of the domain set; nchr, an integer number of characters in dname; rname, an ASCII string containing the name of the range set; rp, an integer array of parameters defining the range set; rm, an array of real*8 values containing the range elements component by component; and pim a counter specifying the number of the mapping being written out.

The return value is 1, if successful; otherwise, 0 is returned and an error message may be retrieved by invoking function PFGERR.


Fortran Example
       integer pfwran
       integer fileid, i, pim, rp(5)
       double precision rm(0:99)
             .
             .
             .

       pim = 0
       rp(1) = 6
       rp(2) = 1
       rp(3) = 1
       rp(4) = 100
       rp(5) = 100
 
       do 100 i = 0, 99
          rm(i) = sin(6.28*float(i)/99.)
  100  continue
 
 c ... `Domain' written previously by pfwset
       if (pfwran(fileid, `Domain', 6, `Range', rp, rm, pim)
      &    .eq. 0)
      &   call errproc
             .
             .
             .

PD_PUT_SET

C Binding:   int PD_put_set(PDBfile *file, PM_set *set)
F77 Binding: integer PFWSET(integer fileid,
                            character dname, integer dp, real*8 dm)
SX Binding:  none
Python Binding:  none

Build a PM_set structure out of the given input data and write it to a PDB file.

Rationale: The PM_set structure is a fundamental component of the PM_mapping structure which is a convenient medium of exchange between data production systems such as simulation codes, storage systems such as PDBLib, and visualization systems such as PDBView. Although the function PFWMAP most conveniently writes a mapping out to a PDB file, it does not make the best use of limited storage space. In many cases a number of PM_mapping's share a common domain set. It is therefore more efficient to write the unique domain sets out separately and use PFWRAN to write out the PM_mapping's without their domains. Post processor codes such as PDBView (by definition) know how to put the full PM_mapping back together. Note: the domain name given for PFWSET must be the same as the domain name passed to the corresponding PFWRAN call!

For each PM_set the following information is given: a name; an array of integer quantities specifying such information as the dimensionality of the set, the dimensionality of the elements, the number of elements, etc.; and a linear array containing the elements of the set.

The entries in the array dp are as follows:

1 the number of characters in the corresponding set name
2 the dimensionality of the set, nd
3 the dimensionality of the set elements, nde
4 the number of elements in the set, ne
5 thru 5+ nd-1 the sizes in each dimension
The layout of the set elements in dm is:

1 thru ne values of the first component
ne+1 thru 2*ne values of the second component
... values of components
(nde-1)*ne+1 thru nde*ne values of the nde'th component
The arguments to PFWSET are: file, the PDBfile for writing; set, the PM_set to be written; fileid, an integer identifier which designates the PDB file to which to write; dname, an ASCII string containing the name of the PM_set; dp, an integer array of parameters defining the PM_set; and dm, an array of real*8 values containing the set elements component by component.

The return value is 1, if successful; otherwise, 0 is returned and an ASCII string error message can be retrieved through a call to PD_get_error. For FORTRAN programs an error message may be retrieved by invoking function PFGERR.


C Example
       PDBfile *file;
       PM_set *set;
             .
             .
             .

       if (!PD_put_set(file, set))
          printf("%s", PD_get_error());
             .
             .
             .

Fortran Example
       integer pfwset
       integer fileid, i, dp(5)
       double precision dm(0:99)
             .
             .
             .

       dp(1) = 6
       dp(2) = 1
       dp(3) = 1
       dp(4) = 100
       dp(5) = 100
 
       do 100 i = 0, 99
          dm(i) = 6.28*float(i)/99.
  100  continue
 
       if (pfwset(fileid, `Domain', dp, dm) .eq. 0)
      &   call errproc
             .
             .
             .

PD_MAKE_IMAGE

C Binding:   PD_image *PD_make_image(char *name, char *type, void *data,
                                     double dx, double dy, int bpp,
                                     double xmin, double xmax,
                                     double ymin, double ymax,
                                     double zmin, double zmax)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Create and initialize a PD_image data structure.

Input for this function is: name, an ASCII string containing the name of the image; type, an ASCII string containing the data type of the image elements (e.g. "char", "float", "complex"); data, pointer to array of image data of type type; dx, width of image; dy, height of image; bpp, bits per pixel of the image; xmin, minimum value of coordinate associated with image x direction; xmax, maximum value of coordinate associated with image x direction; ymin, minimum value of coordinate associated with image y direction; ymax, maximum value of coordinate associated with image y direction; zmin, minimum value of image data (for palette labeling); and zmax, maximum value of image data (for palette labeling).

Returns a pointer to a PD_image.


C Example
 #include "pdb.h"
 
     PDBfile *file;
     PD_image *im;

     im = PD_make_image();
           .
           .
           .

PD_REL_IMAGE

C Binding:   void PD_rel_image(PD_image *image)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Release the space associated with a PD_image data structure. Input to this function is: image, a pointer to a PD_image.


C Example
 #include "pdb.h"
 
     PD_image *image;
           .
           .
           .

     PD_rel_image(image);
           .
           .
           .

PD_AUTOFIX_DENORM

C Binding:   int PD_autofix_denorm(PDBfile *file, int flag)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Activate automatic zeroing out of denormalized float point primitives during PDB read calls (PD_read, PD_read_as, PD_read_alt, PD_read_as_alt). Does not handle C structures.

Input to this function is: file, a PDB file handle. flag, if flag is TRUE, turn automatic fixing of denormalized floats on for the file; otherwise turn it off.

Returns the old flag value that existed before the function was called.


C Examples

File example:

     #include "pdb.h"
 
     PDBfile *file;
     int old_value;
           .
           .
     /* Turn automatic fixing of denormalized floats on for subsequent read calls */         
     old_value = PD_autofix_denorm(file, TRUE);
           .
           .

PD_ACTIVATE_CKSUM

C Binding:   int PD_activate_cksum(PDBfile *file, int flag)
F77 Binding: integer PFSCSM(integer fileid, int flag)
SX Binding:  (set-activate-checksum! file flag)
Python Binding:  XXX - missing

Activate checksum handling functionality. There are three (3) modes that PDB has available (which can be OR'd together):

If flag is set to PD_MD5_OFF or FALSE, then nothing is enabled and no checksums are calculated or added to the file. If flag is set to PD_MD5_FILE or TRUE on any open, writable file, then an MD5 checksum for the entire file will be placed in the file during any subsequent flush or close operation. If flag is set to PD_MD5_RW on any open, writable file, then any subsequent PD_write will create a hidden MD5 checksum variable associated with the variable being written out and any subsequent PD_read will recalculate and compare MD5 checksums for variables read in (returning -1 and setting PD_error if the checksums do not match). If flag is set to (PD_MD5_FILE | PD_MD5_RW), then both file and variable checksums are handled.

Defaults to PD_MD5_OFF for any file that never had PD_MD5_FILE applied to it. PD_activate_cksum acts like a toggle, hence checksums can be turned off or on for the file (PD_MD5_FILE) and/or for individual variables (PD_MD5_RW) at any time. Note that the MD5 checksum done during PD_write/PD_read calls for variables only currently works for data that contains no pointers. This is because memory addresses in pointers will change from run to run.

Input to this function is: file, a PDB file handle. flag, if flag is PD_MD5_FILE and/or PD_MD5_RW, turn checksum handling on for the file or individual variables, respectively; otherwise turn it off.

Returns the old flag value that existed before the function was called.

See also: PD_verify


C Examples

File example:

     #include "pdb.h"
 
     PDBfile *file;
     int old_value;
           .
           .

/* calculate a checksum for the entire file (only) on PD_flush or PD_close */
     old_value = PD_activate_cksum(file, PD_MD5_FILE);
           .
           .

/* this also calculates a checksum for the entire file and adds it in */      
     PD_close(file);

Variable example:

     #include "pdb.h"
 
     PDBfile *file;
     int old_value, retval;
     float x;
           .
           .

/* turn on both file and variable (read/write) checksums */      
     old_value = PD_activate_cksum(file, PD_MD5_FILE | PD_MD5_RW);
           .
           .

     if (!PD_write(file, "x", "float", &x))
        printf("%s", PD_get_error());
           .
           .

/* read and compares x's checksum with freshly computed one */      
     retval = PD_read(file, "x", &x); 

/* determine if read failed or checksum failed: check error */     
     if ((retval == FALSE) || (retval == -1))
        printf("%s", PD_get_error());         
           .
           .

/* this also calculates a checksum for the entire file and adds it in */      
     PD_close(file);      


PD_VERIFY

C Binding:   int PD_verify(PDBfile *file)
F77 Binding: none
SX Binding:  none
Python Binding:  none

Verifies a file's integrity and determines if the file is corrupt. Uses MD5 checksums.

Input to this function is: file, a PDB file handle.

Returns TRUE if there is an MD5 checksum for the entire file and it matches a freshly computed checksum, returns FALSE if there is an MD5 checksum for the entire file and it does not match a freshly computed checksum, and returns -1 if there is no checksum in the file to verify with.

See also: PD_activate_cksum


C Example
 #include "pdb.h"
 
     PDBfile *file;
     int valid;
           .
           .
           .
     valid = PD_verify(file);

     if (valid == -1)
       printf("PDB file contains no checksum to verify with\n");

     if (!valid)
       printf("PDB file is corrupt\n");
           .
           .
           .

Data Structures in PDBLib

The data structures with which the PDBLib system works are passed back to the application program as the result of the high level calls. This gives the programmer access to a great deal of information about the PDB file, the symbol table and the structure chart. Hopefully, this also makes the package more powerful without pushing any special responsibility onto the programmer.

For application developers who require all of the information from a PDB file, the hash lookup function, SC_def_lookup, can be used to obtain symbol table entries (syment) and structure definitions (defstr) from the symbol table or structure chart. Examples can be found in the section at the end of the manual.

DATA_ALIGNMENT

The set of alignments for the primitive types is kept in a structure called data_alignment. Its actual definition is:

 struct s_data_alignment
    {int char_alignment;
     int ptr_alignment;
     int short_alignment;
     int int_alignment;
     int long_alignment;
     int float_alignment;
     int double_alignment;};
 
 typedef struct s_data_alignment data_alignment;
The term alignment refers to the fact that many CPU's require certain data types to begin at memory locations whose addresses are even multiples of some integer number of bytes. So for example, to say that the alignment of a double is 8 means that a double must begin at an address which is a multiple of 8.

Compilers hide this concept from almost all applications. PDBLib is one that must know data alignments precisely. It employs a structure called a data_alignment to record the alignments of the default primitive data types which PDBLib supports. See the discussion of the data_alignment structure in the section on data structures.

The following is the list of data_alignment's which PDBLib provides automatically (applications can add their own as needed):

SPARC_ALIGNMENT = {1, 4, 2, 4, 4, 4, 8}
MIPS_ALIGNMENT = {1, 4, 2, 4, 4, 4, 8}
RS6000_ALIGNMENT = {1, 4, 2, 4, 4, 4, 4}
CRAY_ALIGNMENT = {8, 8, 8, 8, 8, 8, 8}
UNICOS_ALIGNMENT = {1, 8, 8, 8, 8, 8, 8}
M68000_ALIGNMENT = {1, 2, 2, 2, 2, 2, 2}
INTELA_ALIGNMENT = {1, 2, 2, 2, 2, 2, 2}
INTELB_ALIGNMENT = {4, 4, 4, 4, 4, 4, 4}
INTELC_ALIGNMENT = {2, 4, 2, 4, 4, 4, 4}
DEF_ALIGNMENT = {1, 4, 4, 4, 4, 4, 4}

DATA_STANDARD

The set of information describing all of the primitive data types is organized into a structure called a data_standard. The data_standard characterizes the CPU architecture because all types are either primitive or derived from known types.

Its actual definition is:

 struct s_data_standard
    {int ptr_bytes;
     int short_bytes;
     int short_order;
     int int_bytes;
     int int_order;
     int long_bytes;
     int long_order;
     int float_bytes;
     long *float_format;
     int *float_order;
     int double_bytes;
     long *double_format;
     int *double_order;};
 
 typedef struct s_data_standard data_standard;

Floating Point Format Descriptor

The integer types only require a number of bytes and their order. The floating point types require additional information describing the bit layout of the components of the number: the sign bit; the exponent; and the mantissa. These are given as an array of 8 long integers as follows:

format[0] = # of bits per number
format[1] = # of bits in exponent
format[2] = # of bits in mantissa
format[3] = start bit of sign
format[4] = start bit of exponent
format[5] = start bit of mantissa
format[6] = high order mantissa bit
format[7] = bias of exponent The following floating point format descriptors are defined in PDBLib and used in the data_standard's described in the last section:

ieee_float= {32L, 8L, 23L, 0L, 1L, 9L, 0L, 0x7FL}
ieeea_double= {64L, 11L, 52L, 0L, 1L, 12L, 0L, 0x3FFL}
ieeeb_double= {96L, 15L, 64L, 0L, 1L, 32L, 1L, 0x3FFEL}
intel_float= {32L, 8L, 23L, 0L, 1L, 9L, 0L, 0x7FL}
intel_double= {64L, 11L, 52L, 0L, 1L, 12L, 0L, 0x3FFL}
cray_float= {64L, 15L, 48L, 0L, 1L, 16L, 1L, 0x4000L}

Note: There are several variants of floating type format on the VAX. Accordingly the user must decide which one to use and PDBLib has the descriptions:

When using GFLOATs

vax_float= {32L, 8L, 23L, 0L, 1L, 9L, 0L, 0x81L}
vax_double= {64L, 11L, 52L, 0L, 1L, 12L, 0L, 0x401L}

otherwise

vax_float= {32L, 8L, 23L, 0L, 1L, 9L, 0L, 0x81L}
vax_double= {64L, 8L, 55L, 0L, 1L, 9L, 0L, 0x81L}

Byte Ordering

There is much discussion in the literature about little endian and big endian machines. Those two refer to two possible byte orderings for binary data. That is not the most general way to talk about byte ordering however. In fact the VAX format exemplifies the need for generality. PDBLib simply uses an array of integers which describe the order of the bytes in memory relative to CPU's such as the Motorola and SPARC families.

ieee_float_order= {1, 2, 3, 4}
ieeea_double_order= {1, 2, 3, 4, 5, 6, 7, 8}
ieeeb_double_order= {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}
intel_float_order= {4, 3, 2, 1}
intel_double_order= {8, 7, 6, 5, 4, 3, 2, 1}
vax_float_order= {2, 1, 4, 3}
vax_double_order= {2, 1, 4, 3, 6, 5, 8, 7}
cray_float_order= {1, 2, 3, 4, 5, 6, 7, 8}

The following is a list of the data_standard's which PDBLib provides by default. The purpose is twofold: to help users identify target formats; and to guide users who wish to create their own data_standard's.

The members of the data_standard are indicated in the template:

STAND
{size of pointer,
size and order of short,
size and order of int,
size and order of long,
size, format, and order of float,
size, format, and order of double}
The various variables indicated are defined by PDBLib.

DEF_STD
{4,
 2, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, def_float, def_float_order,
 8, def_double, def_double_order}

IEEEA_STD
{4,
 2, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, ieee_float, ieee_float_order,
 8, ieeea_double, ieeea_double_order}

IEEEB_STD
{4,
 2, NORMAL_ORDER,
 2, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, ieee_float, ieee_float_order,
12, ieeeb_double, ieeeb_double_order}

IEEEC_STD
{4,
 2, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, NORMAL_ORDER,
 4, ieee_float, ieee_float_order,
12, ieeeb_double, ieeeb_double_order}

INTELA_STD
{4,
 2, REVERSE_ORDER,
 2, REVERSE_ORDER,
 4, REVERSE_ORDER,
 4, intel_float, intel_float_order,
 8, intel_double, intel_double_order}

INTELB_STD
{4,
 2, REVERSE_ORDER,
 4, REVERSE_ORDER,
 4, REVERSE_ORDER,
 4, intel_float, intel_float_order,
 8, intel_double, intel_double_order},

VAX_STD
{4,
 2, REVERSE_ORDER,
 4, REVERSE_ORDER,
 4, REVERSE_ORDER,
 4, vax_float, vax_float_order,
 8, vax_double, vax_double_order}

CRAY_STD
{8,
 8, NORMAL_ORDER,
 8, NORMAL_ORDER,
 8, NORMAL_ORDER,
 8, cray_float, cray_float_order,
 8, cray_float, cray_float_order}

DEFSTR

An entry in the structure chart is represented by a structure called a defstr. It contains information about the data type such as the type name, the byte size and alignment, and a list of members.

DIMDES

A dimdes or dimension descriptor contains the information necessary to characterize a list of dimension specifications. It contains such information as the minimum and maximum values the dimension index may have and the net size of the dimension index range.

MEMDES

A memdes or member descriptor is the structure used to contain the information about a member of a defstr. It contains information about the type of the member, the name of the member, any dimensions which the member may have, and any casts which have been defined via PD_cast.

PDBFILE

The PDBfile is the analog to the FILE structure in standard C I/O. In fact, the PDBfile contains a FILE pointer to access the file via the standard C library functions. In addition, the PDBfile contains information such as: the symbol table, the structure charts for the file and the host platform; data_standard's and data_alignment's for the file and the host platform; and a modification date.

SYMENT

Just as the defstr type describes entries in the structure chart the syment type describes entries in the symbol table. The syment includes information about the data type of the entry, the number of elements, the dimensions of the entry, and its disk address.

PDBLib by Example

The following code fragments illustrate the functionality of PDBLib. Some of the code is taken from the validation suite and some from the library itself.

Working with PDB files

This routine is taken from the validation suite for PDBLib. In it, a target for the PDB file is chosen with the routine test_target (see the section on PD_target for the definition of this function), a PDB file created, some structures defined, data written, and the file closed. The file is then reopened in append mode, some more data written to the file, and the file is closed again. Finally, the file is opened in read mode, the data read, some comparisons done, and the file is closed. The read and write operations are hidden in this example. The significance of the example is that a PDB file is created, closed, and opened in both append and read-only mode.


 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 test_1(base, tgt, n)
    char *base, *tgt;
    int n;
    {PDBfile *strm;
     char datfile[MAXLINE], fname[MAXLINE];
     int err;
     FILE *fp;
 
 /* target the file as asked */
     test_target(tgt, base, n, fname, datfile);
 
     fp = fopen(fname, "w");
 
 /* create the named file */
     if ((strm = PD_open(datfile, "w")) == NULL)
        {fprintf(fp, "Test couldn't create file %s\r\n", datfile);
         exit(1);};
     fprintf(fp, "File %s created\n", datfile);
 
     prep_test_1_data();
 
 /* make a few defstructs */
     PD_defstr(strm, "l_frame",
               "float x_min", "float x_max", "float y_min",
               "float y_max", LAST);
     PD_defstr(strm, "plot",
               "float x_axis(10)", "float y_axis(10)", "integer npts", 
               "char * label", "l_frame view", LAST);
 
 /* write the test data */
     write_test_1_data(strm);
 
 /* close the file */
     if (!PD_close(strm))
        {fprintf(fp, "Test couldn't close file %s\r\n", datfile);
         exit(1);};
     fprintf(fp, "File %s closed\n", datfile);
 
 /* reopen the file to append */
     if ((strm = PD_open(datfile, "a")) == NULL)
        {fprintf(fp, "Test couldn't open file %s to append\r\n",
                 datfile);
         exit(1);};
     fprintf(fp, "File %s opened to append\n", datfile);
 
     append_test_1_data(strm);
 
 /* close the file after append */
     if (!PD_close(strm))
        {fprintf(fp, "Test couldn't close file %s after append\r\n",
                 datfile);
         exit(1);};
     fprintf(fp, "File %s closed after append\n", datfile);
 
 /* reopen the file */
     if ((strm = PD_open(datfile, "r")) == NULL)
        {fprintf(fp, "Test couldn't open file %s\r\n", datfile);
         exit(1);};
     fprintf(fp, "File %s opened\n", datfile);
 
 /* dump the symbol table */
     dump_test_symbol_table(fp, strm->symtab, 1);
 
 /* read the data from the file */
     read_test_1_data(strm);
 
 /* compare the original data with that read in */
     err = compare_test_1_data(strm, fp);
 
 /* close the file */
     if (!PD_close(strm))
       {fprintf(fp, "Test couldn't close file %s\r\n", datfile);
        exit(1);};
     fprintf(fp, "File %s closed\n", datfile);
 
 /* print it out to stdout */
     print_test_1_data(fp);
 
     fclose(fp);
 
     return(err);}

 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 

Writing Data to PDB files

These two routines exemplify the various write routines of PDBLib. In particular, they were built to test the spectrum of write calls. Notice their demonstration of the rules for write operations: the variable must be a pointer to data of the type specified.

The identifiers beginning with `N_' are `#defined' constants whose values are irrelevant to these examples.


 static char
  cs_w,
  ca_w[N_CHAR],
  *cap_w[N_DOUBLE];
 
 static short
  ss_w,
  sa_w[N_INT];
 
 static int
  is_w,
  ia_w[N_INT],
  p_w[N_INT],
  len;
 
 static float
  fs_w,
  fa2_w[N_FLOAT][N_DOUBLE];
 
 static double
  ds_w,
  da_w[N_FLOAT];
 
 static plot
  graph_w;
 
 static l_frame
  view_w;
 
 static lev1
  *tar_w;
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 void write_test_1_data(strm)
    PDBfile *strm;
    {
 
 /* write scalars into the file */
     PD_write(strm, "cs", "char", &cs_w);
     PD_write(strm, "ss", "short", &ss_w);
     PD_write(strm, "is", "integer", &is_w);
     PD_write(strm, "fs", "float", &fs_w);
     PD_write(strm, "ds", "double", &ds_w);
 
 /* write primitive arrays into the file */
     PD_write(strm, "sa(5)", "short", sa_w);
     PD_write(strm, "ia(5)", "integer", ia_w);
 
 /* write structures into the file */
     PD_write(strm, "view", "l_frame", &view_w);
     PD_write(strm, "graph", "plot", &graph_w);
 
     return;}
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 void write_test_2_data(strm)
    PDBfile *strm;
    {
 
    PD_write(strm, "tar", "lev1 *", &tar_w);
 
     return;}
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/

Reading Data from PDB files

These two routines exemplify the various read routines of PDBLib. In particular, they were built to test the spectrum of read operations. They read the data written out in the previous example. Notice their demonstration of the rules for read operations: the variable must be a pointer to data of the type specified. This is often a more difficult proposition for reads since the type information isn't supplied in the read call.

The member read operations at the end of the first routine should be studied carefully. They are not the most general read example, but they are among the most useful.

The second routine reads not only the entire structure, but picks out each part individually. It demonstrates the rule about dereferencing pointers in the partial read operation. Study the structures of this example carefully!

The identifiers beginning with `N_' are `#defined' constants whose values are irrelevant to these examples. Also, take for granted that the unspecified variables to contain parts of the structures have the correct declarations.

 
 struct s_lev2
  {char **s;
  int type;};
 
 typedef struct s_lev2 lev2;
 
 struct s_lev1
  {int *a;
  double *b;
  lev2 *c;};
 
 typedef struct s_lev1 lev1;
 
 static char
  cs_r,
  ca_r[N_CHAR],
  *cap_r[N_DOUBLE];
 
 static short
  ss_r,
  sa_r[N_INT];
 
 static int
  is_r,
  ia_r[N_INT];
 
 static float
  fs_r,
  fs_app_r,
  fs_p1_r,
  fs_p2_r,
  fs_p3_r,
  fa2_r[N_FLOAT][N_DOUBLE],
  fa2_app_r[N_FLOAT][N_DOUBLE];
 
 static double
  ds_r,
  da_r[N_FLOAT];
 
 static plot
  graph_r;
 
 static l_frame
  view_r;
 
 static lev1
  *tar_r;
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 void read_test_1_data(strm)
    PDBfile *strm;
    {
 
 /* read the scalar data from the file */
     PD_read(strm, "cs", &cs_r);
     PD_read(strm, "ss", &ss_r);
     PD_read(strm, "is", &is_r);
     PD_read(strm, "fs", &fs_r);
     PD_read(strm, "ds", &ds_r);
 
 /* read the primitive arrays from the file */
     PD_read(strm, "ca", ca_r);
     PD_read(strm, "sa", sa_r);
     PD_read(strm, "ia", ia_r);
     PD_read(strm, "fa2", fa2_r);
     PD_read(strm, "da", da_r);
     PD_read(strm, "cap", cap_r);
 
 /* read the entire structures from the file */
     PD_read(strm, "view", &view_r);
     PD_read(strm, "graph", &graph_r);
 
 /* read the appended data from the file */
     PD_read(strm, "fs_app", &fs_app_r);
     PD_read(strm, "fa2_app", fa2_app_r);
 
 /* struct member test */
     PD_read(strm, "graph.view.x_max", &fs_p2_r);
     PD_read(strm, "view.y_max", &fs_p3_r);
 
     return;}
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 /* READ_TEST_2_DATA - read the test data from the file */
 
 void read_test_2_data(strm)
    PDBfile *strm;
    {do_r = strm->default_offset;
 
     PD_read(strm, "tar", &tar_r);
     PD_read(strm, "p", p_r);
 
     PD_read(strm, "tar(0).a", &ap1);
     PD_read(strm, "tar(1).a", &ap2);
 
     PD_read(strm, "tar(0).a(0)", &aa[0]);
     PD_read(strm, "tar(0).a(1)", &aa[1]);
     PD_read(strm, "tar(1).a(0)", &aa[2]);
     PD_read(strm, "tar(1).a(1)", &aa[3]);
 
     PD_read(strm, "tar(0).b", &bp1);
     PD_read(strm, "tar(1).b", &bp2);
 
     PD_read(strm, "tar(0).b(0)", &ba[0]);
     PD_read(strm, "tar(0).b(1)", &ba[1]);
     PD_read(strm, "tar(1).b(0)", &ba[2]);
     PD_read(strm, "tar(1).b(1)", &ba[3]);
 
     PD_read(strm, "tar(0).c", &cp1);
     PD_read(strm, "tar(1).c", &cp2);
 
     PD_read(strm, "tar(0).c(0)", &ca[0]);
     PD_read(strm, "tar(0).c(1)", &ca[1]);
     PD_read(strm, "tar(1).c(0)", &ca[2]);
     PD_read(strm, "tar(1).c(1)", &ca[3]);
 
     PD_read(strm, "tar(0).c(0).s", &sp1);
     PD_read(strm, "tar(0).c(1).s", &sp2);
     PD_read(strm, "tar(1).c(0).s", &sp3);
     PD_read(strm, "tar(1).c(1).s", &sp4);
 
     PD_read(strm, "tar(0).c(0).s(0)", &tp1);
     PD_read(strm, "tar(0).c(0).s(1)", &tp2);
     PD_read(strm, "tar(0).c(1).s(0)", &tp3);
     PD_read(strm, "tar(0).c(1).s(1)", &tp4);
 
     PD_read(strm, "tar(0).c(0).s(0)(2)", &ta[0]);
     PD_read(strm, "tar(0).c(0).s(1)(1)", &ta[1]);
     PD_read(strm, "tar(0).c(1).s(0)(3)", &ta[2]);
     PD_read(strm, "tar(0).c(1).s(1)(2)", &ta[3]);
 
     PD_read(strm, "tar(1).c(0).s(0)", &tp5);
     PD_read(strm, "tar(1).c(0).s(1)", &tp6);
     PD_read(strm, "tar(1).c(1).s(0)", &tp7);
     PD_read(strm, "tar(1).c(1).s(1)", &tp8);
 
     return;}

 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 

Appending Data to PDB file variables

The functions PD_defent, PD_write, and PD_append (and their alternate forms) may be used in several combinations. Users have a variety of scenarios for writing their data. These scenarios are driven by considerations such as: data flow in the application; efficiency of writing the data; or requirements of the application reading the data.

The following examples are taken from the PDB test suite and demonstrate several combinations leaving the rationale to the user. In each example, we are writing a variable IA in three pieces of 5 integers each. The net result is an array which is of dimension (3,5) if the file is set to use row major ordering or (5,3) if the file is set to use column major ordering.

Append Example #1

This is perhaps the simplest case. A variable is written with PD_write and subsequently append to twice with PD_append.
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/

 /* WRITE_TEST_1_DATA - write out the data into the PDB file
  *                   - this is write, append, append
  *                   - row major order
  */

 static int write_test_1_data(PDBfile *strm)
    {

 /* write an array into the file */
     if (!PD_write(strm, "ia(1,5)", "integer", ia_w0))
        {printf("IA WRITE FAILED - WRITE_TEST_1_DATA\n");
         return(FALSE);};

 /* append data to ia */
     if (!PD_append(strm, "ia(1:1,0:4)", ia_w1))
        {printf("IA APPEND 1 FAILED - WRITE_TEST_1_DATA\n");
         return(FALSE);};

 /* append more data to ia */
     if (!PD_append(strm, "ia(2:2,0:4)", ia_w2))
        {printf("IA APPEND 2 FAILED - WRITE_TEST_1_DATA\n");
         return(FALSE);};

     return(TRUE);}

 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 

Append Example #2

This is the same as Example #1 above except that the file has been set to use column major ordering. Compare the index expressions with those in Example #1.
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/

 /* WRITE_TEST_2_DATA - write out the data into the PDB file
  *                   - this is write, append, append
  *                   - row major order
  */

 static int write_test_2_data(PDBfile *strm)
    {

 /* write an array into the file */
     if (!PD_write(strm, "ia(5,1)", "integer", ia_w0))
        {printf("IA WRITE FAILED - WRITE_TEST_2_DATA\n");
         return(FALSE);};

 /* append data to ia */
     if (!PD_append(strm, "ia(0:4,1:1)", ia_w1))
        {printf("IA APPEND 1 FAILED - WRITE_TEST_2_DATA\n");
         return(FALSE);};

 /* append more data to ia */
     if (!PD_append(strm, "ia(0:4,2:2)", ia_w2))
        {printf("IA APPEND 2 FAILED - WRITE_TEST_2_DATA\n");
         return(FALSE);};

     return(TRUE);}

 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 

Append Example #3

In this example, some space is reserved for variable. Data is then written to into the reserved space. Subsquently, more data is appended to variable.
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/

 /* WRITE_TEST_3_DATA - write out the data into the PDB file
  *                   - this is defent, write, append, append
  *                   - row major order
  */

 static int write_test_3_data(PDBfile *strm)
    {

 /* reserve space for an array in the file */
     if (!PD_defent(strm, "ia(1,5)", "integer"))
        {printf("IA WRITE FAILED - WRITE_TEST_3_DATA\n");
         return(FALSE);};

 /* write data to the reserved space */
     if (!PD_write(strm, "ia(0:0,0:4)", "integer", ia_w0))
        {printf("IA WRITE FAILED - WRITE_TEST_3_DATA\n");
         return(FALSE);};

 /* append data to ia */
     if (!PD_append(strm, "ia(1:1,0:4)", ia_w1))
        {printf("IA APPEND 1 FAILED - WRITE_TEST_3_DATA\n");
         return(FALSE);};

 /* append more data to ia */
     if (!PD_append(strm, "ia(2:2,0:4)", ia_w2))
        {printf("IA APPEND 2 FAILED - WRITE_TEST_3_DATA\n");
         return(FALSE);};

     return(TRUE);}

 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 

Append Example #4

In this example, some space is reserved for variable. Data is then written to into the reserved space. Subsquently, another block of space is reserved for the variable and later filled in with calls to PD_write.
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/

 /* WRITE_TEST_4_DATA - write out the data into the PDB file
  *                   - this is defent, write, defent, write, write
  *                   - column major order
  */

 static int write_test_4_data(PDBfile *strm)
    {

 /* reserve space for an array in the file */
     if (!PD_defent(strm, "ia(5,1)", "integer"))
        {printf("IA DEFENT 1 FAILED - WRITE_TEST_4_DATA\n");
         return(FALSE);};

 /* write data to the reserved space */
     if (!PD_write(strm, "ia(0:4,0:0)", "integer", ia_w0))
        {printf("IA WRITE FAILED - WRITE_TEST_4_DATA\n");
        return(FALSE);};

 /* reserve more space for ia */
     if (!PD_defent(strm, "ia(0:4,1:2)", "integer"))
        {printf("IA DEFENT 2 FAILED - WRITE_TEST_4_DATA\n");
         return(FALSE);};

 /* write data to the some of the additional reserved space */
     if (!PD_write(strm, "ia(0:4,1:1)", "integer", ia_w1))
        {printf("IA APPEND 1 FAILED - WRITE_TEST_4_DATA\n");
         return(FALSE);};

 /* write data to the rest of the additional reserved space */
     if (!PD_write(strm, "ia(0:4,2:2)", "integer", ia_w2))
        {printf("IA APPEND 2 FAILED - WRITE_TEST_4_DATA\n");
         return(FALSE);};

     return(TRUE);}

 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 

Inquiries in PDBLib

The following fragments show how to obtain information about PDB files and their contents.

 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 myread(file, name, var, offset, number)
    PDBfile *file;
    char *name;
    void *var;
    long offset, number;
    {long addr, num;
     char *token, *type, memb[MAXLINE];
     dimdes *dims;
     syment *ep;
 
     strcpy(memb, name);
     token = strtok(memb, ".([");
 
 /* look up the variable name */
     ep = PD_query_entry(file, token, NULL);
     if (ep == NULL)
        printf("%s", PD_get_error());
 
     addr = PD_entry_address(ep);
     dims = PD_entry_dimensions(ep);
     num  = PD_entry_number(ep);
     type = PD_entry_type(ep);
 
 /* with ep in hand, we know the variable type, number of elements,
  * dimensions, and disk address
  */
               .
               .
               .
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/
 
 _PD_wr_leaf(file, var, nitems, type)
    PDBfile *file;
    char *var;
    long nitems;
    char *type;
    {char *svar;
     int size;
     FILE *fp;
     defstr *dp;
     memdes *desc, *mem_lst;
 
     fp = file->stream;
            .
            .
            .
 
 /* dispatch all other writes */
     if (file->conversions)
            .
            .
            .
 
 /* obtain a pointer to the defstr associated with type */
     dp = PD_inquire_host_type(file, type);
     if (dp == NULL)
        printf("%s", PD_get_error());
 
 /* if the structure has any pointered members loop over the members */
     if (dp->n_indirects && ((mem_lst = dp->members) != NULL))
        {size = dp->size;
         for (svar = var, offset = 0L, i = 0L; i <; nitems; i++)
             {for (desc = mem_lst; desc != NULL; desc = desc->next)
                  { ... };
              svar += size;};};
            .
            .
            .
 
 /*-----------------------------------------------------------------*/
 /*-----------------------------------------------------------------*/

Browsing PDB files

The following fragment shows how to browse around in PDB files. Note the use of PD_ls. What this example doesn't show is checking for the directory type and perhaps using PD_cd to move to other directories.


    int i, nd, ne;
    long ni;
    long *dims;
    char **names, *fname, *type;
    syment *ep;
    PDBfile *file;

    fname = "/tmp/fubar.pdb";
    file = PD_open(fname, "r");
    if (file == NULL)
       {printf("Error opening %s\n", fname);
	exit(1);};

    printf("\nSymbol Table:\n");

/* print contents of symbol table */
    names = PD_ls(file, NULL, NULL, &ne);
    for (i = 0; i < ne; i++)
	{if (names[i] != NULL)
            {ep = PD_query_entry(file, names[i], NULL);
	     rv = PD_get_entry_info(ep, &type, &ni, &nd, &dims);
	     if (rv)
	        {printf("%20s %10s %8ld %2d (%p)\n",
			names[i], type, ni, nd, dims);
		 PD_free_entry_info(type, dims);};};};

    SFREE(names);

/* close file */
    PD_close(file);

Writing PM_mappings with PFWMAP

The following fragment shows how to write a PM_mapping to a PDB file from a FORTRAN program. This example uses PFWMAP. PFWMAP writes out both domain and range as a complete mapping. The drawback to this approach is that many mappings might have the same domain which would be written out over and over again. This could lead to unacceptably large data files. See the next example for a more space saving approach.

 
 c-----------------------------------------------------------------
 c-----------------------------------------------------------------

  subroutine sxdmp(namesx, namelen)
 
 c traverse plot list to make dumps suitable for sx
 
  integer pfopen, pfclos, pfgerr, pfwmap, pfwset, pfwran
  integer zscanleq
  
  integer pderr(32), rp(6), dp(6)
  integer fileid, pim, dmnsn
 
  double precision rm(nsavept), dm(nsavept)
 
 c ... set up
             .
             .
             .
 
 c ... open the file
  fileid = pfopen(namelen, namesx, 'w')
  if (fileid .eq. -1) then
     iplpderr = pfgerr(nchr, pderr)
     call errproc(pderr, nchr, 0, 0)
  endif
 
  pim = 0
 
 c ... loop over plots
  do ...
 
 c ... setup domain
  dname = <;domain name>
  dp(1) = <;length of domain name>
 
  select case (dmnsn)
  case ('d2r1')
     dp(2) = 2
     dp(3) = 2
     dp(4) = nr
     dp(5) = kmax
     dp(6) = lmax
     call zmovewrd(dm(1), x2d, nr)
     call zmovewrd(dm(nr+1), y2d, nr)
  case ('d1r1')
     dp(2) = 1
     dp(3) = 1
     dp(4) = nr
     dp(5) = nr
     call zmovewrd(dm(1), <;domain data>, nr)
  endselect
 
 c ... set up range
  rname = <;range name>
  rp(1) = <;length of range name>
 
  rp(2) = dp(2)
  rp(3) = 1
  rp(4) = nr
  rp(5) = dp(5)
  rp(6) = dp(6)
  call zmovewrd(rm(1), <;range data>, nr)
 
 c ... write the mapping
  ierr = pfwmap(fileid, dname, dp, dm, rname, rp, rm, pim)
  if (ierr.eq.0) then
     pfgerr(nchr, pderr)
     call errproc(pderr, nchr, 0, 0)
  endif
  pim = pim + 1
  repeat
 
 c ... close the file
  icloseok = pfclos(fileid)
  if (icloseok.eq.0) then
     pfgerr(nchr, pderr)
     call errproc(pderr, nchr, 0, 0)
  endif
 
  return
  end

 c-----------------------------------------------------------------
 c-----------------------------------------------------------------

Writing PM_mappings with PFWSET and PFWRAN

The following fragment shows how to write a PM_mapping to a PDB file from a FORTRAN program. This example uses PFWSET and PFWRAN. With PFWSET and PFWRAN an application can write mappings in the most space efficient way. Instead of writing the same domains over and over again as would be done with PFWMAP, the application can select the unique domains and write them out with PFWSET. Then all mappings can be written using PFWRAN which writes out a PM_mapping with a null domain. The post processing tools (such as PDBView) reconstruct the complete PM_mapping by looking for the domain as a variable with the same name as the domain component of the mapping name. This approach is clearly a little more involved than using PFWMAP and application developers should weigh the advantages and disadvantages before selecting one method over the other. See the previous example for an illustration of the use of PFWMAP.

 
 c-----------------------------------------------------------------
 c-----------------------------------------------------------------

  subroutine sxdmp(namesx, namelen)
 
 c traverse plot list to make dumps suitable for sx
 
  integer pfopen, pfclos, pfgerr, pfwmap, pfwset, pfwran
  integer zscanleq
  
  integer pderr(32), rp(6), dp(6)
  integer fileid, pim, dmnsn
 
  double precision rm(nsavept), dm(nsavept)
 
 c ... set up
             .
             .
             .
 
 c ... open the file
  fileid = pfopen(namelen, namesx, 'w')
  if (fileid .eq. -1) then
     iplpderr = pfgerr(nchr, pderr)
     call errproc(pderr, nchr, 0, 0)
  endif
 
  pim = 0
 
 c ... loop over plots
  do ...
 
 c ... setup domain
  dname = <;domain name>
  dp(1) = <;length of domain name>
 
  select case (dmnsn)
  case ('d2r1')
     dp(2) = 2
     dp(3) = 2
     dp(4) = nr
     dp(5) = kmax
     dp(6) = lmax
     call zmovewrd(dm(1), x2d, nr)
     call zmovewrd(dm(nr+1), y2d, nr)
  case ('d1r1')
     dp(2) = 1
     dp(3) = 1
     dp(4) = nr
     dp(5) = nr
     call zmovewrd(dm(1), <;domain data>, nr)
  endselect
 
  if <;unique domain> then
     ierr = pfwset(fileid, dname, dp, dm)
     if (ierr.eq.0) then
        iplpderr = pfgerr(nchr, pderr)
        call errproc(pderr, nchr, 0, 0)
     endif
  endif
 
 c ... set up range
  rname = <;range name>
  rp(1) = <;length of range name>
 
  rp(2) = dp(2)
  rp(3) = 1
  rp(4) = nr
  rp(5) = dp(5)
  rp(6) = dp(6)
  call zmovewrd(rm(1), <;range data>, nr)
 
 c ... write out range
  ierr = pfwran(fileid, dname, dp(1), rname, rp, rm, pim)
  if (ierr.eq.0) then
     pfgerr(nchr, pderr)
     call errproc(pderr, nchr, 0, 0)
  endif
  pim = pim+1
  repeat
 
 c ... close the file
  icloseok = pfclos(fileid)
  if (icloseok.eq.0) then
     pfgerr(nchr, pderr)
     call errproc(pderr, nchr, 0, 0)
  endif
 
  return
  end

 c-----------------------------------------------------------------
 c-----------------------------------------------------------------

SMP Parallel Example

This section will illustrate the use of PDBLib in a threaded program.


/*
 * PDSMP.C - Test smp i/o in PDBLib
 *
 * Source Version: 9.0
 * Software Release #: LLNL-CODE-422942
 *
 */

#include "cpyright.h"

#include "pdb.h"

#define NPTS 10

#define check_myplot1(xplot, rxplot)                                                                 \
        {int i;                                                                                      \
         if (strcmp(xplot.label, rxplot.label) != 0)                                                 \
            {printf("xplot.label differs from rxplot.label in %s\n", sname1);                        \
             printf("xplot.label: %s, rxplot.label: %s\n", xplot.label, rxplot.label);               \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot.view->x_min != rxplot.view->x_min)                                                \
            {printf("xplot.view->xmin differs from rxplot.view->xmin in %s\n", sname1);              \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot.view->x_max != rxplot.view->x_max)                                                \
            {printf("xplot.view->x_max differs from rxplot.view->x_max in %s\n", sname1);            \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot.view->y_min != rxplot.view->y_min)                                                \
            {printf("xplot.view->y_min differs from rxplot.view->y_min in %s\n", sname1);            \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot.view->y_max != rxplot.view->y_max)                                                \
            {printf("xplot.view->y_max differs from rxplot.view->y_max in %s\n", sname1);            \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot.npts != rxplot.npts)                                                              \
            {printf("xplot.npts differs from rxplot.npts in %s\n", sname1);                          \
             exit(1);}                                                                               \
                                                                                                     \
         for (i = 0; i < 10; i++)                                                                    \
             if (xplot.x_axis[i] != rxplot.x_axis[i])                                                \
                {printf("xplot.x_axis[%d] differs from rxplot.x_axis[%d] in %s\n", i, i, sname1);    \
                exit(1);};}            

#define check_myplot2(xplot, rxplot)                                                                 \
        {int i;                                                                                      \
         if (strcmp(xplot->label, rxplot->label) != 0)                                                   \
            {printf("xplot->label differs from rxplot->label in %s\n", sname1);                      \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot->view->x_min != rxplot->view->x_min)                                              \
            {printf("xplot->view->xmin differs from rxplot->view->xmin in %s\n", sname1);            \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot->view->x_max != rxplot->view->x_max)                                              \
            {printf("xplot->view->x_max differs from rxplot->view->x_max in %s\n", sname1);          \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot->view->y_min != rxplot->view->y_min)                                              \
            {printf("xplot->view->y_min differs from rxplot->view->y_min in %s\n", sname1);          \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot->view->y_max != rxplot->view->y_max)                                              \
            {printf("xplot->view->y_max differs from rxplot->view->y_max in %s\n", sname1);          \
             exit(1);}                                                                               \
                                                                                                     \
         if (xplot->npts != rxplot->npts)                                                            \
            {printf("xplot->npts differs from rxplot->npts in %s\n", sname1);                        \
             exit(1);}                                                                               \
                                                                                                     \
         for (i = 0; i < 10; i++)                                                                    \
             if (xplot->x_axis[i] != rxplot->x_axis[i])                                              \
                {printf("xplot->x_axis[%d] differs from rxplot->x_axis[%d] in %s\n", i, i, sname1);  \
                exit(1);};}        

struct s_l_frame
   {float x_min;
    float x_max;
    float y_min;
    float y_max;};

typedef struct s_l_frame l_frame;

struct s_plot
   {float x_axis[NPTS];
    float y_axis[NPTS];
    int npts;
    char *label;
    l_frame *view;};

typedef struct s_plot myplot;

float d[100], d2[100];

int   j[100], j2[100];
int n_iter = 10;

myplot mypl;

PDBfile *file, *file2;

int
 ok_count;

void *writeit(void *x);
void *writeit2(void *x);
void *readit(void *x);
void *readit2(void *x);
void print_help();

/*--------------------------------------------------------------------------*/
/*--------------------------------------------------------------------------    */

/* Write variables to the already opened file.  The number of variables written */
/* is a function of the number of iterations specified.                         */

void *writeit(arg)
   void *arg;
   {int i, n;
    myplot *xp;
    char sname1[100], sname2[100], sname3[100], suffix[10];

    xp = FMAKE(myplot, "Writeit:xp");
    xp->view = FMAKE(l_frame, "Writeit:xp->view");

    xp->label = SC_strsavef("Dynamic XP label", "char*:writeit:xp");
    xp->view->x_min = 0.2;
    xp->view->x_max = 0.9;
    xp->view->y_min = 0.33;
    xp->view->y_max = 0.99;
    xp->npts       = 10;

    for (i = 0; i < 10; i++)
        xp->x_axis[i] = xp->y_axis[i] = (float)i * 4.0;
         
    strcpy(sname1, "mypl_wr1a"); 
    strcpy(sname2, "xpl_wr1a"); 
    strcpy(sname3, "mypl_wr1b"); 

    for (n = 0; n < n_iter; n++)    
        {sprintf(suffix, "%d", n);

         strcpy(sname1+9, suffix);
         strcpy(sname2+8, suffix);
         strcpy(sname3+9, suffix);

        if (!PD_write(file, sname1, "myplot", &mypl))
           {printf("Error writing %s-exiting\n", sname1);
            exit(1);}

        if (!PD_write(file, sname2, "myplot *", &xp))
           {printf("Error writing %s-exiting\n", sname2);
            exit(1);}

        if (!PD_write(file, sname3, "myplot", &mypl))
           {printf("Error writing %s-exiting\n", sname3);
            exit(1);};}

    ok_count++;

    SFREE(xp->label);
    SFREE(xp->view);
    SFREE(xp);

    return(NULL);}
     
/*--------------------------------------------------------------------------*/
/*--------------------------------------------------------------------------*/

void *writeit2(arg)
   void *arg;
   {int i, n;
    char sname1[100], sname2[100], suffix[100];
    myplot xplot;

    xplot.label = SC_strsavef("Myplot Xplot label", "char*:writeit2:xplot");
    xplot.view = FMAKE(l_frame, "Xplot.view:writeit2");

    xplot.view->x_min = 0.15;
    xplot.view->x_max = 0.85;
    xplot.view->y_min = 0.25;
    xplot.view->y_max = 0.75;
    xplot.npts       = 10;

    for (i = 0; i < 10; i++)
        xplot.x_axis[i] = xplot.y_axis[i] = (float)i;

    strcpy(sname1, "mypl_wr2a"); 
    strcpy(sname2, "xpl_wr2a"); 

    for (n = 0; n < n_iter; n++)
        {sprintf(suffix, "%d", n);

         strcpy(sname1+9, suffix);
         strcpy(sname2+8, suffix);

         if (!PD_write(file, sname1, "myplot", &xplot))
            {printf("Error writing %s-exiting\n", sname1);
             exit(1);}       

         if (!PD_write(file, sname2, "myplot", &xplot))
            {printf("Error writing %s-exiting\n", sname2);
             exit(1);};}

    ok_count++;

    SFREE(xplot.label);
    SFREE(xplot.view);
 
    return NULL;}
     
/*--------------------------------------------------------------------------*/
/*--------------------------------------------------------------------------*/

void *readit(arg)
   void *arg;
   {int i, n;
    myplot *xp, *rxp, rmypl;
    char sname1[100], sname2[100], sname3[100], suffix[10];

    xp = FMAKE(myplot, "Writeit:xp");
    xp->view = FMAKE(l_frame, "Writeit:xp->view");

    xp->label = SC_strsavef("Dynamic XP label", "char*:writeit:xp");
    xp->view->x_min = 0.2;
    xp->view->x_max = 0.9;
    xp->view->y_min = 0.33;
    xp->view->y_max = 0.99;
    xp->npts       = 10;

    for (i = 0; i < 10; i++)
        xp->x_axis[i] = xp->y_axis[i] = (float)i * 4.0;

    strcpy(sname1, "mypl_wr1a"); 
    strcpy(sname2, "xpl_wr1a"); 
    strcpy(sname3, "mypl_wr1b"); 

    for (n = 0; n < n_iter; n++)    
        {sprintf(suffix, "%d", n);

         strcpy(sname1+9, suffix);
         strcpy(sname2+8, suffix);
         strcpy(sname3+9, suffix);

        if (!PD_read(file, sname1, &rmypl))
           {printf("Error writing %s-exiting\n", sname1);
            exit(1);}

/* compare with original */
        check_myplot1(mypl, rmypl);

/* free the memory */    
        SFREE(rmypl.label);
        SFREE(rmypl.view);

        if (!PD_read(file, sname2, &rxp))
           {printf("Error writing %s-exiting\n", sname2);
            exit(1);}

/* compare with original */
        check_myplot2(xp, rxp);

/* free the memory   */ 
        SFREE(rxp->label);
        SFREE(rxp->view);
        SFREE(rxp);

        if (!PD_read(file, sname3, &rmypl))
           {printf("Error writing %s-exiting\n", sname3);
            exit(1);};

/* compare with original */
	 check_myplot1(mypl, rmypl);

/* free the memory    */
	 SFREE(rmypl.label);
	 SFREE(rmypl.view);};

    ok_count++;

    SFREE(xp->label);
    SFREE(xp->view);
    SFREE(xp);

    return NULL;}
     
/*--------------------------------------------------------------------------*/
/*--------------------------------------------------------------------------*/

void *readit2(arg)
   void *arg;
   {int i, n;
    char sname1[100], sname2[100], suffix[100];
    myplot xplot, rxplot;

    xplot.label = SC_strsavef("Myplot Xplot label", "char*:writeit2:xplot");
    xplot.view = FMAKE(l_frame, "Xplot.view:writeit2");

    xplot.view->x_min = 0.15;
    xplot.view->x_max = 0.85;
    xplot.view->y_min = 0.25;
    xplot.view->y_max = 0.75;
    xplot.npts       = 10;

    for (i = 0; i < 10; i++)
        xplot.x_axis[i] = xplot.y_axis[i] = (float)i;

    strcpy(sname1, "mypl_wr2a"); 
    strcpy(sname2, "xpl_wr2a"); 

    for (n = 0; n < n_iter; n++)
        {sprintf(suffix, "%d", n);

         strcpy(sname1+9, suffix);
         strcpy(sname2+8, suffix);

         if (!PD_read(file, sname1, &rxplot))
            {printf("Error writing %s-exiting\n", sname1);
             exit(1);}       

/* compare with original */
         check_myplot1(xplot, rxplot);

/* free the memory    */
         SFREE(rxplot.label);
         SFREE(rxplot.view);

         if (!PD_read(file, sname2, &rxplot))
            {printf("Error writing %s-exiting\n", sname2);
             exit(1);};

/* compare with original */
         check_myplot1(xplot, rxplot);

/* free the memory    */
	 SFREE(rxplot.label);
	 SFREE(rxplot.view);};

    ok_count++;

    SFREE(xplot.label);
    SFREE(xplot.view);
 
    return(NULL);}
     
/*--------------------------------------------------------------------------*/
/*--------------------------------------------------------------------------*/

/* PRINT_HELP - print a help message */

void print_help()
   {

    PRINT(STDOUT, "\nPDSMP - run basic PDB smp test\n\n");
    PRINT(STDOUT, "Usage: pdsmp [-h] [-i n]\n");
    PRINT(STDOUT, "\n");
    PRINT(STDOUT, "       h - print this help message and exit\n");
    PRINT(STDOUT, "       i - set number of iterations in reading and writing loops to n\n");
    PRINT(STDOUT, "\n");

    return;}

/*--------------------------------------------------------------------------*/
/*--------------------------------------------------------------------------*/

main(argc, argv)
   int argc;
   char **argv;
   {int nthreads;
    int i;
    int nt[2];
    void *(*fnc[2])(void *);

    for (i = 1; i < argc; i++)
        {if (argv[i][0] == '-')
            {switch (argv[i][1])
                {case 'h' :
		      print_help();
		      return(1);

                 case 'i' :
		      n_iter = atol(argv[++i]);
		      break;};}
         else
            break;};

    ok_count = 0;

    printf("%d iterations per thread\n", n_iter);

/* load up the output arrays */
    for (i = 0; i < 100; i++)
	{d[i] = d2[i] = (float) i;
         j[i] = j2[i] = i;}

    nthreads = 5;

/* initialize PDBLib for 5 threads (includes main thread) */
    PD_init_threads(nthreads, NULL);

/* create the output file */
    if ((file = PD_open("ptest.pdb", "w")) == NULL)
       {printf("Error creating ptest.pdb\n");
	return(1);};

/* define the structures to the library */
    PD_defstr(file, "l_frame",
              " float x_min",
              "float x_max",
              "float y_min",
              "float y_max",
              LAST);

    PD_defstr(file, "myplot",
              "float x_axis(10)",
              "float y_axis(10)",
              "integer npts", 
              "char * label",
              "l_frame * view",
               LAST);

/* put some values in the structures */
    mypl.label = SC_strsavef("Myplot MYPL label", "PDPTST:main mypl");
    mypl.view  = FMAKE(l_frame, "Myplot MYPL view");

    mypl.view->x_min = 0.1;
    mypl.view->x_max = 0.8;
    mypl.view->y_min = 0.2;
    mypl.view->y_max = 0.7;
    mypl.npts       = 10;
   
    for (i = 0; i < 10; i++)
        mypl.x_axis[i] = mypl.y_axis[i] = (float)i;

    nt[0] = 1;
    nt[1] = 1;

/* two threads write the file */
    fnc[0] = writeit;
    fnc[1] = writeit2;
    SC_do_threads(2, nt, fnc, NULL, NULL);

/* flush the tables to the file */
    if (!PD_flush(file))
       {printf("Error flushing file before reads\n");
        return(1);};

/* two threads read the file */
    fnc[0] = readit;
    fnc[1] = readit2;
    SC_do_threads(2, nt, fnc, NULL, NULL);

/* close file */
    PD_close(file);

    return((ok_count != 4));}


MPI Parallel Example

This section illustrates the use of PDBLib in an MPI program.

/*
 * PDDMP.C - Test dmp i/o in PDBLib
 *
 * Source Version: 9.0
 * Software Release #: LLNL-CODE-422942
 *
 */

#include "cpyright.h"

#include "pdb.h"

#define N_INT 100
#define N_FLOAT 100
#define N_DOUBLE 100
#define N_PTS 10
#define N_ITER 10

#define TEST_TYPE(_x_)                                         \
   {if (_x_ == SC_COMM_SELF)                                  \
       printf("MPI_COMM_SELF test\n");                         \
    else                                                       \
       printf("MPI_COMM_WORLD test\n");}

#define check_myplot1(xplot, rxplot, _comm_)                                                                 \
        {int i;                                                                                              \
         if (strcmp(xplot.label, rxplot.label) != 0)                                                         \
            {printf("xplot.label differs from rxplot.label in %s\n", name);                                  \
             printf("xplot.label: %s, rxplot.label: %s\n", xplot.label, rxplot.label);                       \
             TEST_TYPE(_comm_);}                                                                             \
                                                                                                             \
         if (xplot.view->x_min != rxplot.view->x_min)                                                        \
            {printf("xplot.view->xmin differs from rxplot.view->xmin in %s\n", name);                        \
             TEST_TYPE(_comm_);}                                                                             \
                                                                                                             \
         if (xplot.view->x_max != rxplot.view->x_max)                                                        \
            {printf("xplot.view->x_max differs from rxplot.view->x_max in %s\n", name);                      \
             TEST_TYPE(_comm_);}                                                                             \
                                                                                                             \
         if (xplot.view->y_min != rxplot.view->y_min)                                                        \
            {printf("xplot.view->y_min differs from rxplot.view->y_min in %s\n", name);                      \
             TEST_TYPE(_comm_);}                                                                             \
                                                                                                             \
         if (xplot.view->y_max != rxplot.view->y_max)                                                        \
            {printf("xplot.view->y_max differs from rxplot.view->y_max in %s\n", name);                      \
             TEST_TYPE(_comm_);}                                                                             \
                                                                                                             \
         if (xplot.npts != rxplot.npts)                                                                      \
            {printf("xplot.npts differs from rxplot.npts in %s\n", name);                                    \
             TEST_TYPE(_comm_);}                                                                             \
                                                                                                             \
         for (i = 0; i < N_PTS; i++)                                                                         \
             if (xplot.x_axis[i] != rxplot.x_axis[i])                                                        \
                {printf("xplot.x_axis[%d] differs from rxplot.x_axis[%d] in %s\n", i, i, name);              \
                TEST_TYPE(_comm_);};}     

struct s_l_frame
   {float x_min;
    float x_max;
    float y_min;
    float y_max;};

typedef struct s_l_frame l_frame;

struct s_plot
   {float x_axis[N_PTS];
    float y_axis[N_PTS];
    int npts;
    char *label;
    l_frame *view;};

typedef struct s_plot myplot;
    
static float x[100], xr[100];
static int *pi1, *pi1r;
static float *pf1, *pf1r;
static myplot mypl, myplr;

static void write_data(char *path, int rank, int size, MPI_Comm comm);
static void read_data(char *path, int rank, int size, MPI_Comm comm);

main(argc, argv)
   int argc;
   char **argv;
   {int rank, size;
    char path[MAXLINE];
    PDBfile *file;


    MPI_Init(&argc, &argv);
    MPI_Comm_rank(SC_COMM_WORLD, &rank);
    MPI_Comm_size(SC_COMM_WORLD, &size);

/* if there is a command line argument it is the path of the directory
 * to write in
 */
    if (argc > 1)
       strcpy(path, argv[1]);
    else
       strcpy(path, "/home/foo");
       
/* initialize PDBLib for MPI 
 * master process:    0
 * number of threads: 1
 * tid function:      NULL
 */
    PD_init_mpi(0, 1, NULL);

    write_data(path, rank, size, SC_COMM_WORLD);

    write_data(path, rank, size, SC_COMM_SELF);

    read_data(path, rank, size, SC_COMM_WORLD);

    read_data(path, rank, size, SC_COMM_SELF);

    PD_term_mpi();

    MPI_Finalize();

    return(0);}

/*--------------------------------------------------------------------------    */
/*--------------------------------------------------------------------------*/

static void write_data(path, rank, size, comm)
   char *path;
   int rank, size;
   MPI_Comm comm;
   {char name[MAXLINE], temp[MAXLINE];
    char sx_axis[MAXLINE], sy_axis[MAXLINE];
    PDBfile *file;
    float frank;
    int i, nwrite;

    strcpy(name, path);
    strcat(name, "/");

    if (comm != SC_COMM_SELF)
       strcat(name, "test_mult.pdb");
    else
       {sprintf(temp, "test_single%d.pdb", rank);
        strcat(name, temp);}

/* create the output file */
    if ((file = PD_mp_create(name, comm))
         == NULL)
       {printf("Error creating %s\n", name);
	return;};

/* define the structures to the library */
    PD_defstr(file, "l_frame",
              " float x_min",
              "float x_max",
              "float y_min",
              "float y_max",
              LAST);

    sprintf(sx_axis, "float x_axis(%d)", N_PTS);
    sprintf(sy_axis, "float y_axis(%d)", N_PTS);

    PD_defstr(file, "myplot",
              sx_axis,
              sy_axis,
              "integer npts", 
              "char * label",
              "l_frame * view",
               LAST);

/* put some values in the structures */
    mypl.label = SC_strsavef("Myplot MYPL label", "PDDMP:main mypl");
    mypl.view  = FMAKE(l_frame, "Myplot MYPL view");

    mypl.view->x_min = 0.1;
    mypl.view->x_max = 0.8;
    mypl.view->y_min = 0.2;
    mypl.view->y_max = 0.7;
    mypl.npts       = N_PTS;
   
    for (i = 0; i < N_PTS; i++)
        mypl.x_axis[i] = mypl.y_axis[i] = (float)i;

/* write a struct */
    sprintf(name, "myplot_%d", rank);
    if (!PD_write(file, name, "myplot", &mypl))
       {printf("Error writing mypl: process %d\n", rank);}

/* write an integer */
    sprintf(name, "rank_%d", rank);
    if (!PD_write(file, name, "integer", &rank))
       {printf("Error writing rank: process %d\n", rank);}

/* write a float */
    frank = rank;
    sprintf(name, "frank_%d", rank);
    if (!PD_write(file, name, "float", &frank))
       {printf("Error writing frank: process %d\n", rank);}

/* write an int array */
    pi1 = FMAKE_N(int, N_INT, "WRITE_DATA:pi1");
    if (pi1 == NULL)
       {printf("Error allocating pi1, process %d--quitting\n", rank);
        exit(1);}
    for (i = 0; i < N_INT; i++)
        pi1[i] = rank * i;
    sprintf(name, "pi1_%d", rank);
    if (!PD_write(file, name, "int *", &pi1))
       {printf("Error writing pi1: process %d\n", rank);}

/* write an float array */
    pf1 = FMAKE_N(float, N_FLOAT, "WRITE_DATA:pf1");
    if (pf1 == NULL)
       {printf("Error allocating pf1, process %d--quitting\n", rank);
        exit(1);}
    for (i = 0; i < N_FLOAT; i++)
        pf1[i] = (float)(rank * i);
    sprintf(name, "pf1_%d", rank);
    if (!PD_write(file, name, "float *", &pf1))
       {printf("Error writing pf1: process %d\n", rank);}

/* try a PD_defent */
    if (!PD_defent(file, "x[100]", "float"))
       {printf("PD_defent failed for x[100], process %d\n",
                rank);}

    nwrite = (comm == SC_COMM_SELF) ? 100 : 100 / size;
    for (i = 0; i < 100; i++)
        x[i] = (float)rank;

    if (comm != SC_COMM_SELF)
       sprintf(name, "x[%d:%d]", rank*nwrite, (rank+1)*nwrite - 1);
    else
       strcpy(name, "x[0:99]");

    if (!PD_write(file, name, "float", x))
       {printf("Error writing x, process %d\n", rank);}

/* close file */
    PD_close(file);
    
    return;}
/*--------------------------------------------------------------------------    */
/*--------------------------------------------------------------------------*/

static void read_data(path, rank, size, comm)
   char *path;
   int rank, size;
   MPI_Comm comm;
   {char name[MAXLINE], temp[MAXLINE];
    PDBfile *file;
    int rankr;
    float frank;
    int i, nread;

    strcpy(name, path);
    strcat(name, "/");

    if (comm != SC_COMM_SELF)
       strcat(name, "test_mult.pdb");
    else
       {sprintf(temp, "test_single%d.pdb", rank);
        strcat(name, temp);}

/* open the input file */
    if ((file = PD_mp_open(name, "r", comm))
         == NULL)
       {printf("Error opening %s, rank: %d\n", name, rank);
        TEST_TYPE(comm); 
	return;};

/* read a struct */
    sprintf(name, "myplot_%d", rank);
    if (!PD_read(file, name, &myplr))
       {printf("Error reading mypl: process %d\n", rank);
        TEST_TYPE(comm);}

    check_myplot1(mypl, myplr, comm);

/* read an integer */
    sprintf(name, "rank_%d", rank);
    if (!PD_read(file, name, &rankr))
       {printf("Error reading rank: process %d\n", rank);
        TEST_TYPE(comm);}

    if (rankr != rank)
       {printf("Error: rankr != rank: process %d\n", rank);
        TEST_TYPE(comm);}

/* read a float */
    sprintf(name, "frank_%d", rank);
    if (!PD_read(file, name, &frank))
       {printf("Error reading frank: process %d\n", rank);
        TEST_TYPE(comm);}

    if (frank != (float)rank)
       {printf("Error: frank != rank: process %d\n", rank);
        TEST_TYPE(comm);}

/* read an int *array */
    sprintf(name, "pi1_%d", rank);
    if (!PD_read(file, name, &pi1r))
       {printf("Error reading pi1r: process %d\n", rank);
        TEST_TYPE(comm);}

    for (i = 0; i < N_INT; i++)
        if (pi1r[i] != pi1[i])
           {printf("Error: pi1r[%d] != pi1[%d], pi1r[%d] = %d, pi1[%d] = %d",
                    i, i, i, pi1r[i], i, pi1[i]);
            printf(" Process %d\n", rank);
            TEST_TYPE(comm);
            break;}

/* read a float array */
    sprintf(name, "pf1_%d", rank);
    if (!PD_read(file, name, &pf1r))
       {printf("Error reading pf1: process %d\n", rank);}

    for (i = 0; i < N_FLOAT; i++)
        if (pf1r[i] != pf1[i])
           {printf("Error: pf1r[%d] != pf1[%d], pf1r[%d] = %d, pf1[%d] = %d",
                    i, i, i, pf1r[i], i, pf1[i]);
            printf(" Process %d\n", rank);
            TEST_TYPE(comm);
            break;}

/* read the PD_defented array */
    nread = 100;
    strcpy(name, "x[0:99]");

    if (!PD_read(file, name, xr))
       {printf("Error reading x, process %d\n", rank);
        TEST_TYPE(comm);}

    if (comm == SC_COMM_SELF)
       {for (i = 0; i < 100; i++)
            if (xr[i] != x[i])
               {printf("Error: xr[%d] != x[%d], xr[%d] = %d, x[%d] = %d\n",
                       i, i, i, xr[i], i, x[i]);
                printf(" Process %d\n", rank);
                TEST_TYPE(comm);
                break;};}
    else
       {int nchunk = 100 / size;
        for (i = rank*nchunk; i < (rank+1)*nchunk; i++)
            if (xr[i] != (float)rank)
               {printf("Error: xr[%d] != rank, xr[%d] = %f, rank = %d\n",
                       i, i, xr[i], rank);
                printf(" Process %d\n", rank);
                TEST_TYPE(comm);
                break;};}

/* close file */
    PD_close(file);
    
    return;}

Related Documentation

PDBLib is one part of a collection of libraries called PACT. PDBLib uses the SCORE library in PACT for memory management, hash table, and string handling support. Interested readers should consult the SCORE manual as well as the PDBView manual, the ULTRA II manual, and the PANACEA manual for more information on how PDBLib is used.

The list of PACT documents is:

PACT User’s Guide

SCORE User’s Manual

PPC User’s Manual

PML User’s Manual

PDBLib User’s Manual

PGS User’s Manual

PANACEA User’s Manual

ULTRA II User’s Manual

PDBDiff User’s Manual

PDBView User’s Manual

SX User’s Manual


For questions and comments, please contact the PACT Development Team.
Last Updated: 02/03/2010
llnl logo  
  LLNL-CODE-422942| Privacy & Legal Notice
Last modified: January 28, 2010   
  
Contact: wci-webteam@llnl.gov