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