tcl3270 - IBM host access tool
SYNOPSIS
tcl3270 [script] [options] [host] [-- script-arg...]
DESCRIPTION
tcl3270 opens a telnet connection to an IBM host, then
allows a tcl script to control the host login session. It
is derived from x3270(1), an X-windows IBM 3270 emulator.
It implements RFCs 2355 (TN3270E), 1576 (TN3270) and 1646
(LU name selection), and supports IND$FILE file transfer.
The full syntax for host is:
[prefix:]...[LUname@]hostname[:port]
Prepending a p: onto hostname causes the connection to go
through the telnet-passthru service rather than directly
to the host. See PASSTHRU below.
Prepending an s: onto hostname removes the "extended data
stream" option reported to the host. See -tn below for
further information.
Prepending an n: onto hostname turns off TN3270E support
for the session.
A specific LU name to use may be specified by prepending
it to the hostname with an `@'. Multiple LU names to try
can be separated by commas. An empty LU can be placed in
the list with an extra comma.
On systems that support the forkpty library call, the
hostname may be replaced with -e and a command string.
This will cause tcl3270 to connect to a local child pro
cess, such as a shell.
The port to connect to defaults to telnet. This can be
overridden with the -port option, or by appending a port
to the hostname with a colon `:'. (For compatability with
previous versions of tcl3270 and with tn3270(1), the port
may also be specified as a second, separate argument.)
OPTIONS
tcl3270 understands the following options:
-charset name
Specifies an EBCDIC national character set. See
CHARACTER SETS below.
-clear toggle
Sets the initial value of toggle to false. The
list of toggle names is under TOGGLES below.
The model of 3270 display to be emulated. The
model name is in three parts, any of which may be
omitted:
The first part is the base model, which is either
3278 or 3279. 3278 specifies a monochrome 3270
display; 3279 specifies a color 3270 display.
The second part is the model number, which speci
fies the number of rows and columns. Model 4 is
the default.
Model Number Columns Rows
------------------------------
2 80 24
3 80 30
4 80 43
5 132 27
Note: Technically, there is no such 3270 display as
a 3279-4 or 3279-5, but most hosts seem to work
with them anyway.
The third part specifies the Extended 3270 Data
Stream, and is given as -E. It signals the host
that the 3270 display is capable of displaying
extended field attributes, and supports structured
fields and query replies. A 3279 always uses the
Extended Data Stream (whether or not -E is speci
fied); for a 3278 it is optional.
The default model 3278-4-E.
-mono Forces 3278 emulation.
-oversize colsxrows
Makes the screen larger than the default for the
chosen model number. This option has effect only
in combination with extended data stream support
(the -E suffix on the model), and only if the host
supports the Query Reply structured field. The
number of columns multiplied by the number of rows
must not exceed 16383 (3fff hex), the limit of
14-bit 3270 buffer addressing.
-port n
Specifies a different TCP port to connect to. n
can be a name from /etc/services like telnet, or a
number. This option changes the default port num
ber used for all connections. (The positional
parameter affects only the initial connection.)
Sets the initial value of toggle to true. The list
of toggle names is under TOGGLES below.
-tn name
Specifies the terminal name to be transmitted over
the telnet connection. The default name is
IBM-model_name, for example, IBM-3278-4-E.
Some hosts are confused by the -E suffix on the
terminal name, and will ignore the extra screen
area on models 3, 4 and 5. Prepending an :s on the
hostname removes the -E from the terminal name when
connecting to such hosts.
The name can also be specified with the
"tcl3270.termName" resource.
-trace Turns on data stream and event tracing at startup.
The default trace file name is /tmp/x3trc.pro
cess_id.
-tracefile file
Specifies a file to save data stream and event
traces into, overriding the default of
/tmp/x3trc.process_id.
-xrm "tcl3270.resource: value"
Sets the value of the named resource to value.
Resources control less common tcl3270 options, and
are defined under RESOURCES below.
-- Terminates the list of tcl3270 options. Whatever
follows will be available to the script in the
$argv tcl variable.
CHARACTER SETS
The -charset option or the "tcl3270.charset" resource con
trols the EBCDIC national character set used by tcl3270.
Available sets include:
Charset Name Q121 Code
-------------------------
bracket -
us-intl 01
german 03
finnish 09
uk 22
norwegian 23
french 30
icelandic -
belgian -
italian -
common IBM hosts which use EBCDIC codes 0xAD and 0xBD for
the `[' and `]' characters, respectively.
NVT (ANSI) MODE
Some hosts use an ASCII front-end to do initial login
negotiation, then later switch to 3270 mode. tcl3270 will
emulate an ANSI X.64 terminal until the host places it in
3270 mode (telnet BINARY and SEND EOR modes, or TN3270E
mode negotiation).
If the host later negotiates to stop functioning in 3270
mode, tcl3270 will return to ANSI emulation.
In NVT mode, tcl3270 supports both character-at-a-time
mode and line mode operation. You may select the mode
with a menu option. When in line mode, the special char
acters and operational characteristics are defined by
resources:
Mode/Character Resource Default
--------------------------------------------------------------------
Translate CR to NL tcl3270.icrnl true
Translate NL to CR tcl3270.inlcr false
Erase previous character tcl3270.erase ^?
Erase entire line tcl3270.kill ^U
Erase previous word tcl3270.werase ^W
Redisplay line tcl3270.rprnt ^R
Ignore special meaning of next character tcl3270.lnext ^V
Interrupt tcl3270.intr ^C
Quit tcl3270.quit ^\
End of file tcl3270.eof ^D
TOGGLES
tcl3270 has a number of configurable modes which may be
selected by the -set and -clear options.
monoCase
If set, tcl3270 operates in uppercase-only mode.
blankFill
If set, tcl3270 behaves in some un-3270-like ways.
First, when a character is typed into a field, all
nulls in the field to the left of that character
are changed to blanks. This eliminates a common
3270 data-entry surprise. Second, in insert mode,
trailing blanks in a field are treated like nulls,
eliminating the annoying `lock-up' that often
occurs when inserting into an field with (apparent)
space at the end.
lineWrap
If set, the ANSI terminal emulator automatically
assumes a NEWLINE character when it reaches the end
The names of the toggles for use with the -set and -clear
options are as follows:
Option Name
-------------------------------------
Monocase monoCase
Blank Fill blankFill
Track Cursor cursorPos
Trace Data Stream dsTrace
Trace Events eventTrace
Save Screen(s) in File screenTrace
Wraparound lineWrap
COMMANDS
tcl3270 supports the following additional tcl commands:
Ascii return entire screen contents in ASCII
Ascii length return screen contents at cursor in ASCII
Ascii row col length return screen contents in ASCII
Ascii row col rows cols return screen region in ASCII
AsciiField return current field in ASCII
Attn attention key
BackSpace move cursor left (or send ASCII BS)
BackTab tab to start of previous input field
CircumNot input "^" in NVT mode, or "notsign" in 3270 mode
Clear clear screen
Cols report screen size
Connect host connect to host
CursorSelect Cursor Select AID
Delete delete character under cursor (or send ASCII DEL)
DeleteField delete the entire field
DeleteWord delete the current or previous word
Disconnect disconnect from host
Down move cursor down
Dup duplicate field
Ebcdic return entire screen contents in EBCDIC
Ebcdic length return screen contents at cursor in EBCDIC
Ebcdic row col length return screen contents in EBCDIC
Ebcdic row col rows cols return screen region in EBCDIC
EbcdicField return current field in EBCDIC
Enter Enter AID (or send ASCII CR)
Erase erase previous character (or send ASCII BS)
EraseEOF erase to end of current field
EraseInput erase all input fields
FieldEnd move cursor to end of field
FieldExit clear to end of field and skip to next (5250 emulation)
FieldMark mark field
HexString hex_digits insert control-character string
Home move cursor to first input field
Insert set insert mode
Interrupt send TELNET IP to host
Key 0xxx insert key with ASCII code xx
Left move cursor left
Left2 move cursor left 2 positions
MonoCase toggle uppercase-only mode
MoveCursor row col move cursor to (row,col)
Newline move cursor to first field on next line (or send ASCII LF)
NextWord move cursor to next word
PA n Program Attention AID (n from 1 to 3)
PF n Program Function AID (n from 1 to 24)
PreviousWord move cursor to previous word
Quit exit tcl3270
Redraw redraw window
Reset reset locked keyboard
Right move cursor right
Right2 move cursor right 2 positions
Rows report screen size
Snap same as Snap Save
Snap Ascii report saved screen data (see Ascii)
Snap Cols report saved screen size
Snap Ebcdic report saved screen data (see Ebcdic)
Snap Rows report saved screen size
Snap Save save screen image
Snap Status report saved connection status
Snap Wait [timeout] Output wait for host output and save screen image
Status report connection status
String string insert string (simple macro facility)
SysReq System Request AID
Tab move cursor to next input field
ToggleInsert toggle insert mode
ToggleReverse toggle reverse-input mode
Transfer option=value... file transfer
Up move cursor up
Wait [timeout] 3270Mode wait for 3270 mode
Wait [timeout] Disconnect wait for host to disconnect
Wait [timeout] InputField wait for valid input field
Wait [timeout] NVTMode wait for NVT mode
Wait [timeout] Output wait for more host output
FILE TRANSFER
The Transfer command implements IND$FILE file transfer.
This command requires that the IND$FILE program be
installed on the IBM host, and that the 3270 cursor be
located in a field that will accept a TSO or VM/CMS com
mand.
Because of the complexity and number of options for file
transfer, the parameters to the Transfer command take the
unique form of option=value, and can appear in any order.
The options are:
Option Required? Default Other Values
------------------------------------------------------------------
HostFile Yes
LocalFile Yes
Host No tso vm
Mode No ascii binary
Cr No remove add, keep
Exist No keep replace, append
Recfm No fixed, variable, undefined
Lrecl No
Blksize No
Allocation No tracks, cylinders, avblock
PrimarySpace No
SecondarySpace No
The option details are as follows.
Direction
send (the default) to send a file to the host,
receive to receive a file from the host.
HostFile
The name of the file on the host.
LocalFile
The name of the file on the local workstation.
Host The type of host (which dictates the form of the
IND$FILE command): tso (the default) or vm.
Mode Use ascii (the default) for a text file, which will
be translated between EBCDIC and ASCII as neces
sary. Use binary for non-text files.
Cr Controls how Newline characters are handled when
transferring Mode=ascii files. remove (the
default) strips Newline characters in local files
before transferring them to the host. add adds
Newline characters to each host file record before
transferring it to the local workstation. keep
preserves Newline characters when transferring a
local file to the host.
Exist Controls what happens when the destination file
already exists. keep (the default) preserves the
file, causing the Transfer command to fail.
replace overwrites the destination file with the
source file. append appends the source file to the
destination file.
Recfm Controls the record format of files created on the
host. fixed creates a file with fixed-length
records. variable creates a file with variable-
length records. undefined creates a file with
undefined-length records (TSO hosts only). The
record length for Recfm=fixed and Recfm=variable
files, respectively.
Lrecl Specifies the record length (or maximum record
length) for files created on the host.
Blksize
Specifies the block size for files created on the
host. (TSO hosts only.)
Allocation
Specifies the units for the TSO host PrimarySpace
and SecondarySpace options: tracks, cylinders or
avblock.
PrimarySpace
Primary allocation for a file created on a TSO
host. The units are given by the Allocation
option.
SecondarySpace
Secondary allocation for a file created on a TSO
host. The units are given by the Allocation
option.
NESTED SCRIPTS
The String Command
The simplest method for nested scripts is provided
via the String command. The arguments to String
are one or more double-quoted strings which are
inserted directly as if typed. The C backslash
conventions are honored as follows. (Entries
marked * mean that after sending the AID code to
the host, tcl3270 will wait for the host to unlock
the keyboard before further processing the string.)
\b Left
\f Clear*
\n Enter*
\pan PA key n*
\pfnn PF key nn*
\r Newline
\t Tab
An example keymap entry would be:
Meta<Key>p: String("probs clearrdr\n")
Note: The strings are in ASCII and converted to
EBCDIC, so beware of inserting control codes.
There is also an alternate form of the String com
mand, HexString, which is used to enter non-print
ing data. The argument to HexString is a string of
hexadecimal digits, two per character. A leading
mal data represent EBCDIC characters, which are
entered into the current field. In NVT mode, the
hexadecimal data represent ASCII characters, which
are sent directly to the host.
PASSTHRU
tcl3270 supports the Sun telnet-passthru service provided
by the in.telnet-gw server. This allows outbound telnet
connections through a firewall machine. When a p: is
prepended to a hostname, tcl3270 acts much like the itel
net(1) command. It contacts the machine named internet-
gateway at the port defined in /etc/services as telnet-
passthru (which defaults to 3514). It then passes the
requested hostname and port to the in.telnet-gw server.
RESOURCES
Certain tcl3270 options can be configured via resources.
Resources are defined by -xrm options. The definitions
are similar to X11 resources, and use a similar syntax.
The resources available in tcl3270 are:
Resource Default Option Purpose
--------------------------------------------------------------------------------
blankFill False -set blankFill Blank Fill mode
charset bracket -charset EBCDIC character set
charset.foo Definition of character set foo
dsTrace False -trace Data stream tracing
eof ^D NVT-mode EOF character
erase ^H NVT-mode erase character
extended True Use 3270 extended data stream
eventTrace False -trace Event tracing
ftCommand ind$file Host file transfer command
icrnl False Map CR to NL on NVT-mode input
inlcr False Map NL to CR in NVT-mode input
intr ^C NVT-mode interrupt character
kill ^U NVT-mode kill character
lineWrap False -set lineWrap NVT line wrap mode
lnext ^V NVT-mode lnext character
m3279 (note 1) -mono 3279 (color) emulation
monoCase False -set monoCase Mono-case mode
numericLock False Lock keyboard for numeric field error
oerrLock False Lock keyboard for input error
oversize -oversize Oversize screen dimensions
port telnet -port Non-default TCP port
quit ^\ NVT-mode quit character
rprnt ^R NVT-mode reprint character
secure False Disable "dangerous" options
termName (note 2) -tn TELNET terminal type string
traceDir /tmp Directory for trace files
traceFile (note 3) -tracefile File for trace output
werase ^W NVT-mode word-erase character
Note 1: m3279 defaults to False. It can be forced
Note 2: The default terminal type string is con
structed from the model number, color emulation,
and extended data stream modes. E.g., a model 2
with color emulation and the extended data stream
option would be sent as IBM-3279-2-E. Note also
that when TN3270E mode is used, the terminal type
is always sent as some type of 3278.
Note 3: The default trace file is x3trc.pid in the
directory specified by the traceDir resource.
If more than one -xrm option is given for the same
resource, the last one on the command line is used.
SEE ALSO
x3270(1), s3270(1), c3270(1), telnet(1), tn3270(1)
Data Stream Programmer's Reference, IBM GA23-0059
Character Set Reference, IBM GA27-3831
RFC 1576, TN3270 Current Practices
RFC 1646, TN3270 Extensions for LUname and Printer Selec
tion
RFC 2355, TN3270 Enhancements
COPYRIGHTS
Modifications Copyright 1993, 1994, 1995, 1996, 1997,
1999, 2000 by Paul Mattes.
Original X11 Port Copyright 1990 by Jeff Sparkes.
Permission to use, copy, modify, and distribute
this software and its documentation for any purpose
and without fee is hereby granted, provided that
the above copyright notice appear in all copies and
that both that copyright notice and this permission
notice appear in supporting documentation.
Copyright 1989 by Georgia Tech Research Corporation,
Atlanta, GA 30332.
All Rights Reserved. GTRC hereby grants public use
of this software. Derivative works based on this
software must incorporate this copyright notice.
5250 Emulation Code Copyright Minolta (Schweiz) AG, Beat
Rubischon.
VERSION
tcl3270 3.2.16
Man(1) output converted with
man2html