Description:
This routine obtains a scalar character value from a parameter. The value
must be one of a supplied list of acceptable values, and can be an abbreviation provided it
is unambiguous. A dynamic default may be suggested.
Invocation
CALL PAR_CHOIC(
PARAM, DEFAUL, OPTS, NULL, VALUE, STATUS )
Arguments
PARAM = CHARACTER
(
) (Given)
The name of the parameter.
DEFAUL = CHARACTER
(
)
(Given)
The suggested default value for the parameter. No default will be suggested when DEFAUL
is not one of the options defined by OPTS. A status of PAR__AMBIG is returned if the default is
ambiguous, i.e. an abbreviation of more than one of the options.
OPTS = CHARACTER
(
)
(Given)
The list of acceptable options for the value obtained from the parameter. Items should be
separated by commas. The list is case-insensitive.
NULL = LOGICAL (Given)
NULL controls the
behaviour of this routine when the parameter is in the null state. If NULL is .FALSE., this routine
returns with STATUS=PAR__NULL. If NULL is .TRUE., the returned VALUE takes the value of
DEFAUL and, if the
MSG filtering level (see SUN/104) is ‘verbose’, a message informs the user of the
value used for the parameter. The routine then returns with STATUS=SAI__OK. This feature is
intended for convenient handling of null values. NULL should only be set to .TRUE. when the value
of DEFAUL will always give a reasonable value for the parameter.
VALUE = CHARACTER
(
)
(Returned)
The selected option from the list. It is in uppercase and in full, even if an abbreviation has
been given for the actual parameter. If STATUS is returned not equal to SAI__OK, VALUE takes the
value of DEFAUL.
STATUS = INTEGER (Given and Returned)
The global status.
Notes:
The
search for a match of the obtained character value with an item in the menu adheres to the following
rules.
- All comparisons are performed in uppercase. Leading blanks are ignored.
- 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.
- 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 a new value If a nearest match is selected, the user
is informed unless the MSG filtering level (see SUN/104) is ‘quiet’.