NAME
tcl3270 - IBM host access tool
SYNOPSIS
tcl3270 [script] [options] [host] [-- script-arg...]
tcl3270 opens a telnet connection to an IBM host, then
allows a tcl script to run the host login session. It is
derived from x3270, an X-windows IBM 3270 emulator. It
supports both the "standard" 3270 TELNET protocol and the
TN3270E protocol, except for printers, 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.
A specific LU name to use may be specified by prepending
it to the hostname with an ``@''.
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 x3270 and with tn3270, the port
may also be specified as a second, separate argument.)
OPTIONS
tcl3270 understands the following options:
-apl Sets up APL mode. Also see APL SUPPORT below.
-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.
-model name
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 is 3279-4-E.
-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.)
-set toggle
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-3279-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: onto
the hostname removes the -E from the terminal name
when connecting to such hosts.
-trace Turns on data stream and event (script command)
tracing.
-- Terminates the list of tcl3270 options. Whatever
follows will be available to the script in the
$argv tcl variable.
CHARACTER SETS
The -charset option controls 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
hebrew -
icelandic -
belgian -
The default character set is bracket, which is useful for
common IBM hosts which use EBCDIC codes 0xAD and 0xBD for
the `[' and `]' characters, respectively.
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). This allows
tcl3270 to be used to script standard TELNET sessions as
well.
If the host later negotiates to stop functioning in 3270
mode, tcl3270 will return to ANSI emulation.
When emulating an ANSI terminal, tcl3270 supports both
character-at-a-time mode and line mode operation. When in
line mode, the special characters and operational charac-
teristics are defined as follows:
Mode/Character Setting
---------------------------------------------------
Translate CR to NL true
Translate NL to CR false
Erase previous character ^?
Erase entire line ^U
Erase previous word ^W
Redisplay line ^R
Ignore special meaning of next character ^V
Interrupt ^C
Quit ^\\
End of file ^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
of a line.
COMMANDS
tcl3270 supports the following additional tcl commands:
Ascii return entire screen contents in ASCII
Ascii len return screen contents at cursor, in ASCII
Ascii row col len 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 ANSI mode, or "notsign" in 3270 mode
Clear clear screen
Connect host connect to host
CursorSelect Cursor Select AID
Cut erase selected text
Delete delete character under cursor (or send ASCII DEL)
DeleteField delete the entire field
DeleteWord delete the current or previous word
Disconnect disconnect from the host
Down move cursor down
Dup duplicate field
Ebcdic return entire screen contents in EBCDIC
Ebcdic len return screen contents at cursor, in EBCDIC
Ebcdic row col len 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
Key keysym insert key keysym
Left move cursor left
Left2 move cursor left 2 positions
MoveCursor row col move cursor
MonoCase toggle uppercase-only mode
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
Reset reset locked keyboard
Right move cursor right
Right2 move cursor right 2 positions
Snap save screen image
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 Status report saved connection status
Status report connection status
String string insert string
SysReq System Request AID
Tab move cursor to next input field
ToggleInsert toggle insert mode
Transfer option=value... file transfer
Up move cursor up
Wait 3270Mode wait for 3270 mode
Wait Disconnect wait for host to disconnect
Wait InputField wait for valid input field
Wait NVTMode wait for NVT mode
Wait Output wait for more host output
Note: For backwards compatibility, the following aliases
are defined.
Alias Equivalent To
----------------------------
Wait Wait InputField
Wait ansi Wait NVTMode
Wait 3270 Wait 3270Mode
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
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 command,
HexString, which is used to enter non-printing data. The
argument to HexString is a string of hexadecimal digits,
two per character. A leading 0x or 0X is optional. In
3270 mode, the hexadecimal data represent EBCDIC charac-
ters, which are entered into the current field. In ANSI
mode, the hexadecimal data represent ASCII characters,
which are sent directly to the host.
STATUS COMMAND
The result of the Status command consists of 10 blank-sep-
arated fields:
1 Keyboard State
If the keyboard is unlocked, the letter U. If the
keyboard is locked waiting for a response from the
host, or if not connected to a host, the letter L.
If the keyboard is locked because of an operator
error (field overflow, protected field, etc.), the
letter E.
2 Screen Formatting
If the screen is formatted, the letter F. If
unformatted or in ANSI mode, the letter U.
3 Field Protection
If the field containing the cursor is protected,
the letter P. If unprotected or unformatted, the
letter U.
4 Connection State
If connected to a host, the string C(hostname).
Otherwise, the letter N .
5 Emulator Mode
If connected in 3270 mode, the letter I. If con-
nected in ANSI line mode, the letter L. If con-
nected in ANSI character mode, the letter C. If
not connected, the letter N.
6 Model Number (2-5)
7 Number of Rows
The current number of rows defined on the screen.
The host can request that tcl3270 use a 24x80
screen, so this number may be smaller than the max-
imum number of rows possible with the current
model.
8 Number of Columns
The current number of columns defined on the
screen, subject to the same difference for rows,
above.
9 Cursor Row
The current cursor row (zero-origin).
10 Cursor Column
The current cursor column (zero-origin).
SCREEN CONTENTS COMMANDS
There are several commands to return the current virtual
screen contents. The Ascii and AsciiField commands return
a region of the screen as an ASCII text. The Ebcdic and
EbcdicField commands return a region of the screen as
EBCDIC bytes, with each character represented as a 2-digit
hexadecimal string, prefixed by 0x.
The AsciiField and EbcdicField commands return the con-
tents of the field on the screen which contains the cur-
sor.
The Ascii and Ebcdic commands return abitrary regions of
the virtual screen. They take the same arguments:
If no arguments are given, then entire screen con-
tents are returned.
If one argument is given (len), the region of the
screen starting at the cursor, len bytes long is
returned.
If three arguments are given (row, col, len), the
region of the screen starting at zero-origin coor-
dinates (row, col), length len bytes, is returned.
If four arguments are given (row, col, rows, cols),
then a rectangular region is returned, starting at
zero-origin coordinates (row, col), width rows,
length cols.
Note that is it possible for the host to update the
screen, or even change the logical screen dimensions, at
any time. If a script needs to access screen data when it
is possible that the host may be changing it (such as to
determine when certain commands complete), it should use
the Snap command.
Without arguments, Snap saves the screen image and status
in a buffer.
The command Snap Status returns the saved status. The
commands Snap Cols and Snap Rows return the number of
columns and rows in the saved screen image, respectively.
The commands Snap Ascii and Snap Ebcdic are the same as
the Ascii and Ebcdic commands, repectively, but they oper-
ate on the saved buffer, rather than on the live screen
image.
TRANSFER COMMAND
The Transfer command is used to invoke IND$FILE file
transfer. Note that 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 command.
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
------------------------------------------------------------------
Direction No send receive
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 EBCDCIC 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
Lrecl option controls the record length or maximum
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.
APL SUPPORT
tcl3270 supports the full APL2 character set and the entry
of APL characters with the Key command.
The complete list of special APL keysyms is as follows.
Entries marked with an asterisk (*) represent simple
aliases for standard EBCDIC characters.
APL Symbol Hex tcl3270 Keysym
----------------------------------------------
A underbar 41 apl_Aunderbar
alpha B0 apl_alpha
B underbar 42 apl_Bunderbar
bar 60* apl_bar
C underbar 43 apl_Cunderbar
circle 9D apl_circle
circle bar ED apl_circlebar
circle slope CF apl_circleslope
circle star FD apl_circlestar
circle stile CD apl_circlestile
colon 7A* apl_colon
comma 6B* apl_comma
D underbar 44 apl_Dunderbar
del BA apl_del
del stile DC apl_delstile
del tilde FB apl_deltilde
delta BB apl_delta
delta stile DD apl_deltastile
delta underbar FC apl_deltaunderbar
diamond 70 apl_diamond
dieresis 72 apl_dieresis
dieresis dot EC apl_dieresisdot
divide B8 apl_divide
dot 4B* apl_dot
down arrow 8B apl_downarrow
down caret 78 apl_downcaret
down caret tilde CB apl_downcarettilde
down shoe AB apl_downshoe
down stile 8E apl_downstile
down tack AC apl_downtack
down tack jot FE apl_downtackjot
down tack up tack DA apl_downtackuptack
E underbar 45 apl_Eunderbar
epsilon B1 apl_epsilon
epsilon underbar 75 apl_epsilonunderbar
equal 7E* apl_equal
equal underbar E1 apl_equalunderbar
F underbar 46 apl_Funderbar
G underbar 47 apl_Gunderbar
greater 6E* apl_greater
H underbar 48 apl_Hunderbar
I underbar 49 apl_Iunderbar
iota B2 apl_iota
iota underbar 74 apl_iotaunderbar
J underbar 51 apl_Junderbar
jot AF apl_jot
K underbar 52 apl_Kunderbar
L underbar 53 apl_Lunderbar
left arrow 9F apl_leftarrow
left bracket AD apl_leftbracket
left paren 4D* apl_leftparen
left shoe 9B apl_leftshoe
less 4C* apl_less
M underbar 54 apl_Munderbar
N underbar 55 apl_Nunderbar
not equal BE apl_notequal
not greater 8C apl_notgreater
not less AE apl_notless
O underbar 56 apl_Ounderbar
omega B4 apl_omega
overbar A0 apl_overbar
P underbar 57 apl_Punderbar
plus 4E* apl_plus
Q underbar 58 apl_Qunderbar
quad 90 apl_quad
quad divide EE apl_quaddivide
quad jot 73 apl_quadjot
quad quote DE apl_quadquote
quad slope CE apl_quadslope
query 6F* apl_query
quote 7D* apl_quote
quote dot DB apl_quotedot
R underbar 59 apl_Runderbar
rho B3 apl_rho
right arrow 8F apl_rightarrow
right bracket BD apl_rightbracket
right paren 5D* apl_rightparen
right shoe 9A apl_rightshoe
S underbar 62 apl_Sunderbar
semicolon 5E* apl_semicolon
slash 61* apl_slash
slash bar EA apl_slashbar
slope B7 apl_slope
slope bar EB apl_slopebar
squad CC apl_squad
star 5C* apl_star
stile BF apl_stile
T underbar 63 apl_Tunderbar
tilde 80 apl_tilde
times B6 apl_times
U underbar 64 apl_Uunderbar
underbar 6D* apl_underbar
up arrow 8A apl_uparrow
up caret 71 apl_upcaret
up caret tilde CA apl_upcarettilde
up shoe AA apl_upshoe
up shoe jot DF apl_upshoejot
up stile 8D apl_upstile
up tack BC apl_uptack
up tack jot EF apl_uptackjot
V underbar 65 apl_Vunderbar
W underbar 66 apl_Wunderbar
X underbar 67 apl_Xunderbar
Y underbar 68 apl_Yunderbar
Z underbar 69 apl_Zunderbar
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.
SEE ALSO
tcl(1), telnet(1), tn3270(1), ibm_hosts(5), x3270(1)
X Toolkit Intrinsics
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, 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.13g
Man(1) output converted with
man2html