The KEYSTROKE variable defines the actions to be taken for a single keystroke. You need to add one KEYSTROKE line for each key that you wish to redefine. The maximum number of allowed KEYSTROKE entries is 170.
KEYSTROKE entries consist of keywords and associated values that describe the action to be taken, plus the key code (a two-character name) of the key, or key combination, being defined. All definable keys have such a name. The key code is case sensitive, although the rest of the KEYSTROKE line is not. The ASCII value of the key (decimal) may be used instead of the key code. Note that this is the only way to assign a value to the DEL key (ASCII value 127). The syntax of the KEYSTROKE line is:
KEYSTROKE keyword=value [keyword=value] key-code
The key-code argument is one of the two-character codes shown in the "Table of Keys", section 4.3.2.3. Keywords are separated from each other by spaces or tabs. For example:
KEYSTROKE EDIT=Next TERMINATE=13 ^M
The following keywords may be used:
1. AT-END=value
If value is "Yes", the key becomes a termination key that also causes the AT END condition. This keyword may not be specified along with either the TERMINATE or EXCEPTION keywords. The AT END condition always returns a termination value of "-1" in the CONTROL KEY clause. AT-END keystrokes are always allowed, but will cause no action unless an AT END, EXCEPTION, or CONTROL KEY clause is present in the ACCEPT verb. The default keyboard defines no AT-END keys. See also the AT END phrase of the ACCEPT verb in the ACUCOBOL-GT Reference Manual, Procedure Division.
2. DATA=value
This keyword is used to assign special characters to keys. DATA associates a decimal ASCII value with a key; the Terminal Manager will return this value to the COBOL program when the key is pressed. If the DATA keyword is used, no other keywords may be specified for this key.
3. EDIT=value
EDIT is used to define an editing action for a key. It must be assigned one of the following values:
| Alt
| Left
|
| Auto-Insert
| Menu
|
| Backspace
| Next
|
| Default-Entry
| Next-All
|
| Default-Next
| Next-Line
|
| Delete
| Numeric-Default
|
| Down
| Numeric-Next
|
| End
| Page-Down
|
| Erase-All
| Page-Up
|
| Erase-EOS
| Previous
|
| Erase Field
| Previous-All
|
| Erase-Next
| Previous-Line
|
| Erase-to-End
| Right
|
| First
| Switch-Window
|
| Home
| System-Menu
|
| Insert-Off
| Toggle-Edit-Mode
|
| Insert-On
| Toggle-Insert
|
| Insert-Space
| Up
|
| Last
|
In the following descriptions, the order of fields is the order in which they appear in the Screen Section. Thus, the "next" field may not necessarily be the next one on the physical display. This feature can be used to design special purpose screens.
EDIT keyword values can be:
Alt The character-based version of the runtime supports the use of key letters in controls. The user can activate a particular control by pressing a predesignated key in combination with the control's key letter.
Use the Alt function to designate the key to be pressed in combination with the control's key letter. Note that under Windows and MS-DOS the Alt key is predefined. On these systems the user presses the "Alt" key in conjunction with the key letter.
Auto-Insert Auto-Insert causes all following characters to be entered in insert mode. Auto insert mode is automatically reset when the input terminates, or when any other editing key is typed. This style of insertion is the RM/COBOL-85 default method.
Backspace The Backspace function moves the cursor to the left one character and deletes the character found there. If the Backspace function occurs at the left-most field position, it is ignored unless a TERMINATE or EXCEPTION value has been assigned to the key, in which case it is treated as a termination key.
Default-Entry The Default-Entry action erases the remainder of the field starting at the cursor position provided that the cursor is not in the first position of the field. If the cursor is in the first position, this action does nothing. This editing action is intended to be tied to a termination key (such as the "Return" key or the "Tab" key), and to be used as a reasonable method of handling fields that contain default values. If the default is correct, then this key is typed (which does nothing to the field). If the default is wrong, then the correct value is entered and this key is typed (erasing the part of the old field after the new input).
Default-Next Default-Next combines the Default-Entry action and the Next (described below) action.
Delete Deletes the character that the cursor is on (if any).
Down If there are fields below the current cursor location, the cursor moves to the one on the closest lower line. If there is more than one field on this line, the cursor will move to the one closest to its current horizontal location. The cursor will try to stay in the same column. If there are no fields beneath the current line, then this action does nothing unless an EXCEPTION or TERMINATE value has been assigned to it, in which case it acts as a termination key.
End The cursor is moved to the end of the current field, excluding any trailing prompt characters. If the cursor is already at the end of the field, then this key is ignored unless it has a TERMINATE or EXCEPTION value, in which case it is treated as a termination key.
Erase-All All fields controlled by the ACCEPT statement are erased and the cursor is moved to the home position of the first field. This key may not be assigned a TERMINATE or EXCEPTION value.
Under windows, the field in which the cursor is currently positioned is erased, instead of all fields controlled by the ACCEPT statement being erased.
Erase-EOS The current field is erased from the cursor location to the end of the field, and all fields following the current one are erased. The definition of "following field" is based on the order of fields in the Screen Section. This action may not be assigned a TERMINATE or EXCEPTION value.
Under windows, the current field is erased from the cursor location to the end of the field, but the fields following the current one are not erased.
Erase-Field The field is erased, and the cursor is moved to the first position of the field.
Erase-Next This action combines the functions of the Erase-to-End action and the Next (described below) action.
Erase-to-End This function erases the field from the current cursor position to the end of the field.
First The cursor is moved to the beginning of the first field controlled by the ACCEPT statement. If the cursor is already in the first field, and the key has been assigned a TERMINATE or EXCEPTION value, then the ACCEPT terminates.
Home The cursor is moved to the beginning of the field. If the cursor is already at the beginning and this key has been assigned a TERMINATE or EXCEPTION value, the ACCEPT terminates.
Insert-Off If insertion mode is currently in effect, it is turned off; otherwise does nothing.
Insert-On This causes all following characters to be entered in insert mode. This causes any trailing characters to be moved one space to the right before the added character is printed. Insertion mode stays in effect until explicitly reset by an Insert-Off, an Auto-Insert, or a Toggle-Insert action. Note that insertion mode stays in effect across multiple ACCEPT statements.
Insert-Space A space character is inserted at the cursor position, moving trailing characters over one position.
Last The cursor moves to the end of the last field controlled by the ACCEPT statement. Trailing prompt characters in the last field are ignored in determining the end of the field. If this key has been assigned a TERMINATE or EXCEPTION value and the cursor is already in the last field, the ACCEPT terminates.
Under windows, with TERMINATE and EXCEPTION value, if the cursor is at the last field, the ACCEPT does not terminate and the cursor stays at the current field.
Left The cursor is moved one position to the left; if it is already in the left-most field position, it moves to the end of the previous field. If the cursor is in the left-most position of the first field, the key is ignored unless it also has been assigned a TERMINATE or EXCEPTION value, in which case the ACCEPT terminates.
Under windows, without TERMINATE and EXCEPTION value, if the cursor is in the leftmost position of the first field, the key is not ignored and the cursor is moved to the last field.
Menu The key is defined as a Menu key. Pressing this key will cause a program-defined menu to appear on the screen.
Next The cursor advances to the beginning of the next field. If the cursor is already in the last field, it moves to the end of the field unless this key has been assigned a TERMINATE or EXCEPTION value. In that case, the ACCEPT terminates.
Under windows, without TERMINATE and EXCEPTION value, if the cursor is in the last field, it moves to the first field, instead of moving to the end of the field.
Next-All The cursor moves to the beginning of the next field regardless of whether or not the next field has a Tab-Stop. Thus a key with the "Next" action will skip controls with the NO-TAB style, while a key with the "Next-All" action will not.
By default, the Down key is assigned the Next-All action. This makes the Down key behave more like it does in a common Windows program. Assign the Down keyword (described above) for a more traditional, text-mode behavior.
Next-Line Next-Line functions the same as the Down action, except that the cursor always moves to the beginning of the left-most field on the new line (instead of maintaining the current cursor column).
Numeric-Default If the field is numeric, then this key acts just like the Default-Entry key. Typing this key at the first character position of a numeric field leaves the field unchanged and accepts the default value. Typing this key when the cursor is not in the first position causes erasure of the field from the cursor position to the end. This key allows the user either to accept the default or type over it without having to worry about blanking out the trailing portion of the field.
If the field is alphanumeric, then this action does not affect the field. Numeric-Default is usually made a termination key, so that typing it causes the ACCEPT to finish.
Numeric-Next If the field is numeric, then this key acts just like the Default-Next key. Typing this key at the first character position of a numeric field leaves the field unchanged, accepts the default value, and advances to the beginning of the next field. Typing this key when the cursor is not in the first position causes erasure of the field from the cursor position to the end. The cursor is then advanced to the beginning of the next field. This key allows the user either to accept the default or type over it without having to worry about blanking out the trailing portion of the field.
If the field is alphanumeric, then this key acts just like the Next key. It advances the cursor to the beginning of the next field and does not affect the current field.
Page-Down This keyword sets the key that pages down a multiline entry field, list box, and combo box.
Page-Left This keyword sets the key that scrolls left one page.
Page-Right This keyword sets the key that scrolls right one page.
Page-Up This keyword sets the key that pages up a multiline entry field, list box, and combo box.
Previous The cursor moves to the beginning of the previous field. If the cursor is in the first field, it moves to the beginning of the field unless the key has been assigned a TERMINATE or EXCEPTION value, in which case it acts as a termination key instead.
Previous-All The cursor moves to the beginning of the previous field regardless of whether or not the previous field has a Tab-Stop. Thus a key with the "Previous" action will skip controls with the NO-TAB style, while a key with the "Previous-All" action will not.
By default, the Up key is assigned the Previous-All action. This makes the Up key behave more like it does in a common Windows program. Assign the Up keyword (described below) for a more traditional, text-mode behavior.
Under windows, without TERMINATE and EXCEPTION value, if the cursor is in the first field, it moves to the last field, instead of moving to the beginning of the field.
Previous-Line The cursor moves to the beginning of the left-most field on the next higher line. If there are no fields above the current one, this action does nothing unless it has an EXCEPTION or TERMINATE value, in which case it acts as a termination key.
Right This function moves the cursor one position to the right. This will not move the cursor onto any trailing prompt characters (exception: if the prompt character is a space and the field is being updated, the cursor will move over the trailing spaces).
If the cursor is as far right as it is allowed to go, it will move to the beginning of the next field. If there is no following field, this key is ignored unless a TERMINATE or EXCEPTION value has been assigned, in which case the ACCEPT terminates.
Under windows, without TERMINATE and EXCEPTION value, if the cursor is as far right as it is allowed to go, the key is not ignored and moves to the first field.
Scroll-Left This keyword sets the key that scrolls left one column.
Scroll-Right This keyword sets the key that scrolls right one column.
Switch-Window This keyword defines the key that, when pressed, causes the system to enter "switch window mode." In this mode, the user can press any key to cycle through the modeless windows, with each window border highlighted until the "Return" key is pressed. Window switching order is from top to bottom.
System-Menu Use the System-Menu function to define the key used to activate a floating window's system menu on a text-mode system.
Toggle-Edit-Mode This keyword defines the key that can be used to toggle the presence of the combo box's drop-down list and the paged list box's search box.
Toggle-Insert If insertion mode is currently in effect, it is turned off. Otherwise, insertion mode is turned on.
Up If there are fields above the current cursor location, the cursor moves to the one on the closest higher line. If there is more than one field on this line, the cursor moves to the field closest to its current location. The cursor will try to stay in its current column. If there are no lines above the current line with active fields, then this key is ignored unless it has a TERMINATE or EXCEPTION value, in which case it acts as a termination key.
4. EXCEPTION=value
The purpose of this keyword is to create an exception key. EXCEPTION assigns a decimal ASCII value to a key; the key becomes a termination key that also causes an exception condition. The assigned value is returned in the EXCEPTION clause or the CONTROL KEY clause of the ACCEPT statement. See the TERMINATE keyword below if you want to terminate input without causing an exception condition. Note that ACUCOBOL-GT inhibits exception keys when no EXCEPTION or CONTROL KEY clause is present in the ACCEPT statement, unless the program was compiled with the "-Vx" option.
5. HOT-KEY=value
ACUCOBOL-GT offers two methods for assigning hot keys: the KEYSTROKE keyword HOT-KEY described here, and the HOT-KEY runtime configuration variable described in Appendix H. Either or both may be used, but the results are undefined if you assign the same key using both formats. The total number of hot-key entries defined by both methods cannot exceed 16.
A hot key is a key that is associated with a program, so that when the key is pressed, the corresponding program is run. Value is the program name, which must be specified in single or double quotes if it is lowercase. The full configuration file entry looks like this:
KEYSTROKE HOT-KEY=program-name key-code
Pressing the key specified in key-code initiates execution of the program just as if it were named in a CALL statement. The key-code argument is one of the two-character key codes shown in the "Table of Keys," section 4.3.2.3.
For example, there is a screen printing sample program named PRNTSCRN provided with ACUCOBOL-GT. If you want to be able to initiate that program just by pressing the keyboard's "print" key, add the following line to your configuration file:
KEYSTROKE HOT-KEY=PRNTSCRN KP
Hot keys are active only during Format 1 and Format 2 ACCEPT statements (these are the forms of the ACCEPT verb that allow the user to enter data at the keyboard). When the user presses a hot key, the current program status is saved, and the program associated with the hot key is run. When the hot-key program exits (via the EXIT PROGRAM statement), control is returned to the program that was running when the hot key was pressed. The hot-key function does not save the original contents of the screen. You can accomplish this by popping up a window in your hot-key program, and then closing the window just before you exit the hot-key program.
A hot-key program is automatically passed two parameters. The first parameter is PIC X(200). It contains an image of the data in the field that was being entered at the time the hot key was pressed. The second parameter is a COMP-1 field that contains the length of the field being entered. You can define the first parameter as a table that depends on the second parameter like this:
LINKAGE SECTION.
01 CURRENT-FIELD.
03 OCCURS 1 TO 200 TIMES
DEPENDING ON FIELD-SIZE PIC X.
01 FIELD-SIZE PIC S9(4) COMP-1.
You are not required to declare or use either of these parameters in your hot-key program--they are provided for convenience.
The hot-key program may modify its first parameter. Any modifications made are reflected in the field that was being entered when the hot-key program was called. You might use this capability to perform a look-up function and then return the value found to the field being entered. If you want to pass additional data to the hot-key program, use EXTERNAL DATA ITEMS.
When a hot-key program is started, the value of the RETURN-CODE special register is saved and then set to zero. The hot-key program may alter this value. When the hot-key program exits, the value of RETURN-CODE is checked. The following table shows the possible values and the action that the calling program will take:
| Value
| Action
|
| 0
| continue ACCEPT
|
| >0
| generate exception if allowed
|
| -1
| activate "next field" logic |
If the value is greater than zero, then the calling program acts as if an exception key (with that value) was pressed. This will terminate the ACCEPT statement if it is of a format that allows exception keys.
If the value is "-1", then the ACCEPT statement will act as if a "next field" key were pressed by the user. This will cause the ACCEPT statement to proceed to the next field. If there are no more fields (or if there is only one field), then the ACCEPT statement will terminate with a termination value of zero. The hot-key program should not set RETURN-CODE to any negative value other than "-1". Other negative values are reserved for future use by ACUCOBOL-GT.
In any case, after the RETURN-CODE value established by the hot-key program has been acted upon by the calling program, RETURN-CODE is restored to the value it held before the hot-key program was called.
If a hot-key program cannot be executed, an error message is displayed to the user, and control returns to the ACCEPT statement.
Up to two hot-key programs per process may be active at once.
6. INVALID=value
If value is "Yes", the key is ignored when it is typed. This keyword may not be specified with any other keywords.
7. TERMINATE=value
This keyword is used to create a termination key. TERMINATE assigns a decimal ASCII value to a key; when the key is pressed, the ACCEPT is terminated and the assigned value is returned in the CONTROL KEY clause of the ACCEPT statement. TERMINATE does not cause the key to generate an exception condition when pressed; to define an exception key, use the EXCEPTION keyword instead.