
DOCUMENTATION FILE for MASTERM TNC driver program, v1.19.

This terminal program is for the Acorn/BBC Archimedes/A3000, (the latter
requires the optional serial chips). It is written for TNC2 compatibles such
as the TNC220, TINY2, BSX2 etc.. It is equally suitable for use with a PK88
or PK232 or KAM (packet mode). The program has been designed to be as easy
and natural to use as possible, whilst providing a degree of versatility and
flexibility. Hardware handshaking is used over the serial link, and the
connections are given below. You MUST wire for hardware handshaking; it is
not sufficient to wire up just the RXD and TXD lines.

If you have an older A305, 310 or 440, you may possible experience problems
with characters being 'dropped' on the serial connection. If so, you should
contact your Acorn dealer and ask for the appropriate modifications to be
done. The newer A400/1 series and the A3000 do not suffer from this problem.


    ARC 9-WAY D CONNECTOR                 TNC 25-WAY D CONNECTOR
     
    No connection                         1 Cable screen (optional)
    3 TXD                                 2 TX data
    2 RXD                                 3 RX data
    7 RTS }                            {* 4 RTS
          }                            { 20 DTR
    6 DSR                                 5 CTS
    5 Signal gnd                          7 Signal gnd
    1 DCD}
    4 DTR} All linked together            No connection
    8 CTS}
    9 Ring indicator                    # 8 Connect status (optional)  

* Some TNCs like the PK use pin 4 (RTS) for the handshake input, whereas
  others like the BSX2 use pin 20 (DTR) instead. So, if you make up a cable
  with RTS from the Micro connected to both 4 and 20 on the TNC, then it
  should be suitable for any TNC you are likely to use. Note the rather
  strange connections for the Arc; similar to a PC AT but definitely
  different! DSR is used instead of CTS, and this is quite deliberate.

# This connection is not actually required by the program, but you may wish
  to use it to preserve compatibility with other software.


KEYSTRIP

There is a function keystrip called "Fkeys" inside the !Packet application
directory. It is a !Draw file, and may be printed by installing the
appropriate printer driver on the icon bar, and then dragging the Fkeys icon
onto it. If you are fairly proficient at using !Draw, you can load Fkeys
into it, and edit your own definitions into the blank spaces if you wish.


STARTUP VALUES

Before you start, there are a few things to check. Edit the !RunImage file,
either from BASIC or using the 'ARM BASIC Editor' supplied by Acorn.

Right at the end of the program listing is a Procedure with settings which
you can alter. You  are  free to reprogram any useful strings or commands on
the 'soft' user keys, including the cursor and Copy keys, with the exception
of KEYS 0 and 9, which are used by the program. Note that on the Arc, the
<f0> key is marked <Print>. You may also redefine KEY10, since it is no
longer the same as the <Break> key as on earlier Acorn machines. The key
definitions supplied happen to suit me, and operate as follows...

Keys 1 to 6 are self-explanatory. Keys 7 and 8 switch output streams
(channels) for multi-connect operation; I use <Ctrl><^> as a switch
character, (=$1E). The PK requires "0", "1" etc. as switch IDs, whereas the
TNC2/KAM require "A", "B" etc.. Key 11 <Copy> prints the MHeard list, Key 12
<Cursor left> deletes the current input line (this code of Ctrl-U is not
sent to the TNC), Key 13 <Cursor  right> sends a series of chevrons to
indicate "over", Key 14 <Cursor down> enters Converse mode from Command
mode, and Key 15 <Cursor up> returns to Command  mode and Disconnects. You
can change any of these as you like, but not Keys 0 and 9. The quickest way
to list the key definitions is to type the direct BASIC command LIST IF*KEY
<Return>, or just L.IF*KEY <Return>. The keys are cleared on exit from the
program, so you cannot check them afterwards. KAM users might like to
program one key with |CX which exits from the current data mode.

You can actually get very devious with these soft key definitions. For
example, you can program a key to simulate the pressing of <Shift> or <Ctrl>
plus another soft key, as well as doing whatever else you intended. For
example, |!|@ will simulate <Shift><f0>, |!|# does the same for <f1>, and so
on in ASCII code order. Similarly, |!|P simulates <Ctrl><f0>, |!|Q does the
same for <f1>, and so on. For example, |!|Q|CMH|M simulates <Ctrl><f1> to
clear the upper screen, plus |C to force the TNC into command mode, then
finally MH|M to obtain the MHeard list from the TNC. Sneaky, huh?

