INPUT

Read Terminated by Keystroke

This directive accepts data from a terminal or file. Pressing Enter, a function key, or an editing key generates a CTL value to Thoroughbred Basic, which terminates this directive.

Syntax

INPUT [EDT] [(channel [,I/O-opts])] [@(column[,row])]
[,mnemonic [,mnemonic...]] [,output] [,variable-list [:verification]]
[,IOL=line-ref]

INPUT [EDT] RECORD [(channel [,I/O-opts])] string-variable

EDT: specifies that negative CTL values are to be processed as well as positive CTL values. Without EDT only positive CTL values are processed (see CTL system variable). This option is generally available starting with release level 8.0.
channel: is any integer in the range of 0 to 32764 indicating the channel of the terminal or an OPEN file. If omitted, 0 is the default.
I/O-opts: is one or more of the following specifiers:
Branching: ERR=line-ref DOM=line-ref END=line-ref
Record: IND=numeric-value KEY=string-value
Miscellaneous: TBL=line-ref SIZ=numeric-value TIM=numeric-value LEN=numeric-value ERC=error-code
:verification: is an INPUT verification option (contained in parentheses) that specifies certain parameters necessary for values to be received. Use one of the following specifiers:

string-value=line-ref
LEN=min,max
[-]range-value

column[,: row] indicates the horizontal and vertical positioning of the cursor up to the maximum number of columns and rows available on this terminal; both numbers are zero-based (upper left corner of the screen is 0,0).
mnemonic: is a 2-character code, bounded by apostrophes, which indicate a special procedure to be performed on the terminal or device (e.g., 'LF' for Line Feed, 'CS' for Clear Screen, etc.). For more information on mnemonics, please refer to the Thoroughbred Basic Customization and Tuning Guide.
output: is a numeric or string constant or expression (but not a single variable) to be output to the terminal or device, before accepting input (e.g., a prompting message).
variable-list: is a list of numeric or string variables that receive values; asterisk (*) is a special case, which ignores the data that is entered.
line-ref: (IOL) specifies a program line number or label containing an IOLIST that defines a variable list to receive multiple INPUT fields. If both variable-list and IOL=line-ref are used, the variable-list receives data first, followed by the variables named in the IOLIST directive at line-ref.
string-variable: is any string variable name that receives an entire record as data.

Note: verification, column[, row], mnemonic, output, variable-list, and line-ref(IOL) can appear in other logical sequences than the one shown here.

Remarks

I/O-opts include:

ERR=: specifies the program line number or label to branch to if an error is produced by this directive.
DOM=: specifies the program line number or label to branch to if an attempt is made to access a record using KEY= and no such key value is found (ERR=11). DOM= takes precedence over ERR= in the same INPUT directive.
END=: specifies the program line number or label to branch to if this INPUT senses the end of the file (ERR=2). END= takes precedence over ERR= in the same INPUT directive.
IND=: specifies the INDEX number of the record to access in a file, zero-based.
KEY=: specifies the KEY value of the record to access in a file.
TBL=: specifies the program line number or label of the TABLE directive to be used for code conversion for the incoming data (see TABLE directive).
SIZ=: specifies the integer maximum size of data to be INPUT, in characters, before a field delimiter is automatically returned (results in CTL=5 if an attempt is made to go beyond SIZ= value).
TIM=: specifies the number of seconds allowed to elapse without any INPUT before an ERR=0 is returned, indicating a timeout. Actual time may vary by -1/+0 seconds. If the EDT option is used with a TIM=0, it results in an infinite timeout (normally TIM=0 results in an immediate timeout).
LEN=: specifies the integer maximum size of data to be INPUT, in characters. When the maximum size is reached no additional characters can be added except for a termination key, such as a carriage return.
ERC=: specifies a programmer-defined error code, which enables programmers to define and manage errors without branching. ERC= provides a structured programming alternative to ERR=.

:verification includes:

string-value=line-ref: is the program line number to branch to if the specific string-value is entered.
LEN=min,max: specifies the minimum and maximum number of characters to be accepted for this INPUT; less than minimum or more than maximum results in an ERR=48.
[-] range-value: specifies the minimum and maximum numeric values to be accepted for this INPUT; numbers outside the range results in ERR=48. Unsigned range-value indicates the range is 0 through range-value; negative range-value indicates the range is negative range-value through positive range-value.

Failure to pass all indicated verification clauses returns an ERR=48.

The IND= and KEY= options are mutually exclusive in the same INPUT directive.

Refer to the information on mnemonics in the Thoroughbred Basic Customization and
Tuning Guide for a more detailed discussion of the values available for this option.

Values input from a terminal or file are loaded into the variable list or IOLIST in sequential order. The first data value entered from a terminal or the first field in a record is loaded into the first variable, the second into the second variable, etc. An asterisk (*) is used to specify an entry or field that is skipped and does not have data entered into a variable.

The RECORD modifier is used when specifying a file to allow an entire record, including delimiting characters, to be entered as data into a single string variable. This modifier cannot be used with @(column[, row]), mnemonic, output, :verification, or IOL=line-ref options.

For an INPUT from a terminal, each value entered is followed by pressing Enter or a function key to end the entry.

This directive also sets the value of the CTL variable depending on which function key is pressed.

Examples

INPUT A$,B

provides for the input of data from the user terminal (an unspecified channel number defaults to 0, the user task terminal) into the variables A$ and B. The entry of each value is separated by pressing Enter, a control key, or a function key. If the data for the second variable is not a numeric value, an ERR=26 results.

INPUT *

allows for temporary program suspension until a carriage return or function key is pressed. The CTL variable is set according to which key is returned. No variable is assigned a value by this form of the directive.

INPUT (0,SIZ=4) @ (4,10),"ENTER ID: ",A$,B$

prints starting at column 4, row 10 of the terminal the message “ENTER ID: “ and positions the cursor after this message to accept entry of data. The first 4 characters are entered into the variable A$ and the remaining characters into B$. If less than 4 characters are typed followed by pressing Enter, then more characters, A$ contains the first few characters and B$ the rest. The code for the pressed Enter key does not appear in the INPUT.

INPUT (0,ERR=7999) 'CS', @(2), "FROM", X:(123)

clears the screen (‘CS’) and prints the message “FROM “, starting at column 2, row 0 (clear screen resets column and row to 0) and accepts a numeric value from 0 to 123. If the value entered is out of this range, an ERR=48 is returned and execution branches to statement 7999.

INPUT RECORD (1, IND=X, END=5000) A$

If X=24, accesses the file OPEN on channel 1 and INPUTs the record having the Index value

The entire record, including delimiting characters, is loaded into the variable A$. Execution branches to statement 5000 if an attempt is made to access a record beyond the end of the file.

00100 INPUT (0,SIZ=5,ERR=00100) 'CL' , "STRING$ ?",
STRING$:("GOOD"=01000, LEN=3,5), "NUMBER ?", NUMBER:(-3278)

clears the line the cursor is on (‘CL’), prints the prompt “STRING$ ? “, accepts up to 5 characters (SIZ=5), goes to line 01000 if the word “GOOD” is entered but accepts any 3 to 5 character string (LEN=3,5), then prints the prompt “ NUMBER ? “, and accepts any number in the range of -3278 through +3278. The string appears in STRING$ and the number in NUMBER.

INPUT

Syntax

Remarks

Examples

See also