Configuration Guide

A Panther application must allow users to enter ASCII data characters and to indicate certain logical key values to Panther—EXIT, XMIT, PF1, SPF1, and so on. Because physical keyboards vary from system to system, Panther uses a key translation file to translate sequences that users enter on their physical keyboards into logical keys that Panther understands.

The Panther distribution provides key translation files (in the config directory), that support more than 100 terminal types. One of the distributed key files should work for you. However, you might want to create, modify, or examine the key translation file if you:

• Have a unique keyboard that does not have extended keys corresponding to the Panther logical keys (also referred to as Panther logical keys).

• Want to change or define key assignments for specific logical keys.

• Want to assign or change key labels for logical keys.

This chapter describes:

• What a key translation file does

• How to read the entries in the key translation file

• How to view key sequences produced by your keyboard with the showkey utility

• How to convert key translation files to binary format with the key2bin utility

• Using alternate key translation files in portable applications

The Role of the Key Translation File

During initialization, Panther reads the key translation file specified by SMKEY (in the smvars file) into memory. The value for SMKEY is determined by the terminal type indicated in your SMTERM or system TERM variable. Refer to Chapter 2, "Application Variables," for more information about setting the SMKEY variable. Now Panther can recognize how your physical keys map to the logical keys.

Panther logical keys are defined as hexadecimal values in the include file smkeys.h. This file is terminal-independent, while key translation files are terminal-dependent. ibmkeys, vt220keys, wy75keys are a few of the available key translation files.

For the most part, ASCII data key, logical values between 1 and hex FF, require no translation and are not included in the key translation file. However, some keyboards do not have the same number of function keys, and most do not have logical keys named HELP or XMIT (Transmit). Therefore, the key translation file specifies a physical key which transmits a unique code or sequence of codes which, in turn, works as a HELP key. Another key works as the XMIT key, and so on. Logical values between hex 100 and hex 1FF are cursor control and editing keys; values greater than hex 1FF are function keys.

So, when you press a key, the keyboard generates either a single ASCII data character, or a sequence of characters beginning with an ASCII control code. Panther converts these characters into logical keys, numbered between 1 and 65535 inclusively, before processing them—hence determining if a data character or control character was received.

If the key input is a control character, Panther searches the key translation file for a sequence beginning with that character. If there is a match, additional characters are read until the entire sequence is found, and returns the logical value. So, Panther is able to interpret XMIT when you press a Do key, or an End key, or whatever physical key is mapped to XMIT in your key translation file.

If a match is found on the initial character, but not the whole sequence, the entire sequence is discarded. If there is no match at all with the entered control character, it is returned unchanged; this is useful for machines such as IBM PCs that use control codes for displayable characters. (For more information about key translation, refer to "Processing Keyboard Input" in Upgrade Guide.)

With a one-to-one mapping there are not enough keys on a commercially available keyboard to represent the entire Panther logical keyboard—and for your application, you may not need to use or map all the logical keys. However, to accommodate its larger logical keyboard, Panther combines two or more physical keys to represent a logical key. For example, on a PC the logical key ZOOM is often mapped to Alt-Z.

Learn Your Key Mapping

You can print out the ASCII key translation file that supports your keyboard. Key translation file names begin with a mnemonic for the type of terminal you are using, and end with keys. For example, vt100keys is the key translation file for a VT100 terminal. All key translation files distributed with Panther adhere to this convention.

If you use Panther on different terminals with varying operating systems and keyboards, then each terminal must have its own key translation file. If necessary, you can create more than one key translation file for a terminal. In this way you can tailor the key mapping for a particular application.

Refer to "Processing Keyboard Input" in Upgrade Guide for a discussion of key processing in Panther applications.

Viewing Key Sequences

As an aid to editing key files, the showkey utility is provided. The showkey utility prints out the key sequence of keys that you enter. To run this utility, type showkey at a system prompt. (This is a Panther executable, and as such, the variables SMVARS and SMBASE must be appropriately defined to run this utility.) The Showkey Utility window appears:

In order to assure that you are not mistyping your keystrokes, showkey expects you to enter your keystrokes twice. If you do not press the same key sequence twice, it will not display the generated characters. Type x twice in a monospace font to exit the showkey utility.

If you want to bind the keystroke(s) to a Panther logical key, copy the decoded keystroke text to your key translation file. For example if you wanted to assign Shift-F10 on your keyboard to the logical key which starts the debugger, you would:

1. Start the showkey utility.
2. Enter Shift-F10 twice.

