NDF_OPEN - Open an existing or new NDF

Description:

The routine finds an existing NDF data structure and returns an identifier for it, or creates a placeholder for a new NDF.

Invocation:

CALL NDF_OPEN( LOC, NAME, MODE, STAT, INDF, PLACE, STATUS )

Arguments:

LOC = CHARACTER $*$ ( $*$ ) (Given)

Locator to the enclosing HDS structure.

NAME = CHARACTER $*$ ( $*$ ) (Given)

Name of the HDS structure component.

MODE = CHARACTER $*$ ( $*$ ) (Given)

Type of NDF access required: 'READ', 'UPDATE' or 'WRITE'.

STAT = CHARACTER $*$ ( $*$ ) (Given)

The state of the NDF, specifying whether it is known to exist or not: 'NEW', 'OLD', or 'UNKNOWN'.

INDF = INTEGER (Returned)

NDF identifier.

PLACE = INTEGER (Returned)

NDF placeholder identifying the nominated position in the data system.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• If the STAT argument is set to 'NEW', then this routine will return a placeholder for a new NDF. If STAT is set to 'OLD', it will search for an existing NDF. If STAT is set to 'UNKNOWN', it will first search for an existing NDF but will return a placeholder for a new NDF if an existing one cannot be found.

• If this routine succeeds, then a valid value will be returned for INDF if the NDF already existed, or for PLACE if it did not exist. The unused return argument will be set to the appropriate null value (NDF__NOID or NDF__NOPL respectively).

• If 'WRITE' access is specified for an existing NDF, then all the NDF's components will be reset to an undefined state ready to receive new values. If 'UPDATE' access is specified, the NDF's components will retain their values, which may then be modified.

• An error will result if the STAT argument is set to 'OLD' but no existing NDF could be found. An error will also result if a placeholder for a new NDF is to be returned but 'READ' access was requested.

• The value given for the NAME argument may be an HDS path name, consisting of several fields separated by '.', so that an NDF can be opened in a sub-component (or a sub-sub-component...) of the structure identified by the locator LOC. Array subscripts may also be used in this component name. Thus a string such as 'MYSTRUC.ZONE(2).IMAGE' could be used as a valid NAME value.

• An NDF can be opened within an explicitly named container file by supplying the symbolic value DAT__ROOT for the LOC argument and giving a full HDS object name (including a container file specification) for the NAME argument.

• If a blank value is given for the NAME argument, then the NDF will be the object identified directly by the locator LOC.

• If a placeholder is to be returned and the new NDF is to be a top-level object, then a new container file will be created. Otherwise, the container file and all structures lying above the new NDF should already exist.

• If the LOC and NAME arguments identify a pre-existing object which is not a top-level object, then this may be used as the basis for the new NDF. An object which is to be used in this way must be an empty scalar structure with an HDS type of 'NDF'.

• The locator supplied as input to this routine may later be annulled without affecting the behaviour of the NDF_ system.

• If this routine is called with STATUS set, then a value of NDF__NOPL will be returned for the PLACE argument, and a value of NDF__NOID will be returned for the INDF argument, although no further processing will occur. The same values will also be returned if the routine should fail for any reason.

• The NDF__NOPL and NDF__NOID constants are defined in the include file NDF_PAR. The DAT__ROOT constant is defined in the include file DAT_PAR (see SUN/92).