basic.input@ Statement/BASIC Program


Command basic.input@ Statement/BASIC Program
Applicable release versions: AP, R83, AP 5.2.3, AP 6.2
Category BASIC Program (486)
Description temporarily suspends execution of the program until a response is provided from the keyboard and assigns that response to a specified variable.

The "input @" prompts for the input of data from the terminal, at the coordinates specified in the "col.exp" ("column expression") and "row.exp" ("row expression") parameters. Both expressions must evaluate to valid screen addresses. See the "@" function.

The input received is assigned to the specified variable after performing the optional "mask" function. The mask can contain any valid mask described under "masking (BASIC: General)" except for masks beginning with a "c". If the variable already has a value, and the "@" function has been specified, the current value of the variable is displayed as the default at the specified cursor address. A <return> accepts the default.

In the "regular" form of "input", the ":" suppresses the carriage return/line feed after input has been completed.

As of AP release 6.2, a "val.expression" may be specified to set a default value for the input field. This value is displayed within the input field and the user may edit this value as need be. If no editing is performed, then the default value is accepted as if the user had typed that value at the keyboard.

The "length.expression" indicates the number of characters of input to accept. When the number of characters have been entered, the input instruction terminates exactly as though the operator had pressed <return>.

As of AP release 5.2.3, a "length.expression" of 0 (zero) is allowed. This syntax is more consistent with other implementations of Pick. This suppresses the automatic carriage return after single-character input (i.e. holds the cursor position).

As of AP release 6.2, a "fill.expression" may be specified to perform a background fill within the input field. The first character of this expression indicates the prompt background fill character. This character is used to help the user see the length of a prompt. The second character, if present, indicates the overstrike character used to fill in any blank spots when the input is accepted. After input is accepted, the cursor is placed at the end of the entered data unless a third fill character is specified in which case the cursor is moved to the end of the input field. The "fill.expression" is ignored if there is no "length.expression".

If the input data value is incompatible with the optionally-specified "mask" expression, the statement re-prompts for input. Mask functions may be any combination of conversions, pattern-matching operators, or text justification. See "masking".

The "_" (underscore) outputs a "beep" to the terminal for each character typed that exceeds the specified maximum length. Echoing of characters to the screen is suppressed for the extra characters and a <return> is required for acceptance. Only the number of characters less than or equal to the "length expression" are accepted. (see warnings).

If "mask" is to be used, the "@" function must also be specified. The mask is used to verify and reformat the actual entry of the data. Any valid format string may be specified. The input is verified against the mask and, if acceptable, is assigned to the variable. Data is input and verified according to the mask, then stripped of its output characteristics and stored in internal format.

For example, if the mask contains a decimal digit specification and/or a scaling factor, then numeric checking is performed; or if the mask contains a length specification, then length checking is performed. See "Format Strings".

When an "input" statement is executed, a prompt character is displayed, followed by the cursor. If the "@" function is used, the prompt is displayed preceding the location specified by "@". Unless the prompt character has been changed with the "prompt" statement, the default prompt character is "?" (question mark).

The "time.expression" is the maximum time that the system waits for input before returning to the Pick/BASIC program until any of the following events occur:

1) When a valid termination occurs. The "then" clause is taken.

2) When no carriage return is entered, even though input continues, and no valid termination occurs within the specified time. The "variable" contains all characters entered until the time expired. If no characters are in the type-ahead buffer, "variable" is null. Upon timeout, the "else" clause is taken.

3) When not enough characters are entered to satisfy the "length" requirement within the allocated time, the "else" clause is taken.

The "time.expression" is represented in tenths of a second, as a positive integer from 1 to 32767. Depending on the implementation, there may be significant restrictions on the admissible values for "time.expression". See warnings.

If the "time.expression" is zero and there are characters in the input buffer, these characters are returned immediately when a valid termination criterion is met and the "then" clause is taken.

If "time.expression" is zero and there is no character waiting in the input buffer, the "input" statement returns immediately and the "else" clause is taken.

If "time.expression" is negative, no timeout is in effect.

The "then" clause is taken if valid input is completed within the allocated time. The "else" clause is taken if there is no input, insufficient input, or a non-carriage-return-terminated input occurs in the allocated time.

See the "then/else construct" for an explanation on the use of "then" and "else" clauses in statements that allow or require them.
Syntax input variable{:}

input @(col.exp,{row.exp}){:} variable {,length.expression}{mask} {:}

input variable {=val.expression} {, length.expression} {, fill.expression} {:} {_} {for time.expression {then | else statement.block}}
print 'are you sure? ':
input answer
if answer[1,1]='y' then goto 100

print 'are you sure? ':
input answer,1:

"answer" is the first character entered from the keyboard. No 
<return> is required.

input x,0
x = seq(x)

These two lines perform exactly the same as:

in x

Using 0 (zero) as a length expression is only valid in AP releases 5.2.3 and 

input x for 50 else stop

Wait 5 seconds for input. If there is no input, terminated by a carriage 
return, the program stops.

input x for 0 then print x else x = 0

The time out value equal to 0 means read characters without waiting. If there 
is any, the 'then' clause is taken, otherwise the 'else' 
clause is taken.

print "Enter Cost ":
input @(5,5):cost "r2$"

 This example uses masking, the above mask "r2$" will right justify, 
use 2 decimal places and put a '$' on the left of the forced numeric 

 print @(5,5):"Name: ":
input = item<3>, 20 ,"_ " :_
item<3> =

Displays a prompt for a name on a formatted screen. The data to be edited 
appears as though the user already typed it in a field of 20 underscores (the 
first character in fill.expression).  As the user edits the data (when 
backspace or backword is used), underscores replace any erased data. When done, 
the user must press <CR> or <LF>.  The data is then repainted, the 
underscores dissappear and are replaced with spaces (the second character of 
Related basic.then/else.construct