HOT_KEY

ACUCOBOL-GT offers two methods for assigning hot keys--the HOT_KEY variable, and the KEYSTROKE hot-key format. See The KEYSTROKE Variable in the ACUCOBOL-GT User's Guidefor more information.

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 System Requirements and Remote Name Notation in the ACUCOBOL-GT User's Guide 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. 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. See The KEYSTROKE Variable in the ACUCOBOL-GT User's Guide for more information.