4 ROUTINES AND CONSTANTS

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:

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:

SAE_PAR:

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.

DAT_PAR:

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

DAT_ERR:

This defines symbolic names for the error status values returned by the DAT_ and HDS_ routines.

CMP_ERR:

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: