s3270 - scripted IBM host access tool

SYNOPSIS

s3270 [options] [host]

DESCRIPTION

s3270 opens a telnet connection to an IBM host, then allows a script to run the host login session. It is derived from x3270, an X-windows IBM 3270 terminal 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 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

s3270 understands the following options:
-apl
Sets up APL mode. Also see APL SUPPORT.
-charset name
Specifies an EBCDIC national character set. See CHARACTER SETS.
-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 specifies 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 specified); 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 number 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 on the hostname removes the -E from the terminal name when connecting to such hosts.

CHARACTER SETS

The -charset option controls the EBCDIC national character set used by s3270. 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 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. s3270 will emulate an ANSI X.64 terminal until the host places it in 3270 mode (telnet BINARY and SEND EOR modes). This allows s3270 to be used to script standard TELNET sessions as well.

If the host later negotiates to stop functioning in 3270 mode, s3270 will return to ANSI emulation.

When emulating an ANSI terminal, s3270 supports both character-at-a-time mode and line mode operation. When in line mode, the special characters and operational characteristics 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

s3270 has a number of configurable modes which may be selected by the -set and -clear options.
monoCase
If set, s3270 operates in uppercase-only mode.
blankFill
If set, s3270 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.

ACTIONS

s3270 supports the following basic actions:
    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 ¬ in 3270 mode
    Clear                  clear screen
    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
    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
    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
    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 s3270
    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
    ToggleInsert           toggle insert mode
    Transfer(option=value,...)  file transfer
    Up                     move cursor up

SCRIPTS

There are several types of nested scripting functions available.
The String() Action
The simplest method for macros 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
    \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 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 ANSI mode, the hexadecimal data represent ASCII characters, which are sent directly to the host.

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

APL SUPPORT

s3270 supports the full APL2 character set and the entry of APL characters with the Key() action.

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

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.

SEE ALSO

telnet(1)
x3270(1)
x3270-script(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

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.


s3270 version 3.2.10, last modified 5. July 2000