CREATING OBJECTS

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

      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.

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*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.