Prompt for Hexadecimal Set of Values

This Subprogram will prompt for the Operator to supply a Set of Hexadecimal Integer Values. The specified Prompt will only be issued if the Operator has not anticipated the input request.

Short Name Calling Sequence

         STATUS = UIGTHS(PROMPT,VALUES,VASIZE,
     &                  NVALUE[,LOLIM,HILIM])

Long Name Calling Sequence

         STATUS = UI_GET_HEX_SET(...)

Input Arguments

         PROMPT (Character)     Prompt Text
         VASIZE (Integer)       Maximum No. of Values
         LOLIM  (Integer)       Low Limit (Optional)
         HILIM  (Integer)       High Limit (Optional)

Output Arguments

         VALUES (Integer Array) Response Values Array
         NVALUE (Integer)       No. of returned Values

Function Value

UI__SUCCESS ) Success UISUCC )

UI__NOT_INITIALIZED ) Package not Initialized UININI )

UI__ILLEGAL_LIMITS ) Illegal Limit UIILLI ) specification

UI__TRUNCATED ) List truncated UITRUN )

UI__INPUT_ABORTED ) Input Aborted (Ctrl-Z) UIABRT )

UI__NO_INPUT ) No Input present UINOIN )

UI__END_OF_FILE ) End-of-File detected UIEOF ) in Batch Mode Note:

1. This Subprogram differs from UI_GET_HEX_LIST in not allowing for bounds specifications within the List. UI_GET_HEX_LIST allows implied sequences denoted by lower and upper bounds whereas this Subprogram only allows for a sequence of enumerated hexdecimal numbers.
2. The VALUES Array should be dimensioned (VASIZE). On return it will be setup to contain NVALUE entries, each specifying an enumerated hexadecimal value. No sorting is performed and thus the response:-
   (1,5,2,3)
   will cause the following settings:-

   NVALUE = 4
   
   VALUES(1) =  1
   VALUES(2) =  5
   VALUES(3) =  2
   VALUES(4) =  3
   

3. The range of allowed responses may be limited by specifying the optional LOLIM and HILIM Arguments. If these are present they represent an inclusive range, if absent, the VALUE may lie in the complete range of Integer numbers.
4. It is the Programmers responsibility to ensure that LOLIM (if specified) is not greater than HILIM. Should this unphysical condition be the case, then Function Value UI__ILLEGAL_LIMITS will be returned and the Default VALUE will be unchanged.
5. Unlike the other Prompted Input Subprograms UI_GET_HEX_SET does not accept any Defaults. If a null response (all spaces) is returned then NVALUE will be set to zero, indicating that no Elements are present.
6. The UI__TRUNCATED Return indicates that the list Array VALUES has been exceeded. Excess list elements have therefore been lost.
7. The UI__INPUT_ABORTED Function Value indicates that the User typed Ctrl-Z to abort input. This is only implemented on a VAX/VMS system. It is an informational function value only, no error message will be reported.
8. UI__NO_INPUT will only be returned in Asynchronous Mode (if both UI_INPUT_MODE and UI_GET_MODE have signified Asynchronous Input Mode) and indicates that the User has not yet specified any Input. The Application Program should poll by either calling this Subprogram repeatedly or by calling UI_TEST_INPUT repeatedly until this indicates that some Input has been received. In the latter case (UI_TEST_INPUT called) this Subprogram should be recalled in order to decode the input. UIPACK is setup by default such that this subprogram always acts synchronously unless a prior call to UI_GET_MODE has been made within the Application Program.
9. The UI__END_OF_FILE Function Value indicates that an End-of-File was detected on the main Input Stream in Batch or non-interactive mode where Input is not taken from a terminal but rather from a file. It is a severe error and therefore causes an error to be reported (unless this has been inhibited by a prior call to UI_ERROR_LEVEL).
10. The Prompt string will only be issued if the response is not already present in the input line. Thus this subprogram may be used by itself to accept input values, as part of the general decoding of a Command Line to prompt for Parameters associated with the present Verb, or to prompt for and pickup the value associated with a Qualifier.
11. The format of the Prompt is:-

    Prompt String [Hex]:
    

    or

    Prompt String [Hex (lll:uuu)]:
    

    where ``lll" and ``uuu" are the lower and upper limits if specified.

12. The format of allowed responses is:-

    ?
    xx
    xxZ
    snnI
    xxX
    sooO
    (xx,xx,snnI,sooO)
    "xx,xx,snnI,sooO"
    'xx,xx,snnI,sooO'
    
    where:-
    
    ?       Request for Help
    s       is an optional sign [+/-]
    xx      is a string of hex. digits
    nnI     is a string of decimal digits
    xxX     is a string of hex. digits (terminated by X)
    xxZ     is a string of hex. digits (terminated by Z)
    ooO     is a string of octal digits (terminated by O)
    
    
    Examples:
    
             Response       Internal
    
             1              (1)
             (1,10,20)      (1,16,32)
             (1,10,20,45I)  (1,16,32,45)