path: root/usr.bin/tn3270/tn3270/tn3270.1

.\" Copyright (c) 1986, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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 BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)tn3270.1	8.2 (Berkeley) 4/18/94
.\"	$Id$
.\"
.Dd April 18, 1994
.Dt TN3270 1
.Os BSD 4.3
.Sh NAME
.Nm tn3270
.Nd full-screen remote login to
.Tn IBM VM/CMS
.Sh SYNOPSIS
.Nm
.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
.Tn UNIX
machine
to an
.Tn IBM
(or compatible) machine.
.Nm Tn3270
gives the appearance of being logged in
to the remote machine
from an
.Tn 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
.Tn ASCII
Terminal Communication System II.
.Nm Tn3270
is actually a modification of the Arpanet
.Tn 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:
.Bl -tag -width Fl
.It Fl d
Turn on socket-level tracing (for super-user only).
.It Fl n Ns Ar filename
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.
.It Fl t Ns Ar commandname
Specify a
.Tn UNIX
command to process
.Tn IBM
4994 style transparent mode
data received from the remote
.Tn IBM
machine.
.It 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).
.It Ar port
The port to connect to on the remote system.
Normally,
.Nm
attempts to connect to the
standard
.Tn TELNET
port (port
23) on the remote machine.
.El
.Pp
When
.Nm
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
emulates a 3278 terminal.
To decide which specific model,
.Nm
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
is running, on multiple
window systems) must have at least 80 columns and 24 lines, or
.Nm
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
.Bd -filled -offset center
.Bl -column (rows*columns)
.It minimum_size	emulated
.It (rows*columns)	terminal
.It --------------	------------
.It 27*132	3278 model 5
.It 43*80	3278 model 4
.It 32*80	3278 model 3
.It 24*80	3278 model 2.
.El
.Ed
.Pp
Emulation of the 3270 terminal is done in the
.Tn 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
.Tn 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
.Tn ASCII
keyboard are used whenever possible.
If an entry for the user's terminal
is not found,
.Nm
looks for an entry for the terminal type
.Em unknown .
If this is not found,
.Nm
uses a default keyboard mapping
(see
.Xr map3270  5  ) .
.Pp
The first character of each special keyboard mapping sequence
is either an
.Tn ASCII
escape
.Pq Tn ESC ,
a control character, or an
.Tn ASCII
delete
.Pq Tn DEL .
If the user types an unrecognized function key sequence,
.Nm
sends an
.Tn ASCII
bell
.Pq Tn BEL ,
or a visual bell if
defined in the user's termcap entry, to the user's terminal
and nothing is sent to the
.Tn IBM
host.
.Pp
If
.Nm
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
accepts and executes
all the commands of
.Xr telnet  1  ,
plus one additional command:
.Pp
.Bl -tag -width Ar
.It Ic transcom
Specify
.Tn UNIX
command for
.Tn IBM
4994 style transparent mode processing.
.El
.Pp
.Nm Tn3270
command mode may also be entered, after connecting to a host, by typing
a special escape sequence.
If
.Nm
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
.Tn 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
.Bl -tag -width /usr/share/misc/termcap -compact
.It Pa /usr/share/misc/termcap
.It Pa /usr/share/misc/map3270
.El
.\" .Sh AUTHOR
.\" Greg Minshall
.Sh NOTES
The
.Tn IBM
4994 style transparent mode command is invoked when
.Nm
receives
.Tn 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, signaling the end of transparent mode output.
Transparent mode is necessary for sending
.Tn ASCII
control characters over the
3270 terminal connection;
.Tn 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
.Dv CBREAK
mode, with
.Dv ECHO
and
.Dv 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 map3270 5 ,
.Xr termcap 5
.Rs
.%T "Yale ASCII Terminal Communication"
.%B "System II Program Description/Operator's Manual"
.%R IBM SB30-1911
.Re
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.3 .
.Sh BUGS
.Nm 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.