You can also alter some variables to set your name, callsign and local BBS
callsign, and the string at the end of date/time stamping; "UTC" or "BST",
depending on which you have set the internal clock in the Master to. You can
alter the filename used to save your preferred configuration options; the
default is "<Packet$Dir>.TermCFG". You can set the line widths observed by
the automatic CR (newline) facility when typing manually; the first figure
must be less than the second, and the second should be less than 80. The
defaults are 65 and 79; this is explained more fully later. Finally, you can
alter the filetype used by the download facility; in other words when you
save incoming packet text to disc. Normally one would use "Text" (FFF),
which is a plain ASCII text file. This enables files to be loaded into !Edit
simply by double-clicking on them from the desktop. It makes no difference
to the program what filetypes are set for upload files.

When you've finished, save the altered program. It is wise to keep a
separate copy of the original disc, in case of mishaps!


GETTING STARTED

When you RUN the program by double-clicking on the !Packet icon, the program
will look for a file called "TermCFG", or whatever name you have chosen. The
program will not find this file the very first time, so it will default to
preset settings of screen colours, baudrates etc..

The first thing to do is set your own preferences, so press <Ctrl><f7> to
enter the configure routine. Using the cursor keys as indicated, and also
the "<" and ">" keys, you may choose the screen colours. Setting the border
colour the same as the background colour makes the screen look larger. After
pressing <Return> you may choose the size of the bottom (type-ahead) window.
Size 4 is ok for accessing mailboxes, as it leaves you 25 lines in the upper
(receive) window, but for 'live' person-person QSOs 12 may be more suitable.
The default of 8 is a good compromise I find. Note that this setting will
not have any effect until you exit from the configuration routine.

Next, you may select whether or not you want the program to start a new line
for you automatically when you are typing; file uploading is not affected,
so as to preserve text formatting. In manual mode it is up to you to press
<Return> to start a new line when you want to. It doesn't matter if you
don't with most TNCs, but the result may be a bit untidy. In manual mode the
cursor in the lower screen is the same block shape as that in the upper. In
auto  mode, the program will insert a CR after a certain number of
characters on a line, (default 65), but only when a Space is typed, so as
not to split words. If a Space is not typed before the end of the line, a CR
is inserted regardless, (default 79 characters - do not use 80 as it will
result in double-line spacing). In auto mode the cursor in the lower window
changes shape to a bent arrow; the common symbol for <Return>. As far as the
program is concerned, there need be no CRs at all in a long text message,
but some TNCs object to this. (KAM owners please note!)

Next, you may select the required serial port protocol. "7-E-1" means 7 data
bits, even parity, 1 stop bit, and "8-N-1" means 8 bits, no parity, 1 stop
bit, and so on. A TNC2 defaults to 7-E-1 whereas the PK defaults to 8-N-1.
The PK also defaults to 1200 baud when reset, so it may be best to set this
in the program at first. When you press <Return> you have the option of
saving the settings to disc so that they will be used next time you run the
program. When the program returns to normal mode, no text will be lost from
the screen windows, nor any waiting in the TNC, unless you altered the size
of the lower window, in which case the entire screen is cleared first.

I advise you to use a baud rate of 4800; any speed above this will make no
practical difference whatever, but there is a risk of buffer over-run in the
TNC in some cases.


TNC PARAMETERS

Having configured the program, switch the TNC power on, and check that the
TNC gives a startup message. Random-looking garbage could mean that the
baudrate, data bits, parity etc. are set wrong. In the case of the PK88/232
you may be in autobaud mode; ie the MULTI lamp is lit. Do not type any
asterisks as advised in the manual, as they can only be send a line at a
time, which will confuse the TNC. Instead,  press <Ctrl><f8> at 1-second
intervals until the normal startup message appears. This function has no use
on other TNCs.

The following basic parameters are recommended to get going, so type these
against the "cmd:" prompt:-

XFLOW OFF               Enable hardware handshaking
FLOW OFF                Allow TNC to talk to micro any time
ECHO OFF                Stops TNC echoing your typing back, as this mixes
                        with incoming text, and also slows things down.*
MON OFF                 Stop monitored text before you are ready
MYCALL G????            Set your own callsign
SCREENLN 0   (TNC2)     No auto wraparound - Arc does it anyway
SCREENL 0    (KAM)      ditto
ACRDISP 0    (PK)       ditto
BBS ON                  Read the manual!
HEA ON                  Packet text on fresh line after callsigns
DAYU OFF     (TNC2/KAM) Use European date format
CBELL ON     (TNC2/PK)  Sound a bleep when someone connects
RING ON      (KAM)      ditto
NEWMODE ON              Auto return to command mode after disconnection
STREAMSW $1E (TNC2/KAM) Set <Ctrl><^> as streamswitch
CHSW $1E     (PK)       ditto

