KPG1_GTGPT

Obtains a group of strings from the environment including some that are transient

Description:

This routine obtains group of strings using the specified parameter, and returns them in a GRP group (see SUN/150).

The user specifies the strings by supplying a GRP group expression for the parameter value. If the final character in the supplied string is the group " flag character" (a minus sign by default), then the user is re-prompted for another group expression, and the strings specified by the second group expression are appended to the returned group. This continues until a group expression is supplied that does not end with the continuation character, or a null value is supplied (which is annulled).

The group comprises an optional persistent part that will be written as the parameter’ s current value, and an optional temporary component that only exists for the duration of the current application. The division is determined by the first appearance within the string supplied of a delimiter string or character (the DELIM argument). For instance, assume the delimiter is ’ +’ . If the supplied value is ’ smooth,box=5+filter=gauss’ , the persistent value would be ’ smooth,box=5’ and the temporary value ’ filter=gauss’ . Supplying merely the temporary value, such as ’ +filter=gauss’ would return the existing current value of the parameter as the persistent component, and the temporary component is as before.

Normally, the " current value" for the parameter on exit would be the final group expression. If more than one group expression was supplied, then this will not represent the entire group. For this reason, this routine concatenates all the group expressions supplied, and stores the total group expression as the parameter value before exiting. It also stores the concatenated persistent components and writes this as the current value. Since a new value is stored for the parameter, the parameter should not be given an access mode of READ in the interface file.

If a null value is supplied the first time the parameter value is obtained, then the PAR__NULL status is returned, and SIZE is returned as zero (a valid GRP identifier is still returned however). If a null value is supplied on a subsequent access to the parameter, then the PAR__NULL status is annulled, and the group is returned containing any values obtained earlier.

Invocation

CALL KPG1_GTGPT( PARAM, DELIM, LAST, IGRP, SIZE, STATUS )

Arguments

PARAM = CHARACTER ∗ ( ∗ ) (Given)
The name of the parameter to use.
DELIM = CHARACTER ∗ ( ∗ ) (Given)
The delimiter string used to indicator where the temporary part of a value begins. Any text before the delimiter behaves as if it were obtained using PAR_GET0C. After, and not including, the delimiter the value is deemed to be temporary and is never incorporated into the parameter’ s current value. The delimiter should not be an alphanumeric character or underscore.
LAST = LOGICAL (Given)
If this is the last or only invocation of this routine for a given parameter in a task, set this TRUE. For multiple invocations except the last, set this FALSE. Setting to FALSE causes the full concatenated expression supplied by the user to be stored in the parameter’ s current value, rather than just the persistent-attribute list a TRUE value generates needed when the task ends.
IGRP = INTEGER (Given and Returned)
The group to use. If this is GRP__NOID then a new group is created with default control characters and its identifier is returned. If the group already exists, its contents are discarded before adding new strings.
SIZE = INTEGER (Returned)
The total size of the returned group. Returned equal to zero if an error occurs.
STATUS = INTEGER (Given and Returned)
The global status.

Notes: