INPUT statement

Syntax

INPUT variable [ ,length] [ : ] [ _ ]
INPUT @ (col, row) [ , | : ] variable [ ,length] [ : ] [format] [ _ ]
INPUTIF @ (col, row) [ , | : ] variable [ ,length] [ : ] [format] [ _ ]
[THEN statements] [ELSE statements]

Description

Use the INPUT statement to halt program execution and prompt the user to enter a response. Data entered at the terminal or supplied by a DATA statement in response to an INPUT statement is assigned to variable. Input supplied by a DATA statement is echoed to the terminal. If the response is a RETURN with no preceding data, an empty string is assigned to variable.

The INPUT statement has two syntaxes. The first syntax displays a prompt and assigns the input to variable. The second syntax specifies the location of the input field on the screen and lets you display the current value of variable. Both the current value and the displayed input can be formatted.

Use the INPUTIF statement to assign the contents of the type-ahead buffer to a variable. If the type-ahead buffer is empty, the ELSE statements are executed, otherwise any THEN statements are executed.

Use the @ expression to specify the position of the input field. The prompt is displayed one character to the left of the beginning of the field, and the current value of variable is displayed as the value in the input field. The user can edit the displayed value or enter a new value. If the first character typed in response to the prompt is an editing key, the user can edit the contents of the field. If the first character typed is anything else, the field's contents are deleted and the user can enter a new value. Editing keys are defined in the terminfo files; they can also be defined by the KEYEDIT statement. Calculations are based on display length rather than character length.

col and row are expressions that specify the column and row positions of the input prompt. The prompt is positioned one character to the left of the input field. Because the prompt character is positioned to the left of the col position, you must set the prompt to the empty string if you want to use column 0. Otherwise, the screen is erased before the prompt appears.

length specifies the maximum number of characters allowed as input. When the maximum number of characters is entered, input is terminated. If the @ expression is used, the newline is suppressed.

If length evaluates to less than 0 (for example, -1), the input buffer is tested for the presence of characters. If characters are present, variable is set to 1, otherwise it is set to 0. No input is performed.

If you use the underscore ( _ ) with the length expression, the user must enter the RETURN manually at the terminal when input is complete. Only the specified number of characters is accepted.

Use a format expression to validate input against a format mask and to format the displayed input field. The syntax of the format expression is the same as that for the FMT function. If you specify a length expression together with a format expression, length checking is performed. If input does not conform to the format mask, an error message appears at the bottom of the screen, prompting the user for the correct input.

The colon ( : ) suppresses the newline after input is terminated. This allows multiple input prompts on a single line.

The default prompt character is a question mark. Use the PROMPT statement to reassign the prompt character.

The INPUT statement prints only the prompt character on the screen. To print a variable name or prompt text along with the prompt, precede the INPUT statement with a PRINT statement.

The INPUT statement lets the user type ahead when entering a response. Users familiar with a sequence of prompts can save time by entering data at their own speed, not waiting for all prompts to be displayed. Responses to a sequence of INPUT prompts are accepted in the order in which they are entered.

If col, row, length, or format evaluate to the null value, the INPUT statement fails and the program terminates with a run-time error message. If variable is the null value and the user types the TRAP key, null is retained as the value of variable.

If NLS is enabled, INPUT @ displays the initial value of an external multibyte character set through the mask as best as possible. If the user enters a new value, mask disappears, and an input field of the approximate length (not including any inserted characters) is entered. For details about format and mask, see the FMTDP function.

Only backspace and kill are supported for editing functions when using a format mask with input. When the user finishes the input, the new value is displayed again through the mask in the same way as the original value.

PICK Flavor

In a PICK flavor account, the syntax of the INPUT and INPUT @ statements includes THEN and ELSE clauses:

INPUT variable [ ,length] [ : ] [ _ ] [THEN statements] [ELSE
statements]
INPUT @ (col, row) [ , | : ] variable [ ,length] [ : ] [format] [ _ ]
[THEN statements] [ELSE statements]

To use THEN and ELSE clauses with INPUT statements in other flavors, use the INPUT.ELSE option of the $OPTIONS statement.

PICK, IN2, and REALITY Flavors

In PICK, IN2, and REALITY flavors, values supplied by aDATA statement are not echoed. To suppress echoing input from DATA statements in IDEAL and INFORMATION flavors, use the SUPP.DATA.ECHO option of the $OPTIONS statement.

Examples

In the following examples of program output, bold type indicates words the user types. In the first example the value entered is assigned to the variable NAME:

Source Lines

Program Output

INPUT NAME PRINT NAME

? DaveDave

In the next example the value entered is assigned to the variable CODE. Only the first seven characters are recognized. A RETURN and a LINEFEED automatically occur.

Source Lines

Program Output

INPUT CODE, 7 PRINT CODE

? 12345671234567

In the next example the user can enter more than two characters. The program waits for a RETURN to end input, but only the first two characters are assigned to the variable YES.

Source Lines

Program Output

INPUT YES, 2_ PRINT YES

? 123412

In the next example the colon inhibits the automatic LINEFEED after the RETURN:

Source Lines

Program Output

INPUT YES, 2_: PRINT "=",YES

? HI THERE =HI

In the next example the input buffer is tested for the presence of characters. If characters are present, VAR is set to 1, otherwise it is set to 0. No input is actually done.

Source Lines

Program Output

INPUT VAR, -1 PRINT VAR

0

In the next example the PRINT statement puts INPUT NAME before the input prompt:

Source Lines

Program Output

PRINT "INPUT NAME": INPUT NAME PRINT NAME

INPUT NAME? DaveDave

In the next example the contents of X are displayed at column 5, row 5 in a field of 10 characters. The user edits the field, replacing its original contents (CURRENT) with new contents (NEW). The new input is displayed. If the PRINT statement after the INPUT statement were not used, X would be printed immediately following the input field on the same line, since INPUT with the @ expression does not execute a LINEFEED after a RETURN.

Source Lines

Program Output

PRINT @(-1) X = "CURRENT" INPUT @(5,5) X,10 PRINT PRINT X

    ?NEW_______
NEW