FINPUT

Field Input

This directive INPUTs data from a one-line Thoroughbred Basic Window on a terminal, allowing the use of standard keyboard cursor control keys, and providing for a larger INPUT data length than the Thoroughbred Basic Window used for the INPUT through the use of horizontal scrolling.

Syntax

FINPUT (channel, ATR=attribs [, EDT=edit-modes] [,TIM= seconds]
[,ERR=line-ref|,ERC=error-code]) variable-name

channel: is an integer in the range of 0 to 32764 indicating the channel of an OPEN terminal.
attribs: is a list of attributes defining the position of the Thoroughbred Basic Window on the screen and the length of the Thoroughbred Basic Window and data.
edit-modes: is a list of modes defining how to handle editing.
seconds: is an integer specifying the number of seconds allowed to elapse without any input before a CTL = -99 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).

line-ref: is the program line number or label to branch to if this directive produces an error.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.
variable-name: is the name of a string variable, string array element, or data name.

Remarks

This directive is generally available starting with release level 8.0.

A five- to seven-character attribute string is generally available starting with release level 8.2.

The format of attribs is:

Byte: Description
1: Attribute format: always $05$ for use in Thoroughbred Basic
2: Unsigned binary starting column on the screen (0-based)
3: Unsigned binary starting row on the screen (0-based)
4: Unsigned binary length of one-row Thoroughbred Basic Window in bytes. If set to $00$, input security is activated (entry is accepted but not displayed).

In a Thoroughbred Basic Windows environment, an alternative input security method is to use the EE and BE mnemonics. For more information on these mnemonics, please refer to the Thoroughbred Basic Customization and Tuning Guide.

5: Unsigned binary length of data to accept from window
6: Sets the terminal attribute state for the input Thoroughbred Basic Window (optional). See WINDOW ATTR for attribute state table.
7: Sets the colors (foreground-background color combination) of the input Thoroughbred Basic Window (optional).

A foreground-background combination is built by adding the background color code to the foreground color code. See WINDOW COLOR for the background and foreground color tables.

An invalid attribute number in the ATR string results in the attribute state for the input Thoroughbred Basic Window to default to the current terminal attribute state. If the current attribute state is desired, specify attribute state 255 (hex $FF$) in the attribute string.

This directive is also used by the system dictionary, but has different values in the first byte of attribs. Use of this directive with the first byte of attribs other than $05$ generates unpredictable results.

The EDT option is generally available starting with release level 8.1.

The format of the edit-modes string is:

Byte: Description
1: Unsigned binary starting cursor position within the field. First position is $00$ or $01$. Default is $00$.
2: End-of-field termination mode.

$00$ = Termination mode off (default);
$01$ = Termination mode on (terminates input when user makes entry on last character of field; CTL is set to 0).

3: Initial keystroke clearing mode.

$00$ = Clearing mode off (uses standard edit mode; default)
$01$ = Clearing mode on (uses standard edit mode when the initial keystroke is a field editing key; when the initial keystroke is not a field editing key, clears the field, ignores the starting cursor position from byte 1, and uses the character entered as the first character of the field).

4: Unsigned binary Escape key CTL value. Default is $00$ (CTL is set to 0 when the Escape key is pressed).
5: Upper-case conversion mode:

$00$ = Uppercase conversion off (default).
$01$ = Uppercase conversion of input characters only.
$02$ = Uppercase conversion of input characters and existing field data.

6: Special Key action bits:

$01$ = Exit on Tab and Backtab with CTL set .
$02$ = Exit on Up Arrow with CTL set to -4. The up arrow restart functions are assigned to the Escape key and CTL will be set to the value specified in EDT option byte 4.

The bytes in edit-modes are optional except that all lower position bytes must be specified. For example, use $000000$+CHR(100) to set the Escape key CTL value to 100.

If the user presses the up arrow key when on the first character of the field, the FINPUT terminates by saving any changes that were made, and setting CTL to -4. If the user presses the up arrow key when on any other character of the field, FINPUT ignores any changes that were made and restarts the input at the first character of the field (ignoring any starting cursor position defined in edit-modes). See also EDT option byte 6.

Starting with release level 8.2, a string array element can be specified as variable-name (see the syntax above) and it will receive the final data after all editing is complete.

Starting with release level 8.2, a data name can be specified as variable-name (see the syntax above) and it will receive the final data after all editing is complete. Because a data name has a defined length, the length of data to accept from the Thoroughbred Basic Window (fifth byte of attribs) is ignored, if specified. The number of characters to be accepted from the Thoroughbred Basic Window will be determined by the print length of the data name (ATR function, option 23).

If the final data are determined to be invalid according to a data name’s attributes, an
ERR=166 or ERR=167 results.

Examples

Note: The first input detects that the mouse click occurred by returning a specific CTL value. A second input is then required to return information about the click (i.e. the col and row where the click happened).

FINPUT (0, ATR=$050A0B0810$) B$

positions the cursor at column 10 ($0A$), row 11 ($0B$), which displays 8 underscore characters to show the window ($08$), and accepts up to 16 ($10$) characters of data from the console. Left and right cursor keys, backspace, left and right tabs, character insert, and character delete keys may be used to enter and edit data. The actual input is terminated by a carriage return or the Enter key. B$ contains the final data after all editing is complete. If the sequence of characters entered is the ten alphabetic characters from “A” through “J” followed by a carriage return, the window appears as follows:

A_______
AB______
ABC_____
ABCD____
ABCDE___
ABCDEF__
ABCEDFG_
ABCDEFGH
BCDEFGHI
CDEFGHIJ

and B$ contains the value “ABCDEFGHIJ”.

FINPUT (0, ATR=$05$+CHR(10)+CHR(11)+CHR(8)+CHR(16) ) B$

functions in the same manner as the first example but is easier to read and understand than ATR=$050A0B0810$.

FINPUT (0,ATR=$05$+CHR(10)+CHR(11)+CHR(8)+CHR(16)+CHR(8) ) B$

positions the cursor at column 10, row 11, displaying 8 underscore characters and accepting up to 16 characters where the attribute state of the input window is background intensity and blinking.

FINPUT (0,ATR=$05$+CHR(10)+CHR(11)+CHR(8)+CHR(16)+ CHR(255)CHR(112+9) )
B$

positions the cursor at column 10, row 11, displaying 8 underscore characters and accepting up to 16 characters where the color state of the input window is a blue on light gray color combination. The attribute state does not change.

DIM STR$[10];
FOR ROW=0 to 10;
      FINPUT (0,ATR=$050A$+CHR(5+ROW)+$0A14$) STR$[ROW];
NEXT ROW

positions the cursor at column 10, row 5+ROW, displays a 10-underscore-character input window, and accepts up to 20 characters of keyboard input for each element of the array STR$[ ].

FINPUT (0,ATR=$050A0514$,ERR=8000) #DNFFMT.DNAME

positions the cursor at column 10, row 5, displays a 20-underscore-character input window, and accepts keyboard input. #DNFFMT.DNAME contains the final data after all editing is complete. If an error occurs, statement 8000 is executed.