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 -charset name
68 Specifies an EBCDIC host character set.
69 -clear toggle
71 Sets the initial value of toggle to false. The list of toggle
72 names is under TOGGLES below.
73 -im method
75 Specifies the name of the input method to use for multi-byte
76 input. (Supported only when s3270 is compiled with DBCS sup‐
77 port.)
78 -km name
80 Specifies the local encoding method for multi-byte text. name
81 is an encoding name recognized by the ICU library. (Supported
82 only when s3270 is compiled with DBCS support, and necessary
83 only when s3270 cannot figure it out from the locale.)
84 -model name
86 The model of 3270 display to be emulated. The model name is in
87 two parts, either of which may be omitted:
88 The first part is the base model, which is either 3278 or 3279.
90 3278 specifies a monochrome (green on black) 3270 display; 3279
91 specifies a color 3270 display.
92 The second part is the model number, which specifies the number
94 of rows and columns. Model 4 is the default.
95 Model Number Columns Rows
97 ──────────────────────────────
98 2 80 24
99 3 80 32
100 4 80 43
101 5 132 27
102 Note: Technically, there is no such 3270 display as a 3279-4 or
104 3279-5, but most hosts seem to work with them anyway.
105 The default model is 3278-4.
107 -oversize colsxrows
109 Makes the screen larger than the default for the chosen model
110 number. This option has effect only in combination with
111 extended data stream support (controlled by the "s3270.extended"
112 resource), and only if the host supports the Query Reply
113 structured field. The number of columns multiplied by the
114 number of rows must not exceed 16383 (3fff hex), the limit of
115 14-bit 3270 buffer addressing.
116 -port n
118 Specifies a different TCP port to connect to. n can be a name
119 from /etc/services like telnet, or a number. This option
120 changes the default port number used for all connections. (The
121 positional parameter affects only the initial connection.)
122 -proxy type:host[:port]
124 Causes s3270 to connect via the specified proxy, instead of
125 using a direct connection. The host can be an IP address or
126 hostname. The optional port can be a number or a service name.
127 For a list of supported proxy types, see PROXY below.
128 -scriptport port
130 Causes s3270 to listen for scripting connections on local TCP
131 port port.
132 -set toggle
134 Sets the initial value of toggle to true. The list of toggle
135 names is under TOGGLES below.
136 -socket
138 Causes the emulator to create a Unix-domain socket when it
139 starts, for use by script processes to send commands to the
140 emulator. The socket is named /tmp/x3sck.process_id. The -p
141 option of x3270if causes it to use this socket, instead of pipes
142 specified by environment variables.
143 -tn name
145 Specifies the terminal name to be transmitted over the telnet
146 connection. The default name is IBM-model_name-E, for example,
147 IBM-3278-4-E.
148 Some hosts are confused by the -E suffix on the terminal name,
150 and will ignore the extra screen area on models 3, 4 and 5.
151 Prepending an s: on the hostname, or setting the
152 "s3270.extended" resource to "false", removes the -E from the
153 terminal name when connecting to such hosts.
154 The name can also be specified with the "s3270.termName"
156 resource.
157 -trace Turns on data stream and event tracing at startup. The default
159 trace file name is /tmp/x3trc.process_id.
160 -tracefile file
162 Specifies a file to save data stream and event traces into.
163 -tracefilesize size
165 Places a limit on the size of a trace file. If this option is
166 not specified, or is specified as 0 or none, the trace file will
167 be unlimited. If specified, the trace file cannot already
168 exist, and the (silently enforced) minimum size is 64 Kbytes.
169 The value of size can have a K or M suffix, indicating kilobytes
170 or megabytes respectively.
171 -v Display the version and build options for s3270 and exit.
173 -xrm "s3270.resource: value"
175 Sets the value of the named resource to value. Resources
176 control less common s3270 options, and are defined under
177 RESOURCES below.
178 These names are also used as the first parameter to the Toggle action.
180
183 Here is a complete list of basic s3270 actions. Script-specific
184 actions are described on the x3270-script(1) manual page.
185 Actions marked with an asterisk (*) may block, sending data to the host
187 and possibly waiting for a response.
188 *Attn attention key
190 BackSpace move cursor left (or send
191 ASCII BS)
192 BackTab tab to start of previous input
193 field
194 CircumNot input "^" in NVT mode, or
195 "notsign" in 3270 mode
196 *Clear clear screen
197 *Connect(host) connect to host
198 *CursorSelect Cursor Select AID
200 Delete delete character under cursor
201 (or send ASCII DEL)
202 DeleteField delete the entire field
203 DeleteWord delete the current or previous
204 word
205 *Disconnect disconnect from host
206 Down move cursor down
207 Dup duplicate field
208 *Enter Enter AID (or send ASCII CR)
209 Erase erase previous character (or
210 send ASCII BS)
211 EraseEOF erase to end of current field
212 EraseInput erase all input fields
213 Execute(cmd) execute a command in a shell
214 FieldEnd move cursor to end of field
215 FieldMark mark field
216 HexString(hex_digits) insert control-character
217 string
218 Home move cursor to first input
219 field
220 Insert set insert mode
221 *Interrupt send TELNET IP to host
222 Key(keysym) insert key keysym
223 Key(0xxx) insert key with character code
224 xx
225 Left move cursor left
226 Left2 move cursor left 2 positions
227 MonoCase toggle uppercase-only mode
228 MoveCursor(row, col) move cursor to (row,col)
229 Newline move cursor to first field on
230 next line (or send ASCII LF)
231 NextWord move cursor to next word
232 *PA(n) Program Attention AID (n from
233 1 to 3)
234 *PF(n) Program Function AID (n from 1
235 to 24)
236 PreviousWord move cursor to previous word
237 Quit exit s3270
238 Redraw redraw window
239 Reset reset locked keyboard
240 Right move cursor right
241 Right2 move cursor right 2 positions
242 *Script(command[,arg...]) run a script
243 *String(string) insert string (simple macro
244 facility)
245 *SysReq System Request AID
246 Tab move cursor to next input
247 field
248 Toggle(option[,set|clear]) toggle an option
249 ToggleInsert toggle insert mode
250 ToggleReverse toggle reverse-input mode
251 *Transfer(option=value...) file transfer
252 Up move cursor up
253
255 The Transfer action implements IND$FILE file transfer. This action
256 requires that the IND$FILE program be installed on the IBM host, and
257 that the 3270 cursor be located in a field that will accept a TSO or
258 VM/CMS command.
259 Because of the complexity and number of options for file transfer, the
261 parameters to the Transfer action take the unique form of option=value,
262 and can appear in any order. Note that if the value contains spaces
263 (such as a VM/CMS file name), then the entire parameter must be quoted,
264 e.g., "HostFile=xxx foo a". The options are:
265 Option Required? Default Other Values
267 ────────────────────────────────────────────────────────
268 Direction No receive send
269 HostFile Yes
270 LocalFile Yes
271 Host No tso vm
272 Mode No ascii binary
273 Cr No remove add, keep
274 Remap No yes no
275 Exist No keep replace, append
276 Recfm No fixed, variable,
277 undefined
278 Lrecl No
279 Blksize No
280 Allocation No tracks,
281 cylinders,
282 avblock
283 PrimarySpace No
284 SecondarySpace No
285 BufferSize No 4096
286 The option details are as follows.
288 Direction
290 send to send a file to the host, receive to receive a file from
291 the host.
292 HostFile
294 The name of the file on the host.
295 LocalFile
297 The name of the file on the local workstation.
298 Host The type of host (which dictates the form of the IND$FILE
300 command): tso (the default) or vm.
301 Mode Use ascii (the default) for a text file, which will be
303 translated between EBCDIC and ASCII as necessary. Use binary
304 for non-text files.
305 Cr Controls how Newline characters are handled when transferring
307 Mode=ascii files. remove (the default) strips Newline
308 characters in local files before transferring them to the host.
309 add adds Newline characters to each host file record before
310 transferring it to the local workstation. keep preserves
311 Newline characters when transferring a local file to the host.
312 Remap Controls text translation for Mode=ascii files. The value yes
314 (the default) causes s3270 to remap the text to ensure maximum
315 compatibility between the workstation's character set and
316 encoding and the host's EBCDIC code page. The value no causes
317 s3270 to pass the text to or from the host as-is, leaving all
318 translation to the IND$FILE program on the host.
319 Exist Controls what happens when the destination file already exists.
321 keep (the default) preserves the file, causing the Transfer
322 action to fail. replace overwrites the destination file with
323 the source file. append appends the source file to the
324 destination file.
325 Recfm Controls the record format of files created on the host. fixed
327 creates a file with fixed-length records. variable creates a
328 file with variable-length records. undefined creates a file
329 with undefined-length records (TSO hosts only). The Lrecl
330 option controls the record length or maximum record length for
331 Recfm=fixed and Recfm=variable files, respectively.
332 Lrecl Specifies the record length (or maximum record length) for files
334 created on the host.
335 Blksize
337 Specifies the block size for files created on the host. (TSO
338 hosts only.)
339 Allocation
341 Specifies the units for the TSO host PrimarySpace and
342 SecondarySpace options: tracks, cylinders or avblock.
343 PrimarySpace
345 Primary allocation for a file created on a TSO host. The units
346 are given by the Allocation option.
347 SecondarySpace
349 Secondary allocation for a file created on a TSO host. The
350 units are given by the Allocation option.
351 BufferSize
353 Buffer size for DFT-mode transfers. Can range from 256 to
354 32768. Larger values give better performance, but some hosts
355 may not be able to support them.
356
359 The PrintText produces screen snapshots in a number of different forms.
360 The default form wth no arguments sends a copy of the screen to the
361 default printer. A single argument is the command to use to print,
362 e.g., lpr. Multiple arguments can include keywords to control the
363 output of PrintText:
364 file filename
366 Save the output in a file.
367 html Save the output as HTML. This option implies file.
369 rtf Save the output as RichText. This option implies file. The
371 font defaults to Courier New and the point size defaults to 8.
372 These can be overridden by the printTextFont and printTextSize
373 resources, respectively.
374 string Return the output as a string. This can only be used from
376 scripts.
377 modi Render modified fields in italics.
379 caption text
381 Add the specified text as a caption above the output. Within
382 text, the special sequence %T% will be replaced with a
383 timestamp.
384 command command
386 Directs the output to a command. This allows one or more of the
387 other keywords to be specified, while still sending the output
388 to the printer.
389
392 There are several types of nested script functions available.
393 The String Action
395 The simplest method for nested scripts is provided via the
396 String action. The arguments to String are one or more double-
397 quoted strings which are inserted directly as if typed. The C
398 backslash conventions are honored as follows. (Entries marked *
399 mean that after sending the AID code to the host, s3270 will
400 wait for the host to unlock the keyboard before further
401 processing the string.)
402 \b Left
404 \exxxx EBCDIC character in hex
405 \f Clear*
406 \n Enter*
407 \pan PA(n)*
408 \pfnn PF(nn)*
409 \r Newline
410 \t Tab
411 \T BackTab
412 \uxxxx Unicode character in hex
413 \xxxxx Unicode character in hex
414 Note that the numeric values for the \e, \u and \x sequences can
416 be abbreviated to 2 digits. Note also that EBCDIC codes greater
417 than 255 and some Unicode character codes represent DBCS
418 characters, which will work only if s3270 is built with DBCS
419 support and the host allows DBCS input in the current field.
420 Note: The strings are in ASCII and converted to EBCDIC, so
422 beware of inserting control codes.
423 There is also an alternate form of the String action, HexString,
425 which is used to enter non-printing data. The argument to
426 HexString is a string of hexadecimal digits, two per character.
427 A leading 0x or 0X is optional. In 3270 mode, the hexadecimal
428 data represent EBCDIC characters, which are entered into the
429 current field. In NVT mode, the hexadecimal data represent
430 ASCII characters, which are sent directly to the host.
431 The Script Action
433 This action causes s3270 to start a child process which can
434 execute s3270 actions. Standard input and output from the child
435 process are piped back to s3270. The Script action is fully
436 documented in x3270-script(1).
437
440 s3270 supports the Sun telnet-passthru service provided by the
441 in.telnet-gw server. This allows outbound telnet connections through a
442 firewall machine. When a p: is prepended to a hostname, s3270 acts
443 much like the itelnet(1) command. It contacts the machine named
444 internet-gateway at the port defined in /etc/services as telnet-
445 passthru (which defaults to 3514). It then passes the requested
446 hostname and port to the in.telnet-gw server.
447
449 The -proxy option or the s3270.proxy resource causes s3270 to use a
450 proxy server to connect to the host. The syntax of the option or
451 resource is:
452 type:host[:port]
453 The supported values for type are:
455 Proxy Type Protocol Default Port
457 ──────────────────────────────────────────────
458 http RFC 2817 HTTP 3128
459 tunnel (squid)
460 passthru Sun in.telnet-gw none
461 socks4 SOCKS version 4 1080
462 socks5 SOCKS version 5 1080
464 (RFC 1928)
465 telnet No protocol (just none
466 send connect host
467 port)
468 The special types socks4a and socks5d can also be used to force the
470 proxy server to do the hostname resolution for the SOCKS protocol.
471
473 Certain s3270 options can be configured via resources. Resources are
474 defined by -xrm options. The definitions are similar to X11 resources,
475 and use a similar syntax. The resources available in s3270 are:
476 Resource Default Option Purpose
478 ───────────────────────────────────────────────────────────
479 blankFill False -set blankFill Blank Fill mode
480 charset bracket -charset EBCDIC character
481 set
482 dbcsCgcsgid Override DBCS
483 CGCSGID
484 dsTrace False -trace Data stream
485 tracing
486 eof ^D NVT-mode EOF
487 character
488 erase ^H NVT-mode erase
489 character
490 extended True Use 3270
491 extended data
492 stream
493 eventTrace False -trace Event tracing
494 icrnl False Map CR to NL on
495 NVT-mode input
496 inlcr False Map NL to CR in
497 NVT-mode input
498 intr ^C NVT-mode
499 interrupt
500 character
501 kill ^U NVT-mode kill
502 character
503 lineWrap False -set lineWrap NVT line wrap
504 mode
505 lnext ^V NVT-mode lnext
506 character
507 m3279 (note 1) -model 3279 (color)
508 emulation
509 monoCase False -set monoCase Mono-case mode
510 numericLock False Lock keyboard
511 for numeric
512 field error
513 oerrLock False Lock keyboard
514 for input error
515 oversize -oversize Oversize screen
516 dimensions
517 port telnet -port Non-default TCP
518 port
519 quit ^\ NVT-mode quit
520 character
521 rprnt ^R NVT-mode reprint
522 character
523 sbcsCgcsgid Override SBCS
524 CGCSGID
525 secure False Disable
526 "dangerous"
527 options
528 termName (note 2) -tn TELNET terminal
530 type string
531 traceDir /tmp Directory for
532 trace files
533 traceFile (note 3) -tracefile File for trace
534 output
535 werase ^W NVT-mode word-
536 erase character
537 Note 1: m3279 defaults to False. It can be forced to True with
539 the proper -model option.
540 Note 2: The default terminal type string is constructed from the
542 model number, color emulation, and extended data stream modes.
543 E.g., a model 2 with color emulation and the extended data
544 stream option would be sent as IBM-3279-2-E. Note also that
545 when TN3270E mode is used, the terminal type is always sent as
546 3278, but this does not affect color capabilities.
547 Note 3: The default trace file is x3trc.pid in the directory
549 specified by the traceDir resource.
550 If more than one -xrm option is given for the same resource, the
556 last one on the command line is used.
557
559 /etc/ibm_hosts
560
563 x3270(1), c3270(1), tcl3270(1), ibm_hosts(5), x3270-script(1),
564 telnet(1), tn3270(1)
565 Data Stream Programmer's Reference, IBM GA23-0059
566 Character Set Reference, IBM GA27-3831
567 RFC 1576, TN3270 Current Practices
568 RFC 1646, TN3270 Extensions for LUname and Printer Selection
569 RFC 2355, TN3270 Enhancements
570
572 Copyright 1993-2009, Paul Mattes.
573 Copyright 2004-2005, Don Russell.
574 Copyright 2004, Dick Altenbern.
575 Copyright 1990, Jeff Sparkes.
576 Copyright 1989, Georgia Tech Research Corporation (GTRC), Atlanta, GA
577 30332.
578 All rights reserved.
579 Redistribution and use in source and binary forms, with or without
581 modification, are permitted provided that the following conditions are
582 met:
583 * Redistributions of source code must retain the above copyright
586 notice, this list of conditions and the following disclaimer.
587 * Redistributions in binary form must reproduce the above
589 copyright notice, this list of conditions and the following
590 disclaimer in the documentation and/or other materials provided
591 with the distribution.
592 * Neither the names of Paul Mattes, Don Russell, Dick Altenbern,
594 Jeff Sparkes, GTRC nor the names of their contributors may be
595 used to endorse or promote products derived from this software
596 without specific prior written permission.
597 THIS SOFTWARE IS PROVIDED BY PAUL MATTES, DON RUSSELL, DICK ALTENBERN,
600 JEFF SPARKES AND GTRC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
601 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
602 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
603 NO EVENT SHALL PAUL MATTES, DON RUSSELL, DICK ALTENBERN, JEFF SPARKES
604 OR GTRC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL
605 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
606 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
607 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
608 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
609 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
610 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
611
613 s3270 3.3.10ga4
614 02 October 2009 s3270(1)