Previous: General remarks
Up: General remarks
Previous Page: General remarks
Next Page: General

Example:

The dsdef call above could be written in C like that:

if( !dsdef(".CHAR24","C*24",0,1,"C Character*24",&iv,&ierr))
       {
        printf("Error defining .CHAR24: %i\n",ierr);
        exit(-1);
       }

All character strings used as arguments in C calls must be NULL terminated, even if they are used to return data.

DSPACK makes no attempt to align data. The mininum data 'chunk' is a 4 byte word. The proper alignment should be ensured when defining objects. DSPACK will always assumme that objects are exacly as they are defined and once the number of 4 byte words per objects entry is calculated it is used when moving data. In particular if an element of a structure is of type character it must have the correct number of bytes independently of NULL termination.

Many routines have the list of arguments starting from

NAME

- data set name

*IVDSN*

- data set handle

Unless explicitly stated that 'name' may refer to an 'item' - the name must be a full name of a data set.

IVDSN is a data set handle. DSPACK treats it as follows:

• If IVDSN=0 a search for name is performed and ivdsn is set to correct value. If the search fails IVDSN is set to a negative of the current number of defined data sets.
• If IVDSN>0 and name does not start from '-' - DSPACK checks whether the handle corresponds to the name. If it does not DSPACK acts as if IVDSN=0
• If name starts from '-' DSPACK assummes that ivdsn is correct and does not touch or check it.
• If IVDSN<0 it is checked against the current number of defined data sets. If the number of data sets changed since the last failure for this data set - the search is performed as if IVDSN=0. If no new data sets were defined DSPACK does nothing.

Consequently - a separate variable should be used for ivdsn for each call. It should be preset to 0 before the first call and never touched again. Once found the handle is always valid and allows DSPACK to find the data quickly. It should be included in a SAVE statement in fortran and declared static in C.

As a convention here all returned arguments are marked with an asterisk (Êarg*Ê) and all arguments which are both input and output are marked with preceeding and following asterisk (Ê*arg*Ê)

Fortran and C calls are shown for each routine. Unless explicitly shown otherwise fortran calls are implemented as subroutines. For C calls the return value is usually the same as ierr except if the function returns a pointer.

For succesful return ierr=0.

All arguments containing names are of type character, all others are integer.