### 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:

<pkg>_<func><qual>

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:

<declarations>

INCLUDE ’SAE_PAR’
INCLUDE ’DAT_PAR’
INCLUDE ’DAT_ERR’
INCLUDE ’CMP_ERR’

STATUS = SAI__OK

<executable statements>

END

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:

INCLUDE ’SAE_PAR’
INCLUDE ’DAT_PAR’
INCLUDE ’DAT_ERR’
...

CHARACTER * ( DAT__SZLOC ) LOC1, LOC2
CHARACTER * ( DAT__SZNAM ) NAME
INTEGER STATUS
...

* Find a structure component.
CALL DAT_FIND( LOC1, NAME, LOC2, STATUS )

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