next up previous
Next: Creating New Extensions
Up: EXTENSIONS
Previous: The Contents of Extensions

Accessing Existing Extensions   

The existence or non-existence of a specified extension in an NDF can be determined using the routine NDF_XSTAT. For instance:

      CALL NDF_XSTAT( INDF, 'IRAS', THERE, STATUS )

will return a .TRUE. value via the logical argument THERE if an extension called `IRAS' is present in an NDF. If it is, then it can be accessed using the routine NDF_XLOC. For instance:

      CHARACTER * ( DAT__SZLOC ) LOC

      ...

      CALL NDF_XLOC( INDF, 'IRAS', 'READ', LOC, STATUS )

will return an HDS locator to the extension (which is an HDS object) via the LOC argument.[*]

Note that an access mode of `READ' was specified in this call to NDF_XLOC, indicating that the extension's contents would be read but not modified. An access mode of `UPDATE' would be used if the contents were to be modified, while `WRITE' access would only be used in order to re-write the extension's contents; in this case the NDF_ system will erase any previous contents before returning a locator to the extension.

The contents of an extension can be accessed by passing the resulting locator to suitable HDS routines. For instance, the value of an integer component called OFFSET within the `IRAS' extension could be obtained as follows:

      CHARACTER * ( DAT__SZLOC ) LOC
      INTEGER OFFSET

      ...

      CALL NDF_XLOC( INDF, 'IRAS', 'READ', LOC, STATUS )
      CALL CMP_GET0I( LOC, 'OFFSET', OFFSET, STATUS )
      CALL DAT_ANNUL( LOC, STATUS )

Note that the extension locator LOC must be annulled using the routine DAT_ANNUL when it is no longer required, since the NDF_ system will not perform this task itself.

This process of reading a scalar value from a component within an NDF extension is sufficiently common that a set of routines is provided to do it directly. These routines have names of the form NDF_XGT0x, where the (lower-case) ``x'' represents one of the standard Fortran 77 types and should be replaced by I, R, D, L or C, according to the type of value required. For instance, the above operation of reading an integer value from an `IRAS' extension could also be performed with a single call to NDF_XGT0I, as follows:

      CALL NDF_XGT0I( INDF, 'IRAS', 'OFFSET', OFFSET, STATUS )

These routines also have the advantage that they will accept a compound HDS component name as their third argument, making it possible to access components nested within sub-structures inside an extension. Array subscripts may also be specified, so that individual elements of non-scalar components and extensions may be accessed. For example:

      CALL NDF_XGT0C( INDF, 'FITS', '(13)', RECORD, STATUS )

Would read the 13th element from a `FITS' extension which consists of a 1-dimensional array of character strings.



next up previous
Next: Creating New Extensions
Up: EXTENSIONS
Previous: The Contents of Extensions


Starlink User Note 33
R.F. Warren-Smith
11th January 2000
E-mail:rfws@star.rl.ac.uk

Copyright © 2000 Council for the Central Laboratory of the Research Councils