Copyright (C) 1999, 2000 Chris Vine, G3XXF

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    A copy of the GNU General Public License version 2 is set out
    in the file COPYRIGHT accompanying this distribution.  You can
    also obtain a written copy from the Free Software  Foundation,
    Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

		INSTALLATION: FROM SOURCE FILES

To install, place the distribution file in a local source directory
(eg ~/src).  Untarring/unzipping it will create a sub-directory 'kam'
where the source code can be found.  Edit the file kamrc (which will
be placed by "make install" in /etc) so that it matches your serial
port, speed setting for your Kam, and callsign (see further below
under "setup" for more on this file).  kamrc specifies run-time not
compile-time options, but you might as well edit it now so that the
version installed by "make install" is correct.

NOTE: the format for specifying the serial port in kamrc has changed
with the latest release - you must now specify the port device name
(eg. ttyS0) rather than the COM port number.  (See kamrc for further
details).

Then type "make", and then "make install".  "make install" must be run
as root.  "make" can be run as user.  The program and configuration
files (other than kamrc) will be installed in the directory specified
in makefile (makefile is set to install them in /usr/local/kamdir by
default).

The name of the executable is "kam".  There is also a shell script
executable to run it in a colour xterm called "xkam" which is also
installed by "make install".  See below for further details of xkam.

"make install" will give suid and sgid permissions to the installed
binary.  If appropriate permissions are given to the serial device
(/dev/ttyS*), this can be refined and changed for the security
conscious.

To compile and link, ncurses up to level 4.2 or higher must be
installed.  You must have both the ncurses and ncurses-devel packages
installed if you use the Red Hat rpms.

Note: there is a bug in the ncurses-devel-4.2-6.i386.rpm package that
comes with Redhat 5.1, which means that if you compile against it the
cursor will not switch on and off properly: it will appear to dance
around the screen.  If you use Redhat 5.1 and want to compile from
source, get an updated package, such as the ncurses packages for
Redhat 5.2.

	INSTALLATION: FROM PRE-COMPILED LINUX BINARY FILES

