	     XANT - A New TN3270 for the X Window System
			     Version 4.50
			IBM Internal Use Only


Description
-----------
XANT is a telnet client for Unix systems using the X Window System,
version 11.  The full telnet protocol is not implemented.  XANT only
works with a remote host that supports 3270 mode.  To use XANT, your
Unix system must be able to make a TCP/IP connection to a host which
supports the 3270 telnet protocol (e.g. a VM system running the VM
TCP/IP Product, 5798-FAL).

XANT has many features that are not found in the standard telnet
program, such as font switching, mouse support, support for extended
hilighting and colors, 3277 Graphics Attachment emulation, APL
character set support, image processing support, and an application
program interface.  Also, XANT is faster than the standard program,
supports keystroke queueing, and allows tailoring of colors.

Why is it called XANT?  Well, XTN3270 was too many syllables, and I
thought the name XTN should be reserved for a program that supports
the full telnet protocol.  XANT stands for "A New TN3270" with an "X"
in front because it uses the X Window System.


Binary-only installation
------------------------
Executable modules for AIX 2.2.1 on the RT, AIX 1.2 on the PS/2, and
AIX 3.1 on the RISC System/6000 are included in the XANT distribution.
If you only need the executable code and you are running one of those
systems, do the following to install XANT:

AIX RT:

  1) Copy the XANT TARZBIN file from AIXTOOLS to file "xant.tar.Z" on your
     system (be sure to do this in binary mode).

  2) Do "zcat xant.tar.Z | tar -xvf- xantRT" to extract the executable
     module.  The zcat command is part of the BSDCMDS PACKAGE on
     AIXTOOLS.

  3) Do "mv xantRT xant".

  4) Move the executable module (file "xant") into some directory in
     your search path.

  5) If you need the APL fonts, see the section below on "APL fonts"
     for installation instructions.
 
AIX PS/2:

  1) If you are running AIX version 1.2, you will need to apply
     the mpp1007 corrective service before using XANT.  Earlier
     versions of AIX 1.2 have an error in the recv() system call
     which may cause the XANT window to occasionally close for no
     good reason.

  2) Copy the XANT TARZBIN file from AIXTOOLS to file "xant.tar.Z" on your
     system (be sure to do this in binary mode).

  3) Do "zcat xant.tar.Z | tar -xvf- xantPS2" to extract the executable
     module.

  4) Do "mv xantPS2 xant".
	
  5) Move the executable module (file "xant") into some directory in
     your search path.

  6) If you need the APL fonts, see the section below on "APL fonts"
     for installation instructions.


AIX RISC System/6000:

  1) Copy the XANT TARZBIN file from AIXTOOLS to file "xant.tar.Z" on your
     system (be sure to do this in binary mode).

  2) Do "zcat xant.tar.Z | tar -xvf- xant" to extract the executable
     module.

  3) Move the executable module (file "xant") into some directory in
     your search path.

  4) If you need the APL fonts, see the section below on "APL fonts"
     for installation instructions.


Re-building XANT from source
----------------------------
The XANT distribution contains executable modules only for AIX on the
RT, PS/2, and S/6000.  XANT must be re-compiled to use with other Unix
systems.  The following commands can be used to do that:

  1) Do "mkdir xant" to create an empty directory to hold the files.

  2) Do "cd xant".

  3) Copy the XANT TARZBIN file from AIXTOOLS to file "xant.tar.Z" in the
     new directory (be sure to do this in binary mode).

  4) Do "zcat xant.tar.Z | tar -xvf-" to extract the code.

  5) Set up a "make file" for your system.  Make files for IBM Unix
     systems are provided, but for other systems, you may need to
     create a new file.  Here are the files that are included in the
     XANT distribution:

	 Makefile.6000	  For AIX 3.1 on the S/6000
	 Makefile.RT	  For AIX 2.2.1 on the RT
	 Makefile.PVM	  For AIX 2.2.1 on the RT with PVM/PC support
	 Makefile.PS2	  For AIX 1.2 on the PS/2
	 Makefile.370	  For AIX 1.2 on the 370
	 Makefile.BSD	  For ACIS 4.3 on the RT
	 Imakefile	  For use with the imake utility

  6) Do "make -f mmmm" to re-compile XANT, where "mmmm" is the name
     of the make file for your system.

  7) If you need the APL fonts, see the section below on "APL fonts"
     for further instructions.

The standard make file builds XANT without PVM/PC support.  If you
want to include PVM/PC support, you must first install the NETBIOS
PACKAGE (available on AIXTOOLS).  Then use "make -f Makefile.PVM".  The
distributed version of the XANT executable module for the RT was built
this way.

XANT uses the XLookupMapping X function.  If your X11 system doesn't
have this function, you can add a "-DLOOKUP_STRING" to the DEFINES
definition in the Makefile, and XANT will use the XLookupString
function instead.

The X Toolkit must be available to rebuild XANT.  On AIX, the Toolkit
is included with the X product.  XANT also requires the "Athena Widgets"
set, which is distributed with the AIX version of X as sample code.


