ROUTINE DESCRIPTIONS

This appendix gives specifications for all the stand-alone HDS routines. Some general information on the most common parameters is given below:

• dim, dimx, ndim, ndimx: Parameters dim and ndim specify the shape of an object; dimx and ndimx specify the largest permitted values of dim and ndim. The vector dim holds the sizes of the object dimensions. Thus dim(1) holds the size of the first dimension, dim(2) holds the size of the second dimension, and so on. The integer ndim holds the number of dimensions in an object. HDS supports a maximum of seven object dimensions, thus dim should have a maximum of seven elements and ndim should not be more than 7. The values of dim and ndim must match the actual shape of the object being processed. A value of zero for ndim denotes a scalar object; any value specified for dim will be ignored in this case. A vector containing a single value is different from a scalar.

• el, elx: When an object is a vector (or is treated as one), el holds the number of elements in the vector. When a vector is being read (as in the GET routines), the actual number of elements may be unknown. In this case elx holds the maximum permissible number of elements. This should be equal to the size of the value array which is to receive the vector.

• loc, loc1, loc2, loc3: A locator is a CHARACTER*(DAT__SZLOC) variable, substring or array element used to "locate" objects within the data system. The contents are used by HDS to access internal information and must not be altered explicitly by a program. When more than one routine parameter is a locator, loc1, loc2 and loc3 are used to identify them. The locator for a structure array refers to the array as a whole. Each element of a structure array is itself a structure If you wish to address an element of a structure array you must obtain a new locator for it (using DAT_CELL). It is important to distinguish between routines which operate on structures and those which operate on arrays.

• name: This is a character value specifying the name of an object. A name is written as a character string containing any printing characters. White space is ignored and alphabetic characters are capitalised. There are no special rules governing the first character (i.e. it can be numeric).

• pntr: Routines which map an object value return a pointer to the first element of that object in the parameter pntr. This can be converted to a normal array reference by use of the non-standard Fortran "%VAL" facility together with the CNF_PVAL function as shown in § and §.

• status: This receives the HDS status value. If, on entry, a routine finds that status is not equal to SAI__OK it assumes an error has occurred previously and returns immediately without action. This allows tests of status to be deferred until after several routine calls have been made. If a routine detects an error itself, it will set status to one of the error codes specified in Appendix  and will make an error report in the usual manner (see SUN/104). Where exceptions to this behaviour exist, they are documented in the individual routine descriptions.

• type: This specifies the data type the program wishes to use when manipulating a value. This may be different from the data type used to store the value. We will call the type used by the program the access type and the type used to store the value the storage type. If these two types differ, automatic conversion is performed. This is particularly relevant to the GET, PUT and MAP routines. The types specified in the names or the type parameter of these routines refer to the access type, thus CMP_GET0I will read a scalar component and present it to the program as an integer, no matter how that value is stored in the container file. Thus, type means access type; it also specifies the storage type in routines which write a value.

• value: This holds the value of a primitive and could be a scalar, vector or an array. If a value is being read, the size and shape of the vector or array value should match the shape of the object. In some routines value holds a "vectorised" object value. This means that the value will be addressed as a linear sequence of elements instead of as its normal structure. The effect of this depends on how a structure is mapped. The purpose of vectorising an array is to enable a simple operation (e.g. adding a constant) to be carried out on every element without bothering about how each element should be addressed