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 alreadydefined in the default keymap. The default keymap, documented on the x3270manual page, defines common actions using the Meta key. Forexample, the Reset action, which unlocks the keyboard, is definedas Meta-R.You Might Just Need the Alt Keymap
If your keyboard does not have a Meta key, it probably has an Altkey. For such keyboards, there is an alternate version of the default keymap,called alt; it defines the same actions using the Alt keyinstead. You can also specify the alt keymap at start-upwith the command:x3270 -keymap alt
You can also select the alt keymap at runtime with the Options->ChangeKeymap... 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 altkeymap, then you need to create a custom keymap. The easiest wayto do this is as follows. Using your favorite editor, create a file called.x3270proin your home directory. In that file, put the following:! Use the 'mine' keymap, defined belowx3270.keymap: mine! Definition of the 'mine' keymapx3270.keymap.mine: #override \ <Key>Prior: PF(7)\n\ <Key>Next: PF(8)
The first entry (x3270.keymap) tells x3270 to use the keymapnamed 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 thePageDown key will emulate the 3270 PF8 key. (If you do nothave a Page Up or Page Down key, or if these keys do notgenerate the X11 Prior and Next keysyms, this will notwork, 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 fullset of rules for keymaps (which are actually X11 Translation Tables)takes a couple of chapters in a book -- I would suggest two O'Reilly'sbooks (Volume 4M: X ToolkitIntrinsics Programming Manual, and Volume5: X Toolkit Intrinsics Reference Manual) -- but here are the basics:- The first line is always:
x3270.keymap.name: #override \
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> keysym : Action(args)\n\
where:modifier is an optional keyboard modifier such as Shiftor Ctrl
keysym is an X11 keysym: a symbolic name for a key, such assemicolon(the ';' key) or BackSpace (the Backspace key)
Action is an x3270 action such as Enter or PF
args are the optional action arguments, such as a number tospecify 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> keysym : Action(args)
More-specific definitions must come before less-specific definitions. For example, the definition for Shift<Key>Backspace must comebefore the definition for <Key>BackSpace (which also 'matches'the BackSpace key with the Shift key pressed).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 theFile->TraceKeyboard and Mouse Events menu option, and press theNo Filebutton on the pop-up.An xterm window will appear. In that window, several linesof text will appear for each key you press. Each entry will beginwith the text for the left-hand side of a keymap entry that will matchthe key you pressed. You can cut and paste the text into your keymapdefinition.
How to Find the Actions
These are documented on the x3270manual 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 anxtermwindow 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 windowwhich displays the current keymap. This pop-up tells you exactly whichkeymap entries are active, and can be sorted by keymap name, event, oraction name. Often times it will point out that x3270 isn'tusing the keymap you thought it was, or that some of your keymap entriesare interfering with one another (such as the more-specific rule describedabove).
Note that one of the commonest problems in configuring x3270is figuring out where resources are being defined. Keymaps are definedusing resources, so this problem can complicate keymap definitions. X11 resources can be defined in a number of different places:
- In your X server, by reading them in with the xrdb command
- In the file .Xdefaults in your home directory
- In the file .Xdefaults-hostname in your home directory
- In the file /usr/X11R6/lib/X11/app-defaults/X3270 (this is disabledby default, but x3270 can be built to consult this file)
- In the definitions compiled into x3270 from the file X3270.xad
- In the file .x3270pro in your home directory
Note that of the above list, .x3270pro is guaranteed to be consultedlast, and its definitions override anything that appears in any of theother places. This is why the example in this document uses .x3270pro.