Command format
--------------

    xant [-help] [-display hostname:number.screen] [-d] [-t] [-ext]
      [-sk] [-ga] [-ar] [-z] [-dw] [-W] [-iconic] [-rv] [-bracket]
      [-altcr] [-wmtitle] [-graphics] [-port port] [-bw border_width]
      [-cols columns] [-rows rows] [-fn normal_font] [-fxn text_font]
      [-fb bold_font] [-fzn zoomed_font] [-fzb bold_zoom_font]
      [-fi icon_font] [-fc foreground_color] [-bc background_color]
      [-pn protected_normal_color] [-pi protected_intense_color]
      [-un unprotected_normal_color] [-ui unprotected_intense_color]
      [-bd border_color] [-ms mouse_color] [-cr cursor_color]
      [-cursor cursor_name] [-scursor special_cursor_name]
      [-gcursor ga_cursor_name] [-geom [width]x[height][[+-]xoff[[+-]yoff]]]
      [-igeom [+-]xoff[[+-]yoff]] [-zgeom zoom_geometry]
      [-gageom 3277ga_geometry] [-imgeom image_geometry]
      [-printcmd command] [-keyfile filename] [-session session_ID_letter]
      [-title window_manager_title] [-nm xant_title]
      [-pvm] [-gateway pvm_gateway] [-secondary secondary_route]
      [-workstation workstation_name] [-adapter lan_adapter_number]
      hostname


A list of the XANT options is given below.  Default values for options
may be specified in a .Xdefaults file.


			     OPTIONS LIST
			     ------------

Flag	  Resource Name	  Meaning			Default	     Type
----------------------------------------------------------------------------
-z	  zoom		  Swap normal and zoomed fonts	off	     Boolean
-ar	  autoRaise	  Auto raise mode		off	     Boolean
-iconic	  iconic	  Start with icon mapped	off	     Boolean
-dw	  deIconifyWarp	  Warp mouse on de-iconify      off	     Boolean
-W	  warp            Warp mouse at startup         off	     Boolean
-rv	  reverseVideo    Reverse video mode            off	     Boolean
-sk	  speckey	  Special key assignments	off	     Boolean
-ext	  extended	  Use extended data streams     on	     Boolean
-bracket  bracket	  Change bracket translation    on	     Boolean
-altcr    altcr		  Use alternate cursor style    off	     Boolean
-wmtitle  wmTitle	  Enable window mgr title bar   on	     Boolean
-ga	  gaSupport	  Include 3277-GA support       on	     Boolean
-graphics graphics	  Include 3179-G style graphics	on	     Boolean
-d	  <none>	  Debug mode			off	     Boolean
-t	  <none>	  Trace I/O to stdout		off	     Boolean

-title	  title		  Window manager title string	host name    String
-nm	  title.title	  Title string for XANT windows	xant + host  String
-port	  port		  Telnet port			23	     Number
-bw	  borderWidth	  Border width			1	     Number
-cols	  cols		  Number of columns		80	     Number
-rows	  rows		  Number of rows		24	     Number
-cursor	  cursor	  Cursor name		        left_ptr     Cursor
-scursor  specialCursor	  Special cursor name	        hand1        Cursor
-gcursor  gaCursor	  Graphics attach cursor name   crosshair    Cursor
-tune	  tune		  Tune to play for alarm	NULL	     String
-keyfile  keyfile	  Keyboard translation file     none         File
-geom	  geometry	  Geometry specification	80x24	     Geometry
-igeom	  iconGeometry	  Icon geometry specification	NULL	     Geometry
-zgeom	  zoomGeometry	  Zoomed window geometry	NULL	     Geometry
-gageom	  gaGeometry	  3277-GA window geometry	NULL	     Geometry
-imgeom	  imageGeometry	  Image window geometry		NULL	     Geometry
-printcmd printCommand	  Command for print screen	NULL	     String
-session  session	  Session ID letter for API	NULL	     String
<none>	  hostname	  Name of remote host		NULL	     String

<none>	  translations	  Translation table		none  	     Tr table
<none>	  gaTranslations  Translation table for 3277-GA	none  	     Tr table
<none>	  imTranslations  Translation table for image	none  	     Tr table

-bg	  background	  Background color		white	     Color
-fg	  foreground	  Foreground color		black	     Color
-bc	  backColor	  3270 window background color	white	     Color
-fc	  foreColor	  3270 window foreground color	black	     Color
-bd	  borderColor	  Border color			black	     Color
-ms	  mouseColor	  Mouse color			black	     Color
-cr	  cursorColor	  Cursor color			black	     Color
-pn	  pnColor	  Protected normal color	cyan	     Color
-pi	  piColor	  Protected intense color	white	     Color
-un	  unColor	  Unprotected normal color	green	     Color
-ui	  uiColor	  Unprotected intense color	red	     Color
<none>	  drawColor	  3277-GA drawing color		white	     Color
<none>	  refreshColor	  3277-GA refresh color		cyan	     Color

<none>	  extDefault	  Extended default color	green	     Color
<none>	  extDefIntense	  Extended default intense	white	     Color
<none>	  extBlue	  Extended blue 		cyan	     Color
<none>	  extRed	  Extended red			red	     Color
<none>	  extPink	  Extended pink			pink	     Color
<none>	  extGreen	  Extended green		green	     Color
<none>	  extTurquoise	  Extended turquoise		turquoise    Color
<none>	  extYellow	  Extended yellow		yellow	     Color
<none>	  extWhite	  Extended white		white	     Color

