### 5 CREATING OBJECTS

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

INCLUDE ’SAE_PAR’
INCLUDE ’DAT_PAR’
CHARACTER * ( DAT__SZLOC ) NLOC, ALOC, CELL
INTEGER DIMS( 2 ), STATUS
DATA DIMS / 512, 1024 /

*  Create a container file with a top level scalar object of type NDF.
CALL HDS_NEW( ’dataset’, ’DATASET’, ’NDF’, 0, 0, NLOC, STATUS )

*  Create components in the top level object.
CALL DAT_NEW( NLOC, ’DATA_ARRAY’, ’_UBYTE’, 2, DIMS, STATUS )
CALL DAT_NEWC( NLOC, ’LABEL’, 80, 0, 0, STATUS )
CALL DAT_NEW( NLOC, ’AXIS’, ’AXIS’, 1, 2, STATUS )

*  Create components in the AXIS structure...

*  Get a locator to the AXIS component.
CALL DAT_FIND( NLOC, ’AXIS’, ALOC, STATUS )

*  Get a locator to the array cell AXIS(1).
CALL DAT_CELL( ALOC, 1, 1, CELL, STATUS )

*  Create internal components within AXIS(1) using the CELL locator.
CALL DAT_NEW( CELL, ’DATA_ARRAY’, ’_REAL’, 1, DIM( 1 ), STATUS )
CALL DAT_NEWC( CELL, ’LABEL’, 30, 0, 0, STATUS )

*  Annul the cell locator
CALL DAT_ANNUL( CELL, STATUS )

*  Do the same for AXIS(2).
CALL DAT_CELL( ALOC, 1, 2, CELL, STATUS )
CALL DAT_NEW( CELL, ’DATA_ARRAY’, ’_REAL’, 1, DIM( 2 ), STATUS )
CALL DAT_NEWC( CELL, ’LABEL’, 10, 0, 0, STATUS )
CALL DAT_ANNUL( CELL, STATUS )

*  Access objects which have been created.
...

*  Tidy up
CALL DAT_ANNUL( ALOC, STATUS )
CALL DAT_ANNUL( NLOC, STATUS )

END

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.