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:

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. ‘_CHAR15’ (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.