How to Create a Custom wc3270 Keymap
It Might Already be Defined
First, you might want to make sure that the action you want isn't already
defined in the default keymap. The default keymap, documented on the
wc3270
manual page, defines many common actions.
For example, the Reset action, which unlocks the keyboard, is defined
as Alt-r.
Defining a Keymap in a File
If the mappings you want aren't defined in the default keymap,
you can create a custom keymap.
The easiest way to do this is to follow this example -- a custom keymap that
maps Page Up to PF7 and Page Down to PF8.
First, pick a unique name for your keymap, e.g., mine.
Using a text editor such as notepad, create a file called
mine.wc3270km in the wc3270 installation directory.
(The wc3270 installation directory is usually C:\Program Files\wc3270, but can vary depending on your Windows installation and the options
you chose when you installed wc3270.)
In that file, put the following:
! Definition of the 'mine' keymap
<Key>PRIOR: PF(7)
<Key>NEXT: PF(8)
To use the keymap, you can either create a new wc3270
session, or you can modify an existing one.
To create a new one, run the wc3270 New Session Wizard.
The list of available keymaps should now include mine.
To modify an existing session, use notepad to edit the session
file.
(Session files are located in the wc3270 installation directory, and
have the suffix .wc3270, so the session file for foo is called
foo.wc3270.)
If the session already uses a keymap, it will have a line that starts with
wc3270.keymap:.
If it has this line, modify it to specify mine instead.
If it does not have this line, add it:
wc3270.keymap: mine
Now, run your wc3270 session.
The Page Up key should now emulate the 3270 PF7 key, and the
Page Down key should now emulate the 3270 PF8 key.
Rules for Keymap Definition Files
You may now edit the keymap to create your own custom definition.
Here is the full set of rules.
Each line has the format:
[modifier...] <Key> keyname... : action[(args)]...
where:
modifier is a keyboard modifier such as
Ctrl or Alt
keyname is a key name: a symbolic name for a key,
such as semicolon (the ';' key) or a Windows
key name such as HOME (the Home key)
action is a wc3270 action such as Enter
or PF
args are the optional action arguments, such as a number
to specify which PF key to transmit.
How to Find the Modifiers
The list of modifiers is on the
wc3270 manual page.
How to Find the Key Names
The names for alphanumeric keys are their ISO 8859-1 standard names, e.g.,
a for the a key, or semicolon for the ;
key.
The list of names for special Windows keys, such as PRIOR, NEXT and HOME,
is on the wc3270 manual page.
To find out which key or sequence of keys is being generated for any
given key on your keyboard, start wc3270 with the -trace option,
and do not connect to a host.
Then press the key(s) in question.
Then exit wc3270.
wc3270 will create the file x3trc.pid in the
current directory.
In that file, several lines of text will be generated for each key you press.
Each entry will begin with the text for the left-hand side of a keymap entry
that will match the key you pressed.
You can cut and paste the text into your keymap definition.
How to Find the Actions
These are documented on the wc3270
manual page.
How to Debug Your Keymap
There are two wc3270 options to aid with keymap debugging.
The -trace command-line option causes wc3270 to create a
trace file, x3trc.pid in the current directory.
That file traces each keyboard and mouse event that wc3270 processes.
The information traced includes the keymap (and line within the keymap)
that matched the event, the wc3270 action that was run in response,
and if for some reason the action did not work, why it did not work.
The show keymap command 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.
More Information
This document is not an exhaustive definition of keymaps -- the complete
reference is the wc3270 manual page.
It describes the many subtle variations of the rules described above that
are available.