INPUT@ Statement
Requests data input from the terminal at a specified cursor position while displaying existing variable contents, and provides format masking and pattern matching of the variable.
Syntax
INPUT@(column,row) {:} variable{,length}{:}{_} {formatMask} {WITH delimMask} {FOR time [THEN statement(s) | ELSE statement(s)]}
Note
Syntax elements must appear in the order shown.
Syntax Elements
column,row Specify the column and row position of the cursor where the user is prompted for input. Performs the same as the @ function in a PRINT statement.
: (colon) When specified immediately after the column and row has no significance, but is permitted for compatiblity with the PRINT @(column,row): statement.
When specified after variable and length, inhibits the output of a carriage return/line feed sequence, so that the cursor remains positioned after the characters typed when input is complete. This is useful when programming multiple inputs on one line.
variable A variable or array element to which the value or string entered is assigned.
variable can also be preset to a default value, which is formatted according to the format mask (if any) and displayed at the cursor location. If the user types only a delimiter character (see WITH delimMask), variable remains set to this default value; otherwise, it is returned set to the value entered. The user can set variable to null by entering the character defined by the INPUTNULL statement (default, underscore).
length The maximum number of characters to be entered, after which the input is automatically completed, unless an underscore (see below) is also used. This is useful when programming fixed length input fields, as no delimiter needs to be entered. The maximum, and default, length is 240 characters.
_ (underscore) Valid only with an explicit length. When the specified number of characters has been input, the program waits for a delimiter (see delimMask). Any other character sounds the terminal bell.
formatMask Specifies a format mask for formatting display of variable, verifying operator input, or specifying a pattern-matching mask.
WITH delimMaskSpecifies a read mask to define input delimiters (maximum 256-characters). When a character in the mask is entered, INPUT@ returns, setting variable to the characters entered before the delimiter.
If delimMask is used, the default delimiter of RETURN or LINEFEED is overridden. If you want these to be input delimiters, you must include them in delimMask (as CHAR(13) or CHAR(10) respectively). Specify delimMask as a series of concatenated characters.
FOR timeOptional. Specifies how long the system waits for input before returning. time is specified in tenths of a second as a integer between 1 and 30,000.
-
If time is less than 1 or the FOR clause is omitted, the result is no time-out.
-
For values greater than 30,000, 30,000 is used.
A value of 30,000 corresponds to 50 minutes.
Note
This behaviour can be changed with the INPUTTOUT compatibility option.
statement(s) Either a THEN or ELSE clause (or both). At least one of these must be included if a FOR time clause is used. The THEN clause is executed if input is completed within time. The ELSE clause is executed otherwise.
Cursor Positioning
Cursor positioning with the INPUT@ statement is functionally the same as with the PRINT statement. One difference exists, that being in the way the prompt character is displayed.
Before the INPUT@ statement was available, input at a specific cursor position was typically accomplished using a PRINT statement with the cursor addressing function and a colon to inhibit a RETURN, followed by the INPUT statement, as follows:
PRINT @(5,10):
INPUT X
In the above statements, a prompt character is printed at column 5 of row 10. The cursor is then positioned at column 6 waiting for input. If the prompt character is null, the cursor remains at column 5 waiting for input.
In the INPUT@ statement, the cursor waits for input at the column and row position specified in the statement. If a prompt character is printed, it is printed one character position before the cursor position specified by the statement. Thus, in the statement:
INPUT@(5,10): X
the prompt character is printed at column 4 of row 10 and the cursor then waits for input at column 5 of row 10. If a variable is displayed, the first character of the display is at column 5 of row 10.
Format Masking
The formatMask parameter allows you to display the current value of variable in a specific format and to perform certain error checking on the data input.
In all cases of format masking, the input variable with a value previously assigned is displayed according to the format mask specifications.
Format masking can be a left- or right-aligned format string mask, a date mask, or a pattern-matching mask.
Format String Masking
The parameters that make up a format string mask are a subset of those used in format strings. The syntax is:
{{M}alignment} {$} {,} {precision} {formatMask}
Each parameter has the same function as in a format string, except as follows:
M Optional. Provides compatibility with other MultiValue systems.
If the data is within the length defined by the formatMask, it is formatted according to the mask and printed on the screen at the cursor coordinates. If the data entered is longer than the length specified, an error message is displayed and the user is re-prompted.
If the precision parameter included, the data input is checked to see if it is numeric. If it is nonnumeric, an error message is displayed.
Date Masking
A date mask (see D Code - Date Conversion) can be used as the format mask.
When you use a date mask, the user enters the date in external format. The program checks the input for length and format. If the input does not meet the masking requirements, an error message is displayed and the user is re-prompted. If the input is correct, the date is converted to internal format and assigned to the variable.
If the input variable has previously been assigned a value, that value is converted to the format specified by the mask and displayed at the cursor coordinates. If a value has not been assigned previously, an appropriate date mask (e.g. "MM/DD/YY") is displayed at the cursor coordinates.
Pattern Matching
Pattern matching allows an input string value to a predefined pattern. The pattern specifications are the same as those used with the MATCHES relational operator. The pattern mask can consist of any combination of the following:
nNTests for n numeric characters.
nATests for n alphabetic characters.
nXTests for n alphanumeric characters.
A literal string enclosed in quotes tests for that literal string of characters.
If the variable has been assigned, it is then formatted according to the mask, if possible. If the variable is previously unassigned, a mask is displayed to aid the operator with input.
The following example could be used for the entry of a social security number.
INPUT@(10,10):SSN "3N'-'2N'-'4N"
If the variable is unassigned, a mask in the form NNN-NN-NNNN
is displayed at the cursor coordinates.
The literal mask characters do not have to be entered and, if they are, they are stripped before the string is assigned to the variable.
Case Insensitivity
By default, the characters in delimMask are case sensitive. For a case insensitive match, either include both upper and lower case characters in delimMask or select data case insensitive mode (see Case Sensitivity).
Stacked Input
The process first looks at the data stack to see if data is present. Data is placed in the data stack by a DATA statement or by loading the secondary output buffer while in a Proc. If data is present in the stack, the first attribute in the stack is assigned to the input variable, the INPUT@ statement is satisfied, and no prompt is displayed on the terminal.
Error Messages
A number of special messages are used only with the INPUT@ statement.
Most of these error messages are printed on the Status/Command Line. The user is re-prompted for input and the message is then cleared from the screen. The special INPUT@ error messages are:
entry must be a numeric value!
This message is printed when a numeric value is required due to a decimal specifier in the format mask as in "R2#10".
entry has too many characters!
This message is printed when the number of characters entered exceeds the number of characters specified by the format mask.
entry in date format is required!
This message is printed when an illegal date format is entered. A date mask must have been used in the INPUT@ statement defining a specific format for entry. The character count has already been checked at this point.
mm/dd/yy
This is printed at the screen location defined by the cursor coordinates when a date mask producing this format is used and the input variable is unassigned. This is an input mask to aid the operator with entering dates.
entry does not match pattern!
This message is printed when a pattern matching mask is used and the data entered does not match the pattern defined by the mask.
Example 1
INPUT@(12,18):VAR,12: "R#12" FOR 600 ELSE GO 200
Input is solicited at column 12 of row 18 where the current value of the variable VAR (if assigned) is displayed, right-aligned in a field of 12 characters. The program waits 1 minute for input and if none is received, branches to statement label 200.
When data is entered, the program accepts no more than twelve characters after which the program waits for a RETURN or LINEFEED. After the input, the cursor remains at the end of the input data string.
The data is redisplayed right-aligned in a field of twelve characters. The format string "R#12" also ensures that the input string does not exceed 12 characters but in this example, that action is redundant because the input is already limited to 12 characters.
Example 2
MSG(12)="ENTER SOCIAL SECURITY NUMBER, or <Esc>" INPUTNULL CHAR(27) INPUTERR MSG(12) . INPUT@(35,8):SSN,11 "3N'-'2N'-'4N"
This example prompts for the input of a social security number at column 35 of row 8 and accepts up to eleven characters. A prompt message is printed on the terminal status line. If the user types only RETURN, the program continues to prompt for input. If ESC is pressed, variable SSN is assigned a null value. Input must conform to the format of a social security number as defined by the format string mask.