The first task to perform before any processing of NDF data can take place is
to gain access to an NDF data structure.
The creation of new NDFs (e.g. to contain output from an application)
is left until later (see §), when some of the concepts
involved should be clearer.
To start with, we assume that an NDF structure exists and that we are going to
write an application which needs to access it.
The normal method of obtaining access to an NDF for input is via a parameter, using the routine NDF_ASSOC which associates an NDF with the parameter:
INTEGER INDF
...
CALL NDF_ASSOC( 'IN', 'READ', INDF, STATUS )
Here, the `IN' is being used to obtain `READ' access to an NDF data structure. This means that we will be able to read values from the NDF, but not to modify it. An integer variable INDF is supplied to receive the returned NDF identifier value.
The effect of this call to NDF_ASSOC is that the programming environment will attempt to find a suitable pre-existing NDF data structure, most probably by prompting the person running the application to type in its name. If you are using ADAM, you have considerable control over exactly how the data structure is obtained, but none of this need be specified in the application. Instead, a separate interface file (with a file type of .ifl) is used for this purpose. Interface files are discussed in SUN/101 and full details can be found in the reference document SUN/115. Here, only a very simple interface file is given as an example:
interface PROG # The name of the application
parameter IN # The name of the parameter
prompt 'Input NDF data structure'
endparameter
endinterface
Other parameter entries may also be present in the same file (the text beginning with the `#' signs on the right is commentary and need not be included). In combination with the call to NDF_ASSOC, this interface file would result in a prompt, to which the user could respond with the name of an NDF data structure, most probably simply the name of an HDS container file, as follows:
IN - Input NDF data structure > datafile
Assuming that the data structure is a valid NDF, NDF_ASSOC will return an identifier for it via its INDF argument and this may then be passed to other NDF_ routines to access the NDF's values. If the data structure is not valid, then an error message will appear and the prompt will be repeated until a valid response is given or the user decides to give up (in ADAM this would be done by typing `!!' - the abort response). In this latter case, NDF_ASSOC will return with its STATUS argument set to an error value and INDF will be set to the value of the symbolic constant NDF__NOID, a universal value (defined in the include file NDF_PAR) which indicates that an NDF identifier is not valid.
Note that the routine NDF_EXIST may also be used to access NDF data
structures for input, but is more typically used during the creation of new
NDFs.
Its use is described later in §.