Creating a Custom c3270 Keymap

# How to Create a Custom c3270 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 c3270 manual page, defines common actions using the Control key. For example, the Reset action, which unlocks the keyboard, is defined as Control-R.

## Defining a Simple Keymap in `.c3270pro`

If the action you want isn't defined in the default keymap or the `alt` keymap, then you need to create a custom keymap. The easiest way to do this is as follows. Using your favorite editor, create a file called `.c3270pro` in your home directory. In that file, put the following:

>     ! Use the 'mine' keymap, defined below
>     c3270.keymap: mine
>     ! Definition of the 'mine' keymap
>     c3270.keymap.mine: \
>         <Key>PPAGE: PF(7)\n\
>         <Key>NPAGE: PF(8)

The first entry (`c3270.keymap`) tells c3270 to use the keymap named `mine`. The second entry (`c3270.keymap.mine`) is the definition of the `mine` keymap itself.

Now, run c3270, and do not specify a -keymap option. The PPAGE key (usually labelled Page Up) will now emulate the 3270 PF7 key, and the NPAGE key (usually labelled Page Down) will emulate the 3270 PF8 key. (If you do not have a Page Up or Page Down key, or if these keys are not properly defined in your terminfo or termcap database, this will not work, but for most PC-based systems, it will.)

## Rules for Keymap Definitions

You may now edit the keymap to create your own custom definition. Here is the full set of rules.

- The first line is always:

    c3270.keymap.name: \

where name is replaced by the name of the keymap you want to define. (Note the backslash, which must be the last character on the line).
- The body (middle) lines always have the format:

    modifier <Key> keyname... : Action(args)\n\

where:

modifier is an optional keyboard modifier such as `Ctrl` or `Alt`
keyname is a curses key name: a symbolic name for a key, such as `semicolon` (the ';' key) or `BACKSPACE` (the Backspace key)
Action is a c3270 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 each body line must end with the three characters '`\n\`'.
- The last line is the same as the body lines, but must not have the '`\n\`' at the end:

    modifier <Key> keyname : Action(args)

## 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 keys, such as NPAGE, PPAGE and BACKSPACE, is in the file `/usr/include/ncurses.h` or `/usr/include/curses.h` on your workstation. Look for macros starting with the prefix `KEY_`.

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 option, and do not connect to a host. Then press the key(s) in question. Then exit c3270. c3270 will create the file `/tmp/x3trc.pid`. 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 c3270 manual page.

## How to Debug Your Keymap

There are two c3270 options to aid with keymap debugging. The -trace command-line option causes c3270 to create a trace file, `/tmp/x3trc.pid`. That file traces each keyboard and mouse event that c3270 processes. The information traced includes the keymap (and line within the keymap) that matched the event, the c3270 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 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.

Note that one of the commonest problems in configuring c3270 is figuring out where resources are being defined. Keymaps are defined using resources, so this problem can complicate keymap definitions. c3270 resources can be defined in a number of different places:

- In the definitions compiled into c3270 from the files `fallbacks.txt` and `c3270.c`.
- In the file `.c3270pro` in your home directory
- From -xrm command-line options.