Next: CMP_GET0x - Read scalar component
Up: HDS Hierarchical Data System
Previous: ALPHABETICAL LIST OF HDS ROUTINES
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
Next: CMP_GET0x - Read scalar component
Up: HDS Hierarchical Data System
Previous: ALPHABETICAL LIST OF HDS ROUTINES
HDS Hierarchical Data System
Starlink User Note 92
R.F. Warren-Smith & M.D. Lawden
23rd February 1999
E-mail:rfws@star.rl.ac.uk
Copyright (C) 1999 Central Laboratory of the Research Councils