xenial (1) s3270.1.gz

Provided by: s3270_3.3.14ga11-1build1_amd64 bug

NAME

       s3270 - IBM host access tool

SYNOPSIS

       s3270 [options] [host]

       s3270 [options] session-file.s3270

DESCRIPTION

       s3270  opens  a telnet connection to an IBM host, then allows a 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.

       Prepending  an L: onto hostname causes s3270 to first create an SSL tunnel to the host, and then create a
       TN3270 session inside the tunnel.  (This function is supported only  if  s3270  was  built  with  SSL/TLS
       support).   Note  that  TLS-encrypted  sessions using the TELNET START-TLS option are negotiated with the
       host automatically; for these sessions the L: prefix should not be used.

       A specific Logical Unit (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.  (Note that the LU name is used for different purposes by different kinds of hosts.  For  example,
       CICS uses the LU name as the Terminal ID.)

       The  hostname  may  optionally be placed inside square-bracket characters `[' and `]'.  This will prevent
       any colon `:' characters in the hostname from being interpreted as indicating  option  prefixes  or  port
       numbers.  This allows numeric IPv6 addresses to be used as hostnames.

       On  systems  that  support  the  forkpty library call, the hostname may be replaced with -e and a command
       string.  This will cause s3270 to connect to a local child process, 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 s3270 and with
       tn3270(1), the port may also be specified as a second, separate argument.)

OPTIONS

        s3270 understands the following options:

       -accepthostname spec
              Specifies a particular hostname to accept when validating the name presented  in  the  host's  SSL
              certificate,  instead  of  comparing to the name or address used to make the connection.  spec can
              either be any, which disables name  validation,  DNS:hostname,  which  matches  a  particular  DNS
              hostname, or IP:address, which matches a particular numeric IPv4 or IPv6 address.

       -cadir directory
              Specifies  a  directory  containing  CA  (root)  certificates  to use when verifying a certificate
              provided by the host.

       -cafile filename
              Specifies a PEM-format file containing CA (root) certificates to use when verifying a  certificate
              provided by the host.

       -certfile filename
              Specifies  a file containing a certificate to provide to the host, if requested.  The default file
              type is PEM.

       -certfiletype type
              Specifies the type of the certificate file specified by -certfile.  Type can be pem or asn1.

       -chainfile filename
              Specifies a certificate chain file in PEM format, containing a certificate to provide to the  host
              if requested, as well as one or more intermediate certificates and the CA certificate used to sign
              that certificate.  If -chainfile is specified, it overrides -certfile.

       -charset name
              Specifies an EBCDIC host character set.

       -clear toggle
              Sets the initial value of toggle to false.  The list of toggle names is under TOGGLES below.

       -devname name
              Specifies a device name (workstation ID) for RFC 4777 support.

       -im method
              Specifies the name of the input method to use for multi-byte input.  (Supported only when s3270 is
              compiled with DBCS support.)

       -keyfile filename
              Specifies  a  file containing the private key for the certificate file (specified via -certfile or
              -chainfile).  The default file type is PEM.

       -keyfiletype type
              Specifies the type of the private key file specified by -keyfile.  Type can be pem or asn1.

       -keypasswd type:value
              Specifies the password for the private key  file,  if  it  is  encrypted.   The  argument  can  be
              file:filename,  specifying  that  the  password  is  in  a  file, or string:string, specifying the
              password on the command-line directly.  If the private key file is  encrypted  and  no  -keypasswd
              option is given, secure connections will not be allowed.

       -km name
              Specifies  the  local encoding method for multi-byte text.  name is an encoding name recognized by
              the ICU library.  (Supported only when s3270 is compiled with DBCS  support,  and  necessary  only
              when s3270 cannot figure it out from the locale.)

       -loginmacro Action(arg...) ...
              Specifies a macro to run at login time.

       -model name
              The  model of 3270 display to be emulated.  The model name is in two parts, either of which may be
              omitted:

              The first part is the base model, which is either 3278  or  3279.   3278  specifies  a  monochrome
              (green on black) 3270 display; 3279 specifies a color 3270 display.

              The  second  part is the model number, which specifies the number of rows and columns.  Model 4 is
              the default.

                                             Model Number   Columns   Rows
                                             ──────────────────────────────
                                                  2           80       24
                                                  3           80       32
                                                  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 default model is 3279-4.

       -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 (controlled by  the  "s3270.extended"  resource),
              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 number used for all connections.  (The  positional
              parameter affects only the initial connection.)

       -proxy type:host[:port]
              Causes  s3270  to connect via the specified proxy, instead of using a direct connection.  The host
              can be an IP address or hostname.  The optional port can be a number or a  service  name.   For  a
              list of supported proxy types, see PROXY below.

       -scriptport port
              Causes s3270 to listen for scripting connections on local TCP port port.

       -selfsignedok
              When verifying a host SSL certificate, allow it to be self-signed.

       -set toggle
              Sets the initial value of toggle to true.  The list of toggle names is under TOGGLES below.

       -socket
              Causes  the emulator to create a Unix-domain socket when it starts, for use by script processes to
              send commands to the emulator.  The socket is  named  /tmp/x3sck.process_id.   The  -p  option  of
              x3270if causes it to use this socket, instead of pipes specified by environment variables.

       -tn name
              Specifies  the  terminal  name  to be transmitted over the telnet connection.  The default name is
              IBM-model_name-E, 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, or setting the "s3270.extended"
              resource to "false", removes the -E from the terminal name when connecting to such hosts.

              The name can also be specified with the "s3270.termName" resource.

       -trace Turns  on  data  stream  and  event  tracing  at  startup.   The  default  trace  file   name   is
              /tmp/x3trc.process_id.

       -tracefile file
              Specifies  a  file  to save data stream and event traces into.  If the name starts with `>>', data
              will be appended to the file.

       -tracefilesize size
              Places a limit on the size of a trace file.  If this option is not specified, or is specified as 0
              or none, the trace file size will be unlimited.  The minimum size is 64 Kbytes.  The value of size
              can have a K or M suffix, indicating kilobytes or megabytes respectively.   When  the  trace  file
              reaches the size limit, it will be renamed with a `-' appended and a new file started.

       -user name
              Specifies the user name for RFC 4777 support.

       -utf8  Forces the local codeset to be UTF-8, ignoring the locale or Windows codepage.

       -v     Display the version and build options for s3270 and exit.

       -verifycert
              For  SSL  or  SSL/TLS connections, verify the host certificate, and do not allow the connection to
              complete unless it can be validated.

       -xrm "s3270.resource: value"
              Sets the value of the named resource to value.  Resources control less common s3270  options,  and
              are defined under RESOURCES below.

       These names are also used as the first parameter to the Toggle action.

ACTIONS

       Here  is  a  complete  list  of  basic  s3270  actions.   Script-specific  actions  are  described on the
       x3270-script(1) manual page.

       Actions marked with an asterisk (*) may block, sending data to  the  host  and  possibly  waiting  for  a
       response.

                            *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
                            *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
                            *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
                            Execute(cmd)                     execute a command in a shell
                            FieldEnd                         move cursor to end of field
                            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(keysym)                      insert key keysym
                            Key(0xxx)                        insert key with character 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 s3270
                            Redraw                           redraw window
                            Reset                            reset locked keyboard
                            Right                            move cursor right
                            Right2                           move cursor right 2 positions

                            *Script(command[,arg...])        run a script
                            *String(string)                  insert string (simple macro
                                                             facility)
                            *SysReq                          System Request AID
                            Tab                              move cursor to next input
                                                             field
                            Toggle(option[,set|clear])       toggle an option
                            ToggleInsert                     toggle insert mode
                            ToggleReverse                    toggle reverse-input mode
                            *Transfer(option=value...)       file transfer
                            Up                               move cursor up

       Note  that  certain  parameters  to s3270 actions (such as the names of files and keymaps) are subject to
       substitutions:

       The character ~ at the beginning of a string is replaced with the user's home directory.  A  ~  character
       followed by a username is replaced with that user's home directory.

       Environment variables are substituted using the Unix shell convention of $name or ${name}.

       Two  special  pseudo-environment  variables  are  supported. ${TIMESTAMP} is replaced with a microsecond-
       resolution timestamp; ${UNIQUE} is replaced with a string guaranteed  to  make  a  unique  filename  (the
       process  ID  optionally  followed by a dash and a string of digits). ${UNIQUE} is used to form trace file
       names.

FILE TRANSFER

       The Transfer action implements IND$FILE file transfer.  This action 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  action
       take  the  unique  form  of  option=value,  and can appear in any order.  Note that if the value contains
       spaces (such as a VM/CMS file name), then the entire parameter must be quoted,  e.g.,  "HostFile=xxx  foo
       a".  The options are:

       Option           Required?   Default   Other Values
       ──────────────────────────────────────────────────────────
       Direction           No       receive   send
       HostFile            Yes
       LocalFile           Yes
       Host                No       tso       vm, cics
       Mode                No       ascii     binary
       Cr                  No       remove    add, keep
       Remap               No       yes       no
       Exist               No       keep      replace, append
       Recfm               No                 fixed, variable,
                                              undefined
       Lrecl               No
       Blksize             No
       Allocation          No                 tracks, cylinders,
                                              avblock
       PrimarySpace        No
       SecondarySpace      No
       BufferSize          No       4096

       The option details are as follows.

       Direction
              send 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), vm or cics.

       Mode   Use  ascii  (the  default)  for  a text file, which will be translated between EBCDIC and ASCII as
              necessary.  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.

       Remap  Controls text translation for Mode=ascii files.  The value yes (the default) causes s3270 to remap
              the text to ensure maximum compatibility between the workstation's character set and encoding  and
              the  host's  EBCDIC code page.  The value no causes s3270 to pass the text to or from the host as-
              is, leaving all translation to the IND$FILE program on the host.

       Exist  Controls what happens when the destination file already exists.  keep (the default) preserves  the
              file,  causing  the  Transfer  action  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.  (TSO and VM hosts only.)  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.  (TSO and VM
              hosts only.)

       Blksize
              Specifies the block size for files created on the host.  (TSO and VM hosts only.)

       Allocation
              Specifies the units for the PrimarySpace and SecondarySpace options: tracks, cylinders or avblock.
              (TSO hosts only.)

       PrimarySpace
              Primary allocation for a file, The units are given by the Allocation option. (TSO hosts only.)

       SecondarySpace
              Secondary allocation for a file.  The units are given by the Allocation option. (TSO hosts only.)

       BufferSize
              Buffer size for DFT-mode transfers.  Can range from 256  to  32768.   Larger  values  give  better
              performance, but some hosts may not be able to support them.

THE PRINTTEXT ACTION

       The  PrintText  produces  screen  snapshots  in  a  number  of  different forms.  The default form wth no
       arguments sends a copy of the screen to the default printer.  A single argument is the command to use  to
       print, e.g., lpr.  Multiple arguments can include keywords to control the output of PrintText:

       file filename
              Save the output in a file.

       html   Save the output as HTML.  This option implies file.

       rtf    Save  the output as RichText.  This option implies file.  The font defaults to Courier New and the
              point size defaults to 8.   These  can  be  overridden  by  the  printTextFont  and  printTextSize
              resources, respectively.

       string Return the output as a string.  This can only be used from scripts.

       modi   Render modified fields in italics.

       caption text
              Add  the specified text as a caption above the output.  Within text, the special sequence %T% will
              be replaced with a timestamp.

       command command
              Directs the output to a command.  This allows one or more of the other keywords to  be  specified,
              while still sending the output to the printer.

NESTED SCRIPTS

       There are several types of nested script functions available.

       The String Action
              The simplest method for nested scripts is provided via the String action.  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, s3270 will wait for the host to unlock the keyboard before further processing the string.)

              \b       Left
              \exxxx   EBCDIC character in hex
              \f       Clear*
              \n       Enter*
              \pan     PA(n)*
              \pfnn    PF(nn)*
              \r       Newline
              \t       Tab
              \T       BackTab
              \uxxxx   Unicode character in hex
              \xxxxx   Unicode character in hex

              Note that the numeric values for the \e, \u and \x sequences can be abbreviated to 2 digits.  Note
              also  that  EBCDIC  codes  greater  than  255  and  some  Unicode  character  codes represent DBCS
              characters, which will work only if s3270 is built with DBCS support  and  the  host  allows  DBCS
              input in the current field.

              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 action, 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 characters,
              which are entered into the current field.  In NVT  mode,  the  hexadecimal  data  represent  ASCII
              characters, which are sent directly to the host.

       The Script Action
              This action causes s3270 to start a child process which can execute s3270 actions.  Standard input
              and output from the child process are piped back to s3270.  The Script action is fully  documented
              in x3270-script(1).

PASSTHRU

       s3270 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,  s3270  acts  much
       like  the  itelnet(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.

PROXY

       The  -proxy option or the s3270.proxy resource causes s3270 to use a proxy server to connect to the host.
       The syntax of the option or resource is:
              type:host[:port]

       The supported values for type are:

                               Proxy Type   Protocol                       Default Port
                               ─────────────────────────────────────────────────────────
                                  http      RFC 2817 HTTP tunnel (squid)       3128
                                passthru    Sun in.telnet-gw                   none
                                 socks4     SOCKS version 4                    1080
                                 socks5     SOCKS version 5 (RFC 1928)         1080
                                 telnet     No protocol (just send             none
                                            connect host port)

       The  special  types  socks4a  and  socks5d  can also be used to force the proxy server to do the hostname
       resolution for the SOCKS protocol.

RESOURCES

       Certain s3270 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 s3270
       are:

       Resource      Default    Option           Purpose
       ─────────────────────────────────────────────────────────────────
       blankFill     False      -set blankFill   Blank Fill mode
       charset       bracket    -charset         EBCDIC character set
       dbcsCgcsgid                               Override DBCS CGCSGID
       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
       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)   -model           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
       sbcsCgcsgid                               Override SBCS CGCSGID
       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 to True with the proper -model option.

              Note 2: The default terminal type string is constructed 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 3278, but this does not affect color capabilities.

              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.

FILES

       /usr/local/lib/x3270/ibm_hosts

SEE ALSO

       x3270-script(1), x3270(1), c3270(1), tcl3270(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 Selection
       RFC 2355, TN3270 Enhancements

COPYRIGHTS

       Copyright 1993-2014, Paul Mattes.
       Copyright 2004-2005, Don Russell.
       Copyright 2004, Dick Altenbern.
       Copyright 1990, Jeff Sparkes.
       Copyright 1989, Georgia Tech Research Corporation (GTRC), Atlanta, GA
        30332.
       All rights reserved.

       Redistribution  and  use in source and binary forms, with or without modification, are permitted provided
       that the following conditions are met:

       *      Redistributions of source code must retain the above copyright notice, this list of conditions and
              the following disclaimer.

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

       *      Neither the names of Paul Mattes, Don Russell, Dick Altenbern, Jeff Sparkes, GTRC nor the names of
              their contributors may be used to endorse or promote products derived from this  software  without
              specific prior written permission.

       THIS  SOFTWARE IS PROVIDED BY PAUL MATTES, DON RUSSELL, DICK ALTENBERN, JEFF SPARKES AND GTRC "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 PAUL MATTES, DON
       RUSSELL, DICK ALTENBERN, JEFF SPARKES OR GTRC 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.

VERSION

       s3270 3.3.14ga11

                                                   03 May 2014                                          s3270(1)