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

.\" @(#)map3270.5	1.3
.TH MAP3270 5  "22 February 1985"
.ds ]W UCB Computer Center
.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 UNIX (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 one 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 terminals.  The first part
of an entry lists the names of the terminals which use that entry.
These names should be the same as in
.I /etc/termcap
(see \fItermcap\fR(5));
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.
After the names, separated by vertical bars (`|'), comes a left
brace (`{'); the definitions; and, finally, a right brace
(`}').
.PP
The definitions consist 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 (options) 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,
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.
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 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
        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

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