There is also a default handler for keyboard input, that handles input of text characters.
The keymap resource or the -keymap command-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.
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.
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:
c3270 includes a compiled-in definition for the default keymap, called base.
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.
Resources are defined in three places:
- In the file .c3270pro in the user's home directory.
- In a c3270 session file.
- Through a command-line option (-set or -xrm).
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.
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:
c3270.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()
The format of a keymap entry is:
[modifier...]<Key>keyname: Action([arg[,...]])... [modifier...]<Key>keyname [modifier...]<Key>keyname: Action([arg[,...]])...
- Zero or more keyboard modifiers:
- Ctrl: the Ctrl modifier key.
- Alt: the Alt modifier key.
- 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
- A c3270 action and its arguments.
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.
An entry can execute multiple actions. For example:
Ctrl<Key>x: String("hello") 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.
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.
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 '<Key>F1' (curses key 0x109, char code 0x0)
In this trace, the key generated the input event <Key>F1, which you can paste directly into your keymap definition.
Unlike a PC or Mac, a "dumb" terminal keyboard does not generate any sort of input event when a modifier key (such as Shift, Ctrl or Alt) is pressed. So c3270 cannot see when these keys are pressed by themselves and released, which makes it impossible to do commonly-desired mappings such as using Right-Ctrl for Enter(). Also, a "dumb" terminal tends to generate the same input character (U+0009) when the Tab key is pressed, regardless of what other modifier keys are pressed. This makes an obvious mapping for BackTab() (Shift-Tab) impossible. Similarly, these devices (or device emulators) often generate the same input character for the keypad as for the main keyboard, such as U+000D for both Enter keys, so it is impossible to define different actions for each.
There are two c3270 options to aid with keymap debugging.
The -trace command-line option causes c3270 to create a
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.
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 ~
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<Key>[ <Key>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!