KPG1_MIXVx

←Prev
KAPLIBS – Internal subroutines used within the KAPPA package.
Next→
TOC ↑

KPG1_MIXVx

Obtains from a parameter character values from either a menu of options or within a numeric range

Description:

This routine obtains a group of character values from a parameter. Each value must be either:

o one of a supplied list of acceptable values, with unambiguous abbreviations accepted; or

o a numeric character string equivalent to a number, and the number must lie within a supplied range of acceptable values.

Invocation

CALL KPG1_MIXVx( PARAM, MAXVAL, VMIN, VMAX, OPTS, VALUES, ACTVAL, STATUS )

Arguments

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

The name of the parameter. A GRP group expression should be supplied for the parameter.

MAXVAL = INTEGER (Given)

The maximum number of values required. A PAR__ERROR status is returned when the number of values requested is fewer than one.

VMIN = ? (Given)

The value immediately above a range wherein the obtained numeric values cannot lie. Thus if VMAX is greater than VMIN, VMIN is the minimum numeric value allowed for the obtained values. However, should VMAX be less than VMIN, all numeric values are acceptable except those between VMAX and VMIN exclusive.

VMAX = ? (Given)

The value immediately below a range wherein the obtained numeric values cannot lie. Thus if VMAX is greater than VMIN, VMAX is the maximum numeric value allowed for the obtained values. However, should VMAX be less than VMIN, all numeric values are acceptable except those between VMAX and VMIN exclusive.

OPTS = CHARACTER $$ ( $$ ) (Given)

The list of acceptable options for each value obtained from the parameter. Items should be separated by commas. The list is case-insensitive.

VALUES( MAXVAL ) = CHARACTER $$ ( $$ ) (Returned)

The selected values that are either options from the list or the character form of numeric values that satisfy the range constraint. The former values are in uppercase and in full, even if an abbreviation has been given for the actual parameter. Note that all values must satisfy the constraints. The values will only be valid if STATUS is not set to an error value.

STATUS = INTEGER (Given and Returned)

The global status.

Notes:

There is a routine for each numerical data type: replace " x" in the routine name by D or R as appropriate. The data range arguments supplied to the routine must have the data type specified.
There are two stages to identify or validate each character value obtained from the parameter. In the first the value is converted to the required data type. If this is successful, the derived numeric value is compared with the range of acceptable values defined by VMIN and VMAX. A value satisfying these constraints is returned in the VALUES. The second stage searches for a match of the character value with an item in the menu.
This routine adheres to the following rules. o All comparisons are performed in uppercase. Leading blanks are ignored. o A match is found when the value equals the full name of an option. This enables an option to be the prefix of another item without it being regarded as ambiguous. For example, " 10,100,200" would be an acceptable list of options. o If there is no exact match, an abbreviation is acceptable. A comparison is made of the value with each option for the number of characters in the value. The option that best fits the value is declared a match, subject to two provisos. Firstly, there must be no more than one character different between the value and the start of the option. (This allows for a mistyped character.) Secondly, there must be only one best-fitting option. Whenever these criteria are not satisfied, the user is told of the error, and is presented with the list of options, before being prompted for new values. This is not achieved through the MIN/MAX system.

←Prev
KAPLIBS – Internal subroutines used within the KAPPA package.
Next→
TOC ↑