1s3270(1) General Commands Manual s3270(1)
2
6 s3270 - IBM host access tool
7
9 s3270 [options] [host]
10 s3270 [options] session-file.s3270
12
15 s3270 opens a telnet connection to an IBM host, then allows a script to
16 control the host login session. It is derived from x3270(1), an X-win‐
17 dows IBM 3270 emulator. It implements RFCs 2355 (TN3270E), 1576
18 (TN3270) and 1646 (LU name selection), and supports IND$FILE file
19 transfer.
20 The full syntax for host is:
22 [prefix:]...[LUname@]hostname[:port]
23 Prepending a P: onto hostname causes the connection to go through the
25 telnet-passthru service rather than directly to the host. See PASSTHRU
26 below.
27 Prepending an S: onto hostname removes the "extended data stream"
29 option reported to the host. See -tn below for further information.
30 Prepending an N: onto hostname turns off TN3270E support for the ses‐
32 sion.
33 Prepending an L: onto hostname causes s3270 to first create an SSL tun‐
35 nel to the host, and then create a TN3270 session inside the tunnel.
36 (This function is supported only if s3270 was built with SSL/TLS sup‐
37 port). Note that TLS-encrypted sessions using the TELNET START-TLS
38 option are negotiated with the host automatically; for these sessions
39 the L: prefix should not be used.
40 A specific Logical Unit (LU) name to use may be specified by prepending
42 it to the hostname with an `@'. Multiple LU names to try can be sepa‐
43 rated by commas. An empty LU can be placed in the list with an extra
44 comma. (Note that the LU name is used for different purposes by dif‐
45 ferent kinds of hosts. For example, CICS uses the LU name as the Ter‐
46 minal ID.)
47 The hostname may optionally be placed inside square-bracket characters
49 `[' and `]'. This will prevent any colon `:' characters in the host‐
50 name from being interpreted as indicating option prefixes or port num‐
51 bers. This allows numeric IPv6 addresses to be used as hostnames.
52 On systems that support the forkpty library call, the hostname may be
54 replaced with -e and a command string. This will cause s3270 to con‐
55 nect to a local child process, such as a shell.
56 The port to connect to defaults to telnet. This can be overridden with
58 the -port option, or by appending a port to the hostname with a colon
59 `:'. (For compatability with previous versions of s3270 and with
60 tn3270(1), the port may also be specified as a second, separate argu‐
61 ment.)
62
65 s3270 understands the following options:
66 -cadir directory
68 Specifies a directory containing CA (root) certificates to use
69 when verifying a certificate provided by the host.
70 -cafile filename
72 Specifies a PEM-format file containing CA (root) certificates to
73 use when verifying a certificate provided by the host.
74 -certfile filename
76 Specifies a file containing a certificate to provide to the
77 host, if requested. The default file type is PEM.
78 -certfiletype type
80 Specifies the type of the certificate file specified by -cert‐
81 file. Type can be pem or asn1.
82 -chainfile filename
84 Specifies a certificate chain file in PEM format, containing a
85 certificate to provide to the host if requested, as well as one
86 or more intermediate certificates and the CA certificate used to
87 sign that certificate. If -chainfile is specified, it overrides
88 -certfile.
89 -charset name
91 Specifies an EBCDIC host character set.
92 -clear toggle
94 Sets the initial value of toggle to false. The list of toggle
95 names is under TOGGLES below.
96 -devname name
98 Specifies a device name (workstation ID) for RFC 4777 support.
99 -im method
101 Specifies the name of the input method to use for multi-byte
102 input. (Supported only when s3270 is compiled with DBCS sup‐
103 port.)
104 -keyfile filename
106 Specifies a file containing the private key for the certificate
107 file (specified via -certfile or -chainfile). The default file
108 type is PEM.
109 -keyfiletype type
111 Specifies the type of the private key file specified by -key‐
112 file. Type can be pem or asn1.
113 -keypasswd type:value
115 Specifies the password for the private key file, if it is
116 encrypted. The argument can be file:filename, specifying that
117 the password is in a file, or string:string, specifying the
118 password on the command-line directly. If the private key file
119 is encrypted and no -keypasswd option is given, secure connec‐
120 tions will not be allowed.
121 -km name
123 Specifies the local encoding method for multi-byte text. name
124 is an encoding name recognized by the ICU library. (Supported
125 only when s3270 is compiled with DBCS support, and necessary
126 only when s3270 cannot figure it out from the locale.)
127 -model name
129 The model of 3270 display to be emulated. The model name is in
130 two parts, either of which may be omitted:
131 The first part is the base model, which is either 3278 or 3279.
133 3278 specifies a monochrome (green on black) 3270 display; 3279
134 specifies a color 3270 display.
135 The second part is the model number, which specifies the number
137 of rows and columns. Model 4 is the default.
138 Model Number Columns Rows
140 ──────────────────────────────
141 2 80 24
142 3 80 32
143 4 80 43
144 5 132 27
145 Note: Technically, there is no such 3270 display as a 3279-4 or
147 3279-5, but most hosts seem to work with them anyway.
148 The default model is 3278-4.
150 -oversize colsxrows
152 Makes the screen larger than the default for the chosen model
153 number. This option has effect only in combination with
154 extended data stream support (controlled by the "s3270.extended"
155 resource), and only if the host supports the Query Reply
156 structured field. The number of columns multiplied by the
157 number of rows must not exceed 16383 (3fff hex), the limit of
158 14-bit 3270 buffer addressing.
159 -port n
161 Specifies a different TCP port to connect to. n can be a name
162 from /etc/services like telnet, or a number. This option
163 changes the default port number used for all connections. (The
164 positional parameter affects only the initial connection.)
165 -proxy type:host[:port]
167 Causes s3270 to connect via the specified proxy, instead of
168 using a direct connection. The host can be an IP address or
169 hostname. The optional port can be a number or a service name.
170 For a list of supported proxy types, see PROXY below.
171 -scriptport port
173 Causes s3270 to listen for scripting connections on local TCP
174 port port.
175 -set toggle
177 Sets the initial value of toggle to true. The list of toggle
178 names is under TOGGLES below.
179 -socket
181 Causes the emulator to create a Unix-domain socket when it
182 starts, for use by script processes to send commands to the
183 emulator. The socket is named /tmp/x3sck.process_id. The -p
184 option of x3270if causes it to use this socket, instead of pipes
185 specified by environment variables.
186 -tn name
188 Specifies the terminal name to be transmitted over the telnet
189 connection. The default name is IBM-model_name-E, for example,
190 IBM-3278-4-E.
191 Some hosts are confused by the -E suffix on the terminal name,
193 and will ignore the extra screen area on models 3, 4 and 5.
194 Prepending an s: on the hostname, or setting the
195 "s3270.extended" resource to "false", removes the -E from the
196 terminal name when connecting to such hosts.
197 The name can also be specified with the "s3270.termName"
199 resource.
200 -trace Turns on data stream and event tracing at startup. The default
202 trace file name is /tmp/x3trc.process_id.
203 -tracefile file
205 Specifies a file to save data stream and event traces into. If
206 the name starts with `>>', data will be appended to the file.
207 -tracefilesize size
209 Places a limit on the size of a trace file. If this option is
210 not specified, or is specified as 0 or none, the trace file size
211 will be unlimited. The minimum size is 64 Kbytes. The value of
212 size can have a K or M suffix, indicating kilobytes or megabytes
213 respectively. When the trace file reaches the size limit, it
214 will be renamed with a `-' appended and a new file started.
215 -user name
217 Specifies the user name for RFC 4777 support.
218 -v Display the version and build options for s3270 and exit.
220 -verifycert
222 For SSL or SSL/TLS connections, verify the host certificate, and
223 do not allow the connection to complete unless it can be
224 validated.
225 -xrm "s3270.resource: value"
227 Sets the value of the named resource to value. Resources
228 control less common s3270 options, and are defined under
229 RESOURCES below.
230 These names are also used as the first parameter to the Toggle action.
232
235 Here is a complete list of basic s3270 actions. Script-specific
236 actions are described on the x3270-script(1) manual page.
237 Actions marked with an asterisk (*) may block, sending data to the host
239 and possibly waiting for a response.
240 *Attn attention key
242 BackSpace move cursor left (or send
243 ASCII BS)
244 BackTab tab to start of previous input
245 field
246 CircumNot input "^" in NVT mode, or
247 "notsign" in 3270 mode
248 *Clear clear screen
249 *Connect(host) connect to host
250 *CursorSelect Cursor Select AID
251 Delete delete character under cursor
252 (or send ASCII DEL)
253 DeleteField delete the entire field
254 DeleteWord delete the current or previous
255 word
256 *Disconnect disconnect from host
257 Down move cursor down
258 Dup duplicate field
259 *Enter Enter AID (or send ASCII CR)
260 Erase erase previous character (or
261 send ASCII BS)
262 EraseEOF erase to end of current field
263 EraseInput erase all input fields
264 Execute(cmd) execute a command in a shell
265 FieldEnd move cursor to end of field
266 FieldMark mark field
267 HexString(hex_digits) insert control-character
269 string
270 Home move cursor to first input
271 field
272 Insert set insert mode
273 *Interrupt send TELNET IP to host
274 Key(keysym) insert key keysym
275 Key(0xxx) insert key with character code
276 xx
277 Left move cursor left
278 Left2 move cursor left 2 positions
279 MonoCase toggle uppercase-only mode
280 MoveCursor(row, col) move cursor to (row,col)
281 Newline move cursor to first field on
282 next line (or send ASCII LF)
283 NextWord move cursor to next word
284 *PA(n) Program Attention AID (n from
285 1 to 3)
286 *PF(n) Program Function AID (n from 1
287 to 24)
288 PreviousWord move cursor to previous word
289 Quit exit s3270
290 Redraw redraw window
291 Reset reset locked keyboard
292 Right move cursor right
293 Right2 move cursor right 2 positions
294 *Script(command[,arg...]) run a script
295 *String(string) insert string (simple macro
296 facility)
297 *SysReq System Request AID
298 Tab move cursor to next input
299 field
300 Toggle(option[,set|clear]) toggle an option
301 ToggleInsert toggle insert mode
302 ToggleReverse toggle reverse-input mode
303 *Transfer(option=value...) file transfer
304 Up move cursor up
305
307 The Transfer action implements IND$FILE file transfer. This action
308 requires that the IND$FILE program be installed on the IBM host, and
309 that the 3270 cursor be located in a field that will accept a TSO or
310 VM/CMS command.
311 Because of the complexity and number of options for file transfer, the
313 parameters to the Transfer action take the unique form of option=value,
314 and can appear in any order. Note that if the value contains spaces
315 (such as a VM/CMS file name), then the entire parameter must be quoted,
316 e.g., "HostFile=xxx foo a". The options are:
317 Option Required? Default Other Values
319 ────────────────────────────────────────────────────────
320 Direction No receive send
321 HostFile Yes
322 LocalFile Yes
323 Host No tso vm
324 Mode No ascii binary
325 Cr No remove add, keep
326 Remap No yes no
327 Exist No keep replace, append
328 Recfm No fixed, variable,
329 undefined
330 Lrecl No
331 Blksize No
332 Allocation No tracks,
336 cylinders,
337 avblock
338 PrimarySpace No
339 SecondarySpace No
340 BufferSize No 4096
341 The option details are as follows.
343 Direction
345 send to send a file to the host, receive to receive a file from
346 the host.
347 HostFile
349 The name of the file on the host.
350 LocalFile
352 The name of the file on the local workstation.
353 Host The type of host (which dictates the form of the IND$FILE
355 command): tso (the default) or vm.
356 Mode Use ascii (the default) for a text file, which will be
358 translated between EBCDIC and ASCII as necessary. Use binary
359 for non-text files.
360 Cr Controls how Newline characters are handled when transferring
362 Mode=ascii files. remove (the default) strips Newline
363 characters in local files before transferring them to the host.
364 add adds Newline characters to each host file record before
365 transferring it to the local workstation. keep preserves
366 Newline characters when transferring a local file to the host.
367 Remap Controls text translation for Mode=ascii files. The value yes
369 (the default) causes s3270 to remap the text to ensure maximum
370 compatibility between the workstation's character set and
371 encoding and the host's EBCDIC code page. The value no causes
372 s3270 to pass the text to or from the host as-is, leaving all
373 translation to the IND$FILE program on the host.
374 Exist Controls what happens when the destination file already exists.
376 keep (the default) preserves the file, causing the Transfer
377 action to fail. replace overwrites the destination file with
378 the source file. append appends the source file to the
379 destination file.
380 Recfm Controls the record format of files created on the host. fixed
382 creates a file with fixed-length records. variable creates a
383 file with variable-length records. undefined creates a file
384 with undefined-length records (TSO hosts only). The Lrecl
385 option controls the record length or maximum record length for
386 Recfm=fixed and Recfm=variable files, respectively.
387 Lrecl Specifies the record length (or maximum record length) for files
389 created on the host.
390 Blksize
392 Specifies the block size for files created on the host. (TSO
393 hosts only.)
394 Allocation
396 Specifies the units for the TSO host PrimarySpace and
397 SecondarySpace options: tracks, cylinders or avblock.
398 PrimarySpace
400 Primary allocation for a file created on a TSO host. The units
401 are given by the Allocation option.
402 SecondarySpace
404 Secondary allocation for a file created on a TSO host. The
405 units are given by the Allocation option.
406 BufferSize
408 Buffer size for DFT-mode transfers. Can range from 256 to
409 32768. Larger values give better performance, but some hosts
410 may not be able to support them.
411
414 The PrintText produces screen snapshots in a number of different forms.
415 The default form wth no arguments sends a copy of the screen to the
416 default printer. A single argument is the command to use to print,
417 e.g., lpr. Multiple arguments can include keywords to control the
418 output of PrintText:
419 file filename
421 Save the output in a file.
422 html Save the output as HTML. This option implies file.
424 rtf Save the output as RichText. This option implies file. The
426 font defaults to Courier New and the point size defaults to 8.
427 These can be overridden by the printTextFont and printTextSize
428 resources, respectively.
429 string Return the output as a string. This can only be used from
431 scripts.
432 modi Render modified fields in italics.
434 caption text
436 Add the specified text as a caption above the output. Within
437 text, the special sequence %T% will be replaced with a
438 timestamp.
439 command command
441 Directs the output to a command. This allows one or more of the
442 other keywords to be specified, while still sending the output
443 to the printer.
444
447 There are several types of nested script functions available.
448 The String Action
450 The simplest method for nested scripts is provided via the
451 String action. The arguments to String are one or more double-
452 quoted strings which are inserted directly as if typed. The C
453 backslash conventions are honored as follows. (Entries marked *
454 mean that after sending the AID code to the host, s3270 will
455 wait for the host to unlock the keyboard before further
456 processing the string.)
457 \b Left
459 \exxxx EBCDIC character in hex
460 \f Clear*
461 \n Enter*
462 \pan PA(n)*
463 \pfnn PF(nn)*
464 \r Newline
465 \t Tab
466 \T BackTab
467 \uxxxx Unicode character in hex
468 \xxxxx Unicode character in hex
470 Note that the numeric values for the \e, \u and \x sequences can
472 be abbreviated to 2 digits. Note also that EBCDIC codes greater
473 than 255 and some Unicode character codes represent DBCS
474 characters, which will work only if s3270 is built with DBCS
475 support and the host allows DBCS input in the current field.
476 Note: The strings are in ASCII and converted to EBCDIC, so
478 beware of inserting control codes.
479 There is also an alternate form of the String action, HexString,
481 which is used to enter non-printing data. The argument to
482 HexString is a string of hexadecimal digits, two per character.
483 A leading 0x or 0X is optional. In 3270 mode, the hexadecimal
484 data represent EBCDIC characters, which are entered into the
485 current field. In NVT mode, the hexadecimal data represent
486 ASCII characters, which are sent directly to the host.
487 The Script Action
489 This action causes s3270 to start a child process which can
490 execute s3270 actions. Standard input and output from the child
491 process are piped back to s3270. The Script action is fully
492 documented in x3270-script(1).
493
496 s3270 supports the Sun telnet-passthru service provided by the
497 in.telnet-gw server. This allows outbound telnet connections through a
498 firewall machine. When a p: is prepended to a hostname, s3270 acts
499 much like the itelnet(1) command. It contacts the machine named
500 internet-gateway at the port defined in /etc/services as telnet-
501 passthru (which defaults to 3514). It then passes the requested
502 hostname and port to the in.telnet-gw server.
503
505 The -proxy option or the s3270.proxy resource causes s3270 to use a
506 proxy server to connect to the host. The syntax of the option or
507 resource is:
508 type:host[:port]
509 The supported values for type are:
511 Proxy Type Protocol Default Port
513 ──────────────────────────────────────────────
514 http RFC 2817 HTTP 3128
515 tunnel (squid)
516 passthru Sun in.telnet-gw none
517 socks4 SOCKS version 4 1080
518 socks5 SOCKS version 5 1080
519 (RFC 1928)
520 telnet No protocol (just none
521 send connect host
522 port)
523 The special types socks4a and socks5d can also be used to force the
525 proxy server to do the hostname resolution for the SOCKS protocol.
526
528 Certain s3270 options can be configured via resources. Resources are
529 defined by -xrm options. The definitions are similar to X11 resources,
530 and use a similar syntax. The resources available in s3270 are:
531 Resource Default Option Purpose
533 ───────────────────────────────────────────────────────────
534 blankFill False -set blankFill Blank Fill mode
535 charset bracket -charset EBCDIC character
537 set
538 dbcsCgcsgid Override DBCS
539 CGCSGID
540 dsTrace False -trace Data stream
541 tracing
542 eof ^D NVT-mode EOF
543 character
544 erase ^H NVT-mode erase
545 character
546 extended True Use 3270
547 extended data
548 stream
549 eventTrace False -trace Event tracing
550 icrnl False Map CR to NL on
551 NVT-mode input
552 inlcr False Map NL to CR in
553 NVT-mode input
554 intr ^C NVT-mode
555 interrupt
556 character
557 kill ^U NVT-mode kill
558 character
559 lineWrap False -set lineWrap NVT line wrap
560 mode
561 lnext ^V NVT-mode lnext
562 character
563 m3279 (note 1) -model 3279 (color)
564 emulation
565 monoCase False -set monoCase Mono-case mode
566 numericLock False Lock keyboard
567 for numeric
568 field error
569 oerrLock False Lock keyboard
570 for input error
571 oversize -oversize Oversize screen
572 dimensions
573 port telnet -port Non-default TCP
574 port
575 quit ^\ NVT-mode quit
576 character
577 rprnt ^R NVT-mode reprint
578 character
579 sbcsCgcsgid Override SBCS
580 CGCSGID
581 secure False Disable
582 "dangerous"
583 options
584 termName (note 2) -tn TELNET terminal
585 type string
586 traceDir /tmp Directory for
587 trace files
588 traceFile (note 3) -tracefile File for trace
589 output
590 werase ^W NVT-mode word-
591 erase character
592 Note 1: m3279 defaults to False. It can be forced to True with
594 the proper -model option.
595 Note 2: The default terminal type string is constructed from the
597 model number, color emulation, and extended data stream modes.
598 E.g., a model 2 with color emulation and the extended data
599 stream option would be sent as IBM-3279-2-E. Note also that
600 when TN3270E mode is used, the terminal type is always sent as
601 3278, but this does not affect color capabilities.
602 Note 3: The default trace file is x3trc.pid in the directory
604 specified by the traceDir resource.
605 If more than one -xrm option is given for the same resource, the last
611 one on the command line is used.
612
614 /etc/ibm_hosts
615
618 x3270(1), c3270(1), tcl3270(1), ibm_hosts(5), x3270-script(1),
619 telnet(1), tn3270(1)
620 Data Stream Programmer's Reference, IBM GA23-0059
621 Character Set Reference, IBM GA27-3831
622 RFC 1576, TN3270 Current Practices
623 RFC 1646, TN3270 Extensions for LUname and Printer Selection
624 RFC 2355, TN3270 Enhancements
625
627 Copyright 1993-2013, Paul Mattes.
628 Copyright 2004-2005, Don Russell.
629 Copyright 2004, Dick Altenbern.
630 Copyright 1990, Jeff Sparkes.
631 Copyright 1989, Georgia Tech Research Corporation (GTRC), Atlanta, GA
632 30332.
633 All rights reserved.
634 Redistribution and use in source and binary forms, with or without
636 modification, are permitted provided that the following conditions are
637 met:
638 * Redistributions of source code must retain the above copyright
641 notice, this list of conditions and the following disclaimer.
642 * Redistributions in binary form must reproduce the above
644 copyright notice, this list of conditions and the following
645 disclaimer in the documentation and/or other materials provided
646 with the distribution.
647 * Neither the names of Paul Mattes, Don Russell, Dick Altenbern,
649 Jeff Sparkes, GTRC nor the names of their contributors may be
650 used to endorse or promote products derived from this software
651 without specific prior written permission.
652 THIS SOFTWARE IS PROVIDED BY PAUL MATTES, DON RUSSELL, DICK ALTENBERN,
655 JEFF SPARKES AND GTRC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
656 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
657 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
658 NO EVENT SHALL PAUL MATTES, DON RUSSELL, DICK ALTENBERN, JEFF SPARKES
659 OR GTRC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL
660 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
661 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
662 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
663 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
664 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
665 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
666
668 s3270 3.3.12ga12
669 26 February 2013 s3270(1)