1c3270(1) General Commands Manual c3270(1)
2
6 c3270 - curses-based IBM host access tool
7
9 c3270 [options] [host]
10 c3270 [options] session-file.c3270
12
15 c3270 opens a telnet connection to an IBM host in a console window. It
16 implements RFCs 2355 (TN3270E), 1576 (TN3270) and 1646 (LU name selec‐
17 tion), and supports IND$FILE file transfer. If the console is capable
18 of displaying colors, then c3270 emulates an IBM 3279. Otherwise, it
19 emulates a 3278. The full syntax for host is:
20 [prefix:]...[LUname@]hostname[:port][=accept]
21 Prepending a P: onto hostname causes the connection to go through the
23 telnet-passthru service rather than directly to the host. See PASSTHRU
24 below.
25 Prepending an S: onto hostname removes the "extended data stream"
27 option reported to the host. See -tn below for further information.
28 Prepending an N: onto hostname turns off TN3270E support for the ses‐
30 sion.
31 Prepending an L: onto hostname causes c3270 to first create an SSL/TLS
33 tunnel to the host, and then create a TN3270 session inside the tunnel.
34 (This function is supported only if c3270 was built with SSL/TLS sup‐
35 port). Note that TLS-encrypted sessions using the TELNET START-TLS
36 option are negotiated with the host automatically; for these sessions
37 the L: prefix should not be used.
38 Prepending a Y: onto hostname causes c3270 to skip validation of host
40 SSL/TLS certificates. This overrides any other configuration or com‐
41 mand-line options.
42 Prepending an A: onto hostname is equivalent to setting the -nvt
44 option; it forces an NVT-mode session instead of a 3270-mode session.
45 A specific Logical Unit (LU) name to use may be specified by prepending
47 it to the hostname with an `@'. Multiple LU names to try can be sepa‐
48 rated by commas. An empty LU can be placed in the list with an extra
49 comma. (Note that the LU name is used for different purposes by dif‐
50 ferent kinds of hosts. For example, CICS uses the LU name as the Ter‐
51 minal ID.)
52 The hostname may optionally be placed inside square-bracket characters
54 `[' and `]'. This will prevent any colon `:' characters in the host‐
55 name from being interpreted as indicating option prefixes or port num‐
56 bers. This allows numeric IPv6 addresses to be used as hostnames.
57 On systems that support the forkpty library call, the hostname may be
59 replaced with -e and a command string. This will cause c3270 to con‐
60 nect to a local child process, such as a shell.
61 The port to connect to defaults to telnet. This can be overridden with
63 the -port option, or by appending a port to the hostname with a colon
64 `:'. (For compatability with previous versions of c3270 and with
65 tn3270(1), the port may also be specified as a second, separate argu‐
66 ment.)
67 An optional accept name (a hostname to accept in the host's SSL/TLS
69 certificate) may be specified by appending it to the hostname with an
70 equals sign (`='). The accept name can also be specified with the
71 -accepthostname option.
72
75 c3270 understands the following options:
76 -accepthostname name
78 Specifies a particular hostname to accept when validating the
79 name presented in the server SSL certificate, instead of compar‐
80 ing to the name used to make the connection.
81 -allbold
83 Forces all characters to be displayed in bold. This helps with
84 PC consoles which display non-bold characters in unreadably dim
85 colors. All-bold mode is the default for color displays, but
86 not for monochrome displays.
87 -altscreen rowsxcols=init_string
89 Defines the dimensions and escape sequence for the alternate
90 (132-column) screen mode. See SCREEN SIZE SWITCHING, below.
91 -cadir directory
93 Specifies a directory containing CA (root) certificates to use
94 when verifying a certificate provided by the host. (OpenSSL
95 only)
96 -cafile filename
98 Specifies a PEM-format file containing CA (root) certificates to
99 use when verifying a certificate provided by the host. (OpenSSL
100 only)
101 -cbreak
103 Causes c3270 to operate in cbreak mode, instead of raw mode. In
104 cbreak mode, the TTY driver will properly process XOFF and XON
105 characters, which are required by some terminals for proper
106 operation. However, those characters (usually ^S and ^Q), as
107 well as the characters for interrupt, quit, and lnext (usually
108 ^C, ^\ and ^V respectively) will be seen by c3270 only if pre‐
109 ceded by the lnext character. The susp character (usually ^Z)
110 cannot be seen by c3270 at all.
111 -certfile filename
113 Specifies a file containing a client certificate to provide to
114 the host. The default file type is PEM.
115 -clientcert name
117 Specifies the name of a client certificate to provide to the
118 host. (MacOS only)
119 -certfiletype type
121 Specifies the type of the certificate file specified by -cert‐
122 file. Type can be pem or asn1. (OpenSSL only)
123 -chainfile filename
125 Specifies a certificate chain file in PEM format, containing a
126 certificate to provide to the host, as well as one or more
127 intermediate certificates and the CA certificate used to sign
128 that certificate. If -chainfile is specified, it overrides
129 -certfile. (OpenSSL only)
130 -charset name
132 Specifies an EBCDIC host character set.
133 -clear toggle
135 Sets the initial value of toggle to false.
136 -connecttimeout seconds
138 Specifies the time that c3270 will wait for a host connection to
139 complete.
140 -defaultfgbg
142 Causes c3270 to use the terminal's default foreground color
143 instead of the curses color black, and the terminal's default
144 background color instead of the curses color white. This is
145 helpful for emulators such as gnome-terminal whose representa‐
146 tion of a black background is a murky gray, and for emulators
147 configured to use black text on a white background. It is set
148 automatically if the environment variable COLORTERM is set to
149 gnome-terminal. It is available only if c3270 was compiled with
150 a version of ncurses that supports default colors, if the emula‐
151 tor supports default colors, and if the termcap/terminfo entry
152 indicates this capability.
153 -defscreen rowsxcols=init_string
155 Defines the dimensions and escape sequence for the default
156 (80-column) screen mode. See SCREEN SIZE SWITCHING, below.
157 -devname name
159 Specifies a device name (workstation ID) for RFC 4777 support.
160 -hostsfile file
162 Uses file as the hosts file, which allows aliases for host names
163 and scripts to be executed at login. See ibm_hosts(1) for
164 details.
165 -httpd [addr:]port
167 Specifies a port and optional address to listen on for HTTP con‐
168 nections. Addr can be specified as `*' to indicate 0.0.0.0; the
169 default is 127.0.0.1. IPv6 numeric addresses must be specified
170 inside of square brackets, e.g., [::1]:4080 to specify the IPv6
171 loopback address and TCP port 4080.
172 Note that this option is mutually-exclusive with the -scriptport
174 option
175 -keyfile filename
177 Specifies a file containing the private key for the certificate
178 file (specified via -certfile or -chainfile). The default file
179 type is PEM. (OpenSSL only)
180 -keyfiletype type
182 Specifies the type of the private key file specified by -key‐
183 file. Type can be pem or asn1. (OpenSSL only)
184 -keypasswd type:value
186 Specifies the password for the private key file (OpenSSL) or
187 client certificate file (MacOS), if it is encrypted. The argu‐
188 ment can be file:filename, specifying that the password is in a
189 file, or string:string, specifying the password on the command-
190 line directly. If the private key file is encrypted and no
191 -keypasswd option is given, the password will be prompted for
192 interactively.
193 -keymap name
195 Specifies a keyboard map to be found in the resource
196 c3270.keymap.name or the file name. See KEYMAPS below for
197 details.
198 -km name
200 Specifies the local encoding method for multi-byte text. name
201 is an encoding name recognized by the ICU library. (Supported
202 only when c3270 is compiled with DBCS support, and necessary
203 only when c3270 cannot figure it out from the locale.)
204 -loginmacro Action(arg...) ...
206 Specifies a macro to run at login time.
207 -model name
209 The model of 3270 display to be emulated. The model name is in
210 two parts, either of which may be omitted:
211 The first part is the base model, which is either 3278 or 3279.
213 3278 specifies a monochrome (green on black) 3270 display; 3279
214 specifies a color 3270 display.
215 The second part is the model number, which specifies the number
217 of rows and columns. Model 4 is the default.
218 Model Number Columns Rows
220 ──────────────────────────────
221 2 80 24
222 3 80 32
223 4 80 43
224 5 132 27
225 Note: Technically, there is no such 3270 display as a 3279-4 or
227 3279-5, but most hosts seem to work with them anyway.
228 The default model for a color display is 3279-4. For a
230 monochrome display, it is 3278-4.
231 -mono Prevents c3270 from using color, ignoring any color capabilities
233 reported by the terminal.
234 -noprompt
236 An alias for -secure.
237 -noverifycert
239 For SSL/TLS connections, do not verify the host certificate.
240 -nvt Start in NVT mode instead of waiting for the host to send data,
242 and make the default terminal type xterm.
243 -oversize colsxrows
245 Makes the screen larger than the default for the chosen model
246 number. This option has effect only in combination with
247 extended data stream support (controlled by the "c3270.extended"
248 resource), and only if the host supports the Query Reply
249 structured field. The number of columns multiplied by the
250 number of rows must not exceed 16383 (3fff hex), the limit of
251 14-bit 3270 buffer addressing.
252 It can also be specified as auto, which causes c3270 to fill the
254 entire terminal or console window.
255 -port n
257 Specifies a different TCP port to connect to. n can be a name
258 from /etc/services like telnet, or a number. This option
259 changes the default port number used for all connections. (The
260 positional parameter affects only the initial connection.)
261 -proxy type:host[:port]
263 Causes c3270 to connect via the specified proxy, instead of
264 using a direct connection. The host can be an IP address or
265 hostname. The optional port can be a number or a service name.
266 For a list of supported proxy types, see PROXY below.
267 -printerlu luname
269 Causes c3270 to automatically start a pr3287 printer session.
270 If luname is ".", then the printer session will be associated
271 with the interactive terminal session (this requires that the
272 host support TN3270E). Otherwise, the value is used as the
273 explicit LU name to associate with the printer session.
274 -reconnect
276 Causes c3270 to automatically reconnect to the host if it ever
277 disconnects. This option has effect only if a hostname is
278 specified on the command line.
279 -rv Switches c3270 from a white-on-black display to a black-on-white
281 display.
282 -sl n Specifies that n lines should be saved for scrolling back. The
284 default is 4096.
285 -scriptport [addr:]port
287 Specifies a port and optional address to listen on for scripting
288 connections. Addr can be specified as `*' to indicate 0.0.0.0;
289 the default is 127.0.0.1. IPv6 numeric addresses must be
290 specified inside of square brackets, e.g., [::1]:4081 to specify
291 the IPv6 loopback address and TCP port 4081.
292 Note that this option is mutually-exclusive with the -httpd
294 option
295 -scriptportonce
297 Allows c3270 to accept only one script connection. When that
298 connection is broken, c3270 will exit.
299 -secure
301 Disables the interactive c3270> prompt. When used, a hostname
302 must be provided on the command line.
303 -set toggle
305 Sets the initial value of toggle to true.
306 -socket
308 Causes the emulator to create a Unix-domain socket when it
309 starts, for use by script processes to send commands to the
310 emulator. The socket is named /tmp/x3sck.pid. The -p option of
311 x3270if causes it to use this socket, instead of pipes specified
312 by environment variables.
313 -tn name
315 Specifies the terminal name to be transmitted over the telnet
316 connection. The default name is IBM-model_name-E, for example,
317 IBM-3279-4-E for a color display, or IBM-3278-4-E for a
318 monochrome display.
319 Some hosts are confused by the -E suffix on the terminal name,
321 and will ignore the extra screen area on models 3, 4 and 5.
322 Prepending an s: on the hostname, or setting the
323 "c3270.extended" resource to "false", removes the -E from the
324 terminal name when connecting to such hosts.
325 The name can also be specified with the "c3270.termName"
327 resource.
328 -trace Turns on data stream and event tracing at startup. The default
330 trace file name is /tmp/x3trc.
331 -tracefile file
333 Specifies a file to save data stream and event traces into. If
334 the name starts with `>>', data will be appended to the file.
335 -tracefilesize size
337 Places a limit on the size of a trace file. If this option is
338 not specified, or is specified as 0 or none, the trace file size
339 will be unlimited. The minimum size is 64 Kbytes. The value of
340 size can have a K or M suffix, indicating kilobytes or megabytes
341 respectively. When the trace file reaches the size limit, it
342 will be renamed with a `-' appended and a new file started.
343 -user name
345 Specifies the user name for RFC 4777 support.
346 -utf8 Forces the local codeset to be UTF-8, ignoring the locale or
348 Windows codepage.
349 -v Display the version and build options for c3270 and exit.
351 -verifycert
353 For SSL/TLS connections, verify the host certificate, and do not
354 allow the connection to complete unless it can be validated.
355 (This is the default setting.) This option is overridden by a
356 y: prepended to the hostname when connecting.
357 -xrm "c3270.resource: value"
359 Sets the value of the named resource to value. Resources
360 control less common c3270 options, and are defined under
361 RESOURCES below.
362
364 If the terminal that c3270 is running on has at least one more row that
365 the 3270 model requires (e.g., 25 rows for a model 2), c3270 will
366 display a status line. The c3270 status line contains a variety of
367 information. From left to right, the fields are:
368 comm status
370 The first symbol is always a 4. If c3270 is in TN3270E mode,
371 the second symbol is a B; otherwise it is an A. If c3270 is in
372 SSCP-LU mode, the third symbol is an S. Otherwise it is blank.
373 keyboard lock
375 If the keyboard is locked, an "X" symbol and a message field
376 indicate the reason for the keyboard lock.
377 typeahead
379 The letter "T" indicates that one or more keystrokes are in the
380 typeahead buffer.
381 temporary keymap
383 The letter "K" indicates that a temporary keymap is in effect.
384 reverse
386 The letter "R" indicates that the keyboard is in reverse field
387 entry mode.
388 insert mode
390 The letter "I" indicates that the keyboard is in insert mode.
391 printer session
393 The letter "P" indicates that a pr3287 session is active.
394 secure connection
396 A green letter "S" indicates that the connection is secured via
397 SSL/TLS.
398 LU name
400 The LU name associated with the session, if there is one.
401 cursor position
403 The cursor row and column are optionally displayed, zero padded
404 and separated by a "/". Location 001/001 is at the upper left,
405 which is different from the row and columns parameters used with
406 various actions, where the upper left corner is row 0, column 0.
407
410 Here is a complete list of basic c3270 actions. Script-specific
411 actions are described on the x3270-script(1) manual page. ).PP Actions
412 marked with an asterisk (*) may block, sending data to the host and
413 possibly waiting for a response.
414 *Attn attention key
416 BackSpace move cursor left (or send
417 ASCII BS)
418 BackTab tab to start of previous input
419 field
420 CircumNot input "^" in NVT mode, or
421 "notsign" in 3270 mode
422 *Clear clear screen
423 Compose next two keys form a special
424 symbol
425 *Connect(host) connect to host
426 *CursorSelect Cursor Select AID
427 Delete delete character under cursor
428 (or send ASCII DEL)
429 DeleteField delete the entire field
430 DeleteWord delete the current or previous
431 word
432 *Disconnect disconnect from host
433 Down move cursor down
434 Dup duplicate field
435 *Enter Enter AID (or send ASCII CR)
436 Erase erase previous character (or
437 send ASCII BS)
438 EraseEOF erase to end of current field
439 EraseInput erase all input fields
440 Escape escape to c3270> prompt
441 Execute(cmd) execute a command in a shell
442 FieldEnd move cursor to end of field
443 FieldMark mark field
444 HexString(hex_digits) insert control-character
445 string
446 Home move cursor to first input
447 field
448 Insert set insert mode
449 *Interrupt send TELNET IP to host
450 Keypad Display pop-up keypad
451 Key(keysym) insert key keysym
452 Key(0xxx) insert key with character code
453 xx
454 Left move cursor left
455 Left2 move cursor left 2 positions
456 Menu Display menu bar
457 MonoCase toggle uppercase-only mode
458 MoveCursor(row, col) move cursor to zero-origin
459 (row,col)
460 Newline move cursor to first field on
461 next line (or send ASCII LF)
462 NextWord move cursor to next word
463 *PA(n) Program Attention AID (n from
464 1 to 3)
465 *PF(n) Program Function AID (n from 1
466 to 24)
467 PreviousWord move cursor to previous word
468 Printer(Start[,lu]|Stop) start or stop printer session
469 PrintText(command) print screen text on printer
470 Quit exit c3270
471 Redraw redraw window
472 Reset reset locked keyboard
473 Right move cursor right
474 Right2 move cursor right 2 positions
475 *Script(command[,arg...]) run a script
476 Scroll(Forward|Backward) scroll screen
477 *String(string) insert string (simple macro
479 facility)
480 Tab move cursor to next input
481 field
482 Toggle(option[,set|clear]) toggle an option
483 ToggleInsert toggle insert mode
484 ToggleReverse toggle reverse-input mode
485 *Transfer(option=value...') file transfer
486 Up move cursor up
487 ignore do nothing
488 Any of the above actions may be entered at the c3270> prompt; these
490 commands are also available for use in keymaps (see KEYMAPS). Command
491 names are case-insensitive. Parameters can be specified with
492 parentheses and commas, e.g.:
493 PF(1)
494 or with spaces, e.g.:
495 PF 1
496 Parameters can be quoted with double-quote characters, to allow spaces,
497 commas, and parentheses to be used.
498 c3270 also supports the following interactive commands:
500 Help Displays a list of available commands.
502 ScreenTrace
504 Turns screen tracing (saving screen images to a file) on or off.
505 The command screentrace on enables screen tracing; the command
506 screentrace off disables it. After on, a filename may be
507 specified to override the default trace file name of
508 /tmp/x3scr.pid. The keyaord on can also be followed by the
509 keyword printer and an optional print command to direct screen
510 traces directly to the printer.
511 Show Displays statistics and settings.
513 Trace Turns tracing on or off. The command trace on enables data
515 stream and keyboard event tracing; the command trace off
516 disables it. The qualifier data or keyboard can be specified
517 before on or off to enable or disable a particular trace. After
518 on, a filename may be specified to override the default trace
519 file name of /tmp/x3trc.pid.
520 Note that certain parameters to c3270 actions (such as the names of
522 files and keymaps) are subject to substitutions:
523 The character ~ at the beginning of a string is replaced with the
525 user's home directory. A ~ character followed by a username is
526 replaced with that user's home directory.
527 Environment variables are substituted using the Unix shell convention
529 of $name or ${name}.
530 Two special pseudo-environment variables are supported. ${TIMESTAMP} is
532 replaced with a microsecond-resolution timestamp; ${UNIQUE} is replaced
533 with a string guaranteed to make a unique filename (the process ID
534 optionally followed by a dash and a string of digits). ${UNIQUE} is
535 used to form trace file names.
536
538 The -keymap option or the c3270.keymap resource allow a custom keymap
539 to be specified. If the option -keymap xxx is given (or the
540 c3270.keymap resource has the value xxx), c3270 will look for a
541 resource named c3270.keymap.xxx. If no resource definition is found,
542 it will look for a file named xxx.
543 Multiple keymaps may be specified be separating their names with
545 commas. Definitions in later keymaps supercede those in earlier
546 keymaps.
547 In addition, separate keymaps may be defined that apply only in 3270
549 mode or NVT mode. For example, the resource definition
550 c3270.keymap.xxx.nvt or the file xxx.nvt will augment the definition of
551 keymap xxx in NVT mode. Similarly, the resource definition
552 c3270.keymap.xxx.3270 or the file xxx.3270 will augment the definition
553 of keymap xxx in 3270 mode.
554 Temporary keymaps can also be added or removed while c3270 is running
556 with the Keymap action. See x3270-script(1) for details.
557 Each line (rule) in a keymap specifies actions to perform when a
559 particular key or sequence of keys is pressed. Keymap rules have the
560 following syntax:
561 [Meta][Ctrl]<Key>key...: action[(param[,...])] ...
563 Here is a sample keymap definition from a file:
565 ! Lines beginning with ! are ignored and can
567 ! occur anywhere.
568 ! Definition of keymap xxx
569 ! When Alt-c is pressed, clear the screen.
570 Alt<Key>c: Clear()
571 ! When PageUp is pressed, send PF7 to the host.
572 <Key>PPAGE: PF(7)
573 ! When Ctrl-a is pressed, then F1, send PF13
574 ! to the host.
575 Ctrl<Key>a <Key>F1: PF(13)
576 Here is the same definition as a resource:
578 ! Lines beginning with ! are ignored, but NOT
580 ! within a definition.
581 ! Note that the \ is required at the end of the
582 ! first line, and \n\ is
583 ! required at the end of every other line except
584 ! the last.
585 ! Definition of keymap xxx
586 c3270.keymap.xxx: \
587 Alt<Key>c: Clear() \n\
588 <Key>PPAGE: PF(7) \n\
589 Ctrl<Key>A <Key>F1: PF(13)
590 The optional Alt or Ctrl modifiers specify that the Alt and Ctrl keys
592 are pressed along with the specified key, respectively. Key is either
593 an ISO 8859-1 symbol name, such as equal for `=' and a for `a', or a
594 symbolic ncurses key name, such as UP. More than one key can be
595 specified, indicating that a sequence of keys must be pressed in order
596 for the rule to be matched. The action is an action from the ACTIONS
597 list above. More than one action may be specified; they will be
598 executed in order.
599 Keymap entries are case-sensitive and modifier-specific. This means
601 that a keymap for the b key will match only a lowercase b. Actions for
602 uppercase B, or for Alt-B, must be specified separately.
603 The base keymap is:
605 Key Action
607 ─────────────────────────────────────────
608 Ctrl<Key>] Escape
609 Ctrl<Key>a Ctrl<Key>a Key(0x01)
610 Ctrl<Key>a Ctrl<Key>] Key(0x1d)
611 Ctrl<Key>a <Key>Tab BackTab
612 Ctrl<Key>a <Key>c Clear
613 Ctrl<Key>a <Key>e Escape
614 Ctrl<Key>a <Key>r Reset
615 Ctrl<Key>a <Key>k Keypad
617 Ctrl<Key>a <Key>l Redraw
618 Ctrl<Key>a <Key>m Compose
619 Ctrl<Key>a <Key>n Menu
620 Ctrl<Key>a <Key>p PrintText
621 Ctrl<Key>a <Key>^ Key(notsign)
622 Ctrl<Key>k Keypad
623 Ctrl<Key>n Menu
624 <Key>UP Up
625 <Key>DOWN Down
626 <Key>LEFT Left
627 <Key>RIGHT Right
628 <Key>F(n) PF(n)
629 Ctrl<Key>a <Key>F(n) PF(n+12)
630 Ctrl<Key>a <Key>1 PA(1)
631 Ctrl<Key>a <Key>2 PA(2)
632 Ctrl<Key>a <Key>3 PA(3)
633 <Key>PPAGE Scroll(Backward)
634 <Key>NPAGE Scroll(Forward)
635 The base 3270-mode keymap adds:
637 Key Action
639 ──────────────────────────────
640 Ctrl<Key>c Clear
641 Ctrl<Key>d Dup
642 Ctrl<Key>f FieldMark
643 Ctrl<Key>i Tab
644 Ctrl<Key>l Redraw
645 Ctrl<Key>r Reset
646 Ctrl<Key>u DeleteField
647 <Key>BackSpace BackSpace
648 <Key>Return Enter
649 <Key>Tab Tab
650 <Key>Linefeed Newline
651 <Key>BACKSPACE BackSpace
652 <Key>DC Delete
653 <Key>HOME Home
654 <Key>IC ToggleInsert
655
657 Some keyboards do not have a Meta key. Instead, they have an Alt key.
658 Sometimes this key acts as a proper Meta key, that is, it is a modifier
659 key that sets the high-order bit (0x80) in the code that is transmitted
660 for each key. Other keyboards send a two-character sequence when the
661 Alt key is pressed with another key: the Escape character (0x1b),
662 followed by the code for the other key.
663 The resource c3270.metaEscape and the termcap km attribute control how
665 c3270 will interpret these sequences. When c3270.metaEscape is set to
666 true, or when c3270.metaEscape is set to auto and the termcap km
667 attribute is set, the keyboard is assumed to have a separate Meta key.
668 The Escape key can be used as an ordinary data key and has no special
669 meaning.
670 When c3270.metaEscape is set to true, or when c3270.metaEscape is set
672 to auto and the termcap km attribute is not set, the keyboard is
673 assumed to use the Escape character as a prefix to indicate that the
674 following character is supposed to have the high-order bit set. When
675 c3270 sees an Escape character from the keyboard, it sets a short
676 timeout. If another character arrives before the timeout expires, then
677 c3270 will combine the two characters, setting the high-order bit of
678 the second. In an event trace file, the combined character is listed
679 as derived. In a keymap, only the combined character or the Meta
680 prefix may be used. The Escape key can still be used by itself, but
681 only if there is a short pause before pressing another key.
682 The default value for c3270.metaEscape is auto.
684
686 The Transfer action implements IND$FILE file transfer. This action
687 requires that the IND$FILE program be installed on the IBM host, and
688 that the 3270 cursor be located in a field that will accept a TSO or
689 VM/CMS command.
690 The Transfer action can be entered at the command prompt with no
692 parameters, which will cause it to prompt interactively for the file
693 names and options. It can also be invoked with parameters to define
694 the entire transfer.
695 Because of the complexity and number of options for file transfer, the
697 parameters to the Transfer action take the unique form of option=value,
698 and can appear in any order. Note that if the value contains spaces
699 (such as a VM/CMS file name), then the entire parameter must be quoted,
700 e.g., "HostFile=xxx foo a". The options are:
701 Option Required? Default Other Values
703 ────────────────────────────────────────────────────────
704 Direction No receive send
705 HostFile Yes
706 LocalFile Yes
707 Host No tso vm, cics
708 Mode No ascii binary
709 Cr No remove add, keep
710 Remap No yes no
711 Exist No keep replace, append
712 Recfm No fixed, variable,
713 undefined
714 Lrecl No
715 Blksize No
716 Allocation No tracks,
717 cylinders,
718 avblock
719 PrimarySpace Sometimes
720 SecondarySpace No
721 Avblock Sometimes
722 BufferSize No 4096
723 The option details are as follows.
725 Direction
727 send to send a file to the host, receive to receive a file from
728 the host.
729 HostFile
731 The name of the file on the host.
732 LocalFile
734 The name of the file on the local workstation.
735 Host The type of host (which dictates the form of the IND$FILE
737 command): tso (the default), vm or cics.
738 Mode Use ascii (the default) for a text file, which will be
740 translated between EBCDIC and ASCII as necessary. Use binary
741 for non-text files.
742 Cr Controls how Newline characters are handled when transferring
744 Mode=ascii files. remove (the default) strips Newline
745 characters in local files before transferring them to the host.
746 add adds Newline characters to each host file record before
747 transferring it to the local workstation. keep preserves
748 Newline characters when transferring a local file to the host.
749 Remap Controls text translation for Mode=ascii files. The value yes
751 (the default) causes c3270 to remap the text to ensure maximum
752 compatibility between the workstation's character set and
753 encoding and the host's EBCDIC code page. The value no causes
754 c3270 to pass the text to or from the host as-is, leaving all
755 translation to the IND$FILE program on the host.
756 Exist Controls what happens when the destination file already exists.
758 keep (the default) preserves the file, causing the Transfer
759 action to fail. replace overwrites the destination file with
760 the source file. append appends the source file to the
761 destination file.
762 Recfm Controls the record format of files created on the host. (TSO
764 and VM hosts only.) fixed creates a file with fixed-length
765 records. variable creates a file with variable-length records.
766 undefined creates a file with undefined-length records (TSO
767 hosts only). The Lrecl option controls the record length or
768 maximum record length for Recfm=fixed and Recfm=variable files,
769 respectively.
770 Lrecl Specifies the record length (or maximum record length) for files
772 created on the host. (TSO and VM hosts only.)
773 Blksize
775 Specifies the block size for files created on the host. (TSO
776 and VM hosts only.)
777 Allocation
779 Specifies the units for the PrimarySpace and SecondarySpace
780 options: tracks, cylinders or avblock. (TSO hosts only.)
781 PrimarySpace
783 Primary allocation for a file. The units are given by the
784 Allocation option. Required when the Allocation is specified as
785 something other than default. (TSO hosts only.)
786 SecondarySpace
788 Secondary allocation for a file. The units are given by the
789 Allocation option. (TSO hosts only.)
790 Avblock
792 Average block size, required when Allocation specifies avblock.
793 (TSO hosts only.)
794 BufferSize
796 Buffer size for DFT-mode transfers. Can range from 256 to
797 32768. Larger values give better performance, but some hosts
798 may not be able to support them.
799 There are also resources that control the default values for each of
801 the file transfer parameters. These resources have the same names as
802 the Transfer keywords, but with ft prepended. E.g., the default for the
803 Mode keyword is the c3270.ftMode resource.
804
807 The PrintText produces screen snapshots in a number of different forms.
808 The default form wth no arguments sends a copy of the screen to the
809 default printer. A single argument is the command to use to print,
810 e.g., lpr.
811 Multiple arguments can include keywords to control the output of
813 PrintText:
814 file filename
816 Save the output in a file.
817 html Save the output as HTML. This option implies file.
819 rtf Save the output as RichText. This option implies file. The
821 font defaults to Courier New and the point size defaults to 8.
822 These can be overridden by the printTextFont and printTextSize
823 resources, respectively.
824 string Return the output as a string. This can only be used from
826 scripts.
827 modi Render modified fields in italics.
829 caption text
831 Add the specified text as a caption above the output. Within
832 text, the special sequence %T% will be replaced with a
833 timestamp.
834 command command
836 Directs the output to a command. This allows one or more of the
837 other keywords to be specified, while still sending the output
838 to the printer.
839
842 There are several types of script functions available.
843 The String Action
845 The simplest method for scripting is provided via the String
846 action. The arguments to String are one or more double-quoted
847 strings which are inserted directly as if typed. The C
848 backslash conventions are honored as follows. (Entries marked *
849 mean that after sending the AID code to the host, c3270 will
850 wait for the host to unlock the keyboard before further
851 processing the string.)
852 \b Left
854 \exxxx EBCDIC character in hex
855 \f Clear*
856 \n Enter*
857 \pan PA(n)*
858 \pfnn PF(nn)*
859 \r Newline
860 \t Tab
861 \T BackTab
862 \uxxxx Unicode character in hex
863 \xxxxx Unicode character in hex
864 Note that the numeric values for the \e, \u and \x sequences can
866 be abbreviated to 2 digits. Note also that EBCDIC codes greater
867 than 255 and some Unicode character codes represent DBCS
868 characters, which will work only if c3270 is built with DBCS
869 support and the host allows DBCS input in the current field.
870 An example keymap entry would be:
872 Meta<Key>p: String("probs clearrdr\n")
873 Note: The strings are in ASCII and converted to EBCDIC, so
875 beware of inserting control codes.
876 There is also an alternate form of the String action, HexString,
878 which is used to enter non-printing data. The argument to
879 HexString is a string of hexadecimal digits, two per character.
880 A leading 0x or 0X is optional. In 3270 mode, the hexadecimal
881 data represent EBCDIC characters, which are entered into the
882 current field. In NVT mode, the hexadecimal data represent
883 ASCII characters, which are sent directly to the host.
884 The Script Action
886 This action causes c3270 to start a child process which can
887 execute c3270 actions. Standard input and output from the child
888 process are piped back to c3270. The Script action is fully
889 documented in x3270-script(1).
890
892 c3270 allows the direct entry of accented letters and special symbols.
893 Pressing and releasing the "Compose" key, followed by two other keys,
894 causes entry of the symbol combining those two keys. For example,
895 "Compose" followed by the "C" key and the "," (comma) key, enters the
896 "C-cedilla" symbol. A C on the status line indicates a pending
897 composite character.
898 The mappings between these pairs of ordinary keys and the symbols they
900 represent is controlled by the "c3270.composeMap" resource; it gives
901 the name of the map to use. The maps themselves are named
902 "c3270.composeMap.name". The default is "latin1", which gives mappings
903 for most of the symbols in the ISO 8859-1 Latin-1 character set that
904 are not in the 7-bit ASCII character set.
905 Note: The default keymap defines Meta<Key>m as the "Compose" key. You
907 may set up your own "Compose" key with a keymap that maps some other
908 keysym onto the Compose action.
909
911 c3270 supports associated printer sessions via the pr3287(1) program.
912 The Printer action is used to start or stop a pr3287 session.
913 The action Printer Start starts a printer session, associated with the
915 current LU. (This works only if the host supports TN3270E.)
916 The action Printer Start lu starts a printer session, associated with a
918 specific lu.
919 The action Printer Stop stops a printer session.
921 The resource c3270.printer.options specifies extra options, such as
923 -trace to pass to pr3287.
924 See pr3287(1) for further details.
926 The resource c3270.printerLu controls automatic printer session start-
928 up. If it is set to `.', then whenever a login session is started, a
929 printer session will automatically be started, associated with the
930 login session. If it is set an LU name, then the automatic printer
931 session will be associated with the specified LU.
932
935 c3270 supports the Sun telnet-passthru service provided by the
936 in.telnet-gw server. This allows outbound telnet connections through a
937 firewall machine. When a p: is prepended to a hostname, c3270 acts
938 much like the itelnet(1) command. It contacts the machine named
939 internet-gateway at the port defined in /etc/services as telnet-
940 passthru (which defaults to 3514). It then passes the requested
941 hostname and port to the in.telnet-gw server.
942
944 The -proxy option or the c3270.proxy resource causes c3270 to use a
945 proxy server to connect to the host. The syntax of the option or
946 resource is:
947 type:host[:port]
948 The supported values for type are:
950 Proxy Type Protocol Default Port
952 ──────────────────────────────────────────────
953 http RFC 2817 HTTP 3128
954 tunnel (squid)
955 passthru Sun in.telnet-gw none
956 socks4 SOCKS version 4 1080
957 socks5 SOCKS version 5 1080
958 (RFC 1928)
959 telnet No protocol (just none
960 send connect host
961 port)
962 The special types socks4a and socks5d can also be used to force the
964 proxy server to do the hostname resolution for the SOCKS protocol.
965
967 When running as a 3270 Model 5, c3270 can take advantage of terminals
968 that can switch between 80 and 132 column modes.
969 Because the curses library does not support mode switching, the escape
971 sequences and resulting screen dimensions must be specified explicitly
972 to c3270. These are specified with the -altscreen and -defscreen
973 command-line options, or the altScreen and defScreen resources.
974 -altscreen or altScreen defines the alternate (132-column) mode;
975 -defscreen or defScreen defines the default (80-column) mode.
976 The syntax for the options and resources is rowsxcols=init_string,
978 where rows and cols give the screen dimensions, and init_string is the
979 escape sequence to transmit to the terminal to enter that mode. For
980 defscreen, the minimum dimensions are 24 rows and 80 columns. For
981 altscreen, the minimum dimensions are 27 rows and 132 columns. Within
982 init_string, the usual escape sequences are supported (\E for escape,
983 \r, \b, etc.). For example, the init string for a 132-column xterm is:
984 \E[?40h\E[?3h
986 Note: When defscreen and altscreen are specified, the model number is
988 always set to 5.
989
991 Certain c3270 options can be configured via resources. Resources are
992 defined in the file .c3270pro in the user's home directory, and by -xrm
993 options. The definitions are similar to X11 resources, and use a
994 similar syntax. The resources available in c3270 are:
995 Resource Default Option Purpose
997 ───────────────────────────────────────────────────────────────────────
998 allBold Auto -allbold Display all
999 characters bold
1000 altScreen -altscreen 132-col screen
1001 definition
1002 blankFill False -set blankFill Blank Fill mode
1003 charset bracket -charset EBCDIC character
1004 set
1005 composeMap latin1 Name of
1006 composed-
1007 character map
1008 cursesColor‐ (note 6) Color mapping
1009 ForHostColorn
1010 cursesColor‐ green Default color
1011 ForDefault mapping
1012 cursesColor‐ red Default color
1013 ForIntensified mapping
1014 cursesColor‐ blue Default color
1015 ForProtected mapping
1016 cursesColor‐ white Default color
1017 ForProtectedIntensified mapping
1018 cursesKeymap True Set curses
1019 keymap option
1020 defScreen -defscreen 80-col screen
1021 definition
1022 dbcsCgcsgid Override DBCS
1023 CGCSGID
1024 dsTrace False -trace Data stream
1025 tracing
1026 eof ^D NVT-mode EOF
1027 character
1028 erase ^H NVT-mode erase
1029 character
1030 extended True Use 3270
1031 extended data
1032 stream
1033 eventTrace False -trace Event tracing
1034 hostsFile -hostsfile Host alias/macro
1037 file
1038 icrnl False Map CR to NL on
1039 NVT-mode input
1040 inlcr False Map NL to CR in
1041 NVT-mode input
1042 intr ^C NVT-mode
1043 interrupt
1044 character
1045 keymap -keymap Keyboard map
1046 name
1047 keymap.foo Definition of
1048 keymap foo
1049 kill ^U NVT-mode kill
1050 character
1051 lineWrap False -set lineWrap NVT line wrap
1052 mode
1053 lnext ^V NVT-mode lnext
1054 character
1055 m3279 (note 1) -model 3279 (color)
1056 emulation
1057 metaEscape Auto Interpret ESC-x
1058 as Meta-x
1059 mono (note 5) -mono Ignore terminal
1060 color
1061 capabilities
1062 monoCase False -set monoCase Mono-case mode
1063 noPrompt False -noprompt Disable command-
1064 prompt mode
1065 numericLock False Lock keyboard
1066 for numeric
1067 field error
1068 oerrLock True Lock keyboard
1069 for input error
1070 oversize -oversize Oversize screen
1071 dimensions
1072 port telnet -port Non-default TCP
1073 port
1074 printer.* (note 4) Printer session
1075 config
1076 printerLu (note 4) Printer session
1077 config
1078 quit ^\ NVT-mode quit
1079 character
1080 reconnect False -reconnect Automatically
1081 reconnect to
1082 host
1083 rprnt ^R NVT-mode reprint
1084 character
1085 sbcsCgcsgid Override SBCS
1086 CGCSGID
1087 secure False Disable
1088 "dangerous"
1089 options
1090 termName (note 2) -tn TELNET terminal
1091 type string
1092 traceDir /tmp Directory for
1093 trace files
1094 traceFile (note 3) -tracefile File for trace
1095 output
1096 typeahead True Allow typeahead
1097 werase ^W NVT-mode word-
1098 erase character
1099 Note 1: m3279 defaults to True if the terminal supports color,
1101 False otherwise. It can be forced to False with the proper
1102 -model option.
1103 Note 2: The default terminal type string is constructed from the
1105 model number, color emulation, and extended data stream modes.
1106 E.g., a model 2 with color emulation and the extended data
1107 stream option would be sent as IBM-3279-2-E. Note also that
1108 when TN3270E mode is used, the terminal type is always sent as
1109 3278, but this does not affect color capabilities.
1110 Note 3: The default trace file is x3trc.pid in the directory
1112 specified by the traceDir resource.
1113 Note 4: See PRINTER SUPPORT for details.
1115 Note 5: mono defaults to false if the terminal supports at least
1118 8 colors and to true otherwise.
1119 Note 6: The default curses color mappings for host colors 0
1121 through 15 are: black, blue, red, magenta, green, cyan, yellow,
1122 white, black, blue, yellow, blue, green, cyan, black and white.
1123 In .c3270pro, lines are continued with a backslash character.
1126 -xrm options override definitions found in .c3270pro. If more than one
1128 -xrm option is given for the same resource, the last one on the command
1129 line is used.
1130
1132 /etc/ibm_hosts
1133 $HOME/.c3270pro
1134
1137 pr3287(1), s3270(1), x3270-script(1), x3270(1), tcl3270(1), telnet(1),
1138 tn3270(1)
1139 Data Stream Programmer's Reference, IBM GA23-0059
1140 Character Set Reference, IBM GA27-3831
1141 RFC 1576, TN3270 Current Practices
1142 RFC 1646, TN3270 Extensions for LUname and Printer Selection
1143 RFC 2355, TN3270 Enhancements
1144
1146 Copyright 1993-2019, Paul Mattes.
1147 Copyright 2004-2005, Don Russell.
1148 Copyright 2004, Dick Altenbern.
1149 Copyright 1990, Jeff Sparkes.
1150 Copyright 1989, Georgia Tech Research Corporation (GTRC), Atlanta, GA
1151 30332.
1152 All rights reserved.
1153 Redistribution and use in source and binary forms, with or without
1155 modification, are permitted provided that the following conditions are
1156 met:
1157 * Redistributions of source code must retain the above copyright
1160 notice, this list of conditions and the following disclaimer.
1161 * Redistributions in binary form must reproduce the above
1163 copyright notice, this list of conditions and the following
1164 disclaimer in the documentation and/or other materials provided
1165 with the distribution.
1166 * Neither the names of Paul Mattes, Don Russell, Dick Altenbern,
1168 Jeff Sparkes, GTRC nor the names of their contributors may be
1169 used to endorse or promote products derived from this software
1170 without specific prior written permission.
1171 THIS SOFTWARE IS PROVIDED BY PAUL MATTES, DON RUSSELL, DICK ALTENBERN,
1174 JEFF SPARKES AND GTRC "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
1175 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1176 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
1177 NO EVENT SHALL PAUL MATTES, DON RUSSELL, DICK ALTENBERN, JEFF SPARKES
1178 OR GTRC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL
1179 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
1180 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1181 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1182 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1183 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1184 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1185
1187 c3270 3.6ga8
1188 03 June 2019 c3270(1)