Prompt for Text Value

This Subprogram will prompt for the Operator to supply a text string. The specified Prompt will only be issued if the Operator has not anticipated the input request.

Short Name Calling Sequence

         STATUS = UIGTTX(PROMPT,TEXT[,LENGTH,MINCHA,MAXCHA])

Long Name Calling Sequence

         STATUS = UI_GET_TEXT(...)

Input Arguments

         PROMPT (Character)     Prompt Text
         TEXT   (Character)     Default Text String
         MINCHA (Integer)       Minimum Length (Optional)
         MAXCHA (Integer)       Maximum Length (Optional)

Output Arguments

         TEXT   (Character)     Response Text
         LENGTH (Integer)       Response Length (Optional)

Function Value

UI__SUCCESS ) Success UISUCC )

UI__NOT_INITIALIZED ) Package not Initialized UININI )

UI__ILLEGAL_LIMITS ) Illegal Limit UIILLI ) specification

UI__DEFAULTED ) Input Defaulted UIDFLT )

UI__TRUNCATED ) Input Text String UITRUN ) Truncated

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. The response text string may only consist of a single word containing no embedded spaces or other word terminator characters (``=", ``/"), or a text string contained in quotes (either single or double). Thus the following are valid responses:-

   Hello
   "This is a valid response"
   'This is another valid response'
   

   The same quote character as is used to delimit the text string may not appear within the string (thus 'David's umbrella' is illegal, but ``David's umbrella" is legal).
2. All text is converted to upper case unless it is in the form of a quoted text string, in which case the case as typed is maintained.
3. The UI__TRUNCATED Function Value signifies that the text string was longer than the TEXT Argument and that truncation has taken place.
4. 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.
5. 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.
6. 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).
7. The LENGTH Argument is optional and, if present, will return the length (in characters) of the response text (ignoring trailing spaces or tabs) after truncation.
8. The length of allowed responses may be limited by specifying the optional MINCHA and MAXCHA Arguments. If these are present they represent an inclusive range; if absent, the TEXT Argument may be up to 256 characters long.
9. It is the Programmers responsibility to ensure that MINCHA (if specified) is not greater than MAXCHA. Should this unphysical condition be the case, then Function Value UI__ILLEGAL_LIMITS will be returned and the Default TEXT will be unchanged.
10. The UI__DEFAULTED Function Value indicates that the User just accepted the default value (by typing RETURN only).
11. If the Default text string length is outside the specified Limits, then the User will be forced to override the default and specify a text string with a length within the Limits.
12. 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.
13. The format of the Prompt is:-

    Prompt String [xxx]:
    

    where ``xxx" is the current default text string as specified by the TEXT Argument on entry to this subprogram.

14. A response of ? will be treated as a request for Help. If it is desired that a response of ? be treated as normal text, enclose it in quotes.