Wc3270/keymap

Note
This page is still under construction.

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 or the -keymap commad-line option specify the name of the keymap to use. Multiple names can also be specified, separated by commas. If there are any conflicts in the entries, the entries from keymaps later in the list replace those from earlier in the list.

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

By default, a keymap applies no matter what mode wc3270 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 wc3270 is in 3270 mode. Similarly, if there is a keymap definition for foo.nvt, it will apply only when wc3270 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 wc3270 finds keymap definitions
wc3270 finds keymap definitions in three places, which it searches in order:

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

Resource definitions
If there is no compiled-in definition for a keymap, wc3270 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, wc3270 will look for the keymap named foo in the file named foo.wc3270km. It will look for this file first in the current user's Documents\wc3270 folder, then in the common Documents\wc3270 folder, and then in the current directory.

Keymaps in resources
If a keymap is defined in a resource, it must be defined as a multi-line resource. For example: wc3270.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 Ctrlw: NextWord Ctrlx: Disconnect

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


 * Ctrl: either of the Ctrl modifier keys.
 * LeftCtrl: the left Ctrl modifier key.
 * RightCtrl: the right Ctrl modifier key.
 * Alt: either of the Alt modifier keys.
 * LeftAlt: the left Alt modifier key.
 * RightAlt: the right Alt modifier key.
 * Shift: the Shift key.
 * Extended: the Windows extended qualifier (explained below).
 * 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 code point, e.g., U+0041 for A
 * Action
 * A wc3270 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.

Ordering rules
Unlike other emulators in the x3270 family, there are no ordering rules for wc3270 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 wc3270 with the -trace command-line option.
 * Connect to a host.
 * Press the key(s) in question.
 * Exit wc3270.

wc3270 will create a trace file called  on your desktop. 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.

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

The Show(Keymap) action at the wc3270&gt; prompt displays the current keymap. This tells you exactly which keymap entries are active. Often times it will point out that wc3270 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 problem in configuring wc3270 is figuring out where resources are defined. The rules for specifying resource values are listed under wc3270 resources.