X3270(1)

NAME
x3270 - IBM host access tool

SYNOPSIS
x3270 [ options ] [ [ a: ] hostname ]

DESCRIPTION
x3270 opens a telnet connection to an IBM host in an X window. Since the window created by x3270 can use its own font for displaying characters, is a fairly accurate representation of an IBM 3278. It is similar to tn3270(1) except that it is X-based, not curses-based.

Prepending an a: onto hostname puts x3270 in initial ANSI X3.64 emulation mode. See ANSI MODE below for further information.

OPTIONS
x3270 is a toolkit based program, so it understands standard options and resources. It also understands the following options:

-activeicon
    Specifies that the icon should be a miniature version of the screen image. See ICONS below.

-apl
    Sets up APL mode. This is actually an abbreviation for several options. See APL SUPPORT below.

-efont name
    Specifies a font for the emulator window. See FONTS below.

-keymap name
    Specifies a keymap name and optional modifiers. See KEYMAPS below.

-charset name
    Specifies an EBCDIC national character set. See CHARACTER SETS below.

-model n
    The type of 3278 to be emulated. The sizes of various emulated models are:

    Model | Columns | Rows
    2 | 80 | 24
    3 | 80 | 30
    4 | 80 | 43 | default
    5 | 132 | 27

-mono
    Forces monochrome emulation on a color display.

-port n
    Specifies a different TCP port to connect to. n can be a name from /etc/services like telnet, or a number.

-tn name
    Specifies the terminal name to be transmitted over the telnet connection. The default name is IBM-3278-n where n is the model number. The name can also be specified with the "x3270.termName" resource.

FONTS
By default, x3270 does not use the "*font" resource for its main display. Instead, it uses a custom 14-point font called 3270, which is a close approximation of a real 3278 display and allows x3270 to display a complete EBCDIC character set and special status-line symbols. A more compact font, 3270-12, is also supported.

The font may be specified with the -efont option or the "x3270.emulatorFont" resource.

x3270 can also use any constant-spaced X font, but unless the font implements the entire ISO 8859-1 (Latin-1) character set, x3270 may not properly display several EBCDIC graphics that do not have ASCII equivalents.

