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 §7 and §8.
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 E 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