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