C3270/keymap

Description
A keymap is a mapping from keys to actions. For example, pressing the F1 key on the keyboard may be mapped onto the action PF(1).

There is also a default handler for keyboard input, that handles input of text characters.

The keymap resource gives the name of the keymap to use.

Mode-specific keymaps
c3270 also supports mode-specific keymaps.

By default, a keymap applies no matter what mode c3270 is in. However, if the current keymap is named foo, and a keymap definition exists for the name foo.3270, then the mappings in foo.3270 will apply only when c3270 is in 3270 mode. Similarly, if there is a keymap definition for foo.nvt, it will apply only when c3270 is in NVT mode.

Temporary keymaps
The Keymap action allows for a temporary keymap. When Keymap is invoked with a parameter, a keymap by that name will be applied, and its definitions will override any matching definitions in the current keymap. When Keymap is invoked without a parameter, any temporary keymap will be removed.

Where c3270 finds keymap definitions
c3270 finds keymap definitions in three places, which it searches in order:
 * Compiled-in definitions
 * Resource definitions
 * Files

Compiled-in definitions
c3270 includes a compiled-in definition for the default keymap, called base.

Resource definitions
If there is no compiled-in definition for a keymap, c3270 will look for a resource definition. The resource containing the definition of the keymap named foo is keymap.foo.

Files
If there is no compiled-in definition and no resource definition, c3270 will look for the keymap named foo in the file named foo. There is no file name suffix or path convention for keymap files.

Keymaps in resources
If a keymap is defined in a resource, it must be defined as a multi-line resource. For example: c3270.keymap.foo: \ Ctrlq: PrintText\n\ Ctrlw: NextWord\n\ Ctrlx: Disconnect

Note that the first line ends with a. The "middle" lines end with the sequence, and the last line has no special ending.

Keymaps in files
When a keymap is defined in a file, none of the special line endings are needed. In a file, the above example would be: Ctrlq: PrintText\n\ Ctrlw: NextWord\n\ Ctrlx: Disconnect

Syntax
The format of a keymap entry is: modifier &lt;Key> keyname... : Action(arg,...)...\n\
 * modifier
 * An optional keyboard modifier:


 * Ctrl: the Ctrl modifier key.
 * Alt: the Alt modifier key.
 * keyname
 * A literal character such as a
 * A curses key name such as F1
 * An ISO 8859-1 symbolic name for a key, such as colon (the : key)
 * A Unicode value, e.g., U+0041 for A
 * Action
 * A c3270 action and its arguments.

Multiple-key matches
An entry can match a sequence of keys. For example: Ctrla r: Reset This entry matches the Ctrl-a key, followed by the r key.

Multiple-action entries
An entry can execute multiple actions. For example: Ctrlx: String("hello") Newline This entry maps the key Ctrl-x to two actions, String followed by Newline.

The Alt modifier
c3270 has a specific notion of the Alt key on a PC keyboard. Some terminal emulators generate a two-character sequence when Alt is pressed with a data key: they generate an ESC character (U+001B), followed by the usual value of the data key. For example, pressing Alt with a generates ESC (U+001B) followed by a (U+0061). But not all terminals behave this way.

c3270 does not know if your terminal or terminal emulator generates these two-character sequences, or does not. Your terminal might generate something altogether different, or it might not even have an Alt key on the keyboard. Regardless, if you define a keymap entry that uses the Alt modifier, c3270 will match that entry only if your terminal generates a two-character sequence as described here.

Ordering rules
Unlike other emulators in the x3270 family, there are no ordering rules for c3270 keymaps. Entries for c, Ctrlc and Altc are unrelated and can appear in any order.

If for some reason the same match appears in more than one entry, the first one will be used. This will be indicated in the output of Show(Keymap) with the unused copy(ies) replaced by the text superceded by xxx.

How to figure out what keys are being generated
To find out which key name or sequence of key names is being generated for any given key on your keyboard:
 * Start c3270 with the -trace command-line option.
 * Connect to a host.
 * Press the key(s) in question.
 * Exit c3270.

c3270 will create a trace file called. In that file, several lines of text will be generated for each key you press. For example: 20200324.223022.236 kbd_input: k=256 wch=265 20200324.223022.236 Key 'F1' (curses key 0x109, char code 0x0)

In this trace, the key generated the input event F1, which you can paste directly into your keymap definition.

How to debug your keymap
There are two c3270 options to aid with keymap debugging. The -trace command-line option causes c3270 to create a trace file,. That file traces (among other things) each keyboard event that c3270 processes. The information traced includes the keymap (and line within the keymap) that matched the event, and the c3270 actions that were run in response.

The Show(Keymap) action at the c3270 prompt displays the current keymap. This tells you exactly which keymap entries are active. Often times it will point out that c3270 isn't using the keymap you thought it was, or that some of your keymap entries are interfering with one another.

Note that a common problems in configuring c3270 is figuring out where resources are being defined. c3270 resources can be defined in a number of different places:
 * In the definitions compiled into c3270.
 * In the file  in your home directory.
 * In session file.
 * From -xrm command-line options.

The trouble with Alt
You may reach a point where you simply cannot find a terminfo entry (terminal name) that works correctly for your terminal or emulator. For example, you may find that a particular function key or keypad key generates garbage input instead of being translated into a clean abstract symbol like F1. In that case, you may need to create a keymap to explicitly match the escape sequence coming from the terminal, using a multi-key match.

The procedure outlined above will work for this, but with one caveat: the Alt modifier. c3270 thinks that the input sequence of Esc (U+001B) followed by some character means that Alt was pressed with that character. So for example, if when you press F1, your terminal generates this sequence: Esc [ 1 1 ~ that is: U+001B U+005B U+0031 U+0031 U+007E c3270 will interpret this five-character sequence as a four-key sequence, combining the Esc and [ into Alt-[.

A keymap entry that will match this sequence is: Alt[ 1 <Key>1 <Key>~: PF(1) Do not try this sort of entry. It will not work. <Key>Esc <Key>[ <Key>1 <Key>1 <Key>~: PF(1)  Wrong!