-fn	  font		  Font name (all windows)	Rom14.500    Font
-fxn	  font		  Font name (text window only)	Rom14.500    Font
-fb	  boldFont	  Bold font name		Bld14.500    Font
-fzn	  zoomFont	  Zoomed font name		Rom22.500    Font
-fzb	  boldZoomFont	  Bold zoomed font name		Rom22.500    Font
-fi	  iconFont	  Icon font name		Rom14.500    Font


The following options are used if PVM/PC support is included:

-pvm		pvm		Use PVM/PC instead of TELNET   off   Boolean
-gateway	gateway		PVM network gateway	   none      String
-secondary 	secondary	PVM secondary route        none      String
-workstation	workstation	Workstation name	   hostname  String
-adapter	adapter		LAN adapter number	   0         Number


When using 3277-GA graphics support on a display with at least five
free color planes, lines styles will be converted to colors using
the following color resources:

    Resource Name   Default Value
    -----------------------------
    drawColor1      White
    drawColor2      Blue
    drawColor3      Green
    drawColor4      Red
    drawColor5      Cyan
    drawColor6      Magenta
    drawColor7      Brown
    drawColor8      Orange
    drawColor9      Grey
    drawColor10     Pink
    drawColor11     LightBlue
    drawColor12     Yellow
    drawColor13     Aquamarine
    drawColor14     Sienna
    drawColor15     Black


When 3179-G style graphics support is enabled, the following
additional color resources will be defined for use in graphics
drawing:

    Resource Name   Default Value
    -----------------------------
    gColor1         Blue
    gColor2         Red
    gColor3         Magenta
    gColor4         Green
    gColor5         Turquoise
    gColor6         Yellow
    gColor7         White
    gColor8         Black
    gColor9         DarkSlateBlue
    gColor10        Orange
    gColor11        Plum
    gColor12        DarkGreen
    gColor13        DarkTurquoise
    gColor14        Wheat
    gColor15        Gray
    gColor16        Brown


Note that the standard X Toolkit -xrm flag can be used to specify
XANT options.  For example:

    xant -xrm "*extTurquoise: cyan" -xrm "*extBlue: #5cf" hostname

Options that have a default value of "on" can be turned off by
specifying "-noxxx" on the command line, where "xxx" is the flag
name.  For example, to disable extended data streams, specify the
"-noext" option on the command line.


Option descriptions
-------------------
ext
    This option specifies that extended data streams should be used.
    This will only work if the host system supports extended data
    streams.  Without extended data streams, only the four basic
    colors can be used, extended hilighting (underline and reverse
    video) won't work, only a limited selection of screen sizes will
    be available, and APL2 special characters will not be recognized.

bracket
    This option changes the output translation table for code points hex
    AD and BD so that they are displayed as square brackets.  On a real
    3179 terminal with Text feature, the square brackets are at code
    points hex BA and BB, but many programs display them using AD and BD
    instead, since that is the EBCDIC definition.

altcr
    This option specifies that the alphanumeric cursor should be a
    reverse-video block rather than an underline.

wmtitle
    This option is used to enable the window manager title bar.  Since
    XANT creates its own title bar, the one that is created by the AIX
    window manager isn't very useful, so it is can be suppressed by
    using the "-nowmtitle" option.  Doing that sets the title string
    to null, which tells the AIX window manager to suppress its title.
    Other window managers might not follow this convention.
   
graphics
    This enables 3179-G style graphics support.  This feature is still
    being developed, so many functions are not supported or work
    incorrectly.  However, it should work well enough to be used with
    many GDDM applications.

tune
    This option changes the tune that is played when the alarm sounds.
    Tune strings are specified as one or more pairs of integers.  Each
    pair specifies the frequency of the note in Hertz and the duration in
    milliseconds.  For example:

	xant -tune "800 30 1600 50 800 30" host

    Beware that with the AIX RT version of X windows (and possibly with
    other versions), the Caps Lock light will be turned off whenever a
    tune is played even though the keyboard stays in Caps Lock state.

printcmd
    This specifies a command to use to print a file when doing the
    print screen function.  If it isn't specified, then the command
    used will be "print -cp", "qprt -c", or "lpr", depending on the
    operating system where XANT is running.  The file containing the
    screen image will be written to the /tmp directory, printed, and
    then erased.  Therefore, be sure to use the proper print command
    option so that the file will be copied before printing.  Otherwise,
    the file could be erased before it is printed.

d
    This option might be useful when trying to debug a problem.  When
    it is specified, additional information messages will be printed
    in some situations.  Normally, XANT detaches itself from the
    controlling terminal shortly after it starts, but it won't do that
    when this option is specified.  Since all error messages are
    written to the standard error device, some messages might not
    appear unless this option is used.

t
    This option requests that trace information be written to the
    standard output device.  Tracing can also be started and stopped
    from the pop-up menu.  Note that, unless the debug (-d) option is
    used, XANT will detach from the controlling terminal shortly after
    starting, thus stopping the trace output.


