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

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