x3270 Frequently Asked Questions

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

GENERAL QUESTIONS

Am I allowed to use it?

Yes. Full copyright information is in the Lineage 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. 

You are also free to modify it and to distribute it, provided you include the
existing copyright notices, and don't profit from it. 

How can I tell if I'm running X11R4, X11R5 or X11R6?

This is defined in the header file . Assuming your X header files are in
/usr/include, you can find out with: 

    grep XtSpecificationRelease /usr/include/X11/Intrinsic.h

(You may need to use a different path name if your header files are
somewhere else.) 

If you are running X11R4, the answer will be: 

    #define XtSpecificationRelease 4

If R5: 

    #define XtSpecificationRelease 5

If R6: 

    #define XtSpecificationRelease 6

FATAL ERRORS FROM 'make'

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

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. 

(Carefully note the differences in build procedures between Sun
OpenWindows and other operating systems -- or you'll end up back here
anyway.) 

Make reports: "Don't know how to make 3270.snf. Stop."

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. 

FATAL COMPILE ERRORS

Undefined symbols on a Sun:

    _get_wmShellWidgetClass
    _get_applicationShellWidgetClass

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. 

Undefined symbols on System V, Release 4

    _connect
    _gethostbyname
    _getservbyname
    _setsockopt
    _shutdown
    _socket

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. 

COMPILER WARNINGS

My C compiler says you're calling an X function wrong.

For example, on SGI Irix 4.0.1 with X11R4: 

    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);
          -------^

The prototype arguments for XtVaAppInitialize in 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. 

FATAL x3270 ERRORS

x3270 reports: "Error: No app-defaults file"

x3270 will not run unless its app-defaults file (X3270.ad) has been
installed properly. If you just want to test x3270 in the current directory,
you can use the "dryrun" script provided; this uses an environment variable
to tell x3270 where to find its app-defaults file. 

If you think you have installed x3270 properly and still get this message, or
if you install it in a non-standard place, you can use the same
environment-variable technique to tell x3270 where to find X3270.ad. 

x3270 reports: "Error: Outdated app-defaults file", or "Error:
app-defaults version mismatch: want x, got y"

x3270 not only insists that it have an app-defaults file (as described
above), but it must be the right app-defaults file. The first message
usually means that x3270 found the app-defaults file for an older version,
such as 1.2 or 2.65, rather than the one that was shipped with this version.
The second message usually means that the installed app-defaults file
belongs to an older version of x3270 3.0, but isn't quite the newest version.

See the comments for "No app-defaults file" above for ways to fix this. 

WARNINGS FROM x3270

x3270 reports: "Warning: emulatorFont '3270' doesn't exist, using
default font"

One of the trickiest areas; x3270 uses its own fonts to replicate a life-like
IBM 3278. 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". 

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: 

    xset fp rehash

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: 

    Font Path:
      /usr/lib/X11/fonts/misc/,/usr/lib/X11/fonts/Speedo/,/usr/lib/X11/fonts/75dpi/,/usr/lib/X11/fonts/100dpi/

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: 

    xset fp+ /usr/lib/X11/fonts/misc/
    xset fp rehash

(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.) 

SUBTLE PROBLEMS

x3270 isn't paying any attention to my keymap definition.

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. 

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: 

   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: 
      The -keymap swicth on the command line. 
      The definition of "x3270.keymap" in your .Xdefaults file. 
      The definition of "x3270.keymap" in
      /usr/lib/X11/app-defaults/X3270. 
      The KEYMAP environment variable. 
      The KEYBD environment variable. 
   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: 

           xrdb $HOME/.Xdefaults

   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". 
   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. 
   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: 

           x3270.keymap: sun-k5

   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: 

           x3270.keymap: 1-k5

   causing much confusion. 

   The fix is to add the following line to the top of your .Xdefaults: 

           #undef sun

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. 

The "Alt" key doesn't work.

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: 

        xmodmap -e 'add Mod2 = Alt_L'

If this fixes the problem, you can add it to your .xinitrc file, so it takes
effect every time your start X. 

x3270 is misbehaving on a certain application.

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: 

    x3270 -xrm -trace

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). 

I can't get the numeric keypad to work on my Sun keyboard.

If you are using an X server provided by Sun (xnews, or the XSun that is
provided with OpenWindows 3.3), then the NumLock light should turn on
and off when you press NumLock. If it does, then all you need to do is
make sure you are using the "sun-k5" keymap, which includes definitions
for the numeric keypad. 

If you are using an X server based directly on the MIT distribution, and the
NumLock light does not turn on when you press NumLock, 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.) 

GETTING HELP

If you are still having a problem with x3270, feel free to send e-mail to
Paul Mattes, x3270@cnt.com. 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 (sporadically)
find out about new releases and bug fixes. 

When you send a question about x3270, please include the following
information. It makes it much easier to narrow down the problem. 

 1. The version of x3270 you are using, including all patches, e.g.,
   "3.0.3B3". This is displayed at the top of the "About x3270"
   pop-up. 
 2. What kind of machine you are running on, e.g., "Sun SPARC-10". 
 3. 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. 
 4. 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". 

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. 