Menu
----
Clicking the mouse in the title bar will pop up an options menu.  A
plus sign preceding a menu item means that option is enabled.  Moving
the mouse to one of the menu items and releasing it will change the
state of the option.  Available selections are:

     Special Mouse	- Use special mouse button assignments (see below)
     Zoom		- Use alternate font
     Trace		- Trace I/O to stdout (requires debug option)
     3277-GA		- Support 3277-GA graphics
     Quit		- Close the connection and exit


Mouse button assignments
------------------------
Text window, normal mouse mode:
     Left button = set cursor
     Right button = iconify
     Middle button = zoom

Text window, special mouse mode:
     Left button = set cursor, send PF11
     Right button = send PF8
     Middle button = send PF3

Text window, shift key held down;
     Left button down = start of cut
     Left button up = copy to cut buffer
     Right button = paste from cut buffer (affected by APL mode)
     Middle button = copy whole screen to cut buffer

3277-GA window:
     Left button = track cursor
     Right button = refresh window
     Middle button = clear window

Image window:
     Left button = save
     Middle button = delete window


Screen sizes
------------
Without extended data streams, only a limited number of screen sizes
are available because, in the 3270 telnet protocol, the screen size is
specified by passing a terminal type.  The following table lists the
available sizes:

	Width	Height	 Type
	  80      24   IBM-3278-2
	  80      32   IBM-3278-3
	  80      43   IBM-3278-4
	 132      27   IBM-3278-5

If the host system supports extended data streams and uses the Read
Partition Query command to determine the screen size, then arbitrary
screen sizes can be used provided that the XANT extended data streams
option (-ext) is specified.

The smallest possible screen size is 80x24.  If a smaller size is
specified, it will be automatically increased to 80x24.


Keyboard mapping
----------------
The standard AIX telnet key definitions are used, with some additions.
A complete list of the key assignments is given below.  If the special
key assignments option is specified, the function of the Action and
Enter keys is swapped and Pause becomes PA2 instead of Clear.

An APL keyboard mapping is also available and is toggled on and off
using the Ctrl Backspace key combination.  The keyboard layout is as
defined in the "APL2 for the IBM PC User's Guide" (SC33-0600).
Besides that, "Ctrl" shifts of the alphabetic keys produce the APL
underbar characters.  PS/2 users can order APL2 keycaps as a
publication (SX80-0270).

Here are the standard key assignments:

	Function		Key
	------------------------------------------------
	Clear			Pause, Esc
	Enter			Action
	PA1			Ctrl F1, Print Screen, Ctrl Z
	PA2			Ctrl F2, Scroll Lock, Ctrl L
	PA3			Ctrl F3
	Sysreq			Alt Print Screen, Ctrl Print Screen
	Attn			Ctrl Pause

	Reset			Alt Esc, Ctrl G
	Unlock			Ctrl U
	Print Screen		Shift Print Screen
        APL on/off              Ctrl Backspace

	Up			Up Arrow, Ctrl P
	Down			Down Arrow, Ctrl N
	Left			Left Arrow, Ctrl B
	Right			Right Arrow, Ctrl F
	Newline			Enter, Keypad Enter
	Home			Home
	Tab			Tab
	Backtab			Shift Tab, Ctrl A
	End			End, Ctrl E
	Forward word		Ctrl Right Arrow, Alt F
	Backward word		Ctrl Left Arrow, Alt B

	Insert			Insert
	Delete			Delete, Ctrl D
	Kill word		Alt D
	Backspace		Backspace
	Backward kill word	Alt Backspace

	Erase eof		Ctrl End, Ctrl K
	Erase input		Ctrl Delete
	Dup			Alt End
	Field mark		Shift Home
	Cent			Alt C

	PF1			F1, Keypad 1
	PF2			F2, Keypad 2
	PF3			F3, Keypad 3, Ctrl C
	PF4			F4, Keypad 4
	PF5			F5, Keypad 5
	PF6			F6, Keypad 6
	PF7			F7, Keypad 7, Page Up, Alt V
	PF8			F8, Keypad 8, Page Down, Ctrl V
	PF9			F9, Keypad 9
	PF10			F10, Keypad 0
	PF11			F11
	PF12			F12
	PF13			Shift F1
	PF14			Shift F2
	PF15			Shift F3
	PF16			Shift F4
	PF17			Shift F5
	PF18			Shift F6
	PF19			Shift F7
	PF20			Shift F8
	PF21			Shift F9
	PF22			Shift F10
	PF23			Shift F11
	PF24			Shift F12

        Lower left box corner   Shift Keypad 1
        Bottom box tee          Shift Keypad 2
        Lower right box corner  Shift Keypad 3
        Left box tee            Shift Keypad 4
        Box cross               Shift Keypad 5
        Right box tee           Shift Keypad 6
        Upper left box corner   Shift Keypad 7
        Top box tee             Shift Keypad 8
        Upper right box corner  Shift Keypad 9
        Vertical box bar        Shift Keypad 0
        Horizontal box bar      Shift Keypad .

In special key mode:

	Newline			Alt Enter, Action
	PA2			Pause
	Enter			Enter, Keypad Enter


