4.1 Routine Names
 4.2 Symbolic Names and Include Files

4.1 Routine Names

HDS objects are created, accessed, modified and deleted in programs by means of calls to HDS routines. The routine names have the following structure:


where <pkg> is the “package name”, <func> represents the function performed by the routine and <qual> is a qualifier which is used to identify different versions of the GET, MAP, MOD, NEW and PUT routines.

4.2 Symbolic Names and Include Files

Stand-alone HDS programs will typically have the following structure:

  <executable statements>

Various symbolic names should be used for important constant values in HDS programs to make the programs clear, portable and to insulate them from possible future changes. These symbolic names are defined by several Fortran “include” files. This explains the existence of the INCLUDE statements in the example above. The following include files are available:

This file is not actually part of HDS, but it defines the global symbolic constant SAI__OK (the value of the status return indicating success) and will be required by nearly all routines which call HDS. It should normally be included as a matter of course.
Defines various symbolic constants for HDS. These should be used whenever the associated value is required (typically this is when program variables are defined):
DAT__MXDIM Maximum number of object dimensions
DAT__NOLOC Null (invalid) locator value
DAT__NOWLD Null wild-card search context
DAT__SZGRP Size of group name
DAT__SZLOC Size of locator
DAT__SZMOD Size of access mode string
DAT__SZNAM Size of object name
DAT__SZTYP Size of type string
This defines symbolic names for the error status values returned by the DAT_ and HDS_ routines.
This defines symbolic names for the additional error status values returned by the CMP_ routines.

If it is required to test for specific error conditions, the appropriate include file should be used and the symbolic names (listed in Appendix E) used in the test. Here is an example of how to use these symbols:

  * Find a structure component.
  * Check the status value returned.
        IF ( STATUS .EQ. SAI__OK ) THEN
           <normal action>
           <take appropriate action for object not found>
           <action on other errors>
        END IF