# 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:

>     !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 New 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.

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.

Note that order matters in the keymap. More-specific rules must come before less-specific ones. For example, if you want to map both F1 and Shift-F1, the rule for Shift-F1 must come before the rule for F1. Otherwise, one or more of your rules will be ignored.

Except for ones that use the Ctrl modifier, entries 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 -set eventTrace 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 -set eventTrace 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.

## 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.