|Configuring Enhanced ACCEPT and DISPLAY||Windowing Support for Text-based Systems|
The Keyboard Configuration utility enables you to change the functions assigned to the keys on your keyboard. You can change the action performed by keys during execution of an ACCEPT statement, the keys used by Animator and the function keys used by your own programs.
Normally, the default keys built into Adis should not need changing. However, you may need to change the keys used to emulate a particular dialect of COBOL.
The default set of keys used by your COBOL system is built into Adis. The Keyboard Configuration utility creates a file called cobkeymp which contains the keystrokes that are to be used for function keys and the keys Adis uses during an ACCEPT operation. At run time, Adis checks for cobkeymp in the current directory. If the file is not found, then the COBOL system directories are searched for cobkeymp. If the file is found the set of keys defined in it are used. If not, the default set of keys are used.
The following lists of keys can be reviewed and altered by the Keyboard Configuration utility:
This list defines the keys which carry out specified functions when
you are executing an ACCEPT statement in a COBOL program. See the
section Standard Adis Key Functions for a
description of these keys.
This list is used by Animator and some other Micro Focus programs.
The user function key list defines the keys that are normally returned to your program when a function key is pressed.
This list defines an alternative user key list that can be used if you want to set up keys to be compatible with another dialect of COBOL. If the values returned by such keys differ from the standard user key list, you are advised to alter the compatibility function key list rather than the user function key list. By default, the compatibility function key list is configured for compatibility with RM/COBOL V2.0 on UNIX.
ACCEPT/DISPLAY option 22 in the Adis Configuration utility (see the section ACCEPT/DISPLAY Options in the chapter Configuring Enhanced ACCEPT and DISPLAY for more information) enables you to choose between using the user or compatibility key lists.
By default, the user function keys are initially disabled. In order to use these function keys during the execution of a program, you must first enable them by calling the x"AF" library routine or by altering the configuration using the Adis Configuration utility.
The CRT STATUS clause allows you to ascertain which function key was used to terminate an ACCEPT operation. Full details on the use of this clause can be found in your Language Reference4.
Values within the tables found in cobkeymp (or as the internal defaults) which begin with the prefix KEY_ represent values that have been translated using the terminfo database and the UNIX terminal handling library. These values are independent of the terminal you are currently using, and thus you can define keys which are not actually present on your particular keyboard.
You do not need to create a different cobkeymp file for each terminal type on your system. Instead, try to ensure that your cobkeymp is suitable for as many different types of terminal as possible. All terminal specific decoding is done by the run-time system using the terminfo database. However, you may have to supply alternative keystrokes for those terminals which do not have special function keys. Full details on the KEY_ values are given in your UNIX documentation.
If you decide to have multiple cobkeymp files rather than using the above procedure, you can do this by renaming cobkeymp and then setting up a dd_ environment variable at run time. For example:
causes the run-time system to look for key configuration information in
To set up your own cobkeymp file using the Keyboard Configuration utility, enter the command line:
The Keyboard Configuration utility searches for a file called cobkeymp in the current directory and then the directories specified by the COBDIR environment variable. If the file is found, you are asked if you want to edit it. Answer "Y" if you want to edit the file or "N" if you want to create a new file based on the default set of keys. If the file is not found, one is created.
The Keyboard Configuration utility is menu driven. Once it is invoked, it displays its initial menu as shown in Figure 6-1.
To select the option of your choice, press its associated number. The menu for that function is then displayed. These menus are shown in the following sections.
Figure 6-1: The Keyboard Configuration Utility Main Menu
Entering 1 from the main menu displays the Review Existing Function Key Definitions menu. This menu is shown in Figure 6-2.
Figure 6-2: The Review Existing Function Key Definitions Menu
This menu enables you to list all currently defined function keys in one of four sets: Adis, Animator, user or compatibility. To output the list of your choice, press its associated number. For example, press 2 to output the list of Animator function keys, or 4 to output the list of compatibility keys.
Option 5 is a toggle to determine whether a selected list is shown on the screen or written to a file. If you select the screen as the destination, all the currently defined function keys in that list are displayed together with their hexadecimal values. To page from one screen to the next, press any key. Once the end of the list is reached, press any key to return to the Review Existing Function Key Definitions menu.
If you select to output the list to file, the same information is written to a file called KEYLIST.DMP. This happens without further intervention unless the file KEYLIST.DMP already exists, in which case you are asked whether to overwrite it or append this list to the end. Press "O" to overwrite, "E" to extend.
Press 6 to return to the main menu.
Entering 2 from the main menu displays the Alter Function Key Definition menu in which you are prompted to choose the set of function keys you wish to alter. This menu is shown in Figure 6-3.
Figure 6-3: The Alter Function Key Definition Menu
As with the Review Existing Function Key Definitions menu, you can select the Adis, Animator, user or compatibility function key lists. When you have made your selection, a screen for that selection is displayed. As an example, Figure 6-4 shows the screen for Adis key list.
Figure 6-4: The Alter Menu for the Adis Key List
Each function in the function key list you select is displayed individually. For example, the function displayed in Figure 6-4 is Terminate accept. To enter a new function key press the key you want to perform the function, or use X to enter the hexadecimal code for the key. Once you have entered the new key, the program automatically cycles to the next function after a slight pause. The following keys are available on this menu:
|Space||Cycles from one function to the next, without altering the key defined for each function.|
|Insert||Adds another key to perform the displayed function, but retains the currently defined function key. The word Insert is displayed at the bottom right of the screen.|
|Delete||Deletes a defined function key from a list. The Keyboard Configuration utility automatically cycles to the next function.|
|HeX||Specifies that you will enter the hexadecimal sequence for the required function key. The word Hex is displayed at the bottom right of the screen. If you enter an invalid hexadecimal sequence you receive an error when you attempt to cycle to the next function and you are prompted to enter a valid sequence. This function allows you to define keys which may not actually appear on the keyboard you are using, but will be available on the one on which your program will run.|
|Quit||Returns to the Alter menu.
If you attempt to define a large number of keys you may exceed the limit, in which case you receive the warning:
There is not enough room for that sequence
Should this occur, the only way to add additional keys is to delete unwanted key sequences.
Press 5 to return to the main menu.
Your UNIX documentation contains details on the values for the KEY_ mnemonics . These are 16-bit values, but you can enter them as three 8-bit codes by typing:
FF, high-byte, low-byte
For example, KEY_DOWN has octal value 0402, or hexadecimal value 102. You can enter a code for KEY_DOWN by typing the three bytes:
FF, 01, 02
Alternatively, if you press the down arrow key on your keyboard your system enters these three bytes for you.
If you want to save any alterations you have made to any of the function lists, press 3 from the main menu. This saves the changed function lists to a file called cobkeymp.
To exit from the Keyboard Configuration utility, press 4 from the main menu.
The following example shows how to use the Keyboard Configuration utility to alter the Animator key list. It describes the steps required to insert, delete and change key definitions. The example assumes that the file cobkeymp has not been previously created and hence the values shown by the Keyboard Configuration utility are the defaults.
The screen for Animator function key 1 appears.
The screen for function key 2 now shows.
The screen for Cursor Down now appears.
In order to demonstrate the changes you have just made using the Keyboard Configuration utility, it is necessary to invoke Animator. See the chapter Starting Animator in your Debugging Handbook for instructions on invoking Animator.
After entering Animator, the Animator screen appears.
When you press:
|F1=Help||Nothing happens because the definition of Animator function key 1 was deleted.|
|<up-arrow>||Nothing happens because the definition of <up-arrow> was changed.|
|Ctrl+U||The cursor moves up one line. This is because Ctrl+U was mapped onto the function to move the cursor up one line.|
|<down-arrow>||This still moves the cursor down one line.|
|Ctrl+D||This also moves the cursor down one line because Ctrl+D
was inserted as a new definition, and the old definition (<down-arrow>)
The defaults can be recovered by either using the Keyboard Configuration utility and returning the key definitions to their old values, or by simply deleting cobkeymp.
The standard Adis key functions are described below.
This function terminates an ACCEPT operation. The first byte of any CRT STATUS field (defined as pic 9 display) is set to the character "0" (ASCII 48) and the second byte (defined as PIC 9(2) COMP-X) is set to 0.
If enabled, this function causes the Abort confirmation message to be output to the screen and a character requested from the user. If the user responds with anything other than "Y" or "y", the message is blanked and normal processing of the ACCEPT operation continues. If the user presses "Y", or "y" or no message is configured, the program is terminated as if a STOP RUN had been executed.
The cursor is moved to the first character position that occurs within a field at or after column one on the next or subsequent line of the screen. If there is no such field, no action takes place.
Moves the cursor to the previous character in the field. If the current character is the first character of the field, the cursor is moved to the last character of the preceding field. If the current character is the first character of the first field on the screen, an error is signaled to the user.
Moves the cursor to the next character in the field. If the current character is the last character of the field, the cursor is moved to the first character of the next field. If the current character is the last character of the last field on the screen, an error is signaled to the user.
The cursor is moved to the next unprotected character position; that is, a position that occurs in a field in direct line above the current position.
Moves the cursor to the next unprotected character position in direct line below the current position.
Note: For cursor up and cursor down (functions 5 and 6), cursor movement functions follow the same rules as items defined using the CURSOR IS clause if a position is found that is within a field but is protected by virtue of containing an insertion character or a suppressed numeric digit. In such situations the cursor is moved right to the first unprotected character position within that field. If all such positions are protected, the cursor is moved to the last unprotected character position within the field.
Moves the cursor to the first unprotected character position of the current screen.
Moves the cursor to the next column Tab stop position. The cursor is never moved forward further than the first available character position after the end of the current field (or line in multi-line fields).
Moves the cursor to the previous column Tab stop position. The cursor is never moved back further than the last available character position before the start of the current field (or line in multi-line fields).
Moves the cursor to unprotected character positions in the order:
Moves the cursor to the first unprotected character position of the next field on the screen. If already in the last field and auto-skip out of an ACCEPT is not enabled for this key, the cursor is positioned at the last character of the field and the request is considered to have been unsuccessful.
Moves the cursor to the first unprotected character position in the current field. If the cursor is already at the first position, it moves to the first character position of the previous field. If the cursor is already at the first character of the first field, the request is considered unsuccessful.
Retrieves the character at the current cursor position, changes its case if alphabetic and processes it as if it were just keyed. The function is not permitted in numeric or Kanji fields. Changing case on a non-alphabetic character is treated as equivalent to simply typing the character again. The function cannot be used to override the fold to upper-case mechanism which simply re-inverts the case if an attempt is made to fold a character to lower-case.
Moves the cursor to the unprotected character position logically preceding the current one, pushes the character there into the retype buffer and replaces it with one popped from the restore buffer. When in insert mode, removal is achieved by moving the remaining characters in the field along one position and popping a character from the overflow buffer to occupy the gap at the end.
In either case, if the relevant buffer is empty or the next character is not valid for the field, a space or zero (according to type of field) is used. Action is slightly different when to the left of the decimal point in numeric fields, but the logical effect is the same - that of reversing the effect of typing a character.
One unusual effect emanating from the logical requirements is that where the cursor was unable to move out of a field when a character was keyed into the last position, the cursor is not moved prior to character replacement.
Pops a character from the restore buffer and proceeds as if it had been received from the keyboard. An error is signaled if the buffer is empty or the character is illegal in the current field.
Places a space or zero character (according to the field type) under the current cursor position, making room for it by shuffling characters along the field. Except when to the left of the decimal point in numeric fields, significant characters can be pushed off the end (the character that is lost is pushed into the overflow buffer and an error is signaled to the user). When to the left of the decimal point in a numeric field, an attempted insertion is unsuccessful if a significant digit would otherwise be lost or if the cursor is on the left-most digit position (since the functionality of numeric insertion operations in these circumstances implies a requirement to insert before the current digit).
Pushes the character currently under the cursor into the restore buffer, moving the remaining characters in the field left by one position and pops a character from the overflow buffer to occupy the gap at the end. If the overflow buffer is empty, a space or zero (according to type of field) is used.
Action is slightly different when to the left of the decimal point in numeric fields, but the logical effect is normally the same - that of reversing the effect of inserting or restoring a character. If the field is numeric, the character is discarded and not pushed into the restore buffer.
The effect and restrictions of this function are identical to insert character (function 16 above) except that the character to be inserted is popped from the restore buffer. An error is signaled if the buffer is empty or if the character popped is not valid in the current field. This function is not available in numeric fields.
Characters at, and to the right of, the current cursor position in the current field are pushed into the restore buffer and replaced by spaces or zeros (according to the type of field). Operation is from left to right and includes trailing nonsignificant spaces and zeros. The cursor does not move. Multi-line alphanumeric fields are treated as being split at line boundaries for the purposes of this operation.
The entire contents of the current field (or the current line in the case of a multi-line alphanumeric field) are pushed into the restore buffer as for clear to end of field on the first character position. The field then has spaces (alphanumerics) or zeros (numerics) moved to it and the cursor is placed on its initial position as defined for the type and format of the field.
The action defined for clear to end of field is performed on the current field (or line), and the following fields have spaces or zeros moved to them, as appropriate.
All fields on the screen have spaces or zeros (as appropriate) moved to them and the cursor is moved to its home position (the first unprotected character of the first field). The restore and retype buffers are cleared by this function.
Sets the current editing mode to insert and displays or clears any relevant configured indicators. Any Off end of field indicator is cleared by this function.
Sets the current editing mode to replace, and displays or clears any relevant configured indicators. Any Off end of field indicator is cleared by this function.
The concept of insert mode and replace mode apply only in alphanumeric fields. The mode flag is therefore suppressed while in numeric fields and reinstated on moving to another alphanumeric field.
Replace mode is sometimes known as overtype mode.
Reinstates the current field (or line) to its state when the cursor last moved into it. Operations involving hidden MOVE operations out of the current field (clear screen, clear to end of screen), as well as the more obvious operations such as field-tab and auto-skip out, can result in edits that cannot be undone.
Moves the cursor to unprotected character positions in the order:
Special mapping functions are described below.
This function is provided for RM compatibility. During an ACCEPT operation, if the UPDATE clause is specified, a Cursor Home (function 7) is performed, otherwise Clear Field (function 20) is performed.
This function is provided for RM compatibility. During an ACCEPT operation, if the UPDATE clause is specified, a Cursor Left (function 3) is performed, otherwise Backspace Character (function 24) is performed.
This function is provided for RM compatibility. During an ACCEPT operation, if the UPDATE clause is specified, a Terminate Accept (function 0) is performed, otherwise there is no action.
If the current mode is insert mode, Set Replace Mode (function 24) is performed, otherwise Set Insert Mode (function 23) is performed.
If the current mode is replace mode, Set Insert Mode (function 23) is performed, otherwise Set Replace Mode (function 24) is performed.
If in a multi-field ACCEPT, Move to next field (function 11) is performed, otherwise Move to next tab stop (function 8) is performed.
If in a multi-field ACCEPT, Move to previous field (function 12) is performed, otherwise Move to previous Tab stop (function 9) is performed.
If the current field is numeric or the restore buffer is empty, Insert Single Character (function 16) is performed, otherwise Restore Character (function 18) is performed.
This value is used if no key has been set up for a particular function.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
|Configuring Enhanced ACCEPT and DISPLAY||Windowing Support for Text-based Systems|