HOT-KEY - ACUCOBOL-GT offers two methods for assigning hot keys--the HOT-KEY variable, described here, and the KEYSTROKE hot-key format described in the User's Guide, section 4.3.2.2 .
Using the HOT-KEY variable described below, you can easily assign a whole range of keys to a single hot-key program and determine which key activated the program. This lets you write a single program that handles an entire menu. Each menu item can act as a "hot key" to call this program.
This HOT-KEY format differs from the KEYSTROKE hot-key described in the User's Guide in three ways:
You assign a hot key by referencing its exception value instead of referencing its key code. Thus, if you assign the same exception value to several individual keys,
you can associate these keys with the same hot-key program by making one COBOL
configuration file entry.
Similarly, menu items and individual keys can be assigned the same exception value, and then associated with the same hot-key program in a single configuration file entry.
You may assign a range of exception values to activate the same program. You
could use this to write a menu handler by assigning all of your menu items to a
unique range and then assigning that range to a single hot-key program.
A hot-key program activated using the HOT-KEY format is passed an additional
parameter. This third parameter contains the value of the exception key that
activated the program. This is passed as a COMP-1 data item.
Use this variable to associate an exception value, or range of values, with a program. HOT-KEY has the following format:
HOT-KEY program = value1 [, value2]
where program is the name of the program to run, value1 is the lower (or only) exception value that activates the program, and value2 is the upper value of the activation range. Value2 may be omitted; if it's used it must include the separating comma. You must place program in single or double quotes if you require a lower-case program name.
For example, to assign a program called "mymenu" to exception values 100 through 200, use the following entry:
HOT-KEY "mymenu" = 100, 200
A special exception value named TIMEOUT may be specified as the first exception value. When this value is used as the first exception value for a HOT-KEY program, the runtime will execute the named program whenever an ACCEPT BEFORE TIME times out. When that occurs, the second exception value is ignored.
Remote name notation is allowed for the HOT-KEY variable if your runtime is client-enabled. See User's Guide sections 5.2.1 and 5.2.2 for more information about client-enabled runtimes and remote name notation.
Multiple HOT-KEY entries may reference the same program. This allows you to specify noncontiguous activation ranges. (Be aware that no more than 16 hot-key entries can be included in the COBOL configuration file. Using a contiguous range of exception values assigns many keys while counting as only one entry towards the limit.)
If you specify a value1 value of "0", then all hot-key references to program are removed. Within a given run unit, this is the only way to remove the assignment of an exception value to a hot-key program after it has been assigned. You will probably use SET ENVIRONMENT in your source code to do this.
If you assign multiple hot-key programs to the same exception value, the results are undefined.
You may assign different hot keys using both the HOT-KEY variable, described here, and the KEYSTROKE hot-key format described in the User's Guide, section 4.3.2.2 . 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.