Note: x3270 requires that fonts have a SPACING property with the value C. Many otherwise valid fonts are not properly configured and appear unusable. You may override the check by placing a `!' in front of the font name.

For speed, x3270 also uses a second font for bold (high-intensity) characters. It finds this font by appending bold to the name of its emulator font; if such a font cannot be found, it uses the slower method of overstriking each bold character. The bold font may be specified explicitly with the -bfont option or the "x3270.boldFont" resource.

CHARACTER SETS
The -charset option or the "x3270.charset" resource controls the EBCDIC national character set used by x3270. By default, the U.S. character set (code 01) is used. Available sets include:

Charset Name | Q121 Code
us | 01
german | 03
finnish | 09
uk | 22
norwegian | 23
french | 30

The charset name bracket is also supported to communicate with older IBM hosts which use EBCDIC codes 0xAD and 0xBD for the `[' and `]' characters, respectively.

You can also specify national-language translations for your keyboard; see KEYMAPS below.

KEYPAD
A keypad may optionally be displayed, with a mouse-clickable button for each 3270 function key (these functions are also available from the keyboard). The keypad can be turned on and off by clicking on the "keypad" button in the upper-right-hand corner of the window. The "x3270.keypad" resource controls where it is displayed. Options are:

right | in a separate window, to the right of the screen
bottom | in a separate window, below the screen
integral | in the same window as the screen, below it

The default is right.

If the "x3270.keypadOn" resource is set to true, the keypad will be displayed at startup.

HOSTS DATABASE
x3270 uses the ibm_hosts database to construct a pull-down menu of hosts to connect to. It supports the loginstring function, which allows you to specify a macro to be sent to the host when the connection is first made. See ibm_hosts(5) for details.

You may specify a different ibm_hosts database with the "x3270.hostsFile" resource.

COLOR
x3270 does not understand IBM 3270 color protocols. It draws text in one of three colors depending on the field attributes. Those colors may be customized using the following resources (shown with their default values):
	x3270.normalColor:	green
	x3270.boldColor:	cyan
	x3270.inputColor:	orange
	x3270.colorBackground:	black
	x3270.selectBackground:	dim gray

It is possible to get monochrome colors and behavior using the -mono switch.

ANSI MODE
Some hosts use an ASCII front-end to do initial login negotiation, then later switch to 3270 mode. Prepending an a: onto the hostname causes x3270 to emulate an ANSI X.64 terminal until the host places it in 3270 mode (telnet BINARY and SEND EOR modes). The emulation is far from complete, however, and not intended to make x3270 a replacement for xterm(1).

If the host later negotiates to stop functioning in 3270 mode, x3270 will disconnect.

When emulating an ANSI terminal, x3270 supports both character-at-a-time mode and line mode operation. You may select the mode with a menu option. When in line mode, the special characters and operational characteristics are defined by resources:

Mode/Character | Resource | Default
Translate CR to NL | x3270.icrnl | true
Translate NL to CR | x3270.inlcr | false
Erase previous character | x3270.erase | ^?
Erase entire line | x3270.kill | ^U
Erase previous word | x3270.werase | ^W
Redisplay line | x3270.rprnt | ^R
Ignore special meaning of next character | x3270.lnext | ^V
Interrupt | x3270.intr | ^C
Quit | x3270.quit | ^\\
End of file | x3270.eof | ^D

MENUS
x3270 has a menu bar with three pull-down menus (Quit, Options, and Connect) and a button to turn the keypad on and off. The pull-down menus are also available as pop-up menus by using the "Ctrl" key and the left, middle and right mouse buttons, respectively.

The menu bar can be turned off by setting the "x3270.menuBar" resource to false.

ICONS
If the -activeicon option is given (or the "x3270.activeIcon" resource is set to true), x3270 will attempt to make its icon a miniature version of the current screen image. This function is highly dependent on your window manager:

mwm The size of the icon is limited by the "Mwm.iconImageMaximum" resource, which defaults to 50x50. The image will be clipped at the bottom and right. The icon cannot accept keyboard input.

olwm
    The full screen image of all 3270 models can be displayed on the icon. However, the icon cannot be resized, so if the model is later changed with an x3270 menu option, the icon image will be corrupted. The icon cannot accept keyboard input.

twm and tvtwm
    The full screen image of all 3270 models can be displayed on the icon, and the icon can be resized. The icon can accept keyboard input.

    However, twm does not put labels on application-supplied icon windows. You can have x3270 add its own label to the icon by setting the "x3270.labelIcon" resource to true. The default font for icon labels is 8x13; you may change it with the "x3270.iconLabelFont" resource.

KEYMAPS

The type of keyboard may be specified with the -keymap switch or using either the KEYMAP or KEYBD environment variables. The types of supported keyboards include hp-k1, ncd, sun-k4, and sun-k3.

The keymap may also be specified as a comma-separated list of names. Later definitions override earlier ones. This is used to specify both a primary keyboard type and a set of modifiers. The modifiers defined include:

ow  (OpenWindows) Swaps the middle and right mouse button definitions, so the middle button performs the "Paste" function. Also changes the cut and paste actions to use the OpenWindows CLIPBOARD.

alt Replaces all of the "Meta" key definitions with "Alt" definitions, for keyboards which do not have a "Meta" key.

apl Allows entry of APL characters (see APL SUPPORT below).

finnish7
    Replaces the bracket, brace and bar keys with common Finnish characters.

norwegian7
    Replaces the bracket, brace and bar keys with common Norwegian characters.

The X Toolkit translation mechanism is used to provide keyboard emulation. It maps events into actions. The best documentation can be found with X11R5 X toolkit documents, but the following should suffice for simple customization.

An Xt event consists of (at least) four fields. The first is called a modifier. It may be any combination of meta, shift and ctrl. If it is prefaced by !, it means those modifiers only. The second field is the specific event, in x3270 usually just <Key>. The third field is the detail field, which gives the actual key. The name of the key may be determined using the R5 xev program. The last field is the action, which is the internal emulator function. A complete list of actions may be found later in the manual.

There are three levels of translation tables in x3270. The first is a default, compiled in table. It defines alphabetic, numeric, function keys, and such basic functions as Enter and Delete. It allows a minimal useful functionality.

The second level is a keyboard specific table, which is found in the application default file, which defines actions for such things as keypad keys, and keys unique to certain keyboards.

The third level is a user customizable table which may be used to augment or override key definitions. This will typically be found in the users .Xdefaults file. The naming for a sun4 keyboard would be:
    x3270.keymap.default:
    x3270.keymap.sun-k4:
    x3270.keymap.sun-k4.user:

The basic default translation table is:
    <Key>Return: | Enter()
    <Key>Linefeed: | Newline()
    !Shift<Key>Tab: | BackTab()
    <Key>Tab: | Tab()
    <Key>Home: | Home()
    <Key>Left: | Left()
    !Meta<Key>Left: | Left2()
    <Key>Right: | Right()
    !Meta<Key>Right: | Right2()
    <Key>Up: | Up()
    <Key>Down: | Down()
    <Key>Delete: | Delete()
    <Key>BackSpace: | BackSpace()
    <Btn1Down>: | select-start()
    <Btn1Motion>: | select-extend()
    <Btn2Down>: | ignore()
    <Btn2Motion>: | ignore()
    <Btn2Up>: | insert-selection(PRIMARY)
    <Btn3Down>: | start-extend()
    <Btn3Motion>: | select-extend()
    <BtnUp>: | select-end(PRIMARY)
    Shift<Btn1Down>: | MoveCursor()
    !Meta<Key>F1: | PF13()
    !Meta<Key>F2: | PF14()
    !Meta<Key>F3: | PF15()
    !Meta<Key>F4: | PF16()
    !Meta<Key>F5: | PF17()
    !Meta<Key>F6: | PF18()
    !Meta<Key>F7: | PF19()
    !Meta<Key>F8: | PF20()
    !Meta<Key>F9: | PF21()
    !Meta<Key>F10: | PF22()
    !Meta<Key>F11: | PF23()
    !Meta<Key>F12: | PF24()
    <Key>F1: | PF1()
    <Key>F2: | PF2()
    <Key>F3: | PF3()
    <Key>F4: | PF4()
    <Key>F5: | PF5()
    <Key>F6: | PF6()
    <Key>F7: | PF7()
    <Key>F8: | PF8()
    <Key>F9: | PF9()
    <Key>F10: | PF10()
    <Key>F11: | PF11()
    <Key>F12: | PF12()
    Meta<Key>1: | PA1()
    Meta<Key>2: | PA2()
    Meta<Key>3: | PA3()
    Meta<Key>a: | Attn()
    Meta<Key>c: | Clear()
    Meta<Key>d: | Delete()
    Meta<Key>h: | Home()
    Meta<Key>i: | Insert()
    Meta<Key>l: | Redraw()
    Meta<Key>q: | Quit()
    Meta<Key>r: | Reset()
    Ctrl<Key>u: | DeleteField()
    Ctrl<Key>w: | DeleteWord()
    :<Key>: | Default()

Meta is the diamond shaped key on a sun-k4, "Alt" on an NCD, "Extend Char" on an HP. The following xmodmap command must be used on the NCD to allow use the the "Alt" key:

    xmodmap -e "keysym Alt_L = Meta_L"

The left mouse button may be used to make a selection. Clicking once unselects the current selection. Clicking twice selects the word under the mouse cursor. Clicking three times selects the line under the mouse cursor. Clicking and dragging selects a rectangular area of the display.

The middle mouse button may be used to paste a selection.

The right mouse button may also be used for selections, selecting the rectangular area between the current position and where the left button was last pressed.

On color displays, the "x3270.selectBackground" resource is used to distinguish the selected text from the rest of the screen. On monochrome displays, selected text is in reverse video. (It can be distinguished from a block cursor because the block cursor covers slightly less than an entire character position on the screen.)

The left mouse button, when pressed with the "Shift" key held down, moves the 3270 cursor to the where the mouse cursor is pointing.

This is the complete list of actions:

MACROS
A simple macro facility is provided via the String action. The arguments to String() are one or more double-quoted strings which are inserted directly as if typed. Hex constants may be entered in the form 0xff, and the C backslash conventions are honored as follows:
    \b | Left
    \f | Clear
    \n | Enter
    \r | Newline
    \t | Tab

An example action would be:
    Meta<Key>p: String("probs clearrdr\n")

Note: The strings are in ASCII and converted to EBCDIC, so beware of inserting control codes.

COMPOSITE CHARACTERS
If your keyboard has a "Compose" key, x3270 allows the direct entry of accented letters and special symbols. Pressing and releasing the "Compose" key, followed by two other keys, causes entry of the symbol combining those two keys. For example, "Compose" followed by the "C" key and the "," (comma) key, enters the "C-cedilla" symbol. A `C' on the status line indicates a pending composite character.

The mappings between these pairs of ordinary keys and the symbols they represent is controlled by the "x3270.composeMap" resource; it gives the name of the map to use. The maps themselves are named "x3270.composeMap.name". The default is "latin1", which gives mappings for most of the symbols in the ISO 8859-1 Latin-1 character set that are not in the 7-bit ASCII character set.

Note: The default keymap defines the "Multi_key" keysym as the "Compose" key. If your keyboard lacks such a key, you may set up your own "Compose" key with a keymap that maps smoe other keysym onto the "Compose" action.

APL SUPPORT
x3270 supports an APL character set and the entry of APL characters from the keyboard.

APL characters are supported by a special font (3270-apl) which replaces the accented characters and special symbols with APL graphics.

Keyboard entry of APL characters is supported through the apl keymap modifier. This modifier defines the "Alt" key as an APL shift key, with a typical APL keyboard layout, e.g., "Alt" pressed with the A key results in the APL `alpha' symbol. Overstruck characters such as `quad-quote' are not defined as single keystrokes; instead they are entered as composites (see COMPOSITE CHARACTERS above). A special composite map, apl, is provided for this purpose.

Note: Some keyboards do not define the "Alt" key as a modifier, so keymaps that use the "Alt" key will not function. On a Sun for example, this can be remedied with the command:

    xmodmap -e "add mod2 = Alt_L"

For convenience, an -apl option is defined, which is an abbreviation for the following resource definitions:
    x3270.emulatorFont: 3270-apl
    x3270.keymap: your_keymap_name,apl
    x3270.charset: apl
    x3270.composeMap: apl

There are a number of APL characters that are similar in appearance to non-APL characters. In particular, the APL `stile', `slope,' `tilde' and `quotedot' characters are similar to the EBCDIC `bar', `backslash,' `tilde' and `exclaim' characters. The APL characters are entered with the "Alt" key, and have slightly different appearances.

The complete list of special APL keysyms is as follows:

    Keysym | EBCDIC Code
    apl_Aunderbar | 41
    apl_Bunderbar | 42
    apl_Cunderbar | 43
    apl_Dunderbar | 44
    apl_Eunderbar | 45
    apl_Funderbar | 46
    apl_Gunderbar | 47
    apl_Hunderbar | 48
    apl_Iunderbar | 49
    apl_Junderbar | 51
    apl_Kunderbar | 52
    apl_Lunderbar | 53
    apl_Munderbar | 54
    apl_Nunderbar | 55
    apl_Ounderbar | 56
    apl_Punderbar | 57
    apl_Qunderbar | 58
    apl_Runderbar | 59
    apl_Sunderbar | 62
    apl_Tunderbar | 63
    apl_Uunderbar | 64
    apl_Vunderbar | 65
    apl_Wunderbar | 66
    apl_Xunderbar | 67
    apl_Yunderbar | 68
    apl_Zunderbar | 69
    apl_alpha | b0
    apl_bracketleft | ad
    apl_bracketright | bd
    apl_circle | 9d
    apl_circlebar | cd
    apl_circleslope | cf
    apl_circlestar | fd
    apl_circlestile | cd
    apl_del | ba
    apl_delstile | dd
    apl_delta | bb
    apl_deltastile | dd
    apl_deltaunderbar | fc
    apl_deltilde | fb
    apl_diaeresis | 72
    apl_diaeresisdot | ec
    apl_diamond | 70
    apl_divide | b8
    apl_downarrow | 8b
    apl_downcaret | 78
    apl_downcarettilde | cb
    apl_downshoe | ab
    apl_downstile | 8e
    apl_downtack | ac
    apl_downtackjot | fe
    apl_downtackup | da
    apl_epsilon | b1
    apl_epsilonunderbar | 75
    apl_iota | b2
    apl_iotaunderbar | 74
    apl_jot | af
    apl_leftarrow | 9f
    apl_leftshoe | 9b
    apl_lefttack | 76
    apl_multiply | b6
    apl_notequal | be
    apl_notgreater | 8c
    apl_notless | ae
    apl_omega | b4
    apl_overbar | a2
    apl_plusminus | 9e
    apl_quad | 90
    apl_quaddivide | ee
    apl_quadjot | 73
    apl_quadquote | de
    apl_quotedot | db
    apl_rho | b3
    apl_rightarrow | 8f
    apl_rightshoe | 9a
    apl_righttack | 77
    apl_slashbar | ea
    apl_slope | b7
    apl_slopebar | eb
    apl_slopequad | ce
    apl_splat | 9c
    apl_squad | cc
    apl_stile | bf
    apl_tilde | 80
    apl_uparrow | 8a
    apl_upcaret | 71
    apl_upcarettilde | ca
    apl_upshoe | aa
    apl_upshoejot | df
    apl_upstile | 8d
    apl_uptack | bc
    apl_uptackjot | ef

BUGS
Cursor highlighting will not work with if you use the NoTitleFocus option in your .twmrc file.

FILES
/usr/lib/X11/app-defaults/X3270
/usr/local/pub/ibm_hosts

SEE ALSO
telnet(1), tn3270(1), ibm_hosts(5)
X Toolkit Intrinsics (R5 version)
Data Stream Programmer's Reference, IBM GA23-0059
Character Set Reference, IBM GA27-3831

AUTHORS
Robert Viduya - SunView based 3270tool
Jeff Sparkes - X11 port
Paul Mattes - X enhancements and fixes