[unix-history] / usr / src / usr.bin / tn3270 / mset / map3270.5

.\" Copyright (c) 1986 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)map3270.5	4.4 (Berkeley) %G%
.\"
.TH MAP3270 5  ""
.UC 6
.SH NAME
map3270 \- database for mapping ascii keystrokes into IBM 3270 keys
.SH SYNOPSIS
.B map3270
.SH DESCRIPTION
When emulating IBM-syle 3270 terminals under \s-UNIX\s0 (see \fItn3270\fR(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
.B 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
.B EEOF
function.
.PP
The requirements for these sequences are:
.nf
.ta 4n 9n
.sp
	1)	that the first character of the sequence be outside of the
		standard ascii printable characters;
.sp
	2)	that no sequence \fIbe\fR an initial part of another (although
		sequences may \fIshare\fR initial parts).
.sp
.fi
.SH FORMAT
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
.I /etc/termcap
(see
.IR termcap (5));
however, note that often the terminals from various termcap entries will all
use the same
.I map3270
entry; for example, both 925 and 925vb (for
925 with visual bells) would probably use the same
.I 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
.B 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
(`}').
.PP
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
.I printable
ascii characters enclosed inside single quotes (`\(aa');
various ways (alternatives) are separated by vertical bars (`|').
.PP
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
.B 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^').
.PP
In addition to the caret, a letter may be preceeded 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.
.PP
In addition, the following characters are special:
.sp
.nf
.in +0.5i
`\eE'  means an escape character;
`\en'  means newline;
`\et'  means tab;
`\er'  means carriage return.
.in -0.5i
.fi
.sp
It is not necessary for each character in a string
to be enclosed within single quotes.
`\eE\eE\eE' means three escape characters.
.PP
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.
.PP
.SH 3270 KEYS SUPPORTED
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.
.sp
.B In the following list, the
.B starred ("*")
.B functions are not supported by
.IR tn3270 (1).
An unsupported function will cause
.IR tn3270(1)
to send a (possibly visual) bell sequence to the user's terminal.
.sp
.nf
        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
.SH 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:
.sp
.nf
        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 = '\E1'; pfk2 = '\E2'; pfk3 = '\E3'; pfk4 = '\E4';
        pfk5 = '\E5'; pfk6 = '\E6'; pfk7 = '\E7'; pfk8 = '\E8';
        pfk9 = '\E9'; pfk10 = '\E0'; pfk11 = '\E-'; pfk12 = '\E=';
        pfk13 = '\E!'; pfk14 = '\E@'; pfk15 = '\E#'; pfk16 = '\E$';
        pfk17 = '\E%'; pfk18 = '\E'; pfk19 = '\E&'; pfk20 = '\E*';
        pfk21 = '\E('; pfk22 = '\E)'; pfk23 = '\E_'; pfk24 = '\E+';
        }
.fi
.SH "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
.IR tn3270 (1)
and
.IR mset (1).
.sp
.nf
     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
.fi
.SH FILES
/etc/map3270
.SH SEE ALSO
tn3270(1), mset(1), \fIYale ASCII Terminal Communication
System II Program Description/Operator's Manual\fR
(IBM SB30-1911)
.SH AUTHOR
Greg Minshall
.SH BUGS
.I Tn3270
doesn't yet understand how to process all the functions
available in
.I map3270;
when such a function is requested 
.I tn3270
will beep at you.
.PP
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).
Commit	Line	Data
70f58f09 KB	1	.\" Copyright (c) 1986 The Regents of the University of California.
70f58f09 KB	2	.\" All rights reserved.
b5bef96d	3	.\"
91cff1e1	4	.\" %sccs.include.redist.man%
70f58f09	5	.\"
91cff1e1	6	.\" @(#)map3270.5 4.4 (Berkeley) %G%
b5bef96d KM	7	.\"
	8	.TH MAP3270 5 ""
	9	.UC 6
cfcb59fc GM	10	.SH NAME
	11	map3270 \- database for mapping ascii keystrokes into IBM 3270 keys
	12	.SH SYNOPSIS
dd13e0cd	13	.B map3270
cfcb59fc	14	.SH DESCRIPTION
449f67e9	15	When emulating IBM-syle 3270 terminals under \s-UNIX\s0 (see \fItn3270\fR(1)),
cfcb59fc GM	16	a mapping must be performed between sequences of keys hit on
	17	a user's (ascii) keyboard, and the keys that are
	18	available on a 3270. For example, a 3270 has a key labeled
	19	.B EEOF
	20	which erases the contents of the current field from the
	21	location of the cursor to the end.
	22	In order to accomplish this function,
	23	the terminal user and a program emulating a 3270 must
	24	agree on what keys will be typed
	25	to invoke the
	26	.B EEOF
	27	function.
	28	.PP
	29	The requirements for these sequences are:
	30	.nf
	31	.ta 4n 9n
	32	.sp
449f67e9	33	1) that the first character of the sequence be outside of the
cfcb59fc GM	34	standard ascii printable characters;
cfcb59fc GM	35	.sp
449f67e9	36	2) that no sequence \fIbe\fR an initial part of another (although
cfcb59fc GM	37	sequences may \fIshare\fR initial parts).
	38	.sp
	39	.fi
	40	.SH FORMAT
