next up previous
Next: PAR_MIXVx - Obtains from a parameter character values from either a menu of options or within a numeric range
Up: Reference Manual
Previous: PAR_MINx - Sets a minimum value for a parameter

    
PAR_MIX0x - Obtains from a parameter a character value from either a menu of options or within a numeric range

Description:
This routine obtains a scalar character value from a parameter. The value must be either:
  • one of a supplied list of acceptable values, with unambiguous abbreviations accepted; or
  • a numeric character string equivalent to a number, and the number must lie within a supplied range of acceptable values.

A dynamic default may be suggested.

Invocation:
CALL PAR_MIX0x( PARAM, DEFAUL, VMIN, VMAX, 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 numeric within the range of acceptable values defined by VMIN and VMAX, and 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.
VMIN = ? (Given)
The value immediately above a range wherein the obtained numeric value cannot lie. Thus if VMAX is greater than VMIN, VMIN is the minimum numeric value allowed for the obtained value. 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 value cannot lie. Thus if VMAX is greater than VMIN, VMAX is the maximum numeric value allowed for the obtained value. 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 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 or the character form of the numeric value. The former 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:
  • There is a routine for each of the data types double precision, integer, and real: replace "x" in the routine name by D, I, or R respectively as appropriate. The VMIN and VMAX arguments must have the corresponding data type.
  • There are two stages to identify or validate the character value obtained from the parameter.

    In the first the value is converted to the data type specified by the "x" in the routine name. 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 VALUE and the routine exits.

    The second stage searches for a match of the character value with an item in the menu. This step adheres to the following rules.

    • The value is converted to the data type specified by the "x" in the routine name. If this is successful, the numeric value is compared with the range of acceptable values defined by VMIN and VMAX. A value satisfying these constraints is returned and the matching process terminates.
    • 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 up previous
Next: PAR_MIXVx - Obtains from a parameter character values from either a menu of options or within a numeric range
Up: Reference Manual
Previous: PAR_MINx - Sets a minimum value for 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