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[,...]]) ... [modifier...]&lt;Key>keyname [modifier...]&lt;Key>keyname: Action([arg[,...]]) ...
 * modifier
 * Zero or more keyboard modifiers:


 * keyname
 * A literal character such as a
 * A Windows VKEY name (without the VK_ prefix) such as NUMPAD5 (the 5 key on the numeric keypad) or NEXT (the Page Down key) -- note that not all VKEYs are supported by wc3270
 * 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.

Case sensitivity
An entry that uses the Ctrl modifier is not case sensitive. For example, the following two keymap entries are the same: Ctrlx: String("foo") CtrlX: String("foo")

All other entries (those without any modifiers, and those using modifiers other than Ctrl) are case-sensitive. So the following entry would match x pressed with the Alt key, but not X pressed with the Alt key: Altx: String("bar")

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.

Left and Right modifier keys
An entry that matches on a Left or Right modifier (LeftAlt, LeftCtrl, RightAlt, RightCtrl) takes precedence over an entry with an unqualified modifier (Alt, Ctrl).

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 in x3270, 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 entry(ies) replaced by the text superceded by xxx.

The Extended modifier
Syntactically, the Extended modifier looks like a modifier key, but it is actually an extra attribute that Windows includes with certain keys. For example, the Enter key on the main keyboard is reported as the VKEY RETURN, but the Enter key on the numeric keypad is reported as the VKEY RETURN with the Extended modifier. To define separate actions for the two Enter keys, you could define a keymap like this: RETURN: Newline Extended<Key>RETURN: Enter

The RightCtrl Key
A common keymap question is how to create an entry that matches the right-side Ctrl key itself, as opposed to using RightCtrl as a modifier. Here is the trick: RightCtrl<Key>CTRL: Enter

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: 20200926.232517.915 KeyDown vkey 0x70 (F1) scan 0x3b char U+0000 state 0x0 (none) 20200926.232517.915 [xk 0x700000] <Key>F1 ->lookup_key(0x00700000, 0x0) 20200926.232517.915 CB(default)[#3] started 20200926.232517.915 CB(default)[#3.1] IDLE -> RUNNING (child task to be pushed next) 20200926.232517.915 Macro[#3.2] IDLE -> RUNNING (fresh push) 20200926.232517.915 lazya_flush: 11 slots 20200926.232517.915 Macro[#3.2] RUNNING -> IDLE (about to resume) 20200926.232517.915 Macro[#3.2] running 20200926.232517.915 Macro[#3.2] IDLE -> RUNNING (executing) 20200926.232517.915 Macro[#3.2] 'PF(1)' 20200926.232517.915 default -> PF("1")

In this trace, the key generated the input event <Key>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.