@READ_CHAR reads a character string entered from the keyboard and displays the characters as they are entered in a window at the specified location. When entry from the keyboard has been terminated, the entire input string of characters is returned. Since the characters are displayed as they are entered, the specified window must be pasted before using this function.
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.
Editing functions are available for @READ_CHAR input strings. When entering or changing data, the user can enter edit mode to modify the data instead of re-entering the entire field.
When the input from the keyboard is completed, the string of alphanumeric characters 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 which 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 will have a value of zero.
@READ_CHAR (window_id start_row start_column width rendition [,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:
|
| default_value | is an optional string argument that specifies a default value which is returned if a new value is not obtained from the keyboard. |
@READ_CHAR(MAIN_ID 5 10 20 REVERSE "N/A") TO &
STUDENT_NAME
...
SCREEN CHANGE_RENDITION USING MAIN_ID 5 10 1 20 &
NORMALThis example demonstrates a procedure which obtains the student's name. When the first statement is executed, the cursor is positioned at row 5, column 10 of the window. The rendition of the input field (row 5, column 10 to row 5, column 30) is changed to reverse video with the default string "N/A" displayed. If only the Return key is pressed, the default string "N/A" is stored in STUDENT_NAME. If entering the string "John Doe" and pressing the Return key, this statement will store that string in the user-defined field STUDENT_NAME. In both cases, @TERM_CODE will be set to 13, the keycode for the Return key.
The original rendition is not restored by @READ_CHAR 5. After the verification of STUDENT_NAME, the input field's original rendition is restored by the SCREEN CHANGE_RENDITION statement.SEE ALSO: "SMF FORMS FOR END-USERS" (earlier in this section) @TERM_LIST, @END_CODE, @CANCEL_CODE, @TERM_CODE System Fields (earlier in this section) SCREEN CHANGE_RENDITION Statement (later in this section).