*NB: With ECHO ON, the echoed text may be badly corrupted by the TNC when
     you are uploading a file off disc, though the actual text will be sent
     ok. This is a quirk of some TNC firmware, not of the program, and is
     harmless. For this, and other reasons, I strongly recommend setting
     ECHO OFF.

     The DEL setting is unimportant, as the program accepts either the <BS>
     or <Delete> key equally happily, but sends neither to the TNC.

     The AUTOLF (auto-linefeed) setting on the TNC is unimportant, as the
     program ignores linefeeds on receive, and does not send them to the
     TNC either.

You may find it useful to create a file of all these setting, together  with
CTEXT, BTEXT  etc., so that you can upload them off disc instead of having
to retype them in future, and !Edit is ideal for this. Make sure that XFLOW
OFF and FLOW OFF are right at the beginning of the file.

USING THE PROGRAM

The  central status window tells you the current Download (*SPOOL) filename,
the  current Upload filename, the current connect callsign, the current
serial port protocol, and whether the printer is in use, (a tick symbol
appears when it is).

The following keys have special functions within the program itself, and you
will need to make up a keystrip for the red keys. Please note that the
<Print> key is effectively <f0> and is defined by the program.

<Ctrl>             Slows screen scrolling speed slightly; standard feature
                   of RISC OS.

<Shift><Ctrl>      Holds both screens from scrolling until released;
                   standard feature of RISC OS.

<Alt>              Also holds both screens from scrolling until released.
                   This is more convenient than <Shift><Ctrl>. The
                   <Scroll Lock> key may also be used if required.

<Tab> or <Ctrl><C> COMMAND MODE
                   Returns TNC to Command (cmd:) mode.

<Ctrl> <U>         DELETE LINE
                   Deletes current input line, as in BBC BASIC.

<Print>            PRINT
                   Enables printer. Shown in Status window as a tick. If
                   printer is not already online, you will be warned. 
                   Cancel printer by pressing <Print> again.

<Shift><Print>     PRINT
                   Ditto. Not normally used, as <Print> is easier.

<Ctrl> <Print>     PRINT INCLUDING SCREEN
                   Ditto, but also dumps existing text on screen to printer
                   first, so you don't miss anything already in view.
                   Cancel printer by pressing <Print>.

<Shift><f1>        CLEAR LOWER WINDOW
                   Clears lower (type ahead) screen window.

<Ctrl> <f1>        CLEAR UPPER WINDOW
                   Clears upper (receive) screen window.

<Shift><f2>        STAR COMMANDS
                   Carry out "*" commands. Screen contents are saved
                   to memory, and full edit cursor control is available.
                   Exit by pressing just <Return> against "*" prompt.
                   You can do this at any time without corrupting the
                   dialogue with the TNC, and without affecting a qso in
                   any way. Received text will not be lost unless you exit
                   with <Escape>, when a small amount may be lost. When
                   screen is restored, any inverse characters will have been
                   replaced by a block graphic symbol.

<Ctrl> <f2>        STAR COMMANDS + CLS
                   Same as above, but screen is cleared first.

<Shift><f3>        DOWNLOAD FILE
                   Opens download file on disc. Current filename is shown 
                   in Status window. You are warned if filename already 
                   exists, and have a choice of actions. If you choose to
                   append to an existing file, the filename is suffixed with
                   a "+" in the status window. Pressing <Return> instead  of
                   entering a filename, or against the action prompt, quits.
                   Press <Shift><f3> or <Ctrl><f3> again to close the file. 

<Ctrl> <f3>        DOWNLOAD FILE INCLUDING SCREEN
                   Ditto but saves existing text on screen to the file first,
                   so you don't miss anything already in view. (See note 1) 

<Shift><f4>        UPLOAD FILE
                   Uploads from disc file. Can be used in Converse mode to
                   send long files, or in Command  mode to reset TNC
                   parameters. You are warned if file not found, and given
                   a choice of actions. Pressing <Return> instead of
                   entering a filename, or against the action prompt, quits.
                   You can abort uploading by pressing <Shift><f4> or
                   <Ctrl><f4> again, or by pressing <Escape>. (See note 2)
                   If the file contains 'illegal' characters which will
                   cause problems then you are warned and upload is aborted.
                   See the later section on CONTROL CODES.

<Ctrl> <f4>        UPLOAD FILE + Ctrl-Z
                   Ditto but appends Ctrl-Z plus CR.

