Wc3270/keymap

Overview

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 in effect 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.

Resources are defined in two places:

In a wc3270 session file.
Through a command-line option (-set or -xrm).

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.

Rules for keymap definitions

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: \
 Ctrl<Key>q: PrintText()\n\
 Ctrl<Key>w: NextWord()\n\
 Ctrl<Key>x: Disconnect()

Note that the first line ends with a \. The "middle" lines end with the sequence \n\, 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:

Ctrl<Key>q: PrintText()
Ctrl<Key>w: NextWord()
Ctrl<Key>x: Disconnect()

Syntax

The format of a keymap entry is:

[modifier...]<Key>keyname: Action([arg[,...]]) ...
[modifier...]<Key>keyname [modifier...]<Key>keyname: Action([arg[,...]]) ...

modifier: Zero or more keyboard modifiers:

Modifier	Meaning
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
Enhanced	The Windows enhanced modifier (explained below)

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:

Ctrl<Key>x: String("foo")
Ctrl<Key>X: 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:

Alt<Key>x: String("bar")

Multiple-key matches

An entry can match a sequence of keys. For example:

Ctrl<Key>a <Key>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:

Ctrl<Key>x: String("hello") Newline()

This entry maps the key Ctrl-x to two actions, String() followed by Newline().

Ordering rules

As with x3270, more-specific entries must appear before less-specific entries in wc3270 keymaps. For example, an entry for Alt<Key>c must appear before an entry for <Key>c.

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 Enhanced modifier

Syntactically, the Enhanced 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 Enhanced modifier. To define separate actions for the two Enter keys, you could define a keymap like this:

Enhanced<Key>RETURN: Enter()
<Key>RETURN: Newline()

Note that Enhanced is not a synonym for "keypad". For example, the VKEY for the 1 key on the keypad is NUMPAD1. So trying to match on Enhanced<Key>1 will not work.

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 /tmp/x3trc.pid.txt 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, /tmp/x3trc.pid.txt 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> 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.