Specifying default values
-------------------------
Resources may be specified in the .Xdefaults file using either the
resource name or the resource class.  The "Resource Name" column in the
options list shows the resource name.  The class name is generally the
same as the resource name with the first letter changed to upper case.

Here are some simple examples of .Xdefaults entries:

    xant*speckey: on
    xant*pnColor: sky blue
    xant*Rows: 32

More complex resource specifications are also possible.  For example,
you can set the title bar background and the popup menu background to
different colors like this:

    xant*title.background: light blue
    xant*menu.box.background: slate blue

See the section of the X documentation on "Using the Resource Manager"
for further details on how to specify resources.  See Appendix A for
a description of XANT's resource hierarchy.


Sample default settings
-----------------------
XANT is distributed with defaults set so that it will work on most
systems.  However, these aren't necessarily the best settings to use.
Here are some sample .Xdefaults file entries:

    xant*speckey: on
    xant*autoRaise: on
    xant*deIconifyWarp: on
    xant*backColor: #444
    xant*rows: 32
    xant*tune: 800 10 1200 10 1600 10
    xant*pnColor: #5cf
    xant*extBlue: #5cf
    xant*extRed: #f22
    xant*extTurquoise: cyan
    xant*x3270.font: Rom22.500
    xant*x3270.boldFont: Rom22.500
    xant*x3270.zoomFont: Rom10.500
    xant*x3270.boldZoomFont: Rom10.500
    xant*ga3270.backColor: #116
    xant*gaGeometry: 768x600-100-0
    xant*MenuBtn.Background: light blue
    xant*MenuBtn.Font: Rom14.500


Tailoring the keyboard
----------------------
Mapping can be changed by specifying the "-keyfile" option with the
name of a translation table file.  Standard X Toolkit translation
tables are used.  See the X Toolkit documentation section on
"Translation Table File Syntax" for a complete description of 
the syntax (e.g. see the IBM AIX X-Windows Programmer's Reference,
SC23-2118, pages 4-77 to 4-84, or search for "translation table
file" using InfoExplorer).

An example of a translation table is shown below.  Other examples
are supplied in the XANT distribution in files sample.keyfile and
sample.aplkeys.  

     Ctrl<Key>Right:	forward-word()
     Alt<Key>F:		forward-word()
     <Key>Right:	right()
     Ctrl<Key>F:	right()
     Alt<Key>W:         omega()
     Shift<Key>Tab:	backtab()
     Ctrl<Key>A:	backtab()
     <Key>KP_Enter:	clear() enter() string("LOGON JOE") enter()


Translations can also be specified in a .Xdefaults file.  For example:

xant*x3270.translations: #override \
   Ctrl<Key>w: erase-input() \n\
   Alt<Key>x: string("#CP DISC HOLD") enter()


If the APL keyboard is to be used you must take care that keyboard
mapping changes that you make (using -keyfile or .Xdefaults) do not
interfere with the APL keyboard definitions.  Consider this example:
     Ctrl<Key>A:        backtab()
Because of the way the translation manager operates, this statement
will cause "Ctrl A" to be "backtab" for both the standard and the APL
keyboards (overlaying the APL meaning of "Ctrl A" as "a-underbar").
For the mapping change not to affect the APL keyboard it should be
specified as:
     ~Mod3 Ctrl<Key>A:  backtab()
Alternatively, you could re-specify the APL meaning AHEAD of the non-APL 
meaning:
     Mod3 Ctrl<Key>A:   a-underbar()
     Ctrl<Key>A:        backtab()


A list of the key names that may be used on the left-hand side of a
translation can be found in file /usr/include/X11/keysymdef.h (leave
out the "XK_"part).  Also, the command "xmodmap -pk" may be used to
display the keyboard table (xmodmap is distributed with the AIX
version of X as sample code).

Functions that may be used on the right-hand side of a translation are:

    pf1 to pf24, clear, enter, pa1, pa2, pa3, sysreq, attention, reset,
    unlock, print-screen, up, down, left, right, newline, home, tab,
    backtab, end, forward-word, backward-word, aplonoff, insert, delete,
    backspace, kill-word, backward-kill-word, erase-eof, erase-input, dup,
    upper-left-box-corner, upper-right-box-corner, lower-left-box-corner,
    lower-right-box-corner, top-box-tee, bottom-box-tee, left-box-tee,
    right-box-tee, box-cross, horizontal-box-bar, vertical-box-bar,
    modlock, field-mark, cent, string, stringa, hex, hex-ge, system, 
    and many APL character names.


Function descriptions
---------------------
string
    The "string" function passes the character string specified as
    the function argument to the host as if it were keyboard input.
    Characters will be translated from ASCII (Code Page 850) to EBCDIC
    (Code Page 37).

stringa
    The "stringa" function is similar to the "string" function above,
    but translates ASCII-APL (Code Page 910) to EBCDIC-APL2/TN (Code Page
    310).  ASCII characters which are not APL characters are translated
    just as for the "string" function.  ASCII characters which are
    used as APL/Text characters appear on the host as EBCDIC-APL/Text
    characters when stringa() is used.  (You could use stringa() to
    implement a "Text" keyboard under XANT.)

hex
    This function translates its parameter from hex to binary and sends
    it to the host as keyboard input.  For example, "hex(C1C2C3)" would
    type in "ABC".

hex-ge
    This function is the same as the "hex" function except that the
    characters it sends are preceded by a Graphic Escape order.

system
    This function will run the specified Unix command.

aplonoff
    This function is used to toggle APL keyboard behavior.  When used
    with no arguments (e.g. "aplonoff()") its only action is to toggle
    the "cut/paste" operation so that APL characters are pasted
    correctly.  This might be useful for an APL "union" keyboard where
    you only want to change cut/paste and not the keyboard mapping
    itself.  Some ASCII characters have both an APL and non-APL use.
    The "!" character for example, will be pasted as an exclamation
    point when APL-cut/paste is off.  It will be pasted as the APL
    "quote-dot" character when APL-cut/paste is on.

    The "aplonoff" function can also be called with a numeric argument.
    The default assignment of Ctrl Backspace is "aplonoff(3)".
    When used with a numeric argument it does three things:
       1) It toggles the APL cut/paste operation.
       2) It toggles the "APL" indicator in the XANT title bar.
       3) It calls the "modlock" function with the same numeric parameter
          as an argument.  Refer to the description of "modlock" below.
          The effect of this is to turn on the APL keyboard mapping.

