3 OBJECTS

3.1 Name
3.2 Type
3.3 Shape
3.4 State
3.5 Group
3.6 Value
3.7 Illustration

HDS files are known as container files and by default have the extension ‘.sdf’. HDS files contain data objects which will often be referred to simply as objects. An object is an entity which contains data or other objects. This is the basis of the hierarchical nature of HDS and is analogous to the concepts of file and directory – a directory can contain files and directories which can themselves contain files and directories and so on (see Fig 1).

An HDS object possesses a number of attributes, each of which is described in more detail below:

3.1 Name

The primary way of identifying an HDS object is by its name, which must be unique within its own container object. The name of an object is a character string which may contain any printing characters; white space is ignored and alphabetic characters are capitalised. The maximum length of an HDS name is 15 characters.

There are no special rules governing the first character (i.e. it can be numeric), so HDS itself allows great freedom in specifying names (and also types – see below). In practice, however, some restrictions will be imposed by considerations of portability of data and applications, and of possible syntax conflicts with the environment within which HDS is used.

3.2 Type

The type of an HDS object falls into two classes:

• Structure
• Primitive

Structure objects contain other objects called components. Primitive objects contain only numeric, character, or logical values. Objects in the different classes are referred to as structures and primitives while the more general term object refers to either a structure or a primitive. Structures are analogous to the directories in a filing system – they can contain a part of the hierarchy below them. Primitives are analogous to files – they are at the bottom of any branch of the structure and contain the actual data.

In HDS, structure types are represented by character strings with the same rules of formation as name, except that a structure type may not start with an underscore character ‘_’ (a structure type may also be completely blank). Examples of structure types are ‘IMAGE’, ‘SPECTRUM’, ‘INSTR_RESP’, etc. These do not begin with an underscore, so they are easily distinguished from the primitive types, which do.

Special rules apply to the primitive types, which all begin with an underscore and are “pre-defined” by HDS, as follows:

 HDS Type Fortran Type Description _INTEGER INTEGER Integer (signed) _INT64 INTEGER$\ast$8 64-bit Integer (signed) _REAL REAL Single precision _DOUBLE DOUBLE PRECISION Double precision _LOGICAL LOGICAL Logical _CHAR[$\ast$n] CHARACTER[$\ast$n] Character string _WORD INTEGER$\ast$2 Word (signed) _UWORD INTEGER$\ast$2 Unsigned word _BYTE BYTE Byte (signed) _UBYTE BYTE Unsigned byte

The first five of these primitive types are referred to as standard data types, since they correspond with standard Fortran 77 data types. The last four are non-standard data types and are typically required to accommodate raw data from instrumental hardware, which may generate numbers in these formats. The range of values which may be stored in each primitive numeric type is determined by the numerical capabilities of your machine and the particular implementation of Fortran you are using. Details of HDS, which include information about the properties of the primitive data types on the system you are using, may be found in the file:

hds_machine

in the directory \$STARLINK_DIR/help.

The rules by which character values are handled by HDS is the same as for Fortran 77, i.e. character values are padded with blanks or truncated from the right depending on the relative length of the program value and the object.

3.3 Shape

Every HDS object has a shape or dimensionality. This is described by an integer (the number of dimensions) and an integer array (containing the size of each dimension). A scalar (for example a single number) has, by convention, a dimensionality of zero; i.e. its number of dimensions is 0. A vector has a dimensionality of 1; i.e. its number of dimensions is 1, and the first element of the dimension array contains the size of the vector. An array refers to an object with 2 or more dimensions; a maximum of 7 dimensions are allowed. Objects may be referred to as scalar primitives or vector structures and so on.

3.4 State

The state of an HDS object specifies whether or not its value is defined. It is represented as a logical value where .TRUE. means defined and .FALSE. means undefined.

Objects start out undefined when they are created and become defined when you write a value to them. In general, an error will result if you attempt to obtain the value of an object while it is still undefined.

3.5 Group

In order to access an HDS object it is first necessary to “associate” a locator with it (like opening a file). This locator can then be used to address the object. When the program no longer needs to access the object the locator should be “annulled” (like closing the file again). A locator is roughly analogous to a Fortran logical unit number (but is actually a character variable, not an integer). The group attribute is used to form an association between objects so that all their locators can be annulled together. A group is written as a character string whose rules of formation are the same as for name.

3.6 Value

When a primitive object is first created it contains no value (rather like opening a file) and it must be given a value in a separate operation. A value can be a scalar, a vector or an array. The elements of a vector or array must all be of the same type.

3.7 Illustration

To fix these ideas, look at the example below. Here we have described a structure of type ‘NDF’ using the following notation to describe each object:

NAME[(dimensions)] <TYPE> [value]

Note that scalar objects have no dimensions and that each level down the hierarchy is indented.

DATASET <NDF>
DATA_ARRAY(512,1024)    <_UBYTE>   0,0,0,1,2,3,255,3,...
LABEL                   <_CHAR*80> ’This is the data label’
AXIS(2) <AXIS>
AXIS <AXIS>
DATA_ARRAY(512)   <_REAL>    0.5,1.5,2.5,...
LABEL             <_CHAR*30> ’Axis 1’
AXIS <AXIS>
DATA_ARRAY(1024)  <_REAL>    5,10,15.1,20.3,...
LABEL             <_CHAR*10> ’Axis 2’

This example exhibits several of the properties mentioned above:

• Both structures and primitives are present in the structure.
• Scalar and non-scalar objects are present.
• The AXIS component is a vector structure (with two elements).