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. (Note that in the default keymap, Page Up scrolls the display up, and Page Down scrolls it down; this keymap will override that.)

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 AppData directory (that directory is where the Session Wizard saves session files; it is usually something like C:\Users\yourname\AppData\Roaming\wc3270, but the name varies with different versions of Windows and different languages. The Start Menu command wc3270 Explore AppData will open Explorer windows on the two AppData directories -- yours and the all-users one.)

In that file, put the following, using a text editing program like Notepad:

!description: Map PageUp and PageDown to PF7/PF8
<Key>PRIOR: PF(7)
<Key>NEXT: PF(8)

Note that in a keymap file, comment lines start with !. Comment lines are ignored, except for one special one (shown above): a comment line starting with !description: will be displayed by the Session Wizard as the description of the keymap.

To use the keymap, you can either create a new wc3270 session, or you can modify an existing one. In either case, run the Session Wizard. The list of available keymaps should now include mine.

Tell the Session Wizard to change the keymap and rewrite the session file.

Now, run your wc3270 session again. The Page Up key should now emulate the 3270 PF7 key, and the Page Down key should now emulate the 3270 PF8 key.

Full Keymap File Name Conventions

Keymap files can come in three flavors:

The file foo.wc3270km contains keymap definitions that apply to all wc3270 modes.
The file foo.nvt.wc3270km contains keymap definitions that apply only to NVT (non-3270) mode.
The file foo.3270.wc3270km contains keymap definitions that apply only to 3270 mode.

Any or all of the three files can be present. The one, two or three files are taken together to represent a single keymap named foo.

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

Ctrl

Alt

keyname

semicolon

HOME

Home

action

wc3270

Enter

PF

args

Note that order matters in the keymap. Three important rules apply:

User-specified keymaps appear after the default keymap.
More-specific entries must come before less-specific ones.
If there is more than one entry mapping exactly the same key (with the modifiers), the last one wins.

An example of the second rule is if you want to map both BACK (the Backspace key) and Shift-BACK. The entry for Shift-BACK must come before the entry for BACK, otherwise the entry for Shift-BACK will be ignored.

The first rule, combined with the second, means that a default key mapping may interfere with your keymap. For example, if you want to define a mapping for Ctrl-Shift-F1, the default mapping for Shift-F1 (PF13) will override it. The way around this is to use the third rule: define your own mapping for Shift-F1. Your entry will disable the one in the default keymap. But (because of the second rule) be sure to put it after your entry for Ctrl-Shift-F1.

Also note that except for entries that use the Ctrl modifier, mappings are case-sensitive. For example, an entry for Alt-p will not be matched if the Shift key is down or Caps Lock is in effect. To match both Alt-p and Alt-P, there must be two entries in your keymap.

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 can be entered literally, e.g., a for the A key. They can also be entered using ISO 8859-1 standard names, such as colon for the : key (which would otherwise confuse the keymap syntax). Finally, Unicode values (U+nnnn) can be used.

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. wc3270 will create a pop-up window showing a trace file, which will include several lines of text for each key that is pressed. Each entry will include the text for the left-hand side of a keymap entry that will match that key. You can copy and paste the text into a keymap definition. The trace file is x3trc.pid in the current directory.

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 first is the -trace option described above. 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 second is the show keymap command at the wc3270> prompt, which 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.

Keymaps as Resources

It is also possible to put your keymap directly in your wc3270 session file, using resource definitions. This leaves fewer files to carry around if you want to move your session from one workstation to another.

Keymap resource definitions go at the very end of a wc3270 session file. The above example would look like this:

    ! Note that in this file, backslash ('\') characters are used to specify
    ! escape sequences, such as '\r' for a Carriage Return character or '\t'
    ! for a Tab character.  To include literal backslashes in this file, such as
    ! in Windows pathnames or UNC paths, they must be doubled, for example:
    !
    !   Desired text            Must be specified this way
    !    C:\xdir\file            C:\\xdir\\file
    !    \\server\printer        \\\\server\\printer
    !
    !*Additional resource definitions can go after this line.
    ! Define my meymap.
    wc3270.keymap.mine: \n\
      <Key>PRIOR: PF(7) \n\
      <Key>Next: PF(8) \n
    ! Select my keymap.
    wc3270.keymap: mine

Note that wc3270 resource definitions use backslash quoting conventions, so a backslash ('\') inside a keymap must be quoted with another backslash. Also, keymaps are multi-line resource definitions, so each line except the last must end with a newline ('\n') and a backslash ('\'), as shown above.

Note that similar naming conventions are used to define the mode-specific keymap resources are are used to name the files: the wc3270.keymap.foo resource would define the mappings that are used in all modes; the wc3270.keymap.mine.nvt resource would define the mappings that apply only to NVT mode, and the wc3270.keymap.mine.3270 resource would define the mappings that apply only to 3270 mode. The one, two or three keymap resources above are taken together to define a single keymap, mine.

More Information

This document is not an exhaustive definition of keymaps -- the complete reference is the wc3270 manual page. It describes the many possible, subtle variations of the rules described above.