Pickup next Qualifier

This Subprogram will return the text of the next qualifier present on the Command Line. Thus the normal mode of decoding of a Command Line would be to branch on the Verb and then loop calling this subprogram until no more qualifiers are detected. This would then detect all Qualifiers directly associated with the Verb within the Command Line, but not those associated with any Parameters. These may be picked up by applying this Subprogram after each Parameter is itself picked up via the appropriate Prompted Input Subprogram. Positional Qualifiers may be specified by associating a Parameter Name with each Parameter and defining Qualifiers associated with this Parameter Name.

Short Name Calling Sequence

STATUS = UIGTQU(QUAL)

Long Name Calling Sequence

STATUS = UI_GET_QUALIFIER(...)

Input Arguments

None

Output Arguments

QUAL (Character) Text of Qualifier

Function Value

UI__QUAL_PRESENT ) Qualifier present having UIQUPR ) no associated Value

UI__QUAL_NEGATED ) Qualifier present but UIQUNE ) negated

UI__QUAL_VALUE ) Qualifier present with UIQUVA ) associated value

UI__QUAL_DEFAULTED ) Qualifier present with UIQUDF ) defaulted value

UI__QUAL_ABSENT ) No more Qualifiers UIQUAB ) present

UI__ILLEGAL_QUALIFIER ) Illegal Qualifier UIILQU ) present

UI__DUPLICATE_QUALIFIER ) Duplicate (ambiquous) UIDUQU ) Qualifier present

UI__ILLEGAL_SYNTAX ) Illegal Qualifier Syntax UIILSY )

UI__NOT_INITIALIZED ) Package not Initialized UININI ) Note:

1. The full text coresponding to the detected qualifier will be returned (in upper case), truncated or padded out if necessary.
2. UI__QUAL_ABSENT is informational only, no error signalling is performed.
3. If no qualifier is detected (corresponding to UI__QUAL_ABSENT function value), then QUAL is set to all spaces.
4. If the qualifier has an associated value (as indicated by the UI__QUAL_VALUE function value), then it may be received by calling the appropriate UI_GET_xxxx subprogram (e.g. UI_GET_TEXT or UI_GET_INTEGER).
5. UI__QUAL_DEFAULTED indicates that a Qualifier defined as having an associated Value (via UI_DEFINE_QUALIFIER) is present but with no associated value specified.
6. Function value UI__ILLEGAL_QUALIFIER will be returned, but no error will be signalled, if an illegal Qualifier is specified on the Input Line. UI__DUPLICATE_QUALIFIER will be returned if an ambiguous Qualifier is specified. QUAL will be set to the text of the illegal or ambiguous Qualifier. It is the Application Programmers responsibility to inform the User that an error was made and ask for further input. The Input Buffer will be flushed in this case unless inhibited by a prior call to UI_FLUSH_MODE.
7. UI__ILLEGAL_SYNTAX signifies that a syntax error was detected. This could imply that a valueless Qualifier has been assigned a value, or that a non-negatable Qualifier has been negated. No error will be signalled, it being the Application Programmer's responsibility to inform the User that an error was made and ask for further input. The Input Buffer will be flushed in this case unless inhibited by a prior call to UI_FLUSH_MODE.
8. The scan for qualifiers proceeds only for the current object on the Command Line. Thus if a verb was the last detected Object, then only Qualifiers attached to the Verb will be detected. Furthermore, only Qualifiers defined as being directly associated with the Verb will be treated as legal. Such Qualifiers were defined (via UI_DEFINE_QUALIFIER) without a prior call to UI_DEFINE_PARAMETER. If a Parameter was the last detected Object in the Input Line, then only Qualifiers attached to this Parameter will be detected. Furthermore, only Qualifiers defined as being associated with the Parameter will be treated as legal. Such Qualifiers were either defined without a prior call to UI_DEFINE_PARAMETER and UI_USE_PARAMETER has not been called prior to this call, or were defined with a prior call to UI_DEFINE_PARAMETER and UI_USE_PARAMETER has been called prior to this call.