3 Using the package

Two main uses for this package are foreseen:

(1)
To maintain a catalogue of HDS objects.
(2)
To avoid duplicating a large dataset.

As an example of the second case, suppose that a large dataset is logically required to form part of a number of other datasets. To avoid duplicating the common dataset, the others may contain a reference to it.

For example:

     Name                type                  Comments
  
  DATA                DATA_SETS
    .SET1             SPECTRUM
       .AXIS1         _REAL(1024)          Actual axis data
       .DATA_ARRAY    _REAL(1024)
    .SET2             SPECTRUM
       .AXIS1         REFERENCE_OBJ        Reference to DATA.SET1.AXIS1
       .DATA_ARRAY    _REAL(1024)
    .SET3             SPECTRUM
       .AXIS1         REFERENCE_OBJ        Reference to DATA.SET1.AXIS1
       .DATA_ARRAY    _REAL(1024)
     -
    etc.

Then a piece of code which handles structures of type SPECTRUM, which would normally contain the axis data in .AXIS1 (as SET1 does), could be modified as follows to handle an object .AXIS1 containing either the actual axis data or a reference to the object which does contain the actual axis data.

  *    LOC1 is a locator associated with a SPECTRUM object
  *    Obtain locator to AXIS data
        CALL DAT_FIND(LOC1, ’AXIS1’, LOC2, STATUS)
  *    Modification to allow AXIS1 to be a reference object
  *    Check type of object
        CALL DAT_TYPE(LOC2, TYPE, STATUS)
        IF (TYPE .EQ. ’REFERENCE_OBJ’) THEN
            CALL REF_GET(LOC2, ’READ’, LOC3, STATUS)
            CALL DAT_ANNUL(LOC2, STATUS)
            CALL DAT_CLONE(LOC3, LOC2, STATUS)
            CALL DAT_ANNUL(LOC3, STATUS)
        ENDIF
  *    End of modification
  *    LOC2 now locates the axis data wherever it is.

This code has been packaged into the subroutine REF_FIND which can be used instead of DAT_FIND in cases where the component requested may be a reference object.

When a locator which has been obtained in this way is finished with, it should be annulled using REF_ANNUL rather than DAT_ANNUL. This is so that, if the locator was obtained via a reference, the HDS_OPEN for the container file may be matched by an HDS_CLOSE. Note that this should only be done when any other locators derived from the locator to the referenced object are also finished with.