modlock
    This function can be used to create additional keyboard states
    which are "locked" (i.e., similar to Caps Lock in that no key has to
    be held down to maintain the state).  It does this by toggling on
    or off the "Modn" modifier bit, where "n" is the argument passed to
    modlock.  For example, pressing Ctrl Backspace causes a call to
    "modlock(3)".  After this call, all translation lookups are done
    with the "Mod3" modifier bit on.  Calling "modlock(3)" again
    toggles the state so that the "Mod3" modifier is off again.

    As an example, XANT's default translation table has a statement
    like this:

        Mod3 Shift<Key>8: not-equal()

    This specifies that the Shift-8 key should produce an APL "not-equal"
    character when the APL keyboard (Mod3) is active.

    The "Modn" modifier bits are currently used as follows:
       - Mod1:  Is the same as the "Alt" modifier (AIX X server default)
       - Mod2:  Available
       - Mod3:  Available -- XANT's default translation tables assign
                    APL characters to the Mod3 shift
       - Mod4:  Available
       - Mod5:  Indicates the state of "Num Lock" (AIX X server default)

    So, for example, you could use Mod4 (via "modlock(4)") to implement
    a "Text" keyboard under XANT.

"APL character name" functions
    91 functions are available for the APL characters.  The names used
    are the "Symbol Name" given in Appendix A of "APL2 Programming
    Language Reference" (SH20-9227).  If the symbol name has more than
    one word, the words should be joined with a hyphen to get the
    function name (e.g. "up-arrow").  Several symbol names exist which
    are also standard characters (such as "plus").  APL character name
    functions do NOT exist for these standard characters.

    Besides the symbol names listed in the APL2 reference, 29 other
    function names are defined.  They are "diamond", "left-tack",
    "right-tack", and the 26 underscored alphabet characters (e.g.
    "a-underbar"). 

    A sample file named "sample.aplkeys" is included in the xant.tar.Z
    distribution file.  This file uses all the APL character name
    functions.  It can be used to create an APL "union" keyboard.


Tailoring mouse buttons
-----------------------
The "translations" resource or the keymap file can also be used to
change the mouse button assignments.  For example, the following
entries could be placed in a keymap file:

     Ctrl<Btn1Down>:	select-start()
     Ctrl<Btn1Motion>:	select-adjust()
     Ctrl<Btn1Up>:	select-end()

Functions that may be used on the right-hand side are:

    select-start, select-adjust, select-end, select-all,
    insert-selection, zoom, iconify, set-cursor, special1,
    special2, special3, ga3277-clear, ga3277-refresh,
    ga3277-set-cursor, image-save, image-destroy

Note that these functions can also be assigned to keys.  Likewise,
keyboard functions can be assigned to mouse buttons.


APL fonts
---------
The following APL fonts are included with XANT:

    apl6   apl10   apl12   apl14   apl17   apl22

These are Roman style fonts conforming to IBM Code Page 910.  In most
cases they can be used successfully for normal terminal operation as
well as for APL operation.  The most noticeable exceptions to this are
the "cent" symbol (which appears as an APL left arrow) and some of the
accented alphabetic characters.

To use the APL fonts, you must first install them on your X server
using the procedure below.  Then you must use the font options on the
command line (or in .Xdefaults) to request that the APL fonts be used.
Here is an example:

    xant -fxn apl14 -fzn apl22 hostname

On the RT, the font naming convention is to append a ".500" to the
font name to indicate the density factor.  Therefore, on the RT, the
APL fonts are named apl6.500, apl10.500, etc.


Installation on AIX RT:

  1) Do "zcat xant.tar.Z | tar -xvf- fonts-RT" to create a "fonts-RT"
     directory containing the APL font files.  The zcat command is part
     of the BSDCMDS PACKAGE on AIXTOOLS.

  2) Do "cp -r fonts-RT/apl* /usr/lpp/fonts" to copy the font files
     to the system fonts directory.

  3) Do "cd /usr/lpp/fonts; /usr/lpp/X11/bin/mkfontdir" to add the new
     APL fonts to the font directory file (fonts.dir).

  4) Restart the X server so that it will recognize the new fonts.


