NDG_ASSOC - Store names of existing NDFs specified through the environment

Description:

A group expression is obtained from the environment using the supplied parameter. The expression is parsed (using the facilities of the GRP routine GRP_GROUP, see SUN/150) to produce a list of explicit names for existing NDFs which are appended to the end of the supplied group (a new group is created if none is supplied). If an error occurs while parsing the group expression, the user is re-prompted for a new group expression. NDF identifiers for particular members of the group can be obtained using NDG_NDFAS.

Invocation:

CALL NDG_ASSOC( PARAM, VERB, IGRP, SIZE, FLAG, STATUS )

Arguments:

PARAM = CHARACTER$*$($*$) (Given)

The parameter with which to associate the group expression.

VERB = LOGICAL (Given)

If TRUE then errors which occur whilst accessing supplied NDFs are flushed so that the user can see them before re-prompting for a new NDF ("verbose" mode). Otherwise, they are annulled and a general "Cannot access file xyz" message is displayed before re-prompting.

IGRP = INTEGER (Given and Returned)

The identifier of the group in which the NDF names are to be stored. A new group is created if the supplied value is GRP__NOID. It should be deleted when no longer needed using GRP_DELET.

SIZE = INTEGER (Returned)

The total number of NDF names in the returned group.

FLAG = LOGICAL (Returned)

If the group expression was terminated by the GRP "flag character", then FLAG is returned true. Otherwise it is returned false. Returned .FALSE. if an error occurs.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

• Any file names containing wildcards or "[..]" globbing patterns are expanded into a list of NDF names. The supplied strings are interpreted by a shell (/bin/tcsh if it exists, otherwise /bin/csh, otherwise /bin/sh), and so may contain shell meta-characters (e.g. twiddle, $HOME, even command substitution and pipes - but pipe characters "$\vert$" need to be escaped using a backslash "$\backslash$" to avoid them being interpreted as GRP editing characters).

• Each supplied name may include an HDS path. For instance, "/home/dsb/mydata.a.c(1).b" refers to an NDF stored in component "a.c(1).b" in the HDS container file /home/dsb/mydata.sdf. Note, wild cards are not allowed within HDS component paths (i.e. they are only allowed within the specification of the container file).

• If an HDS object is specified which is not an NDF, then the object will be searched for NDF components. This search is recursive, in that any components of the specified object are also searched. The supplied name will be expanded into a group of names, one for each NDF found within the specified HDS object. Note, NDFs are not themselves searched for other NDFs. That is, the expanded group of names will not include any NDF which is contained within another NDF (i.e. NDFs which are stored as an extension item of another NDF are not included in the group). For instance, if the string "fred" is given, the HDS file fred.sdf will be searched for NDFs and the returned group will contain references for all NDFs found within fred.sdf.

• If the environment variable NDF_FORMATS_IN is defined (see SSN/20) then only the highest priority file with any give file name is included in the returned group. The priority of a file is determined by its file type. Native NDFs (.sdf) have highest priority. After that, priority decreases along the list of file types specified in NDF_FORMATS_OUT. If no file type is given by the user, the highest priority available file type is used. If an explicit file type is given, then that file type is used.

• Care should be taken if a trailing string enclosed in square brackets is appended to the end of the file name. These are interpreted first as a globbing pattern. Thus "fred[12]" would match files with base names "fred1" and "fred2". If the pattern does not match any existing files, then the trailing "[..]" string is next interpreted as a foreign extension specifier. Thus if fred.fit is a multi-extension FITS file, "fred[12]" would be interpreted as the twelfth image extension in fred.fit only if files cannot be found with basenames "fred1" or "fred2".

• NDFs contained within HDS files are opened in order to ensure that they are valid NDFs. The user is notified if there are no valid NDFs matching a supplied name, and they are asked to supply a replacement parameter value. No check is made that any foreign data files contain valid NDFs since this would involve a potentially expensive data conversion. So, for instance, "$*$.fit" could pick up FITS catalogues as well as FITS images. If a foreign data file does not contain a valid NDF, an error will be reported when the NDF is accessed using NDG_NDFAS.

• Each element in the returned group contains a full specification for an NDF. Several other groups are created by this routine, and are associated with the returned group by means of a GRP "owner-slave" relationship. These supplemental groups are automatically deleted when the returned group is deleted using GRP_DELET. The returned group should not be altered using GRP directly because corresponding changes may need to be made to the supplemental groups. Routines NDG_SETSZ, NDG_GTSUP and NDG_PTSUP are provided to manipulate the entire chain of groups. The full chain (starting from the head) is as follows:

• NDF slice specifications

• HDS paths

• File types

• Base file names

• Directory paths

• Full NDF specification (this is the returned group IGRP)

• If an error is reported the group is returned unaltered. If no group is supplied, an empty group is returned.

• A null value (!) can be given for the parameter to indicate that no more NDFs are to be specified. The corresponding error is annulled before returning unless no NDFs have been added to the group.

• If the last character in the supplied group expression is a colon (:), a list of the NDFs represented by the group expression (minus the colon) is displayed, but none are actually added to the group. The user is then re-prompted for a new group expression.