Next: NDF_PLACE - Obtain an NDF placeholder
Up: FORTRAN ROUTINE DESCRIPTIONS
Previous: NDF_NOACC - Disable a specified type of access to an 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).
Next: NDF_PLACE - Obtain an NDF placeholder
Up: FORTRAN ROUTINE DESCRIPTIONS
Previous: NDF_NOACC - Disable a specified type of access to an NDF
Starlink User Note 33
R.F. Warren-Smith
11th January 2000
E-mail:rfws@star.rl.ac.uk
Copyright © 2000 Council for the Central Laboratory of the Research Councils