NAME

       tcl3270 - IBM host access tool


SYNOPSIS

       tcl3270 [script] [options] [host]
       tcl3270 -- host

       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
              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 MENUS 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
              the hostname removes the -E from the terminal  name
              when connecting to such hosts.

       --     A  no-op  option.   Because  of  a "feature" in how
              libtcl parses command-line options, it is necessary
              to  specify  some  option  if you want to specify a
              hostname on the command line,  but  don't  want  to
              specify a script name.


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
       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


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.

       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 11 blank-sep-
       arated fields:

       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.

       Screen Formatting
              If  the  screen  is  formatted,  the  letter F.  If
              unformatted or in ANSI mode, the letter U.

       Field Protection
              If the field containing the  cursor  is  protected,
              the  letter  P.  If unprotected or unformatted, the
              letter U.

       Connection State
              If connected to a  host,  the  string  C(hostname).
              Otherwise, the letter N .

       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.

       Model Number (2-5)

       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.

       Number of Columns
              The  current  number  of  columns  defined  on  the
              screen,  subject  to  the same difference for rows,
              above.

       Cursor Row
              The current cursor row (zero-origin).

       Cursor Column
              The current cursor column (zero-origin).


SCREEN CONTENTS COMMANDS

       There are four 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.


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
              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.8


































Man(1) output converted with man2html