To install, place the distribution file in a local source directory
(eg ~/src).  Untarring/unzipping it will create a sub-directory 'kam'
where the source code and binary files can be found.  Edit the file
kamrc (which will be placed by "make libc5_install" or "make
libc6_install" in /etc) so that it matches your serial port, speed
setting for your Kam, and callsign (see further below under "setup"
for more on this file), then type "make libc5_install" or "make
libc6_install", depending on your version of libc.

NOTE: the format for specifying the serial port in kamrc has changed
with the latest release - you must now specify the port device name
(eg. ttyS0) rather than the COM port number.  (See kamrc for further
details).

The pre-compiled version for libc6 has been compiled with egcs, and
the libc5 version has been compiled with gcc-2.7.2.  egcs and
gcc-2.7.* use different C++ name mangling schemes, so if you use some
other distribution than the ones mentioned above the binary may not
dynamically link with the libc++ shared library file in your
distribution, if the distribution has been compiled with the "wrong"
compiler.

Furthermore, the libc6 version has been compiled with glibc-2.1.*.  It
will not work with glibc-2.0.* (as used in Red Hat 5.*).  If you get a
segmentation fault when trying to start the program, library
incompatibility is probably the reason.  You will have to compile the
program from source.  This is very easy (see above), and recommended
in any event.

"make libc5_install" or "make libc6_install" must be run as root.  The
program and configuration files (other than kamrc) will be installed
in the directory specified in Makefile (Makefile is set to install
them in /usr/local/kamdir by default).

If you don't have 'make' installed (shame on you), you will need to
copy by hand kam, xkam, endhost, cq, messages and helpfile to your
chosen install directory as specified in kamrc, copy tnc.parms, home
and away into the sub-directory "parms" in the install directory, copy
kamrc to /etc, and give kam and endhost the necessary permissions to
write to the serial port device (/dev/ttyS*).  This can be done by
setting 'kam' and 'endhost' suid root (chmod +s kam), although there
are other ways of doing it (eg make /dev/ttyS* writable by a group
such as uucp and make 'kam', 'endhost' and 'xkam' members of that
group and setting sgid).

The name of the installed executable is "kam".  There is also a shell
script executable to run it in a colour xterm called "xkam" which is
also installed by "make libc5_install" or "make libc6_install".  See
below for further details of xkam.

"make libc5_install" or "make libc6_install" will give suid and guid
permissions to the installed binary.  If appropriate permissions are
given to the serial device (/dev/ttyS*), this can be refined and
changed for the security conscious.

To run, ncurses up to level 4.2 or higher must be installed.

                            SETUP

Before being used, the kam configuration file (kamrc) must be
completed with (a) your callsign, (b) the serial port on which the Kam
tnc operates, (c) the speed to which the Kam has been initialised (or
to which it is to be initialised) and (d) the directory in which other
relevant kam files (such as "messages") can be found and in which the
capture file capture.txt and certain temporary files will be written.
The directory must therefore be one in which there will be write
permission (this is not so much of an issue if kam is set suid root -
see above).

It is recommended that this directory should either be the same one in
which the kam executable is installed - normally /usr/local/kamdir, as
"make install" "make libc5_install" or "make libc6_install" will
automatically give the necessary permissions to that directory.

In looking for kamrc, the program first searches for a file
$HOME/.kamrc, and if that is not found looks for the global
configuration file /etc/kamrc.  "make install", "make libc5_install"
or "make libc6_install" will install a global /etc/kamrc file, which
you should have previously edited as mentioned above.

The kam configuration file (kamrc) may also specify your Amtor
selcall, but it does not need to do so.  If you do not specify a
selcall, then the standard four letter selcall matching your callsign
will automatically be generated by the program for you.

The sample file /etc/kamrc which comes with this distribution gives
further details - it is much easier than this explanation sounds.

Before using the program you must also have initialised the Kam (if
you have already used your Kam with another program then it will
already be initialised, and you can skip this part, subject to the
comment about speeds below).  To do this you can put the program in
terminal mode instead of host mode by typing "kam setup" instead of
"kam" when starting the program.  To see how to go from there, look at
the handbook under "Initializing the KAM Plus".

The SPEED: setting in the Kam configuration file (kamrc) must match
the speed the Kam has been initialised for.

Note that if you have previously initialised the kam using the DOS
Pacterm program which comes with the Kam Plus, Pacterm operates at
1200 baud Kam/Computer link speed, whereas you will be better off with
9600 baud, as host mode involves additional tnc/computer traffic in
order to keep track of the Kam status information.

It is therefore best to set up the Kam for 9600 baud.  One way of
doing this if the Kam has previously been initialised for a lower
speed is to put the SPEED: setting in kamrc to the speed the Kam has
previously been initialised for, start the program as "kam setup" so
that you are in terminal mode, and then enter the Kam command RESTORE
DEFAULTS.  This will cause the Kam to re-initialise.  Then quit the
program (Ctrl-Q), amend the speed setting in /etc/kamrc to 9600,
restart the program with "kam setup", wait for the auto-baud detect
prompt and press '*'.  See the Kam Plus handbook for further details.

		      USE OF THE PROGRAM

When first used in host mode, the Kam must be switched on before the
program is run, so the program will place the Kam in Host mode.  Once
the program is started for the first time, Press F9 to send the Kam
parameters in file "tnc.parms".  Until this is done, the program will
not interface with the Kam correctly.

The program will leave the Kam in Host mode.  If you want to get out
of host mode, either use the "endhost" utility installed in the same
directory as "kam", or start the program again using "kam setup" so
that the Kam is placed in terminal mode.

The first time you use the program, you will be asked if you accept
the terms of the General Public Licence, version 2.

The keyboard operates as follows:

(Note Alt-P has changed its meaning in release 0.97: to send FEC
Pactor in Tor mode, now press Alt-T)

Cursor up - Scroll up.
Cursor down - Scroll down.
Cursor right - Scroll out (end scroll).

Page Up - changeover to transmit (HF modes).
Page Down - changeover to receive (HF modes).

Note: if using xterm, you may need to use the Page Up and Page Down on
the number pad to make this work, rather than the Page up and Page
Down on the main keyboard.

Ctrl-A: change to Amtor mode (or send Ctrl-A - see below).
Ctrl-C: change to CW mode (if not in CW mode) or set the speed (if in CW
	mode).
Ctrl-D: disconnect (Packet, Pactor, Amtor and Gtor).
Ctrl-F: change to FEC.
Ctrl-G: change to G-tor.
Ctrl-L: change to Lamtor.
Ctrl-O: change to Gmon.
Ctrl-P: change to Pactor.
Ctrl-Q: quit the program.
Ctrl-R: change to RTTY (Baudot).
Ctrl-S: change to ASCII.
Ctrl-T: change to TOR mode (or send Ctrl-T - see below).
Ctrl-X: change to HF Packet.
Ctrl-Z: send Ctrl-Z (see below).

Alt-B: print the current scroll buffer.
Alt-C: send an auto-cq (Pactor, Amtor, Gtor or Tor)
       or (if in auto-cq mode) end auto-cq.
       (see also Alt-T below).
Alt-D: Download a 7plus/uuencoded file to a local file (Packet, Pactor
       or Gtor) (this makes no translations other than CR -> LF).
       (Press again to end the download).
Ctrl- Alt-D: Download a binary file to a local file (Packet, Pactor or
       Gtor) (this saves the raw data to disk).
       (Press again to end the download).
Alt-I: send ident ([CALL IN STORE] de [YOUR CALL]).
Alt-L: toggle whether receive speed locked to 100 baud (Pactor or Gtor).
Alt-P: set a print mark, or if one is already set, print from the mark.
Alt-R: enter an RST report to be stored in the RST buffer.
Alt-S: sync the transmit speed to the current receive speed (CW), or
       resync the Amtor decoder when monitoring (Amtor/Lamtor).
Alt-T: send an auto-cq when listening in Tor-standby mode but using
       Pactor FEC to send the CQ.
Alt-U: Upload a 7plus/uuencoded file (Packet, Pactor or Gtor) (this
       makes no translations other than LF -> CR).
       (Press again to abort the upload).
Ctrl-Alt-U: Upload a binary file (Packet, Pactor or Gtor) (this
       sends raw data and makes no translations).
       (Press again to abort the upload).
Alt-X: abort (Pactor, Amtor, Gtor or Tor)
Alt-0 to Alt-9: send the messages specified in the "messages" file.

F1: toggle display of Help file.
F2: toggle on/off capture of current stream to file [KAMDIR:]/capture.txt.
F3: toggle transmitting of text after word/line or with a guard in
    non-packet mode (see below).  
F4: connect with another station (Packet, Pactor, Amtor and Gtor).  
F5: send a command to the Kam (press again to run a configuration script).
F6: send a text file.  (Press again to abort the upload).
F7: enter another station's callsign in the callsign store.  
F8: toggle the callsign lock (see below).  
F9: send the Kam parameter file tnc.parms to Kam.  
F10: toggle the screen display between VHF and HF port of Kam.  
F11: go down a stream on the screen display (e.g. from stream C on current
     port to stream B).  
F12: go up a stream on the screen display (e.g. from stream A on current
     port to stream B).

Pressing Ctrl-A when in Packet, Pactor or Gtor mode and connected
will send a Ctrl-A character instead of asking whether to change to
Amtor mode (some BBSs use Ctrl-A to abort a message being sent)

Pressing Ctrl-T when in Packet, Pactor or Gtor mode and connected
will send a Ctrl-T character instead of asking whether to change to
Tor mode (some BBSs use Ctrl-T to abort a telnet session)

Pressing Ctrl-Z when in Packet, Pactor or Gtor mode and connected
will send a Ctrl-Z character (some BBSs use Ctrl-Z to end a message as
an alternative to /EX)

If Alt-C is pressed when in Pactor, Amtor, Gtor or Tor-Standby modes,
the program will run the CQ message found in the file 'cq' placed in
the directory specified by 'KAMDIR:' in kamrc, repeating until a link
is made.  It can be turned off by pressing Alt-C again.  The delay
between the end of one CQ message and the start of the next may be
specified by the AUTOCQ: parameter in kamrc.  If none is specified,
the default is 90 seconds (don't cook your output stage).  If in
Tor-Standby mode, pressing Alt-T will do the same, except that the CQ
message will be sent in Pactor FEC not Amtor FEC mode.

If Alt-D is pressed and the Kam is connected in Packet, Pactor or Gtor
mode, you can download a 7-plus file to local disc.  If Alt-U is
pressed, a 7-plus file can be sent.  The only character tranlations
made are LF -> CR when uploading, and CR -> LF when downloading, as
required by the Packet network.  These differ from sending a text file
via F6 or capturing a file via F2 by making no other character
translations.  With an ordinary compile, F2 and F6 will send and
receive continental characters with a Latin-1 (computer) <-> Code Page
437 (packet network) translation.  To work, the Kam parameters are
best set so that AUTOLF is OFF, AUTOCR is 0, CRADD is OFF, CRSUP is
OFF, LFADD is OFF and LFSUP is OFF.  (Running tnc.parms via F9 will
set these correctly automatically and the program will carry out all
the necessary CR/LF insertions (HF Tor modes) and CR <-> LF
translations (Packet mode).

When Ctrl-Alt-D is pressed, if the Kam is connected in Packet, Pactor
or Gtor mode, a download can be made of raw data to local disc with no
character translations, and Ctrl-Alt-U will upload raw data.  However,
these do not use any special protocal such a YAPP, so they are as yet
only really suitable for 7plus or UUencoded files which are being sent
on a direct station to station link not involving the Packet network,
or which have already had a LF -> CR translation made to them.  To
send raw data, it is essential that the Kam parameters are set so that
AUTOLF is OFF, AUTOCQ is 0, CRADD is OFF, CRSUP is OFF, LFADD is OFF
and LFSUP is OFF as mentioned above.

If Alt-L is pressed when in Pactor or Gtor mode, the receive speed
will be locked to 100 baud, and the bottom status line will show
"LOCK".

If Alt-1 to Alt-5 are pressed, the message specified in the file
"messages" will be sent ("messages" will be looked for in the
directory specified by KAMDIR: in kamrc).  Such a message should not
exceed MESSAGE_SIZE defined in prog_defs.h (276 bytes in the standard
distribution).  If Alt-6 to Alt-0 are pressed, the file specified in
the "messages" file will be sent.  There is no maximum message size
for a file sent with Alt-6 to Alt-0.  See the specimen "messages" file
installed by "make install" for further details.  Also see the
specimen "kamrc" file for the NOPROMPT option which will send the
relevant message without asking for confirmation first.

When sending a message or file via Alt-0 to Alt-9, six shortcuts are
provided - $a is translated to your call, $b is translated to your
selcall, $c will be translated to the call in the callsign store
buffer for the currently active screen, $d will be translated to the
current time in UTC (hours and minutes),$e will be translated to the
current date (day-month-year) and $f will be translated to the value
(if any) currently held in the RST report buffer.  These translations
do not apply to any file sent via the F6 key - files sent via F6 are
sent exactly as they appear.

F5 can now be used to send configuration scripts as well as sending
Kam commands entered directly at the keyboard.  Such scripts must be
placed in the KAMDIR:/parms/ directory.  The distribution comes with
two scripts - 'home' and 'away', which contain the kind of Kam
parameters suitable for attended and unattended operation.  To run a
script, instead of entering a command directly at the keyboard, press
F5 again, and then enter the name of the script - for example, enter
"home" (without the quotes).

When the HF port is not in a packet mode, it will send text to the Kam
depending on the setting toggled by F3.  If set to "Word", it will
send text at the end of each word, if set to "Line" it will send it at
the end of each line (when Return is pressed).  If set to "Guard", a
minimum of 10 characters in any line will be retained in the transmit
queue, which can be erased from the keyboard before being sent to
enable correction of errors.  This can be useful in Amtor and RTTY
modes which do not allow the transmission of backspace characters.
Pactor and Gtor do allow transmission of backspace/delete, so this
setting is not so important for those modes.

When the HF port is not in a packet mode, the program will search
incoming text for a valid callsign format, and if it finds one, enter
it in the Call Sign buffer (and also generate a SELLCALL for calling a
station in Amtor).  Pressing F8 will lock the Call Sign buffer to the
current displayed callsign so that the buffer will not be updated.
When locked, an asterisk will be displayed in front of the callsign
shown on the screen.  Pressing F8 again will unlock the displayed
callsign, so that it will be displaced by the next detected valid
callsign.

                      CONNECT SCRIPTS

The program can ease the task of making Packet connects via nodes by
running automatic connect scripts.  See the file CONNECT_SCRIPTS with
this distribution for further details.

		   UNIX TERMINAL ISSUES

If running in an xterm, you may need to fiddle things to get it to
display in colour.  You will find the file xkam in the distribution.
This is an executable shell script which starts xterm with appropriate
parameters.  It assumes your curses distribution contains a terminfo
file for xterm-color.

Some distributions do not have the terminfo file correctly configured.
If you use version 3.3 of XFree86 and cannot get colour with
xterm-color, try xterm-xf86-v33 instead and amend the part of the
script in xkam which refers to xterm-color.  Check by looking in
/usr/lib/terminfo/x or /usr/share/terminfo/x.  However, distributions
being what they are, even if you do have the right terminfo file for
xterm-xf86-v33, xterm may complain that it can't find a termcap entry
for that TERM.  If so, go to the /etc/termcap entry for xterm-color
and insert immediately after "xterm-color|" the following:
 "xterm-xf86-v33|".  (The | is a pipe sign, not a 1).

Because of the way terminals have developed in Unix, function keys F1
to F4 can be problematic.  The program will automatically recognise
the keycodes for these keys using the standard Linux console or an
xterm.  If you are using some other terminal and F1 to F4 do not work
properly, go to the terminal prompt and enter Ctrl-V immediately
followed by F1.  Note the keycode displayed.  Go to Makefile, and
uncomment and define the variable F1_USER_CODE with that keycode
without the initial "^[" (which represents the initial escape
character), and recompile.  For example, if Ctrl-V followed by F1
displays "^[[ta~", then the makefile should show: F1_USER_CODE = [ta~.
Then recompile.

The detection of the Alt (Meta) key depends on it generating the
escape character rather than setting the 8th bit of the character byte
high - this leaves characters of a value above 127 available for use
by continental characters.  To achieve this the program calls
'setmetamode' when the program starts, which will work with standard
login consoles.  If using an xterm, the same result can be achieved by
executing it with the resource parameter:
 -xrm "XTerm*eightBitInput: false".
(The xkam script uses this parameter.)  Most terminals, other than
xterm, will generate the escape character by default.

                 CONTINENTAL CHARACTERS (LATIN-1)

To display continental characters, compile the program with CHARSET in
Makefile defined as LATIN_1 (the precompiled binaries are already
compiled this way).

You will probably also need to include the
following lines in a file .inputrc in your home directory -

set meta-flag On
set convert-meta Off
set output-meta On

                           PRINTING

Received text can be printed in two ways:

1.  By pressing Alt-B, the entire contents of the scroll buffer for
the stream currently displayed can be printed.

2.  By pressing Alt-P, a print mark can be made in the stream
currently displayed.  At any later time, the text following the print
mark can be printed by pressing Alt-P again.

The default printer command used is 'lpr'.  A special printer command
can be set with the PRINT_CMD: setting in kamrc (see the sample kamrc
file for further details).

		     CONTACTING THE AUTHOR

I can be reached at:

chris@cvine.freeserve.co.uk
G3XXF@GB7MSW.#33.GBR.EU

Updates can be obtained from:
http://www.cvine.freeserve.co.uk/

I am happy to arrange skeds on HF.

73, Chris.
