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

You Might Just Need the Alt Keymap

If your keyboard does not have a Meta key, it probably has an Alt key. For such keyboards, there is an alternate version of the default keymap, called alt; it defines the same actions using the Alt key instead.  You can also specify the alt keymap at start-up with the command:
x3270 -keymap alt
You can also select the alt keymap at runtime with the Options->Change Keymap... menu option; type alt in the pop-up window.

Defining a Simple Keymap in .x3270pro

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 .x3270pro in your home directory.  In that file, put the following:
! Use the 'mine' keymap, defined below
x3270.keymap: mine
! Definition of the 'mine' keymap
x3270.keymap.mine: #override \
    <Key>Prior: PF(7)\n\
    <Key>Next: PF(8)
The first entry (x3270.keymap) tells x3270 to use the keymap named mine.  The second entry (x3270.keymap.mine) is the definition of the mine keymap itself.

Now, run x3270, and do not specify a -keymap option.  The Page Up key will now emulate the 3270 PF7 key, and the Page Down key will emulate the 3270 PF8 key.  (If you do not have a Page Up or Page Down key, or if these keys do not generate the X11 Prior and Next keysyms, 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. The full set of rules for keymaps (which are actually X11 Translation Tables) takes a couple of chapters in a book -- I would suggest two O'Reilly's books (Volume 4M: X Toolkit Intrinsics Programming Manual, and Volume 5: X Toolkit Intrinsics Reference Manual) -- but here are the basics:

How to Find the Keysyms

To find out which keysym is being generated for any given key on your keyboard, start x3270, but do not connect to a host.  Then select the File->Trace Keyboard and Mouse Events menu option, and press the No File button on the pop-up.

An xterm window will appear.  In that window, several lines of text will appear 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 x3270 manual page.

How to Debug Your Keymap

There are two x3270 options to aid with keymap debugging.  The File->Trace Keyboard and Mouse Events menu option pops up an xterm window which traces each keyboard and mouse event that x3270 processes.  The information traced includes the keymap (and line within the keymap) that matched the event, the x3270 action that was run in response, and if for some reason the action did not work, why it did not work.

The Options->Display Current Keymap menu option pops up a window which displays the current keymap. This pop-up tells you exactly which keymap entries are active, and can be sorted by keymap name, event, or action name.  Often times it will point out that x3270 isn't using the keymap you thought it was, or that some of your keymap entries are interfering with one another (such as the more-specific rule described above).

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

Note that of the above list, .x3270pro is guaranteed to be consulted last, and its definitions override anything that appears in any of the other places.  This is why the example in this document uses .x3270pro.