Installation on AIX PS/2:

  1) Do "zcat xant.tar.Z | tar -xvf- fonts-PS2" to create a "fonts-PS2"
     directory containing the APL font files. 

  2) Do "cp -r fonts-PS2/apl* /usr/lpp/X11/lib/fonts/misc" to copy the
     font files to the system fonts directory.

  3) Do "cd /usr/lpp/X11/lib/fonts/misc".

  4) Do "echo 'FILE_NAMES_ALIASES' >> fonts.alias" so that file names will
     be acceptable as font names.

  5) Do "/usr/lpp/X11/bin/mkfontdir" to add the new APL fonts to the font
     directory file (fonts.dir).

  6) Restart the X server so that it will recognize the new fonts.


Installation on AIX RISC System/6000:

  1) Do "zcat xant.tar.Z | tar -xvf- fonts-6000" to create a "fonts-6000"
     directory containing the APL font files. 

  2) Do "cp -r fonts-6000/apl* /usr/lib/X11/fonts" to copy the font files
     to the system fonts directory.

  3) Do "cd /usr/lib/X11/fonts".

  4) Do "/usr/lpp/X11/bin/mkfontdir" to add the new APL fonts to the font
     directory file (fonts.dir).

  5) Restart the X server so that it will recognize the new fonts.


For systems other than AIX RT, AIX PS/2 and AIX 6000, standard Bitmap
Distribution Format (BDF) files are supplied for the APL fonts.  To
retrieve these from the XANT distribution file, do the following:

    zcat xant.tar.Z | tar -xvf- apl6.bdf apl10.bdf apl12.bdf \
				apl14.bdf apl17.bdf apl22.bdf

These files must be converted to the X server's private format before
they can be used.  Each operating system is supposed to provide a
command for converting from BDF format to the format used by the X
server for that system.  For example, the X server on AIX PS/2 uses
Server Natural Format (SNF) and provides a "bdftosnf" command to
convert fonts.  The AIX RT server uses RTX format and provides a
"bdftortx" command.

The fonts must be made available to the X server either by placing
them in the standard system directories or by making whatever
directory the fonts are in part of the X server's "font path".
Specifying the font path can usually be done at invocation of the X
server or by using the X distribution sample client "xset".  "xset q"
shows server defaults and "xset fp" dynamically alters the font path.
The only disadvantage to using the default directory is the chance
that new X11 maintenance will replace it.  The disadvantage to using
multiple directories is that you have to alter X invocation procedures
or learn how to use xset.


Application program interface
-----------------------------
XANT has an application program interface which is designed to be
compatible with the OS/2 Emulator High-Level Language Application
Programming Interface (EHLLAPI).  This interface is documented in the
EHLLAPI Programming Reference (S01F-0266).  XANT supports only a
subset of the EHLLAPI functions.  See Appendix C for a list of what is
supported. 

To use the application program interface, a program must be linked
with the libxant.a file which is included in the xant.tar.Z
distribution file.  File "hapi_c.h" is also included.  It has
symbolic definitions for the EHLLAPI functions and return codes.

To have an application connect with XANT, the "-session" option must
be used when XANT is started.  The session ID letter given in the
"-session" option to XANT must match the one used by the Connect
Presentation Space (HA_CONNECT_PS) call in the application program.

The libxant.a file in the distribution was built for the Risc
System/6000 version of AIX.  For AIX on the RT or PS/2, get
libxant.a-RT or libxant.a-PS2 from the distribution and rename it to
libxant.a.  For other systems, libxant.a must be rebuilt from source.

Here is a sample program which calls the application program interface:

	#include <string.h>
	#include "hapi_c.h"
	main()
	{
	  int function, data_length, rc;
	  char data_string[100];

	  function = HA_CONNECT_PS;
	  data_string[0] = 'a';
	  data_length = 1;
	  hllc(&function, data_string, &data_length, &rc);
	  if (rc != HARC_SUCCESS) exit(1);

	  function = HA_SENDKEY;
	  strcpy(data_string, "@C@EMSG * Testing@E");
	  data_length = strlen(data_string);
	  hllc(&function, data_string, &data_length, &rc);
	  if (rc != HARC_SUCCESS) exit(1);

	  function = HA_DISCONNECT_PS;
	  hllc(&function, data_string, &data_length, &rc);

	  return rc;
	}


XANT orders
-----------
Some XANT functions can be performed by a host program by writing
data starting with the special XANT order code hex 2B5C.  The
functions currently defined are:
	
	String		Function
	--------	----------------------------
	2B5C0100	Set normal mouse mode
	2B5C0101	Set special mouse mode

	2B5C0201	Initialize image window
	2B5C0202nn	Load pre-defined color look-up table
	2B5C0203dd...  	Load color look-up table from data
	2B5C0204dd...	Write data to image window
	2B5C0205nn	Use a new color map for the next look-up table

The XANTIAX PACKAGE (available on AIXTOOLS) uses the XANT image
processing functions enabling XANT users to display images in an X
window using the IAX product on VM.

Here is an example of a REXX exec to set the mouse mode, using the
XANTSTR command (part of XANTIAX PACKAGE):

    /* Set XANT mouse mode */
    Address COMMAND
    Arg mode
    mode = strip(mode)
    setmouse = '402B5C01'
    If abbrev('SPECIAL', mode) then 'XANTSTR' setmouse'01'
    Else 'XANTSTR' setmouse'00'

Using the set mouse exec, another exec can be written that will set
special mouse mode, call FILELIST or RDRLIST, and then set normal
mouse mode again.  This would let you use the mouse to select files.


Acknowledgements
----------------
Thanks to Michael Goodfellow for providing me with the 3277-GA
emulation code he wrote for the Quicksilver operating system that I
was able to adapt for XANT, and to Marc Kaplan for giving me good
3277-GA translate tables.  Also, thanks to Edie Gunter for writing code
to support PVM/PC gateways.  Thanks to John Gerth and Barry Dorfman
for doing the APL support, and to Norm Brenner for the APL fonts.


Appendix A - Resources
----------------------
Here are the prefixes of the resource names used by XANT:

    Top level window:
	xant
	xant.form

    Title bar:
	xant.form.title

    Popup menu:
	xant.form.title.menu
	xant.form.title.menu.box
	xant.form.title.menu.box.menubutton

    Main text window:
	xant.form.x3270

    3277-GA graphics window:
	xant.ga3270

    Image window:
	xant.im3270


The class names for the resources given above are:

    Resource    Class name
    --------	----------------
    xant	ApplicationShell or TopLevelShell
    menu	OverrideShell
    form	Tform
    box		Box
    menubutton	MenuBtn
    title	Title3270
    x3270	X3270 or Gr3270
    ga3270	Ga3270
    im3270	Im3270

Resources available everywhere:
	background, borderColor, borderWidth, width, height, x, y,
	translations

Resources for shells:
	geometry

Resources for title:
	foreground, font, title, cursorColor, cursor, internalWidth,
	internalHeight

Resources for xant application:
	extended, bracket, altcr, gaSupport, wmTitle, graphics, port,
	title, iconGeometry, zoomGeometry, gaGeometry, imageGeometry,
	printCommand, session, hostname, pvm, gateway, secondary,
	workstation, adapter

Resources for x3270, ga3270, or im3270:
	foreground, backColor, foreColor, mouseColor, cursor, speckey,
	keyfile

Resources for x3270:
	cols, rows, pnColor, piColor, unColor, uiColor, extDefault,
	extDefIntense, extBlue, extRed, extPink, extGreen, extTurquoise,
	extYellow, extWhite, gColor1-16, cursorColor, font, boldFont,
	zoomFont, boldZoomFont, iconFont, autoRaise, warp, deIconifyWarp,
	zoom, tune, specialCursor

Resources for ga3270:
	drawColor, drawColor1-15, refreshColor, gaCursor, gaTranslations

Resources for im3270:
	imTranslations


Appendix B - Deviations from 3270 architecture
----------------------------------------------
1) XANT doesn't lock the keyboard.  If the host system isn't accepting
   input, keystrokes are queued until the system is ready for them or
   until the reset key is pressed.

2) The cursor changes to a double bar when the host system isn't
   accepting input.

3) Attempting to enter data into a protected field or insert data into
   a filled field just dings the bell and does not lock the keyboard
   until reset is pressed.

4) When inserting data into a field, trailing blanks will be deleted
   at the end of the field if necessary (not just trailing nulls).

5) When a field is modified, all nulls that are not at the end of the
   field are converted to spaces.

6) Backspace is destructive.  It not only moves the cursor left, but
   also deletes the previous character.

7) Blink isn't supported.

8) Support for structured fields is limited.  The supported outbound
   structured fields are:  Read Partition, Erase/Reset, Set Reply
   Mode, and Outbound 3270DS.  Read Partition Query List is not
   supported. 

9) Invalid or unsupported orders are ignored rather than rejected
   because the telnet protocol does not provide a way for a client
   program to pass back sense code information to the host.

10) 3179-G graphics support is still being developed, so many functions
    are not supported or work incorrectly.


Appendix C - Application program interface support
--------------------------------------------------
XANT supports only a subset of the EHLLAPI functions.  The supported
functions are:

	Connect Presentation Space
	Convert Position or Row Column
	Copy Field to String
	Copy PS to String
	Copy Presentation Space
	Copy String to Field
	Copy String to PS
	Disconnect Presentation Space
	Find Field Length
	Find Field Position
	Query Cursor Location
	Query Field Attribute
	Query Session Status
	Query Sessions
	Query System
	Reset System
	Search Field
	Search Presentation Space
	Send Key
	Set Cursor
	Set Session Parameters
	Wait

For the Set Session Parameters function, XANT supports only the
following session options:

	STRLEN / STREOT
	EOT
	SRCHALL / SRCHFROM
	SRCHFRWD / SRCHBKWD
	ESC
	AUTORESET / NORESET
	TWAIT / LWAIT / NWAIT
	
---------------------------------------------------------------------

Tom Engelsiepen (ENGELSPN at ALMADEN)
IBM Research Division
Almaden Research Center
