INPUT

Receives user input.

Synopsis

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

INPUT variable,-1

Arguments

@(col,row)	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 Terminal window; row=23 is the bottom of the Terminal window.
variable	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.
length	Optional — 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. If length is omitted, or length=0, data of any length can be specified. The data is accepted by pressing the Enter key. The length integer can be followed by the underscore (_) character, and/or the colon (:) character (in any order). These special-purpose characters are described below. If length 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.
format	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.
FOR n WAITING n	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.

Description

The INPUT statement has two forms:

INPUT with length specified as a positive integer, or with length unspecified. This syntax receives input data. It can be used in interactive programs to receive input data from the user, or to receive input data non-interactively from the DATA statement.
INPUT with length specified as -1. This syntax tests for the presence of input data and returns a boolean value.

Receiving Input Data

The INPUT 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.

If length 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 (or 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 argument, 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.

INPUT 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 if length is not specified; otherwise, append the colon to length. You can include or omit a space between variable or length and the colon.

If length=0, user input continues until the Enter key is pressed.

If you specify the optional @(col,row) 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,row) clause suppresses the line return following data input. For further details, refer to the @ function.

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.

Timeout

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.

The n 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.

INPUT and INPUTIF

INPUT 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 and INPUTIF are otherwise identical.

Testing for the Presence of Input Data

If length=-1, INPUT 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 with length=-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
DATA "abc"
INPUT var,-1 THEN PRINT "Boolean=",var    ;! prints 1
CLEARDATA
INPUT var,-1 THEN PRINT "Boolean=",var    ;! prints 0

Because INPUT with length=-1 does not prompt for data, the underscore (_) and colon (:) special-purpose characters have no effect. The @(col,row), format, 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:

SLEEP 5
  ;! 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.

Non-text Input Values

Null String

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.

Space and Tab

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.

Ctrl-C

If the user types Ctrl-C at the prompt, INPUT behavior depends on the BREAK setting.

If 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.
If BREAK is enabled (ON), the process checks the login mode. If in Programmer mode, the process enters the ObjectScript debugger. If in Application mode, it does not enter the debugger. For further details refer to the ObjectScript BREAK command in the Caché ObjectScript Reference.

INPUT and DATA

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.

The length argument suffix characters (colon or underscore) have no effect on DATA statement input.

INPUT treats a DATA value of the empty string (DATA "") as an actual data value: If length=-1, INPUT sets variable=1.

If a DATA statement contains a comma-separated list of arguments, these arguments are supplied in order to multiple invocations of the INPUT statement.

Values supplied by a DATA can be flushed using the CLEARDATA statement. Following a CLEARDATA, the next INPUT prompts the user for input data.

You can configure INPUT to accept only stacked DATA input values. You can configure this behavior using the class method %SYSTEM.MV.InputDataOnly()Opens in a new tab. Setting InputDataOnly() to 0 (the default) causes INPUT to accept both stacked DATA and user-input data values; once all stacked DATA values are exhausted, the next INPUT statement prompts the user for input data. Setting InputDataOnly() to 1 causes INPUT to accept only stacked DATA values; once all stacked DATA values are exhausted, the next INPUT statement issues an ABORT. You can determine the status of the InputDataOnly() flag by displaying the ObjectScript $MVV(218) special variable.

Examples

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
IF namevar=""
   PRINT "No name input"
ELSE
   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".

namevar="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:

DATA "Adams","Bean","Clarkenwell","Davis"
FOR i=1 TO 4
  INPUT namevar,5
  PRINT "Last name (max 16 chars) ":namevar
NEXT

Emulation

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.