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 Table of Keys. 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 F11 key, add the following line to your configuration file:
KEYSTROKE HOT-KEY=PRNTSCRN U1
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 of RETURN-CODE is zero, then the calling program continues to a normal completion of the ACCEPT statement that was active when the hot key was pressed.
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.