The showkey window displays the character sequence that the keystroke transmits. On one platform, the sequence for Shift-F10 was ESC [ 4 5 ~

3. Bind the key label and character sequence to the debugger hot key:

   DBUG(Shift-F10)= Esc [ 4 5 ~

4. Run the key2bin utility on your altered key file.
5. Type xx to exit the utility.

---

Key Translation File Syntax

Each entry in a key translation file has the format:

logical-key(key-label) = character-sequence

Lines beginning with a pound sign # are treated as comments. They are ignored by the key2bin utility.

logical-key

The mnemonic or the hexadecimal value of a Panther logical key. For example, the logical TRANSMIT key is represented by the mnemonic XMIT or by the hex value 0x104. The mnemonics and hex values for all logical keys are defined in smkeys.h. Refer to Table 6-1 for a list of these mnemonics and values.

You can assign the same logical-key to two (or more) different character-sequences. For example, in a key translation file for the PC, you can make these entries:

HELP(Ctrl-F1) = NUL ^
HELP(Ctrl-Home) = NUL w

When these entries are used with a PC, both Ctrl-F1 and Ctrl-Home will execute HELP.

key-label

The letter, numeral, character, or character string engraved on a physical keytop. One or more physical key labels may be included inside the parentheses, for example (Alt-F1). key-label is optional. It can be accessed at runtime through various library functions and the %K escape in status line messages. (Refer to sm_d_msg_line.) Key labels are often helpful in user messages and prompts. If key-label is not specified, the logical key value is used in screen displays.

character-sequence

The sequence of characters, up to six characters not including blanks, produced by a keystroke. Panther translates character-sequence to be the logical key on the left of the equal sign.

When a physical key is pressed, it transmits a character code which is unique from the code produced by any other key on the keyboard. Each complete character sequence has only one logical value. Although a sequence may include another as a substring.

In character-mode, if you use key sequences that are lead-ins of other sequences, you must assign a timing interval with the video file entry keyword KBD_DELAY. For example, if you have defined one logical value to ESC, another to ESC [ F and have set KBD_DELAY to 5, Panther will wait a half of a second after ESC is pressed to resolve the ambiguity. If during that interval [ F is not received (or any other identifiable sequence that is prefixed with ESC) Panther passes on the logical value of ESC. For more information on keyboard delay, refer to "KBD_DELAY."

The following example is an excerpt from a key translation file:

EXIT (F1) = SOH @ CR
XMIT (Enter) = SOH O CR
TAB = HT
BACK = NUL SI
BKSP = BS

Table 6-1is derived from the include file smkeys.h which defines the Panther logical keyboard. Some entries are required by the editor and are indicated with double asterisks (**).

Note: The documentation on error messages and error acknowledgment often refers to an error acknowledgment key whose default is the space bar. Because the space bar is a data entry key, it cannot be used as a logical key. Instead, the key is defined as the application behavior variable ER_ACK_KEY. You can change the entry in the SMVARS file, in a setup file, in the system environment, or at runtime with the library function sm_option.

Table 6-2 includes the mnemonics and hexadecimal values for function keys (PF), shifted function keys (SPF), and ALT keys. Table 6-3 includes the mnemonics and hexadecimal values for application function keys (APP).

ASCII Character Mnemonics and Hex Values

Table 6-4 lists two- and three-letter ASCII mnemonics for control and extended control characters. It is derived from the include file smascii.h.

Creating and Modifying a Key Translation File

To create or modify a key translation file:

1. Access the desired ASCII key translation file (or create a new one) using a text editor.
2. Edit the ASCII key translation file as required.
3. Use key2bin to convert the ASCII file to binary format.
4. If this is a new key translation file, include the path name of the binary file as the value of the SMKEY configuration variable. (The default value for SMKEY is set in the file pointed to by SMVARS. Refer to Chapter 2, "Application Variables," for information on changing configuration variables in setup files.)

You can change the mappings of logical keys for the preferences of users or developers by:

• Changing the key translation file (which affects the entire application).

• Calling sm_keyoption to change the behavior at runtime. For more information, refer to "Key Change Function" in Application Development Guide.

Example: Changing the Key Translation File

In the distributed key translation files for the PC, XMIT is mapped to the physical End key, and NL is mapped to the Enter key. The key translation file entries look like this:

XMIT(End) = NUL O

NUL O is the character-sequence transmitted by the PC's End key; when

Panther receives this sequence, it carries out its XMIT function. Similarly, CR is transmitted by the PC's Enter key and Panther responds appropriately.

To use the Enter key for XMIT and the End key for NL, you can change the key translation file entries to read:

XMIT(Enter) = CR

---

Using Alternate Key Translation Files

Many applications support more than one type of keyboard. With Panther you can provide this support without recompiling the application for each keyboard. Each terminal must have a working key translation file and video file (for character-mode only). List the path names for the key translation and video files in your application's SMVARS file. Assuming the SMTERM variable is set correctly, Panther selects the correct key translation file from the SMVARS file during initialization.

For example, the following excerpt is from the SMVARS file:

SMKEY = (hp|hp2392) $SMBASE/config/hpkeys.bin