This file is a note of some of the things which can sometimes go wrong,
and how to avoid them. It also may help you to get the best out of the
3270 emulation program.

Most important is that tn3270 uses the termcap definition of your
terminal (in fact, only a small set of the items therein). Thus, this
ought to be correct. One frequent error is that the termcap entry supplied
for some workstations claims to have the sequences necessary for
setting up and using a host-writeable status line (ds, es, fs, hs and
cs capabilities) but they failed completely. The program will normally
try to give you a status line and will use these sequences if necessary.
In fact, I have also seen these sequences in an xterm definition on an
Apollo, so they must have some basis in fact: any ideas?
As from version 3.5 I try to handle such cases better: I refuse to
believe that an xterm can have a host-writeable status line unless
you choose a specific compile option to say that it can. For more
information see the README.ALSO file.

Regarding the host-writeable status line as implemented on a DEC VT300 or
clone thereof, the standard DEC definition for selecting it (the ts
sequence in the termcap file) includes blanking it out (it includes \E[1K).
This is highly inefficient on serial line terminals when all that
I want to do is insert/delete 'X' in it to indicate IBM busy or not.
I have therefore included from version 5 onwards a compile option to
specify if the selection sequence does NOT blank out the existing status
line information (and, by implication, once the status line has been
selected I can skip to the line position which I intend to rewrite by
a standard cursor move sequence).

Another warning with the status line. The above ts sequence will normally
force a VT300 (or emulation such as DXterm) to include the status line.
In fact, I have found it best when using DXterm not to have it selected
at the time when the emulator starts up, but rather to allow the ts
sequence to initiate this status line. This is because there has long
been a DXterm bug whereby if the host status line is already selected
the sequences that I use fail to write anything unless you deselect it
then reselect it. However, it may be possible to set up terminals so as
to inhibit any possibility of having this status line even after the
correct ts sequence: in this case the status line will often get written
on the top line, i.e. will overwrite what should have been the first line
of the IBM screen.

Many termcap entries that I have seen include delays on some sequences
(such as clear screen, newline and so on), where these delays are changed
into a number of nulls dependent upon the terminal speed. On Ultrix 3.1 LAT
terminals the speed is not correctly evaluated, but that does not seem
to matter because on most modern terminals (VT100/200/300 or clones)
no delays are necessary. Thus, if your termcap entry has delays then
look to see if they are necessary! (to be honest, I must admit that I know
of at least one terminal which is supposed to emulate a VT100 but which
does need delays). In the version that I include I have put delays into
the vt100 entry, so if you have any problems try running as a vt100.

For even more efficiency I have invented some new termcap sequences.
It does not really matter if you do not have them (although if you
want to run properly as a 27*132 or 24*80 Model 5 then you would be
best having sn and sw). They are:-

   ib=\E[1q:            turn on LED 1 when turning on insert mode
   ie=\E[0q:            turn off LED 1 when turning off insert mode
   sn=100\E[?3l:        switch to normal mode (80-char lines)
   sw=100\E[?3h:        switch to wide mode (132-char lines)
   rt=\E[%dC:           move right n positions on a line
   vw:                  VT100-style wrap at end of line.

(Actually, I try to work out for myself whether vw is to be true or false:
I never trust your termcap! Likewise I work out how big your screen is,
not trusting the lines and columns that you state, unless you compile
the emulator with the NOSIZER option)
In view of the fact that some people do not wish to, or cannot, change
the termcap file I have included in version 3.5 the compile options
-DANSI_VT, -DANSI_XTERM and -DANSI_ALL, which force in at least some
of the above sequences (including sn and sw) for all vt-type terminals,
any xterm type or all terminal types. For more information see the
README.ALSO file.

The initialisation string which you have in the termcap is important,
since I need to use it to reset the terminal after any use of the on-line
help features. If mine has something that yours does not then look carefully
into the reason. For instance, I always make sure that the correct
extended character set is loaded into G0, G1, G2 and G3 in order to.
get the widest possible range of screen characters.

The binding of key sequences to IBM functions (the map3270 file) is
also vital. Remember that by default I look for a map3270 entry for
the terminal type name (as in termcap). However, since everyone's ideas
of an ideal mapping are not always identical you can define an environment
variable KEYMAP to be used instead of the terminal type. If all else fails
then the default definition is in the file finddef.c.

The included map3270 files are (I think) not bad. I hope they correspond
to the various mappings shown in simple figure form in the corresponding
keyboard help files. However, the entry for xterm is much more problematic,
since different types of workstation offer xterm but yet have completely
different keyboards. If you add in the fact that most workstations can
offer vt100/200/300 emulators (complete with setting of the TERM environment
variable) then it is clear that one single map3270 file for everyone is
not possible. What I do is include a generic map3270 file which tries
to cater for most types of terminal plus individual map3270 files for
the different types of workstation. The makefile for that particular
type of workstation will then copy this file whose name is
map3270-<workstation type>
into the directory specified for map3270 with filename map3270.

The various entries in the keyboards directory are basically help files
which are put out on the screen when the user wants help on the
map layout for the particular mapping on the particular terminal type
in use. As such, if you modify map3270 then you ought to modify the relevant
keyboards files. If you have terminal types which are not there (nor in
my map270 or termcap) then you can easily create new ones after having
seen how the current ones work for a standard terminal like a VT200.

You will see in this keyboards directory that there are various possible
entries of name
xterm-<workstation type>
which are specific to the standard keyboards for that type of workstation
and which (should) correspond to the map3270 file for that type of
workstation. Since I always try to make a map3270 file which allows
a workstation to be run with either xterm or its normal shell window
and have the same mappings this xterm keyboard entry can often be used
for the normal shell window also. However, in some cases it seems difficult,
if not plain impossible, to do this.

If the program bombs out on you then look at the log file (see the
Makefile for where to put it) to see if it helps. Remember, also, to
get rid of this logfile every so often (I use crontab to keep the logfiles
of the previous 7 days in 7 files).

There are a few "goodies" in the program, notably the blinking "more"
or "holding" (my favourite!). Please give me your reactions: at some
time in the future goodies which are not universally liked may go in
as conditional code.

If on a multi-user system then the various user options choices are held in
the OPTDIR (which for me is /usr/local/lib/3270/options) directory. If, like us,
there are multiple entries to the local IBM system then it is useful to include
all of the names/IP addresses for the IBM in OPTDIR/default_hosts. For instance,
mine is

cernvm
cernvm.cern.ch
crnvma
crnvma.cern.ch
128.141.2.4
crnvmb
crnvmb.cern.ch
128.141.2.3
crnvmc
crnvmc.cern.ch
128.141.2.5

cernvm
cernvm.cern.ch
crnvma
crnvma.cern.ch
128.141.2.4
crnvmb
crnvmb.cern.ch
128.141.2.3
crnvmc
crnvmc.cern.ch
128.141.2.5
