GRP_GROUP - Append a list of names obtained from the environment to a previously created group

Description:

A group expression is obtained from the environment using the supplied parameter name. The expression is parsed to produce a list of names which are appended to the end of the group identified by IGRP2. Note, no permanent association between the parameter and the group exists. The parameter value can be cancelled without effecting the contents of the group. If an error occurs while parsing the group expression, the user is re-prompted for a new group expression.

If the group expression contains any modification elements, then the list of names added to the output group is based on the group identified by IGRP1. If IGRP1 is invalid (equal to the symbolic constant GRP__NOID for instance), then any elements with the syntax of a modification element are stored in the output group as a single literal name.

If the last character read from the group expression (or from a text file if the last element of the group expression is an indirection element) is equal to the current "flag" character for the group IGRP2 (see routine GRP_SETCC), then argument FLAG is returned set to .TRUE. Otherwise, it is returned set to .FALSE. The calling application can use this flag for any purpose (eg it may use it to indicate that the user wants to give more names). Note, the flag character itself is not included in the returned group.

Invocation:

CALL GRP_GROUP( PARAM, IGRP1, IGRP2, SIZE, ADDED, FLAG, STATUS )

Arguments:

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

The ADAM parameter with which to associate the group expression. This may be of any type.

IGRP1 = INTEGER (Given)

A GRP identifier for the group to be used as the basis for any modification elements which may be contained within the group expression obtained from the environment. This can be set to the symbolic constant GRP__NOID if modification elements are to be treated as literal names.

IGRP2 = INTEGER (Given)

A GRP identifier for the group to which the new names are to be appended.

SIZE = INTEGER (Returned)

The number of names in the returned group. It is returned equal to 1 if an error status exists on entry. If an error occurs during execution of this routine, then SIZE is returned equal to the size of the group on entry (unless the group has zero size on entry, in which case it is returned equal to 1).

ADDED = INTEGER (Returned)

The number of names added to the group as a result of the current call to this routine.

FLAG = LOGICAL (Returned)

.TRUE. if the last character in the group expression is equal to the current flag character for group IGRP2. Note, if this is the case, then the flag character itself is not included in the returned group. FLAG is returned .FALSE. if the last character is not a flag character. Returned .FALSE. if an error occurs.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

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