NDG_CREAT - Obtain the names of a group of NDF to be created from 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 NDF names. These names are appended to the group identified by IGRP. The user is re-prompted if an error occurs while parsing the group expression. If IGRP has the value GRP__NOID on entry, then a new group is created and IGRP is returned holding the new group identifier.

If IGRP0 holds a valid group identifier on entry, then the group identified by IGRP0 is used as the basis for any modification element contained in the group expression obtained from the environment. If IGRP0 holds an invalid identifier (such as GRP__NOID) on entry then modification elements are included literally in the output group.

Invocation:

CALL NDG_CREAT( PARAM, IGRP0, IGRP, SIZE, FLAG, STATUS )

Arguments:

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

The parameter with which to associate the group.

IGRP0 = INTEGER (Given)

The GRP identifier for the group to be used as the basis for any modification elements. If a valid GRP identifier is supplied, and if the supplied group expression contains a modification element, then:

• the basis token (an asterisk) is replaced by the file basename associated with the corresponding element of the basis group (the "basis NDF").

• if no directory specification is included in the group expression, the directory specification associated with the basis NDF is used.

• if no HDS component path is included in the group expression, the HDS component path associated with the basis NDF (if any) is used. Any required higher level HDS objects are created in the output HDS file by copying the structure of the HDS file containing the basis NDF. Thus if, the basis NDF is fred.a.b(2).c, and the group expression is "$*$_a", then an HDS container file called "fred_a.sdf" is created by copying fred.sdf and then deleting all NDFs from fred_a.sdf (unless this has already been done while creating a previous member of the returned group). Other non-NDF components in fred_a.sdf are retained. This ensures that all necessary structure exists in fred_a.sdf, so that the NDF fred_a.a.b(2).c can be created when necessary.

The supplied group will often be created by NDG_ASSOC, but groups created "by hand" using GRP directly can also be used (i.e. without the supplemental groups created by NDG). In this case, there are no defaults for directory path, file type, or HDS component path, and the basis token ("$*$") in the group expression represents the full basis file specification supplied in IGRP0, not just the file basename.

IGRP = INTEGER (Given and Returned)

The GRP identifier for the group to which the supplied .sdf files are to be appended.

SIZE = INTEGER (Returned)

The total number of file 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:

• If an error is reported the group is returned unaltered.

• 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.

• Explicit file types are included in all the elements of the returned group. This is done because the name may be passed out to a script (eg POLPACK:POLKA) which may change the value of NDF_FORMATS_OUT before using the NDF name. If no file type is supplied in the group expression, then the first file type listed in the current value of the NDF_FORMATS_OUT environment variable (see SSN/20) is used. If this is "$*$" then the file type is copied from the corresponding input file if a modification element was used to specify the output file name (if the NDF was not specified by a modification element, the second file type in NDF_FORMATS_OUT is used).

• 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.

• The returned group has no associated groups holding supplemental information (unlike the group returned by NDG_ASSOC).