@READ_NUM

@READ_NUM reads a numeric value entered from the keyboard. The digits are displayed in a window by applying the specified picture format at the specified location as each digit is entered. When the input from the keyboard has been terminated, this system function returns the numeric value entered from the keyboard. Since the numeric value is displayed as they are entered, the specified window must be pasted before using this function.

When @READ_NUM starts execution, the cursor is pointing at the right most column of the input field. As the digits are being entered from the keyboard, the digits are shifted to the left and the cursor remains at the right most column.

During the input process, the only editing allowed is to delete the characters one at a time with the Delete /Rubout key. The input from the keyboard is terminated if:

The number of characters entered from the keyboard equals the width of the input field specified by the parameter of this function.

Any one of the cursor keys (arrow keys) is pressed.

One of the terminator characters is entered from the keyboard. The terminator characters are defined in the system fields @TERM_LIST, @END_ CODE, and @CANCEL_CODE. The Return key and the Tab key are the default character codes stored in @TERM_LIST. The default character codes stored in @END_CODE and @CANCEL_CODE are Control-Z (^Z) and Control-G (^G), respectively. These system fields are described under Related system fields in this section.

These system fields are also used by the FILL statement/command. Be aware that any changes that are made to these user-modifiable system fields will also affect the FILL statement/command.

RETURNS

When the input from the keyboard is completed, the numeric value entered from the keyboard is returned as the value of this system function.

There is another value returned by this system function. This value is stored in the integer system field @TERM_CODE and contains the keycode of the key that was used to terminate the data input from the keyboard. For example, if the Tab key is used to terminate the input, the value of @TERM_CODE is 9. However, if the input is terminated because the number of characters entered from the keyboard is equal to the width of the input field, @TERM_ CODE has a value of zero.

SYNTAX

@READ_NUM (window_id start_row start_column width rendition picture_format [,default_value])

window_id	is an integer system field, Global Storage (GS) field, or user-defined field that contains the window ID assigned to the window.
start_row	is an integer expression that specifies the row position where the input field begins in the window.
start_column	is an integer expression that specifies the column position where the input field begins in the window.
width	is an integer expression that specifies the width or number of columns in the input field.
rendition	specifies the video attributes for the input field. The video attributes for the entire input field are changed and the original video attributes are not restored. More than one attribute may be defined by separating the attributes with plus signs.
	The valid video attributes are: NORMAL specifies normal video attribute. [default setting] BLINK specifies blinking video attribute. BOLD specifies bold face video attribute. REVERSE specifies reverse video attribute. UNDERLINE specifies underlining video attribute.
picture_format	is a quoted string literal that specifies the desired picture format. This format controls the form in which the numeric value will be displayed. See the ACCENT R Reference Manual for additional details on picture formats.
default_value	is an optional numeric argument that specifies a default value which is returned if a new value is not obtained from the keyboard.

EXAMPLE

@READ_NUM(MAIN_ID 5 10 10 REVERSE "$$$ $$$.DD") &
TO CREDIT_LIMIT

SCREEN CHANGE_RENDITION USING MAIN_ID 5 10 1 10 &
NORMAL

When the first statement is executed, the cursor is positioned at row 5, column 20 of the window. The rendition of the input field (row 5, column 10 to row 5, column 20) is changed to reverse video. If the numeric value "3000" was entered then followed by a Tab, the statement stores that numeric value in the user-defined field CREDIT_LIMIT. The picture format is dynamically applied to the numeric value and the numeric value is finally displayed as: $3,000.00.

The original rendition is not restored by @READ_NUM. The input field's original rendition is restored by the SCREEN CHANGE_RENDITION statement.

SEE ALSO: SCREEN CHANGE_RENDITION Statement (later in this section) @TERM_LIST, @END_CODE, @CANCEL_CODE, @TERM_CODE System Fields (earlier in this section).