<Shift><f5>        SEND TIME/DATE
                   Used in Converse mode; sends message like "73 de Rick
                   G4BLT @ GB7YAX" plus date/time. This uses the realtime
                   clock in the Arc, and does not rely on the less accurate
                   one in the TNC.

<Ctrl> <f5>        SET TNC CLOCK
                   Used  in Command mode; sets TNC realtime clock from the
                   one in the Master. Only needs resetting after TNC power
                   turned off. The TNC clock is not used by the program.

<Shift><f6>        REPEAT LINE
                   Repeats last input line typed, but without a CR at the
                   end, in case you want to alter it or add to it. Do not
                   use if you have started to type another line, as results
                   are rather unpredictable.

<Ctrl> <f6>        REPEAT LINE + CR
                   Ditto, but with CR at the end.

<Shift><f7>        VIEW/PRINT FILE
                   Enables you to view a text file on disc. The current
                   directory is *CATalogued first, so this is useful in
                   itself. When viewing a file, page mode is engaged unless
                   the printer was previously enabled, in which case the
                   file will be printed.
                   
<Ctrl> <f7>        CONFIGURE
                   Enters the configure routine described earlier.

<Shift><f8>        EXIT TRANSPARENT MODE
                   Sends 3 Ctrl-Cs to exit Transparent mode in case you
                   entered it by mistake. Note that pressing <Tab> or Ctrl-C 
                   directly 3 times will not work.

<Ctrl> <f8>        PK AUTOBAUD ROUTINE
                   Sends a single asterisk for PK autobaud routine, though 
                   nothing appears on the screen. Only for PK88/232 etc..

       <f9>        STORED CALLSIGN
                   Recall stored callsign for connect.

<Shift><f9>        ENTER CALLSIGN
                   Enter callsign for connect, eg G7XYZ-2. This is then
                   stored on *KEY9 for recall as above.

<Ctrl> <f9>        Ditto.

Note 1:
When using <Ctrl><f3> to enable downloading to disc, the screen contents
are saved to the file first. No CRs are saved, but all trailing spaces on
lines are. The result should look quite normal if viewed on  an 80-column
screen, but may need a little editing if the file is loaded into a
word-processor or text editor later. Any further text saved in the file will
have CRs as normal.

Note 2:
If you abort upload with <Escape>, up to 80 characters may be lost due to
the RS232 output buffer being cleared. Aborting with <Shift><f4> or
<Ctrl><f4> will avoid this happening, but until the buffer empties a little
the normal transmit cursor will be replaced by an hourglass. Just wait until
the TNC clears a few more packets, and the cursor will return to normal so
you can type. The hourglass symbol is normally only seen during and
immediately after uploading, but you still have access to many of the
<Shift> and <Ctrl> red key functions.


ERROR MESSAGES

If an error is reported in the Status window, all files will be closed and
printer output will be cancelled. You then have 3 choices. You can press
Escape to exit from the program into BASIC, (to make some alterations to the
program for example), you can press Q to Quit to the RISC OS Desktop, or you
can press <Return> to continue running the program. If the error was a
deliberate <Escape>, then a small amount of incoming and/or outgoing text
may be lost.

Under some circumstances, you may be presented with a blank desktop window
when you use the <Q>uit option. Simply press <Return> against the "*"
prompt, and the desktop will appear as normal. 


CONTROL CODES

Any control codes, other than ones which the TNC or the program intercept,
will appear in inverse colours; eg the <Ctrl><Z> end-of-file marker, which
is often used to terminate mailbox messages, will appear as an inverse "Z".
This applies to both text being sent and received. The only codes from the
TNC which are acted upon by the program are CR, TAB (which appears as a
single space), and BELL (which makes a Bleep sound). If you press <Ctrl><G>
(BELL) on the keyboard, it will show as an inverse "G" on the lower screen
window, but will actually make the sound when received at the other station
or if ECHO is ON. DELETE characters in incoming text, (which shouldn't be
there but often are), are displayed as shaded blocks, but will be converted
to harmless spaces for output to printer and/or disc.

Most control codes typed on the keyboard will be sent to the TNC, as well as
appearing in inverse colours. The exceptions are TAB (ie <Ctrl><I>) which is
expanded to a single blank space, and <Ctrl><U> which is used by the program
to delete the current line. In order to avoid causing problems with people
using simple dumb-terminals, it is best to avoid sending any control codes
other than <Ctrl><G> and <Ctrl><Z>. Note that <Tab> is generated with
<Ctrl><I> only, as for convenience the <Tab> key is reconfigured to generate <Ctrl><C> instead.

