4.3BSD-Reno/src/usr.bin/tn3270/tn3270.1
.\" Copyright (c) 1986, 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted provided
.\" that: (1) source distributions retain this entire copyright notice and
.\" comment, and (2) distributions including binaries display the following
.\" acknowledgement: ``This product includes software developed by the
.\" University of California, Berkeley and its contributors'' in the
.\" documentation or other materials provided with the distribution and in
.\" all advertising materials mentioning features or use of this software.
.\" Neither the name of the University nor the names of its contributors may
.\" 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
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" @(#)tn3270.1 4.3 (Berkeley) 6/11/90
.\"
.Dd June 11, 1990
.Dt TN3270 1
.Os BSD 4.3
.Sh NAME
.Nm tn3270
.Nd full-screen remote login to IBM VM/CMS
.Sh SYNOPSIS
.Nm tn3270
.Op Fl d
.Op Fl n Ar filename
.Op Fl t Ar commandname
.Op Ar sysname Op port
.Sh DESCRIPTION
.Nm Tn3270
permits a full-screen, full-duplex connection
from a UNIX
machine
to an IBM (or compatible) machine.
.Nm Tn3270
gives the appearance of being logged in
to the remote machine
from an IBM 3270 terminal.
Of course, you must have an account on the machine
to which you connect in order to log in.
.Nm Tn3270
looks to the user in many respects
like the Yale ASCII Terminal Communication System II.
.Nm Tn3270
is actually a modification of the Arpanet TELNET user interface (see
.Xr telnet 1 )
which will, in certain circumstances, interpret and generate
raw 3270 control streams.
.Pp
The flags to
.Nm tn3270
are as follows:
.Tw Fl
.Tp Fl d
Turn on socket-level tracing (for super-user only)
.Ct Fl n
.Ar filename
.Cx
Specify a file to receive network trace data
output (from commands "toggle netdata" and
"toggle options", see
.Xr telnet 1 ) ;
the default is for output
to be directed to the standard error file.
.Ct Fl t
.Ar commandname
.Cx
Specify a UNIX
command to process IBM 4994 style transparent mode
data received from the remote IBM machine.
.Tp Ar sysname
The name of the remote system. If the remote name
is NOT specified, the user will be prompted for a
command (see below).
.Tp Ar port
The port to connect to on the remote system.
Normally,
.Nm tn3270
attempts to connect to the
standard TELNET port (port
23) on the remote machine.
.Tp
.Pp
When
.Nm tn3270
first connects to the remote system, it will negotiate to go into
3270 mode.
Part of this negotiation involves telling the remote system what model
3270 it is emulating.
In all cases,
.Nm tn3270
emulates a 3278 terminal.
To decide which specific model,
.Nm tn3270
looks at the number of lines and columns on the actual terminal (as
defined in the
.Ev TERM
environment variable; see
.Xr termcap 5 ) .
The terminal (or window in which
.Nm tn3270
is running, on multiple
window systems) must have at least 80 columns and 24 lines, or
.Nm tn3270
will not go into emulation mode.
If the terminal does have at least 80 columns and at least 24 lines,
the following table describes the emulation:
.Pp
.ne 7v
.Ds C
.Cw (rows*columns)
.Cl minimum_size emulated
.Cl (rows*columns) terminal
.Cl -------------- ------------
.Cl 27*132 3278 model 5
.Cl 43*80 3278 model 4
.Cl 32*80 3278 model 3
.Cl 24*80 3278 model 2.
.Cw
.De
.Pp
.Pp
Emulation of the 3270 terminal is done in the UNIX
process.
This emulation involves mapping
3270-style commands from the host
into appropriate sequences to control the user's terminal screen.
.Nm Tn3270
uses
.Xr curses 3
and the
.Pa /usr/share/misc/termcap
file to do this.
The emulation also involves simulating the special 3270 keyboard keys
(program function keys, etc.)
by mapping sequences of keystrokes
from the ASCII keyboard into appropriate 3270 control strings.
This mapping is terminal dependent and is specified
in a description file,
.Pa /usr/share/misc/map3270 ,
(see
.Xr map3270 5 )
or in an environment variable
.Ev MAP3270
(and, if necessary,
.Ev MAP3270A ,
.Ev MAP3270B ,
and so on - see
.Xr mset 1 ) .
Any special function keys on the ASCII keyboard are used whenever possible.
If an entry for the user's terminal
is not found,
.Nm tn3270
looks for an entry for the terminal type
.Em unknown .
If this is not found,
.Nm tn3270
uses a default keyboard mapping
(see
.Xr map3270 5 ) .
.Pp
The first character of each special keyboard mapping sequence
is either an ASCII escape (ESC),
a control character, or an ASCII delete (DEL).
If the user types an unrecognized function key sequence,
.Nm tn3270
sends an ASCII bell (BEL), or a visual bell if
defined in the user's termcap entry, to the user's terminal
and nothing is sent to the IBM host.
.Pp
If
.Nm tn3270
is invoked without specifying a remote host system name,
it enters local command mode,
indicated by the prompt
.Dq Li tn3270>\ .
In this mode,
.Nm tn3270
accepts and executes
all the commands of
.Xr telnet 1 ,
plus one additional command:
.Pp
.Tw Ar
.Tp Ic transcom
Specify UNIX
command for IBM 4994 style transparent mode processing.
.Tp
.Pp
.Nm Tn3270
command mode may also be entered, after connecting to a host, by typing
a special escape sequence.
If
.Nm tn3270
has succeeded in negotiating 3270 mode with the remote host, the
escape sequence will be as defined by the map3270 (see
.Xr map3270 5 )
entry for the user's terminal type
(typically control-C);
otherwise the escape sequence will initially be set to the
single character
.Sq Li \&^]
(control right square bracket).
.Pp
While in command mode, any host login session is still alive
but temporarily suspended.
The host login session may be resumed by entering an empty line
(press the
.Li RETURN
key)
in response to the command prompt.
A session may be terminated by logging off the foreign host,
or by typing ``quit'' or ``close'' while in local command mode.
.Sh FILES
.Dw /usr/share/misc/termcap
.Di L
.Dp Pa /usr/share/misc/termcap
.br
.Dp Pa /usr/share/misc/map3270
.Dp
.Sh AUTHOR
Greg Minshall
.Sh NOTES
The IBM 4994 style transparent mode command is invoked when
.Nm tn3270
receives IBM 4994 style transparent output from the remote host.
Output and input pipes are created for communication between the two
processes.
The pipes are closed when a 3270 clear command is received from the remote
hosts, signalling the end of transparent mode output.
Transparent mode is necessary for sending ASCII control characters over the
3270 terminal connection; ASCII graphics terminal support is accomplished this
way.
Developers of
.Ic transcom
commands should note that the
.Ic transcom
stdin pipe end will be in CBREAK mode, with ECHO and CRMOD turned off.
.Sh ENVIRONMENT
.Nm Tn3270
checks the following environment variables:
.Ev TERM ,
.Ev MAP3270 ,
.Ev MAP3270[A...] .
Information on these can be found in
.Xr mset 1 .
.Nm Tn3270
also checks
.Ev SHELL ,
.Ev KEYBD
and
.Ev API3270 .
.Sh SEE ALSO
.Xr mset 1 ,
.Xr telnet 1 ,
.Xr curses 3 ,
.Xr termcap 3 ,
.Xr termcap 5 ,
.Xr map3270 5 ,
.br
.Em Yale ASCII Terminal Communication
.Em System II Program Description/Operator's Manual
.Pq IBM SB30-1911
.Sh HISTORY
.Nm
appeared in 4.3 BSD.
.Sh BUGS
Tn3270 is slow and uses system resources prodigiously.
.Pp
Not all 3270 functions are supported,
nor all Yale enhancements.
.Pp
Error conditions (attempting to enter data in a protected field, for
example) should cause a message to be sent to the user's terminal
instead of just ringing a bell.