Caché MultiValue Basic Reference
Receives user input.
INPUT [@(col[,row])] variable [,length [_]] [:] [format] [FOR n | WAITING n]
[THEN statements] [ELSE statements]
||Optional A clause that specifies the location (column and row) to put the input prompt on the screen. If you specify this clause, INPUT displays the previous value of variable at the prompt. A col value of 0 or 1 displays the prompt at column 1. If row is omitted, it defaults to row=1, the top of the Caché terminal window; row=23 is the bottom of the Caché terminal window.
||A variable used to receive the user input. This variable does not need to be previously defined. If length is not specified, you can follow variable with a colon (:) character to suppress the line return. This character is further described below.
An integer specifying the maximum length of the input data. By default, the input data is accepted when the number of characters specified in length
are input. If less than the number of characters specified in length
are input, the input data is accepted when the user presses the Enter key.
is omitted, or length
=0, data of any length can be specified. The data is accepted by pressing the Enter key.
integer can be followed by the underscore (_) character, and/or the colon (:) character (in any order). These special-purpose characters are described below.
is -1, variable
is assigned a boolean value indicating whether or not data was input. This option does not prompt the user for data.
||Suppresses line return.
||Requires Enter key to accept input data, regardless of the length of the input data.
||Optional A format mask string used to validate the input data. format can be specified with or without length. If length is specified, format can be preceded by a comma delimiter or just a blank space. For further details on format mask strings, refer to the FMT function.
||The FOR n and WAITING n clauses are functionally identical ways to specify a timeout value. n is an integer specifying tenths of a second to wait before timing out. Caché rounds n to the nearest whole second interval.
statement has two forms:
statement is used in interactive programs to receive input from the user. INPUT
pauses program execution while awaiting user input. By default, it displays a question mark (?) prompt to receive user input. (This prompt is modifiable using the PROMPT
statement.) The user types this input which is echoed character-by-character at the input prompt.
omitted, the user must press the Enter key to accept the input data.
If the input data is less than the number of characters specified in length
=0), the user must press the Enter key to accept the input data.
If the input data is equal to the number of characters specified in length
the input data is accepted without pressing the Enter key. However, if the underscore (_) character is specified after the length
specifies the maximum number of characters that can be input, but accepting the input data requires pressing the Enter key, regardless of the number of input characters.
can also receive data from the DATA
statement, as described below. If data is present in a DATA
statement, the ? prompt and user input are suppressed, and input is taken from DATA
By default, when INPUT
accepts data input it performs a line return. You can suppress this line return by following either the variable
or the length
argument with a colon character (:). You can append a colon to variable
is not specified; otherwise, append the colon to length
. You can include or omit a space between variable
and the colon.
=0, user input continues until the Enter key is pressed.
If you specify the optional @(col
) clause, the question mark (?) prompt appears at the specified column and row location. This prompt displays the previous value of variable
. (If variable
is undefined, the prompt displays an empty string as the previous value.) To accept the previous value, press the Enter key. To delete and replace this value, type the new value. To replace this value with a null value, press the space bar or tab key, then press the Enter key. This @(col
) clause suppresses the line return following data input. For further details, refer to the @
By default, the input characters and the @ clause previous value are echoed, regardless of the setting of ECHO
. However, INPUT
echoing is emulation-dependent. These values are echoed to the terminal; they are never echoed to the printer.
You can optionally specify a THEN clause, an ELSE clause, or both a THEN and an ELSE clause. If any data is input, the THEN clause is executed. If no data is input (the Enter key is pressed), the ELSE clause is executed. The statements
argument can be the NULL
keyword, a single statement, or a block of statements terminated by the END
keyword. A block of statements has specific line break requirements: each statement must be on its own line and cannot follow a THEN, ELSE, or END keyword on that line.
You can also use the KEYIN
function or the IN
statement to receive a single character of user input. You can use the <<...>>
inline prompt to prompt for a user input value to insert in a MVBasic statement or a MultiValue command line command. The <<...>>
inline prompt is described in the Caché MultiValue Commands Reference
Specifying a timeout for a user input prompt is optional, but highly recommended. You can specify a FOR n
clause or a WAITING n
clause to establish how long INPUT
should wait for completion of user input data before timing out. These two clauses are functionally identical. Input completion is determined by either the Enter key or length
value is an integer, specifying timeout in tenths of a second. However, Caché timeout is executed in whole seconds. For n
values less than 10, Caché times out at 1 second. For n
values greater than 10, Caché rounds to the closest whole second interval. Therefore an n
value of 3 specifies three-tenths of a second, but actually times out at one second; an n
value of 13 specifies thirteen-tenths of a second, but is rounded down to 10, so actually times out at one second; an n
value of 16 is rounded up to 20, so actually times out at two seconds.
When timeout occurs, Caché MVBasic executes the ELSE clause (if present). If no ELSE clause is specified, Caché MVBasic executes the next statement.
does not support type-ahead the user's ability to type input data before the prompt is displayed. The INPUTIF
statement does support type-ahead. INPUT
are otherwise identical.
Testing for the Presence of Input Data
does not prompt the user for data. It checks the input buffer for the presence of data and places a boolean value in variable
: 1 if data was present in the input buffer; 0 if no data was present in the input buffer. An empty string ("") is considered data. INPUT
=-1 tests for the presence of input data, but does not remove data from the input buffer or advance a buffer pointer.
You can use the DATA
statement to place data in the input buffer. You can use the CLEARDATA
statement to remove all data from the input buffer. This is shown in the following example:
INPUT var,-1 THEN PRINT "Boolean=",var ;! prints 0
INPUT var,-1 THEN PRINT "Boolean=",var ;! prints 1
INPUT var,-1 THEN PRINT "Boolean=",var ;! prints 0
=-1 does not prompt for data, the underscore (_) and colon (:) special-purpose characters have no effect. The @(col
, and FOR n
or WAITING n
clauses also have no effect.
To test for the presence of user-input data, use the SLEEP
statement to allow time for the user to type (or not type) data to the input buffer before INPUT
checks the input buffer for the presence of data. This is shown in the following example:
;! suspends execution for 5 seconds, allowing the user to type data
INPUT var,-1 THEN PRINT "Boolean=",var
;! prints 1 if user input data during sleep interval
;! or prints 0 if the user did not input data during sleep interval
;! The user-input data (if any) will appear at the MV command prompt
;! after the execution of this statement.
To input a null string, you must first designate a character to represent the null string using the INPUTNULL
statement. You then specify that designated character to INPUT
to specify the null string. This INPUTNULL
character designation only applies to the INPUT
statement. In all other contexts this character is a literal.
The user can input space characters and tab characters. In variable
space and tab are distinct characters. Both space and tab are length
=1, and both can be removed using a single backspace. However, when echoing input to the terminal, both space and tab are echoed as a space character.
If the user types Ctrl-C
at the prompt, INPUT
behavior depends on the BREAK
is disabled (OFF), any input data that the user has typed into INPUT
up to that point is deleted. The user can then type a new input value at the prompt and press Enter.
is enabled (ON), the process checks the login mode. If in Programmer mode, the process enters the Caché ObjectScript debugger. If in Application mode, it does not enter the debugger. For further details refer to the Caché ObjectScript BREAK
command in the Caché ObjectScript Reference
If you use the DATA
statement to pre-define a user input value, the INPUT
statement takes its value from the DATA
statement rather than from user input. The INPUT
statement does not pause program execution or require user interaction. The DATA
statement value does not conclude with a return character, and the INPUT
statement does not issue a line return. If the length
argument is specified, only that number of characters is input from the DATA
item value, but the entire DATA
item is consumed.
argument suffix characters (colon or underscore) have no effect on DATA
If a DATA
statement contains a comma-separated list of arguments, these arguments are supplied in order to multiple invocations of the INPUT
Values supplied by a DATA
can be flushed using the CLEARDATA
statement. Following a CLEARDATA
, the next INPUT
prompts the user for input data.
The following example displays the input prompt and pauses ten seconds for user input:
PRINT "Input the person's last name"
INPUT namevar,16 FOR 100
PRINT "No name input"
PRINT "Last name (max 16 chars) ":namevar
The following example positions the input prompt using the @(col,row) clause, then takes an input of any length to variable namevar
. If you press the Enter key or timeout without supplying any user input, namevar
retains the default value "ANONYMOUS".
INPUT @(1,23) namevar,16 FOR 100
The following example takes input data from the DATA
statement. At each iteration INPUT
takes the next DATA
value. Note that in this program INPUT
takes a maximum of 5 characters, regardless of the length of each DATA
value; each iteration advances to the next DATA
value. This program does not pause for user input. However, if the FOR
loop iterated one more time, the fifth INPUT
would prompt the user:
FOR i=1 TO 4
PRINT "Last name (max 16 chars) ":namevar
Several aspects of INPUT
echoing display are emulation-dependent:
For all emulations, except PIOpen, regardless of ECHO
setting, with INPUT @, the cursor is initially positioned, the prompt displayed, the original value of the data is displayed, and the cursor is positioned on the first character of the original value for user input.
For PIOpen, the cursor is positioned at the location specified by INPUT@, not on the prior position (as in other emulations), and the original value of the data is not displayed.
With ECHO OFF
set, the original value of the input variable is not displayed in all emulations except UniVerse and Cache.
With ECHO OFF
set, when you type user input it is displayed character-by-character in Cache, UniVerse, INFORMATION, PIOpen, PICK, and IN2 emulations; typing is not echoed in all other emulations.
With ECHO OFF
set, when input has been satisfied (by pressing Enter or by entering the number of characters specified on INPUT @) the new value of the variable is redisplayed for most emulations. On PIOpen and UniData no redisplay occurs. On jBASE, if ECHO ON
the cursor is positioned and the new value is displayed; if ECHO OFF
the cursor is positioned, and blank spaces the length of the new value are displayed. With ECHO OFF
set, D3 and Reality replace the length of the original value with blank spaces and then display the new value. With ECHO OFF
set, UniVerse replaces the original value with blank spaces when the user types the first character; UniVerse redisplays the new value after you press the Enter key.