5 CREATING OBJECTS

Here is an example showing how to create the NDF structure in §3.7.

The following points should be borne in mind:

• The structure we have created is in no way static – we can add new objects or delete existing ones at any level without disturbing what already exists.
• No primitive values have been stored yet (i.e. the structure does not yet contain any data) – we will do that next.
• All new container files are created using the disk format indicated by the “VERSION” tuning parameter.

Here are some notes on particular aspects of this example:

DAT__SZLOC:

This is an INTEGER constant which is defined in the include file DAT_PAR and specifies the length in characters of all HDS locators. Similar constants, DAT__SZNAM and DAT__SZTYP, specify the maximum lengths of object names and types.

STATUS:

HDS routines conform to Starlink error handling conventions (described fully in SUN/104) and use inherited status checking. This normally means (unless otherwise noted in the routine description) that if the STATUS variable is not set to a value indicating success on entry (STATUS=SAI__OK), then the subroutine will exit without action. This behaviour can be very useful in reducing the effort required to check properly for all possible error conditions.

HDS_NEW:

A container file called “dataset” is created (HDS provides the default file extension of ‘.sdf’). A scalar structure called DATASET with a type of ‘NDF’ is created within this file, and a locator (NLOC) is associated with this structure. It is usually convenient, although not essential, to make the top-level object name match the container file name, as here.

DAT_NEW/DAT_NEWC:

These routines create new objects within HDS itself – they are not equivalent to HDS_NEW because they don’t have any reference to the container file, only to a higher level structure.

We use two variants of this routine simply because the character string length has to be specified when creating a character object and it is normally most convenient to provide this via an additional integer argument. However, DAT_NEW may be used to create new objects of any type, including character objects. In this case the character string length would be provided via the type specification, e.g. ‘_CHAR$\ast$15’ (a character string length of one is assumed if ‘_CHAR’ is specified alone).

DAT_FIND:

After an object has been created it is necessary to associate a locator with it before values can be inserted into it; DAT_FIND performs this function.

DAT_CELL:

There are several routines for accessing subsets of objects. DAT_CELL obtains a locator to a scalar object (structure or primitive) within a non-scalar object like a vector.

DAT_ANNUL:

This is used to release a locator (just as CLOSE releases a logical unit number in Fortran). It also closes the container file when it is no longer being used.