Next: PAR_CHOIV - Obtains from a parameter a list of character values selected from a menu of options
Up: Reference Manual
Previous: PAR_CANCL - Cancels a parameter
PAR_CHOIC
- Obtains from a parameter a character value selected from a menu
of options
- 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
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
is `quiet'.
Next: PAR_CHOIV - Obtains from a parameter a list of character values selected from a menu of options
Up: Reference Manual
Previous: PAR_CANCL - Cancels a parameter
PAR Interface to the ADAM Parameter System
Starlink User Note 114
Malcolm J. Currie
Alan J. Chipperfield
1999 September 24
E-mail:ussc@star.rl.ac.uk