New version of the README file -- LINUX5250

Hi,

It seems to me that the number one (non-bug) problem people have been
having with the emulator, is getting all of the function keys to work
properly.  I have updated the README file in order to make the process a
little bit clearer.  This has not yet made it into the source tree, so I
am posting it here.  Please let me know if you find any problems.


This is my implementation of the 5250 Telnet protocol for LINUX.  This code
(as well as the documentation) is extremely BETA.  That said, it does more or 
less work...

This version has been substantially re-written with a more object oriented
approach.  Hopefully, the code is should be easier to follow, enhance, and
maintain.

Quick Start (for the impatient)
===========

To Install:

% tar -zoxvf tn5250-0.13.13.tar.gz      # unpack the sources
% cd tn5250-0.13.13                     # change to the top level directory
% ./configure                           # run `configure' script
% make                                  # build tn5250
% su                                    # become root (enter root password)
# make install                          # install tn5250
# tic 5250.terminfo                     # compile and install terminal entry
# exit                                  # become yourself again
% cat Xdefaults >> ~/.Xdefaults         # add tn5250 entries to .Xdefaults

It is very important to update your .Xdefaults file.  If you don't do this,
the xterm (and therefore the emulator) won't see the proper keycodes and
your function keys won't work.

Running from XWindows:

% xt5250 my.ip.address                  # opens an xterm an connects

Running from the console:

% su                                    # become root (enter root password)     
                        
# loadkeys us5250.map                   # load the console keymap
# exit                                  # become yourself again
% export TERM=5250                      # select the 5250 terminal entry
% tn5250 -u my.ip.address               # connect

Details
=======

Building the emulator

To build the emulator simply type the following:

   ./configure
   make
   make install

The emulator uses the ncurses library for manipulating the console.  Make
sure you have the ncurses development libraries installed before trying to
compile the source.

Console usage

The linux console only defines F1-F20 by default.  I have included a sample
map file which has all the function keys.  It also has a modified definiton
for the tab key to allow the use of Shift-Tab to move backwards through
fields.  It is based on the stock linux console.  To make use of the file, you 
need to use the loadkeys command.  As the root user, type the following:

   loadkeys us5250.map (or uk5250.map if you have that keyboard)

After doing this, all the function keys will now return unique 
codes.  One caveat, is that this will effect all of your consoles.  Also, the 
change is only temporary, so you will have to invoke it again unless you put 
it in a startup file somewhere.

In addition to the map file you also need to make sure that the terminfo
file that you are using is properly set up.  In particular, it needs to have
definitions for all 24 function keys, and it must have the proper code for
back tab.  To look at the current contents of your terminfo, use the infocmp
command to dump them to a file.  After making any necessary changes, you can
recompile the file with the tic command.  For details please see the man
pages for those commands.  There is a file called 5250.terminfo which shows
what I use.  To add this terminfo entry, type the following as root:

   tic  5250.terminfo

Now all you need to do is set your TERM environment variable to 5250.

Xterm usage

To use the emulator in an xterm, make sure you have compiled 5250.terminfo
using the tic command.  In addition, you will have to update the contents of
your .Xdefaults file.  Appending the contents of the included Xdefaults file
will ensure that the proper keycodes will be sent to the Xterm (and
therefore to the emulator).  This step is not optional.  If you don't do it,
your function keys won't work.

To launch an xterm of the proper dimensions (a standard xterm is only 24 rows 
high), use the xt5250 shell script.  This shell script will open an xterm 80X25 
and sets the TERM environment variable to the correct value, then launches the 
emulator.  Below is an example command line:

  xt5250 -s MIKEM01 192.168.1.10

Where MIKEM01 is the device name I want on the AS/400, and 192.168.1.10 is
the address of the host system. NOTE:  as things stand, function keys will
only work properly in a genuine x-term.  This means that rxvt won't respond
to function keys correctly.  I'd be happy to include sample Xdefault
settings for rxvt or other X windows terminals if someone sends them to me.

Please send me any comments, questions, bug reports or patches. 

Michael Madore
mmadore@blarg.net
http://www.blarg.net/~mmadore
October 5th, 1999

+---
| This is the LINUX5250 Mailing List!
| To submit a new message, send your mail to LINUX5250@midrange.com.
| To subscribe to this list send email to LINUX5250-SUB@midrange.com.
| To unsubscribe from this list send email to LINUX5250-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---