Top  Previous  Next


The INPUT @ statement enables entry of data from the keyboard at a specific screen position or from previously stored DATA statements.





INPUT @(x, y) {,} {:} var {, length {, fill}} {_} {:} {format} {modes}

{THEN statement(s)}

{ELSE statement(s)}




x, yare the screen position (column and line) at which input is to occur.


varis the variable in which the data is to be stored.


lengthis the maximum length of data to be allowed. Because of a potential syntactic ambiguity in the language, this must be enclosed in brackets if it is an expression.


fillis a Pick style fill expression. The first character will be used to fill any spare space in the input field to make the field width clear to the user. The second character will be used to fill unused space after input is completed. If the fill string is only one character, spaces will be used. The third character, if present causes the cursor to be left at the end of the input field instead of the default action of leaving it after the last character of the entered data string. The fill option cannot be used with a format mask, PANNING or HIDDEN.


formatis the format specification to the used for initial display of var and to redisplay the data on completion of input.


modesare any combination of the following keywords:
APPENDPosition the cursor at the end of the data. Use of this keyword also implies EDIT mode.
EDITStarts in "edit" mode, suppressing the normal clearance of the input field if the first character entered by the user is a data character rather than an edit character.
HIDDENechoes characters back to the screen as asterisks for password type fields.
NO.ECHOSuppresses echo of input data.
NO.ENCODINGSuppresses decode of encoded input when the terminal is set to operate in UTF-8 mode. Use of this mode will also suppress encoding of data echoed back to the terminal.
OVERLAYStarts in "overlay" mode where data entered by the user replaces the character under the cursor rather than being inserted.
PANNINGAllows entry of an unlimited number of characters in a field width of the given length by panning the data if it is longer than the display width. Use of this option requires length to be specified and implies the presence of the underscore.
TIMEOUT waitSets a timeout period in seconds. If input is not received in this time, the INPUT terminates, leaving var unchanged. The keywords FOR or WAITING can be used in place of TIMEOUT for compatibility with other environments.
UPCASEconverts the input data to uppercase.


The comma after the cursor position is optional and has no effect on the operation of the statement.


The optional THEN and ELSE clauses used with TIMEOUT allow a program to determine whether the input timed out. Successful input executes the THEN clause. A timeout will execute the ELSE clause.



The INPUT @ statement reads data from the DATA queue or, if there is no stored data, from the keyboard.



Keyboard Input


When reading from the keyboard, the current prompt character will be displayed to the left of the given input position. No prompt is displayed if the input column position, x, is zero or if the prompt has been disabled using the PROMPT statement. The prompt character will be removed from the screen on completion of the input.


If the colon character before var is present, the original contents or var are displayed in the input area and entry commences in overlay mode. If the colon character before var is not present, entry commences in insert mode with a blank field.


The user has three options:

Pressing the return key retains the original content of var.

Typing a data character replaces the original content of var, clearing any old displayed data (unless the EDIT option is used).

Using an edit key (see below) allows the old data to be edited.


The values stored for printing characters are the ASCII characters associated with the key. Non-printing characters result in stored character values as listed under Character Values for Terminal Input.


If no length expression is included, data characters are stored until the return key is pressed.


If length is specified, up to that number of characters may be entered after which input is automatically terminated as though the return key had been pressed, any subsequent key entries being retained for the next INPUT statement. The return key is not stored as part of the input data.


The INPUT @ statement may not behave correctly if the length of the input field causes it to extend over multiple lines and the terminal in use does not automatically wrap from one line to the next when displaying long text output.


The optional underscore component of the statement suppresses the automatic input termination when length characters have been entered. Any number of characters may be entered but only length characters will be displayed.


The optional colon causes the carriage return and line feed output when the return key is used or on reaching the input length limit to be suppressed.


In all cases, the following editing keys are available.




Position the cursor at the start of the input data


Cursor left

Move the cursor left one character



Delete character under cursor



Position the cursor at the end of the input data


Cursor right

Move the cursor right one character



Backspace one character



Delete all characters after the cursor



Toggle insert/overlay mode. When overlay mode is enabled, data entered by the user replaces the character under the cursor rather than being inserted before this character. Unless the OVERLAY option is used, the input begins  in insert mode.


These editing keys can be modified using the KEYEDIT statement.


When the return key is pressed to terminate input, if a format is specified, the data is redisplayed using this mask to apply format rules such as right justification.



DATA Queue Input


Where the data queue is not empty, the INPUT @ statement reads the item at the head of this queue, copying it verbatim to var with no processing of any embedded control characters. The length expression is ignored. The item is displayed as though it had been typed but the prompt character is not displayed. Unless the NO.ECHO.DATA mode of the $MODE compiler directive or the NO.ECHO.DATA setting of the OPTION command is enabled, the item is displayed as though it had been typed.



Use of the STATUS() function after an INPUT @ statement returns zero unless input was terminated by a key defined using the KEYEXIT or KEYTRAP statements.



Use of Pipes


QM recognises input from pipes as a special case. Programs that process data from a pipe can read the data using the same QMBasic statements and functions as for keyboard input. If the end of the data is reached, a subsequent INPUT @ will return a null string. The STATUS() function will return ER$EOF.





DISPLAY @(0,10) : "Account " :


INPUT @(8, 10) : ACCOUNT.NO, 16


This program fragment displays the current value of ACCOUNT.NO with a suitable annotation and accepts input. Pressing the RETURN key alone will retain the original value as displayed. The PROMPT statement has been used to suppress display of the prompt character.



INPUT @(10, 5) : PRICE, 10 '10R'


This program fragment inputs a value for the PRICE variable, redisplaying it right justified on completion of input.



See also: