<HTML>
<TITLE>x3270 Frequently Asked Questions</TITLE>
<H1>x3270 Frequently Asked Questions</H1>

If you have a problem building, installing, or running x3270, please browse
through this file first.

<H2>GENERAL QUESTIONS</H2>

<H3>Am I allowed to use it?</H3>

    Yes.  Full copyright information is in the
    <A HREF="Lineage.html">Lineage</A> file, but the gist
    is that anyone is free to use the code, but not to sell it.  This was
    not clear in earlier versions of x3270, but it is explicit here.
<P>
    You are also free to modify it and to distribute it, provided you include
    the existing copyright notices, and don't profit from it.

<H3>How can I tell if I'm running X11R4, X11R5 or X11R6?</H3>

    This is defined in the header file <X11/Intrinsic.h>.  Assuming your X
    header files are in /usr/include, you can find out with:
<PRE>
    grep XtSpecificationRelease /usr/include/X11/Intrinsic.h
</PRE>
    (You may need to use a different path name if your header files are
    somewhere else.)
<P>
    If you are running X11R4, the answer will be:
<PRE>
    #define XtSpecificationRelease 4
</PRE>
    If R5:
<PRE>
    #define XtSpecificationRelease 5
</PRE>
    If R6:
<PRE>
    #define XtSpecificationRelease 6
</PRE>

<H2>FATAL ERRORS FROM 'make'</H2>

<H3>Make reports: Fatal error: Don't know how to make target `FontObj(3270)'.</H3>

    This generally means that you are running X11R4, rather than X11R5 or
    X11R6.  The procedure for building x3270 under X11R4 is explained in
    the "Build" document.
<P>
    (Carefully note the differences in build procedures between Sun OpenWindows
    and other operating systems -- or you'll end up back here anyway.)

<H3>Make reports: "Don't know how to make 3270.snf.  Stop."</H3>

    This is usually a symptom of running a hybrid X implementation -- one that
    is based on X11R4 but uses some of the later font conventions.  Assuming
    you have already renamed Imakefile.R4 to Imakefile, what you need to do is
    to edit Imakefile and change every occurrence of ".snf" to ".pcf".  Then
    try again with xmkmf.

<H2>FATAL COMPILE ERRORS</H2>

<H3>Undefined symbols on a Sun:</H3>
<PRE>
    _get_wmShellWidgetClass
    _get_applicationShellWidgetClass
</PRE>
    This is a bug in Sun's X11 libraries, and can be corrected by obtaining
    patches 100512-02 and 100573-03 from Sun.  As a short-term workaround,
    edit Makefile.openwin; there is a line you can uncomment for just this
    purpose.

<H3>Undefined symbols on System V, Release 4</H3>
<PRE>
    _connect
    _gethostbyname
    _getservbyname
    _setsockopt
    _shutdown
    _socket
</PRE>

    Network calls are in a separate library on SVR4 systems.  You need to
    umcomment the line in the Imakefile that begins "#EXTRA_LIBRARIES",
    then try again with xmkmf.

<H2>COMPILER WARNINGS</H2>

<H3>My C compiler says you're calling an X function wrong.</H3>

    For example, on SGI Irix 4.0.1 with X11R4:
<PRE>
    ccom: Warning: x3270.c, line nnn: Argument 5 Type Doesn't Match
     prototype description; prototype: pointer to unsigned int is different
     from actual: pointer to int
		0);
	  -------^
</PRE>

    The prototype arguments for XtVaAppInitialize in <X11/Intrinsic.h> changed
    between X11R4 and X11R5.  x3270 uses the newer version, but will work just
    fine with R4.  You can ignore the warning.  Other compiler warnings are
    indeed of interest and should be reported.

<H2>WARNINGS FROM x3270</H2>

<H3>x3270 reports: "Warning: emulatorFont '3270' doesn't exist, using default
		font"</H3>

    One of the trickier areas; x3270 uses its own fonts to replicate a
    life-like IBM 3270.  This is not fatal, however; x3270 can use any fixed-
    width X font.  If it can't find its own font, it defaults to "fixed".
<P>
    The simplest probem to fix is that you haven't told your X server that
    there are new fonts it can use.  This is corrected with:
<PRE>
    xset fp rehash
</PRE>
    If this doesn't help, it is possible that your X server font path doesn't
    include the directory that the 3270 fonts were installed in.  Run the
    command "xset q".  The output will include an entry like:
<PRE>
    Font Path:
      /usr/lib/X11/fonts/misc/,/usr/lib/X11/fonts/Speedo/,/usr/lib/X11/fonts/75dpi/,/usr/lib/X11/fonts/100dpi/
</PRE>
    x3270's fonts are usually installed in /usr/lib/X11/fonts/misc.  If this
    (or some variation on it) does not appear in the "xset q" output, you can
    try:
<PRE>
    xset fp+ /usr/lib/X11/fonts/misc/
    xset fp rehash
</PRE>
    (Note that on Sun OpenWindows prior to version 3.3, the only directory in
    your font path is usually /usr/openwin/lib/fonts, and there is no "misc"
    directory to add to your path.)

<H2>STRANGE 3270 BEHAVIOR</H2>

<H3>Why does my keyboard lock with that funny "X" symbol at the bottom?</H3>
You have discovered that 3270 displays are rather different
from standard ASCII terminals.  <B>x3270</B> attempts to emulate a real
3270 display as closely as possible; this can be rather disconcerting to
people who are used to simple ASCII terminals or terminal emulators.
<P>The "X" symbol means that the keyboard is locked.  This can be
locked for any of the following reasons:
<UL>
<LI>The host has not finished processing your last command.
<LI>You attempted to type into a protected area of the screen.
<LI>You typed too many characters into a field in Insert mode.
</UL>
If the keyboard is locked for the first reason, your only recourse is to
wait.  However, you may type ahead.  If the keyboard is locked for one of
the other two reasons, you can press the 3270 <B>Reset</B> key (usually
mapped to <B>Alt-r</B>) to unlock it.

<H3>Why doesn't Insert turn off Insert Mode?</H3>
Because that's how real 3270s work.
<P>Pressing the <B>Insert</B> key (<B>Alt-i</B> or the <B>Insert</B> key if
your keyboard has one) puts x3270 into Insert mode.  Pressing it again
does not disable Insert mode; to do that you must use <B>Reset</B>.
<P>There is an alternate <B>x3270</B> action you can bind to the <B>Insert</B>
key, <B>ToggleInsert()</B>, to change that behavior.

<H3>This field has lots of empty space.  Why can't I insert into it?</H3>
You can only insert characters into a field that has empty space at the
end.  Depending on the application you are running on the host, the
<I>apparently</I> empty space at the end of a field can either be NULL
characters (which truly are empty space), or SPACE characters (which are not).
Unforturnately, NULLs are indistinguishable from SPACEs on the screen, so
often a simple attempt to insert a character results in a locked keyboard.
<P><B>x3270</B> has a configurable option, "Blank Fill", which disables this
"3270 warts-and-all" emulation behavior.

<H2>SUBTLE PROBLEMS</H2>

<H3>x3270 isn't paying any attention to my keymap definition.</H3>

    There are two likely causes for this problem: either x3270 isn't seeing
    your keymap definition, or there is something wrong with the definition
    itself.
<P>
    You can tell exactly which keymap and keymap modifiers x3270 is using with
    the "About x3270" option on the "Options" menu.  There is an entry labeled
    "Keyboard map:" which lists the keymap(s) in effect.  If yours is missing,
    there are a number of possible causes:
<UL>
<LI>
    There is a hierarchy of places that x3270 looks for the keymap list,
      and the one you are assuming may not be the one it finds.  In the
      following list, earlier objects override those below:
<UL>
	<LI>The -keymap swicth on the command line.
	<LI>The definition of "x3270.keymap" in your .Xdefaults file.
	<LI>The KEYMAP environment variable.
	<LI>The KEYBD environment variable.
</UL>
    <LI>You may have modified your .Xdefaults file, but not yet re-read the
      database.  You can either log off of X and start over, or you can run
      the command:
<PRE>
	xrdb $HOME/.Xdefaults
</PRE>
    <LI>Beware that there are some subtle interactions between .Xdefaults and
      cpp on your system.  On a sun4 for example, cpp defines the symbol "sun"
      as "1", so a keymap definition for "sun-k4" becomes "1-k4".

    <LI>A keymap definition is in two parts, the name of the keymap and the
      definition of the keymap.  The "x3270.keymap" resource controls the name
      of the keymap; then for each keymap type "x" there must be an additional
      resourced named "x3270.keymap.x".  If this definition is missing, x3270
      will not recognize the keymap.
<LI>
    One other cause of missed keymaps is the symbol "sun" defined by the
    C preprocessor.  If you have an entry in your .Xdefaults file that looks
    like:
<PRE>
	x3270.keymap: sun-k5
</PRE>
    then use xrdb to read in the file, the symbol "sun" may be defined as
    "1" as the file is read.  This turns the above into:
<PRE>
	x3270.keymap: 1-k5
</PRE>
    causing much confusion.
<P>
    The fix is to add the following line to the top of your .Xdefaults:
<PRE>
	#undef sun
</PRE>
</UL>
    If your keymap appears in the list, but doesn't seem to have any effect,
    the causes are probably more subtle.  Keymap definitions (X translation
    tables) are an object of study in themselves; the O'Reilly books (volume 4
    in particular) are your best guide here, along with a thorough reading of
    the "Resources" document.

