@READ_DATE reads a date value entered from the keyboard. The characters for the date value are displayed in a window at the specified location. When the input from the keyboard has been terminated, the date value is re-displayed with the specified date format. Since the date value is displayed as it is entered, the specified window must be pasted before using this function.
When @READ_DATE starts execution, the cursor is pointing at the left most column of the input field. The date value is entered like a character field. The input formats for the date value allowed in this system function are:
- MM/DD/YY or MM/DD/YYYY if American Date is enabled.
- DD/MM/YY or DD/MM/YYYY if European Date is enabled.
- YY/MM/DD or YYYY/MM/DD if International Date is enabled.
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 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.
When the input from the keyboard is completed, the date 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 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 has a value of zero.
@READ_DATE (window_id start_row start_column width rendition date_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:
|
|
date_format |
is a string argument that represents a @DATSTR date conversion string. This format controls the form in which the date value will be displayed. If an empty string is specified, the default value of MM/DD/YYYY will be used (optionally YYYY-MM-DD or DD/MM/YYYY if ENABLE (INTER-NATIONAL; EUROPEAN) DATE is in effect). |
|
default_value |
is an optional date argument that specifies a default value which is returned if a new value is not obtained from the keyboard. |
@READ_DATE(MAIN_ID 5 10 15 REVERSE, &
"mmm dd,yyyy") TO BIRTHDAYSCREEN CHANGE_RENDITION USING MAIN_ID 5 10 1 15 & NORMAL
This example demonstrates a procedure that obtains an employee's birthday. 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 25) is changed to reverse video. If entering the date "7/4/1776" followed by a Tab, this statement stores that date in the user-defined field BIRTHDAY and the date is re-displayed as: Jul 4, 1776. @TERM_CODE is also set to 9, the keycode for Tab.
The original rendition is not restored by @READ_DATE. The input field's original rendition is restored by the SCREEN CHANGE_RENDITION statement.
SEE ALSO: @TERM_LIST, @END_CODE, @CANCEL_CODE, @TERM_CODE, SCREEN CHANGE_RENDITION Statement.