Received control codes will not be saved into a Download file, nor sent to
the printer, with the sole exception of CR (+LF to the printer as
appropriate). Any received characters with ASCII>127 (ie with the 8th bit
set) will be ignored by the program, regardless of whether 7 or 8-bit
protocol is in use.

The program will refuse to upload files which contain 'illegal' characters;
that is characters such as control codes. (Characters with the 8th bit set,
ie with ASCII>127 are 'masked' to 7 bits before checking. Eg the "" Pound
symbol (163) would be masked so as to appear as ASCII 35 - a "#" Hash
symbol.) The exceptions to this are BELL and TAB, which are fairly harmless,
CR, LF (which is normally ignored), and 26 (<Ctrl><Z>) end-of-file marker.
Note that TAB is expanded to a single blank space.

A classic mistake is to make an ASCII listing of a BASIC program using
*SPOOL, forgetting that there are MODE7 teletext control codes in REM and/or
PRINT statements. Do also be very careful to avoid sending a file containing
the character which the TNC is using as a streamswitch (channelswitch), eg
the default "|". This can result in the message "out of range", but more
subtle nasties can also occur! That is why I now use <Ctrl><^>, which would
be detected as an illegal character in the file, and is extremely unlikely
to be present anyway, and I haven't had any problems since.

The British Pound symbol has no official ASCII code, and different computers
deal with it in different ways under different circumstances. Basically you
should not try and use them on packet, and indeed the "" Pound key will not
operate correctly within the program as it is an 8-bit character. You can
however send the character just above the <Tab> key if you wish; it looks
like an apostrophe on most computers, but BBC Micros and Masters will
interpret it as a Pound symbol.


FILES and !EDIT

Unless you change directories manually using '*' commands, all file
downloading and uploading will use the default directory !Packet.PackFiles.
This can be changed if necessary by editing the !Run file. When you first
create a download file, the filetype will be set to the type mentioned
earlier; usually "Text", ie FFF (plain ASCII text). This is for
compatibility with the RISC OS !Edit text editor. If you are appending to an
existing file, then the filetype will remain at the original setting for
that file. You can view the file at any time using <Shift><f7>. However,
from the desktop you can enter the !Packet directory by holding <Shift>
while double-clicking on the !Packet icon, and then examine and edit the
downloaded files by double-clicking on the file icon. This will load !Edit
if necessary; if it is already installed on the icon bar, then you could
drag the file to the icon bar instead if you prefer. The text will look very
odd at first, as !Edit prefers LFs (ASCII 10) as a line separator, rather
than the more usual CRs (ASCII 13). This is easily cured; press the middle
mouse button and select the edit option, then the further sub-option to swap
CR<->LF. All will then become clear! If you are likely to append to this
file later, reverse the CR<>LF swap before saving it.

Files created with !Edit can still be uploaded even if the LFs have not been
swapped to CRs. The reason is that, at the same time as checking an upload
file for illegal characters, the program counts the LFs and CRs. If there
are more than 3 times as many LFs as CRs then the LFs are automatically
swapped to CRs during uploading.

HINTS

If you leave your TNC running, and then switch your computer on in order to
run this program, you may be faced with a blank screen, even though the
program forces the TNC into command mode. In order to confirm that the TNC
is responding, press <Return> once or twice so you get a "cmd:" prompt.

If you forget to leave the disc in the drive, and the program tries to
access the disc, eg for file upload, then you may get a message from RISC OS
telling you to insert the disc and press Space or click the mouse. Do NOT
use Space; always click the mouse instead. Do not worry if you see a
flashing cursor instead of a steady one after this; it will revert to normal
when the disc file is closed. In some cases, the central status window will
just go blank with a flashing block cursor on the left. Just insert the disc
and click the mouse to correct this. If this doesn't work then press
<Escape> and check you have the right disc!

If your printer fails to feed the paper, and tries to overprint the same
line continuously, then you must configure the machine to send LFs to the
printer. Do this from BASIC or after pressing <f12> from the desktop, with
the command...
*CO. IGNORE
On the other hand, if your printer prints text with double-line spacing,
then you need to prevent the machine sending LFs, and the command is...
*CO. IGNORE 10
Alternatively, you may use the !Configure utility on Applications disc-1. If
you set 'no ignore', (ie by toggling the asterisk off), then it is advisible
to set the ignore character to 0 as well, in order to fully emulate the
*CO. IGNORE command. Having done this, in each case you must press
<Ctrl><Break> or switch the machine off and on again, in order for the
command to take permanent effect, (ie until such time as you change it
again).


Well, that's the lot. If anything isn't clear, or if you have problems,
then please contact me via Packet. Have fun!

73 from Rick G4BLT @ GB7WRG