449f67e9 GM	41	The file consists of entries for various keyboards. The first part
	42	of an entry lists the names of the keyboards which use that entry.
	43	These names will often be the same as in
cfcb59fc	44	.I /etc/termcap
449f67e9 GM	45	(see
	46	.IR termcap (5));
	47	however, note that often the terminals from various termcap entries will all
cfcb59fc GM	48	use the same
	49	.I map3270
	50	entry; for example, both 925 and 925vb (for
	51	925 with visual bells) would probably use the same
	52	.I map3270
	53	entry.
449f67e9 GM	54	Additionally, there are occasions when the terminal type defines
	55	a window manager, and it will then be necessary to specify a
	56	keyboard name (via the
	57	.B KEYBD
	58	environment variable) as the name of the entry.
cfcb59fc GM	59	After the names, separated by vertical bars (`\|'), comes a left
	60	brace (`{'); the definitions; and, finally, a right brace
	61	(`}').
	62	.PP
449f67e9	63	Each definition consists of a reserved keyword (see list below) which
cfcb59fc GM	64	identifies the 3270 function (extended as defined below), followed
	65	by an equal sign (`='), followed by the various ways to generate
	66	this particular function, followed by a semi-colon (`;').
	67	Each way is a sequence of strings of
	68	.I printable
	69	ascii characters enclosed inside single quotes (`\(aa');
449f67e9	70	various ways (alternatives) are separated by vertical bars (`\|').
cfcb59fc GM	71	.PP
	72	Inside the single quotes, a few characters are special.
	73	A caret
	74	(`^') specifies that the next character is
	75	the ``control'' character of whatever the character is.
	76	So, `^a'
	77	represents control-a, ie: hexadecimal 1
	78	(note that `^A' would generate the same code).
	79	To generate
449f67e9 GM	80	.B rubout
449f67e9 GM	81	(DEL),
cfcb59fc GM	82	one enters `^?'.
	83	To represent a control character inside a file
	84	requires using the caret to represent a control sequence;
	85	simply typing control-A will not work.
	86	Note: the ctrl-caret sequence
	87	(to generate a hexadecimal 1E)
	88	is represented as `^^' (not `^\e^').
	89	.PP
	90	In addition to the caret, a letter may be preceeded by a backslash (`\e').
	91	Since this has little effect for most characters,
	92	its use is usually not recommended.
	93	For the case of a single quote (`\(aa'), the backslash
	94	prevents that single quote from terminating the string.
449f67e9 GM	95	For the case of a caret (`^'), the backslash prevents
449f67e9 GM	96	the caret from having its special meaning.
cfcb59fc GM	97	To have the backslash be part of the string, it is necessary to
	98	place two backslashes ('\e\e') in the file.
	99	.PP
	100	In addition, the following characters are special:
	101	.sp
	102	.nf
	103	.in +0.5i
	104	`\eE' means an escape character;
	105	`\en' means newline;
	106	`\et' means tab;
	107	`\er' means carriage return.
	108	.in -0.5i
	109	.fi
	110	.sp
	111	It is not necessary for each character in a string
	112	to be enclosed within single quotes.
	113	`\eE\eE\eE' means three escape characters.
	114	.PP
	115	Comments, which may appear anywhere on a line,
	116	begin with a hash mark (`#'), and terminate
	117	at the end of that line.
	118	However, comments cannot begin inside a quoted string;
	119	a hash mark inside a quoted string has no special meaning.
	120	.PP
	121	.SH 3270 KEYS SUPPORTED
	122	The following is the list of 3270 key names that are supported in this file.
	123	Note that some of the keys don't really exist on a 3270.
	124	In particular, the developers of this file have relied
	125	extensively on the work at the Yale University Computer Center with
	126	their 3270 emulator which runs in an IBM Series/1 front end.
	127	The following list corresponds closely to the functions
	128	that the developers of the Yale code offer in their product.
	129	.sp
	130	.B In the following list, the
	131	.B starred ("*")
	132	.B functions are not supported by
	133	.IR tn3270 (1).
	134	An unsupported function will cause
	135	.IR tn3270(1)
449f67e9	136	to send a (possibly visual) bell sequence to the user's terminal.
cfcb59fc GM	137	.sp
	138	.nf
	139	3270 Key Name Functional description
	140
	141	(*)LPRT local print
	142	DP dup character
	143	FM field mark character
449f67e9 GM	144	CURSEL cursor select
449f67e9 GM	145	CENTSIGN EBCDIC cent sign
cfcb59fc GM	146	RESHOW redisplay the screen
	147	EINP erase input
	148	EEOF erase end of field
	149	DELETE delete character
	150	INSRT toggle insert mode
	151	TAB field tab
	152	BTAB field back tab
	153	COLTAB column tab
	154	COLBAK column back tab
	155	INDENT indent one tab stop
	156	UNDENT undent one tab stop
	157	NL new line
	158	HOME home the cursor
	159	UP up cursor
	160	DOWN down cursor
	161	RIGHT right cursor
	162	LEFT left cursor
	163	SETTAB set a column tab
	164	DELTAB delete a columntab
	165	SETMRG set left margin
	166	SETHOM set home position
	167	CLRTAB clear all column tabs
	168	(*)APLON apl on
	169	(*)APLOFF apl off
	170	(*)APLEND treat input as ascii
	171	(*)PCON xon/xoff on
	172	(*)PCOFF xon/xoff off
	173	DISC disconnect (suspend)
	174	(*)INIT new terminal type
	175	(*)ALTK alternate keyboard dvorak
	176	FLINP flush input
	177	ERASE erase last character
	178	WERASE erase last word
	179	FERASE erase field
	180	SYNCH we are in synch with the user
	181	RESET reset key-unlock keyboard
	182	MASTER_RESET reset, unlock and redisplay
	183	(*)XOFF please hold output
	184	(*)XON please give me output
	185	ESCAPE enter telnet command mode
3692533f GM	186	WORDTAB tab to beginning of next word
	187	WORDBACKTAB tab to beginning of current/last word
	188	WORDEND tab to end of current/next word
	189	FIELDEND tab to last non-blank of current/next
	190	unprotected (writable) field.
cfcb59fc GM	191
	192	PA1 program attention 1
	193	PA2 program attention 2
	194	PA3 program attention 3
	195
	196	CLEAR local clear of the 3270 screen
	197	TREQ test request
	198	ENTER enter key
	199
	200	PFK1 program function key 1
	201	PFK2 program function key 2
	202	etc. etc.
	203	PFK36 program function key 36
	204	.SH A SAMPLE ENTRY
	205	The following entry is used by
	206	tn3270(1) when unable to locate a reasonable version in the
	207	user's environment and in /etc/map3270:
	208	.sp
	209	.nf
	210	name { # actual name comes from TERM variable
	211	clear = '^z';
	212	flinp = '^x';
	213	enter = '^m';
	214	delete = '^d' \| '^?'; # note that '^?' is delete (rubout)
	215	synch = '^r';
	216	reshow = '^v';
	217	eeof = '^e';
	218	tab = '^i';
	219	btab = '^b';
	220	nl = '^n';
	221	left = '^h';
	222	right = '^l';
	223	up = '^k';
	224	down = '^j';
	225	einp = '^w';
	226	reset = '^t';
	227	xoff = '^s';
	228	xon = '^q';
	229	escape = '^c';
	230	ferase = '^u';
	231	insrt = '\E ';
	232	# program attention keys
	233	pa1 = '^p1'; pa2 = '^p2'; pa3 = '^p3';
	234	# program function keys
	235	pfk1 = '\E1'; pfk2 = '\E2'; pfk3 = '\E3'; pfk4 = '\E4';
	236	pfk5 = '\E5'; pfk6 = '\E6'; pfk7 = '\E7'; pfk8 = '\E8';
	237	pfk9 = '\E9'; pfk10 = '\E0'; pfk11 = '\E-'; pfk12 = '\E=';
	238	pfk13 = '\E!'; pfk14 = '\E@'; pfk15 = '\E#'; pfk16 = '\E$';
	239	pfk17 = '\E%'; pfk18 = '\E'; pfk19 = '\E&'; pfk20 = '\E*';
	240	pfk21 = '\E('; pfk22 = '\E)'; pfk23 = '\E_'; pfk24 = '\E+';
	241	}
	242	.fi
	243	.SH "IBM 3270 KEY DEFINITONS FOR AN ABOVE DEFINITION"
	244	The charts below show the proper keys to emulate
	245	each 3270 function when using the default key mapping supplied
	246	with
	247	.IR tn3270 (1)
	248	and
	249	.IR mset (1).
	250	.sp
	251	.nf
	252	Command Keys IBM 3270 Key Default Key(s)
	253	Enter RETURN
	254	Clear control-z
255	Cursor Movement Keys
256	New Line control-n or
257	Home
258	Tab control-i
259	Back Tab control-b
260	Cursor Left control-h
261	Cursor Right control-l
262	Cursor Up control-k
263	Cursor Down control-j or
264	LINE FEED
265	Edit Control Keys
266	Delete Char control-d or
267	RUB
268	Erase EOF control-e
269	Erase Input control-w
270	Insert Mode ESC Space
271	End Insert ESC Space
272	Program Function Keys
273	PF1 ESC 1
274	PF2 ESC 2
275	... ...
276	PF10 ESC 0
277	PF11 ESC -
278	PF12 ESC =
279	PF13 ESC !
280	PF14 ESC @
281	... ...
282	PF24 ESC +
283	Program Attention Keys
284	PA1 control-p 1
285	PA2 control-p 2
286	PA3 control-p 3
287	Local Control Keys
288	Reset After Error control-r
289	Purge Input Buffer control-x
290	Keyboard Unlock control-t
291	Redisplay Screen control-v
292	Other Keys
449f67e9	293	Erase current field control-u
cfcb59fc GM	294	.fi
	295	.SH FILES
	296	/etc/map3270
	297	.SH SEE ALSO
	298	tn3270(1), mset(1), \fIYale ASCII Terminal Communication
	299	System II Program Description/Operator's Manual\fR
	300	(IBM SB30-1911)
	301	.SH AUTHOR
	302	Greg Minshall
	303	.SH BUGS
	304	.I Tn3270
	305	doesn't yet understand how to process all the functions
	306	available in
	307	.I map3270;
	308	when such a function is requested
	309	.I tn3270
	310	will beep at you.
3692533f	311	.PP
449f67e9	312	The definition of "word" (for "word erase", "word tab") should be a run-time
3692533f	313	option. Currently it is defined as the kernel tty driver defines it (strings
449f67e9	314	of non-whitespace); more than one person would rather use the "vi" definition
3692533f	315	(strings of specials, strings of alphanumeric).