NDG_ASEXP - Store names of existing NDFs supplied as a group expression

Description:

The supplied group 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). NDF identifiers for particular members of the group can be obtained using NDG_NDFAS.

If any of the NDFs specified by the group expression cannot be accessed, an error is reported and STATUS is returned equal to NDG__NOFIL. If this happens strings holding the name of each bad NDF are appended to the group identified by IGRP1 (so long as IGRP1 is not equal to GRP__NOID).

Invocation:

CALL NDG_ASEXP( GRPEXP, VERB, IGRP1, IGRP2, SIZE, FLAG, STATUS )

Arguments:

GRPEXP = CHARACTER $*$ ( $*$ ) (Given)

The group expression specifying the NDF names to be stored in the group.

VERB = LOGICAL (Given)

If TRUE then errors which occur whilst accessing supplied NDFs are flushed so that the user can see the details ("verbose" mode). Otherwise, they are annulled and a general "Cannot access file xyz" message is reported instead.

IGRP1 = INTEGER (Given)

The identifier of a group to which the names of any inaccessible NDFs will be appended. The group should already have been created by a call to GRP_NEW, and should be deleted when no longer needed by a call to GRP_DELET. If IGRP1 is supplied equal to symbolic constant GRP__NOID, then no information is stored describing the bad NDFs.

IGRP2 = 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 IGRP2.

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 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 all possible NDFs matching the supplied string are included in the returned group. For instance, if the string "fred" is supplied, then the returned group will contain references to all files with basename fred which also have a file type specified in NDF_FORMATS_IN. If a FITS file "fred.fit" exists, and HDS file "fred.sdf" also exists (and contains an NDF), then supplying the name "fred" will result in both being included in the returned group. If the file "fred.sdf" contains a component called ".fit", then this will be included in the returned group in place of "fred.sdf".

• NDFs contained within HDS files are opened in order to ensure that they are valid NDFs. The NDF name is returned in IGRP1 if there are no valid NDFs matching a supplied name. 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)