ContentsIndexPreviousNext

The KEYSTROKE Variable

KEYSTROKE entries define how a particular key (or key combination) is interpreted. They consist of one or more keywords and associated values that describe the action to be taken, plus the two-character key code of the key being defined. 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 , which is in the section that follows. Spaces or tabs separate the sets of keywords and values from each other. 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. 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 cause no action unless an AT END, EXCEPTION, or CONTROL KEY clause is present in the ACCEPT statement.

2. DATA=value

This keyword is used to assign special characters to keys. Value is a decimal ASCII number; the Terminal Manager returns that 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

Used to define an editing action for a key; value specifies one of the functions described below. EDIT keys may also be designated as termination keys; when that is so, the EDIT is applied and then the input is terminated. For actions that move the cursor, the field terminates only if the cursor cannot be moved farther in the requested direction.

Note that the "next", "following", "first", "last", or "previous" field in the descriptions below refers to the order in the program's Screen Section, which may not be the same as on the physical display.

Also note that "end of field" does not usually include trailing prompt characters.
EDIT keyword values:

Alt

You can activate a particular control by pressing a predesignated key in combination with a control's key letter. This value allows you to designate that key. For character-based systems only.

Auto-Insert

Causes all following characters to be entered in insert mode until the input terminates or another editing key is typed.

Backspace

Moves the cursor to the left one character and deletes that character. At the left-most field position, it is ignored unless a TERMINATE or EXCEPTION value has been assigned to it, in which case it is treated as a termination key.

Default-Entry

Erases the remainder of the field starting at the cursor position if the cursor is not in the first position of the field. If the cursor is in the first position, this action does nothing, and the data in the field is accepted. The key must also be defined as a termination key to have these effects.

Default-Next

Combines the Default-Entry action and the Next action.

Delete

Deletes the character that the cursor is on.

Down

Cursor moves to the same column, or the closest column that is within a field, on the next lower line. If there are no fields beneath the current line, this action does nothing unless it has an EXCEPTION or TERMINATE value, in which case it acts as a termination key.

End

The cursor is moved to the end of the current field; if the cursor is already there, this key is ignored unless it has a TERMINATE or EXCEPTION value, in which case it acts 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. A key with this action may not be assigned a TERMINATE or EXCEPTION value.

Erase-EOS

The current field is erased from the cursor location to the end of the field, and all following fields are erased. A key with this action may not be assigned a TERMINATE or EXCEPTION value.

Erase-Field

The field is erased, and the cursor is moved to the first position of the field.

Erase-Next

Combines the Erase-to-End action and the Next action.

Erase-to-End

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 this key has a TERMINATE or EXCEPTION value, 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 a TERMINATE or EXCEPTION value, the ACCEPT terminates.

Insert-Off

If insertion mode is currently in effect, it is turned off; otherwise Insert-Off does nothing.

Insert-On

All following characters are entered in insert mode. Insertion mode stays in effect, across multiple ACCEPT statements, until reset by an Insert-Off, Auto-Insert, or Toggle-Insert action.

Insert-Space

A space character is inserted at the cursor position.

Last

The cursor moves to the end of the last field controlled by the ACCEPT statement. If this key has a TERMINATE or EXCEPTION value and the cursor is already in the last field, the ACCEPT terminates.

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 a TERMINATE or EXCEPTION value, in which case the ACCEPT terminates.

In the case of Windows, the left and right arrow keys move the cursor inside a field but do not act as terminators. 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 causes 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 which case the ACCEPT terminates.

Next-All

The cursor moves to the beginning of the next field whether or not the next field has a Tab-Stop. Thus, a key with the Next action skips controls with the NO-TAB style, while a key with the Next-All action does not.

By default, the Down key is assigned the Next-All action. This makes the Down key behave as it does in a common Windows program. Assign the Down keyword (described above) for a more traditional, text-mode behavior.

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.

Numeric-Default

If the field is numeric, this key acts like the Default-Entry key. If the field is alphanumeric, this key has no effect. Numeric-Default is usually made a termination key, so that typing it causes the ACCEPT to finish.

Numeric-Next

Combines the function of the Numeric-Default action and the Next action.

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 that field, unless the key has been assigned a TERMINATE or EXCEPTION value, in which case the ACCEPT terminates.

Previous-All

The cursor moves to the beginning of the previous field whether or not the previous field has a Tab-Stop. Thus, a key with the Previous action skips controls with the NO-TAB style, while a key with the Previous-All action does not.

By default, the Up key is assigned the Previous-All action. This makes the Up key behave as it does in a common Windows program. Assign the Up keyword (described below) for a more traditional, text-mode behavior.

Previous-Line

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

Moves the cursor one position to the right. This does 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 moves over the trailing spaces). If the cursor is as far right as it is allowed to go, it moves 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.

In the case of Windows, the left and right arrow keys move the cursor inside a field but do not act as terminators. 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. (See Book 2, User Interface Programming, section 11.1.4, "Regarding Configuration Variables")

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 then press any key to cycle through modeless windows until the "Return" key is pressed. Window switching order is from top to bottom.

System-Menu

Defines 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

Cursor moves to the same column, or the closest column that is within a field, on the next higher line. If there are no fields above the current line, this action does nothing unless it has an EXCEPTION or TERMINATE value, in which case it acts as a termination key.

4. EXCEPTION=value

This keyword is used to create an exception key. Value is a decimal ASCII number. The key becomes a termination key that also causes an exception condition. Value is returned in the EXCEPTION clause or the CONTROL KEY clause of the ACCEPT statement. 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

Associates a key with a specific COBOL program, initiating execution just as if it were specified in a CALL statement. Effective only during ACCEPT. Value is the program name, which must be specified in single or double quotes if it is lower case.

ACUCOBOL-GT offers another method for assigning hot keys: the HOT_KEY runtime configuration variable described in the "Runtime Configuration File" chapter of this document. The total number of hot-key entries defined by both methods cannot exceed 16. Results are undefined if you assign the same key using both that method and the method described above.

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. Value is a decimal ASCII number. When the key is pressed, the ACCEPT is terminated and value is returned in the CONTROL KEY clause of the ACCEPT statement. This does not cause an exception; to define an exception key, use the EXCEPTION keyword instead.