<H3>The "Alt" key doesn't work.</H3>

    If the "A" appears on the status line when you press the Alt key, but
    none of the key mappings that use Alt seem to work (i.e., the APL keys),
    perhaps your X server isn't configured with Alt as a modifier.  Try
    the following xmodmap command:
<PRE>
	xmodmap -e 'add Mod2 = Alt_L'
</PRE>
    If this fixes the problem, you can add it to your .xinitrc file, so it
    takes effect every time your start X.

<H3>x3270 is misbehaving on a certain application.</H3>

    If x3270 produces a different display or interaction than a real 3270 or
    some other emulator, it is entirely possible that x3270 is at fault.
    What you can do to help debug it is to capture a trace of the session.
    The easiest way to do this is:
<PRE>
    x3270 -trace
</PRE>
    x3270 will create a trace file in /usr/tmp, which will contain a dump of
    all of the data that x3270 sent or received, along with its interpretation.
    x3270 will also pop up a window to view the file while it is being created;
    the title of that window is the full pathname of the trace file.  If you
    are familiar with the 3270 Data Stream protocol, you may be able to figure
    out the problem yourself; otherwise, after suitable editing to remove
    passwords and proprietary information, you may send it in (see below).

<H3>I can't get Num Lock to work on my Sun keyboard.</H3>

    If you are using an X server based directly on the MIT distribution (the
    NumLock light does not turn on when you press the NumLock key), then you
    are pretty much stuck; your server does not support NumLock.  (However,
    you can get the keypad to produce numbers by holding down the Shift key.)

<H3>There is no termcap entry for "IBM-3278-xxx"</H3>

    If you log into a non-IBM host with x3270, your TERM variable will be
    set to "IBM-327x", which is not especially useful for running programs
    like vi.
<P>
    One solution is to set your TERM variable to "xterm" after you log in,
    and to set the number of lines and columns to match the current x3270
    model number (this is done through the "stty" command or with environment
    variables, depending on your system).
<P>
    A second solution is to create termcap entries for the 3270 terminal
    types.  Here are some sample entries:
<PRE>
    I2|IBM-3278-2|x3270 Emulating 3278-2:li#24:tc=xterm:
    I3|IBM-3278-3|x3270 Emulating 3278-3:li#32:tc=xterm:
    I4|IBM-3278-4|x3270 Emulating 3278-4:li#43:tc=xterm:
    I5|IBM-3278-5|x3270 Emulating 3278-5:li#27:co#127:tc=xterm:
</PRE>

<H3>My screen isn't being drawn properly</H3>

    There is a bug in certain versions of the Linux Mach32 X server, which
    causes the x3270 screen to be drawn incompletely.  The screen image can
    be restored by iconifying and un-iconifying the window.
<P>
    x3270 can be modified to work around this problem.  An unfortunate
    side-effect is that it will no longer be able to display APL characters,
    or line-drawing characters with any of the 3270 fonts.
<P>
    To rebuild x3270 to work around this bug, edit the Imakefile and add a
    line at the top:
<PRE>
    EXTRA_DEFINES = -DBROKEN_MACH32
</PRE>
    Then rebuild the makefile, the module "screen.o", and x3270:
<PRE>
    rm screen.o
    xmkmf
    make depend
    make
</PRE>

<H2>OTHER COMMON QUESTIONS</H2>

<H3>Can I move the 3270 cursor with the mouse?</H3>
Yes, hold down the <B>Shift</B> key while pressing the left mouse button.

<H2>GETTING HELP</H2>

    If you are still having a problem with x3270, feel free to send e-mail to
    Paul Mattes, <B>x3270@cnt.com</B>.  No guarantees are made about responses to
    particular problems, but a patches are usually forthcoming in a few days.
    It will also get you on an x3270 mailing list, where you can find out
    about new releases and bug fixes.
<P>
    When you send a question about x3270, please include the following
    information.  It makes it much easier to narrow down the problem.
<OL>
    <LI> The version of x3270 you are using, including all patches, e.g.,
        "3.1.0.0".  This is displayed at the top of the "About x3270" pop-up.

    <LI> What kind of machine you are running on, e.g., "Sun SPARC-10".

    <LI> What operating system you are running, and what version, e.g., "SunOS
       4.1.3_U1" or "Irix 5.2".  The "uname -a" command will usually provide
       this information.

    <LI> What version of X Windows you are running, and where it came from, e.g.,
        "X11R6 built from the MIT distribution", or "Sun OpenWindows 3.0 as
        delivered with the machine".
</OL>
    Complaints, suggestions, requests for enhancements, and porting experiences
    are also welcome.  Code changes for bug fixes and enhancements are also
    welcome, provided that you don't mind your code being placed (often
    anonymously) in the public domain.
