Copyright (c) 1986, 1993
The Regents of the University of California. All rights reserved.

%sccs.include.redist.man%

@(#)map3270.5 8.3 (Berkeley) 04/19/94

C 6 map3270 - database for mapping ascii keystrokes into IBM 3270 keys map3270 When emulating IBM-style 3270 terminals under \s-1UNIX\s0 (see tn3270(1)), a mapping must be performed between sequences of keys hit on a user's (ascii) keyboard, and the keys that are available on a 3270. For example, a 3270 has a key labeled EEOF which erases the contents of the current field from the location of the cursor to the end. In order to accomplish this function, the terminal user and a program emulating a 3270 must agree on what keys will be typed to invoke the EEOF function.

The requirements for these sequences are:

 1) that the first character of the sequence be outside of the
 standard ascii printable characters;
 2) that no sequence be an initial part of another (although
 sequences may share initial parts).

The file consists of entries for various keyboards. The first part of an entry lists the names of the keyboards which use that entry. These names will often be the same as in /etc/termcap (see termcap (5)); however, note that often the terminals from various termcap entries will all use the same map3270 entry; for example, both 925 and 925vb (for 925 with visual bells) would probably use the same map3270 entry. Additionally, there are occasions when the terminal type defines a window manager, and it will then be necessary to specify a keyboard name (via the KEYBD environment variable) as the name of the entry. After the names, separated by vertical bars (`|'), comes a left brace (`{'); the definitions; and, finally, a right brace (`}').

Each definition consists of a reserved keyword (see list below) which identifies the 3270 function (extended as defined below), followed by an equal sign (`='), followed by the various ways to generate this particular function, followed by a semi-colon (`;'). Each way is a sequence of strings of printable ascii characters enclosed inside single quotes (`\(aa'); various ways (alternatives) are separated by vertical bars (`|').

Inside the single quotes, a few characters are special. A caret (`^') specifies that the next character is the ``control'' character of whatever the character is. So, `^a' represents control-a, ie: hexadecimal 1 (note that `^A' would generate the same code). To generate rubout (DEL), one enters `^?'. To represent a control character inside a file requires using the caret to represent a control sequence; simply typing control-A will not work. Note: the ctrl-caret sequence (to generate a hexadecimal 1E) is represented as `^^' (not `^\e^').

In addition to the caret, a letter may be preceded by a backslash (`\e'). Since this has little effect for most characters, its use is usually not recommended. For the case of a single quote (`\(aa'), the backslash prevents that single quote from terminating the string. For the case of a caret (`^'), the backslash prevents the caret from having its special meaning. To have the backslash be part of the string, it is necessary to place two backslashes ('\e\e') in the file.

In addition, the following characters are special:

`\eE' means an escape character;
`\en' means newline;
`\et' means tab;
`\er' means carriage return.

It is not necessary for each character in a string to be enclosed within single quotes. `\eE\eE\eE' means three escape characters.

Comments, which may appear anywhere on a line, begin with a hash mark (`#'), and terminate at the end of that line. However, comments cannot begin inside a quoted string; a hash mark inside a quoted string has no special meaning.

The following is the list of 3270 key names that are supported in this file. Note that some of the keys don't really exist on a 3270. In particular, the developers of this file have relied extensively on the work at the Yale University Computer Center with their 3270 emulator which runs in an IBM Series/1 front end. The following list corresponds closely to the functions that the developers of the Yale code offer in their product. In the following list, the starred ("*") functions are not supported by tn3270 (1). An unsupported function will cause tn3270(1) to send a (possibly visual) bell sequence to the user's terminal.

 3270 Key Name Functional description

 (*)LPRT local print
 DP dup character
 FM field mark character
 CURSEL cursor select
 CENTSIGN EBCDIC cent sign
 RESHOW redisplay the screen
 EINP erase input
 EEOF erase end of field
 DELETE delete character
 INSRT toggle insert mode
 TAB field tab
 BTAB field back tab
 COLTAB column tab
 COLBAK column back tab
 INDENT indent one tab stop
 UNDENT undent one tab stop
 NL new line
 HOME home the cursor
 UP up cursor
 DOWN down cursor
 RIGHT right cursor
 LEFT left cursor
 SETTAB set a column tab
 DELTAB delete a columntab
 SETMRG set left margin
 SETHOM set home position
 CLRTAB clear all column tabs
 (*)APLON apl on
 (*)APLOFF apl off
 (*)APLEND treat input as ascii
 (*)PCON xon/xoff on
 (*)PCOFF xon/xoff off
 DISC disconnect (suspend)
 (*)INIT new terminal type
 (*)ALTK alternate keyboard dvorak
 FLINP flush input
 ERASE erase last character
 WERASE erase last word
 FERASE erase field
 SYNCH we are in synch with the user
 RESET reset key-unlock keyboard
 MASTER_RESET reset, unlock and redisplay
 (*)XOFF please hold output
 (*)XON please give me output
 ESCAPE enter telnet command mode
 WORDTAB tab to beginning of next word
 WORDBACKTAB tab to beginning of current/last word
 WORDEND tab to end of current/next word
 FIELDEND tab to last non-blank of current/next
 unprotected (writable) field.

 PA1 program attention 1
 PA2 program attention 2
 PA3 program attention 3

 CLEAR local clear of the 3270 screen
 TREQ test request
 ENTER enter key

 PFK1 program function key 1
 PFK2 program function key 2
 etc. etc.
 PFK36 program function key 36
 A SAMPLE ENTRY
The following entry is used by
tn3270(1) when unable to locate a reasonable version in the
user's environment and in /etc/map3270:
 name { # actual name comes from TERM variable
 clear = '^z';
 flinp = '^x';
 enter = '^m';
 delete = '^d' | '^?'; # note that '^?' is delete (rubout)
 synch = '^r';
 reshow = '^v';
 eeof = '^e';
 tab = '^i';
 btab = '^b';
 nl = '^n';
 left = '^h';
 right = '^l';
 up = '^k';
 down = '^j';
 einp = '^w';
 reset = '^t';
 xoff = '^s';
 xon = '^q';
 escape = '^c';
 ferase = '^u';
 insrt = '\E ';
 # program attention keys
 pa1 = '^p1'; pa2 = '^p2'; pa3 = '^p3';
 # program function keys
 pfk1 = '\eE1'; pfk2 = '\eE2'; pfk3 = '\eE3'; pfk4 = '\eE4';
 pfk5 = '\eE5'; pfk6 = '\eE6'; pfk7 = '\eE7'; pfk8 = '\eE8';
 pfk9 = '\eE9'; pfk10 = '\eE0'; pfk11 = '\eE-'; pfk12 = '\eE=';
 pfk13 = '\eE!'; pfk14 = '\eE@'; pfk15 = '\eE#'; pfk16 = '\eE$';
 pfk17 = '\eE%'; pfk18 = '\eE'; pfk19 = '\eE&'; pfk20 = '\eE*';
 pfk21 = '\eE('; pfk22 = '\eE)'; pfk23 = '\eE_'; pfk24 = '\eE+';
 }

 "IBM 3270 KEY DEFINITONS FOR AN ABOVE DEFINITION"
The charts below show the proper keys to emulate
each 3270 function when using the default key mapping supplied
with
 tn3270 (1) and
 mset (1). 
 Command Keys IBM 3270 Key Default Key(s)
 Enter RETURN
 Clear control-z
 Cursor Movement Keys
 New Line control-n or
 Home
 Tab control-i
 Back Tab control-b
 Cursor Left control-h
 Cursor Right control-l
 Cursor Up control-k
 Cursor Down control-j or
 LINE FEED
 Edit Control Keys
 Delete Char control-d or
 RUB
 Erase EOF control-e
 Erase Input control-w
 Insert Mode ESC Space
 End Insert ESC Space
 Program Function Keys
 PF1 ESC 1
 PF2 ESC 2
 ... ...
 PF10 ESC 0
 PF11 ESC -
 PF12 ESC =
 PF13 ESC !
 PF14 ESC @
 ... ...
 PF24 ESC +
 Program Attention Keys
 PA1 control-p 1
 PA2 control-p 2
 PA3 control-p 3
 Local Control Keys
 Reset After Error control-r
 Purge Input Buffer control-x
 Keyboard Unlock control-t
 Redisplay Screen control-v
 Other Keys
 Erase current field control-u

 FILES
/etc/map3270
 SEE ALSO
tn3270(1), mset(1), Yale ASCII Terminal Communication
System II Program Description/Operator's Manual
(IBM SB30-1911)
 AUTHOR
Greg Minshall
 BUGS
 Tn3270 doesn't yet understand how to process all the functions
available in
 map3270; when such a function is requested 
 tn3270 will beep at you.

The definition of "word" (for "word erase", "word tab") should be a run-time
option. Currently it is defined as the kernel tty driver defines it (strings
of non-whitespace); more than one person would rather use the "vi" definition
(strings of specials, strings of alphanumeric).