2 Associating with an Object

If you just want to perform some operations on an existing HDS object using basic HDS subroutines, you need an HDS locator (see SUN/92) for the object and usually you will want to specify the name of the object as a parameter of the program.

The DAT_ASSOC routine will associate an object with a program parameter and return a locator for it. The association can be cancelled and the locator annulled by calling DAT_CANCL.

  INCLUDE ’DAT_PAR’
  
  INTEGER STATUS
  CHARACTER*(DAT__SZLOC) LOC
  
  CALL DAT_ASSOC( ’OBJECT’, ’READ’, LOC, STATUS )
  
  ... HDS operations ...
  
  CALL DAT_CANCL( ’OBJECT’, STATUS )

If DAT_ASSOC fails to associate the parameter with an object it will report the problem and prompt for a new value. It will do this up to five times before giving up and returning status PAR__NULL.

DAT_EXIST is similar to DAT_ASSOC but it will return immediately if the association fails. It can therefore be used to test for the existence of an object. Status PAR__ERROR (not DAT_EXIST, for historical reasons) will be returned if the object does not exist, but the parameter value will not be cancelled so a subsequent HDSPAR subroutine call (such as DAT_CREAT) specifying the same parameter would not prompt for a new object name. See the example in Section 10 for an illustration of this.

The ACCESS Field (see SUN/115) specified in the Interface Module for the program must be compatible with the access mode specified in the DAT_ASSOC or DAT_EXIST call, otherwise status SUBPAR_ICACM will be returned.

Both routines may be called more than once for the same parameter but DAT_CANCL must be called to cancel an existing association if a different object is required (see ‘Parameter States’, Section 3).