File QL2KER.DOC
---------------
Kermit for the Sinclair QL
--------------------------
AUTHOR : David Harper
Dept of Applied Maths and Theoretical Physics
The University
P.O. Box 147
Liverpool L69 3BX
EMAIL : SX36 at UK.AC.LIVERPOOL.IBM
OPERATING
SYSTEM : QDOS (Sinclair QL and derivatives)
LANGUAGE : BCPL (Metacomco)
DATE : 29 May 1987
(1) Generating the EXECable program
This version of QL Kermit is written in BCPL and should be compiled using
Metacomco's BCPL Development Kit
There are four source files. They should be renamed as follows (assuming
that you have disc drives - if not, change FLP to MDV).
File QDOS name Purpose
QL2KER.BCP FLP2_KERMAIN_BCPL Command parser & executive
QL2SET.BCP FLP2_KERSET_BCPL Handles the SET command
QL2PRO.BCP FLP2_KERPROTO_BCPL Kermit protocol routines
QL2HDR.BCP FLP2_KERHDR Header file - defines globals
and manifest constants
The header file is imbedded in each of the other three files using the
BCPL GET directive. Within KERMAIN, KERSET and KERPROTO it is referred
to as FLP2_KERHDR so if you are using microdrives, you should edit
each of the three files and change the line
GET "FLP2_KERHDR"
to
GET "MDV2_KERHDR"
To construct the EXECable program, compile the files KERMAIN, KERSET
and KERPROTO then use the linker 'BLINK' to join their object code
files together. The result is a program which can be run under QDOS
in tandem with other tasks, using QDOS's multi-tasking capability.
I use the name FLP2_KERMIT_EXE for the EXECable file.
***** NOTE : Metacomco BCPL Development Kit versions 1.nn *****************
* *
* If you don't have a copy of version 2.0 (or later) of Metacomco's *
* BCPL compiler, you will need to assemble the file 'qtrap_asm' and *
* link it with the other object code files. You should alter the *
* header file 'kerhdr' to include a suitable global reference to qtrap. *
* Dr Alex Finch's version of qtrap has global number 276 so you should *
* include *
* *
* GLOBAL $( qtrap : 276 $) *
* *
* in 'kerhdr' at some point, or add it to the existing global list. *
* *
* Versions from 2.0 have qtrap as part of the BCPL library at global 101 *
* and so they don't require this extra file. *
* *
***************************************************************************
(2) Running Kermit
To run the task, use
EXEC FLP2_KERMIT_EXE
You can use EXEC_W if you prefer, but Kermit will run quite happily
alongside other tasks as long as they don't demand too large a share
of processor time. Besides, since Kermit doesn't support QDOS commands
such as DIR, it is useful to be able to switch to SuperBasic for a moment
to issue such commands directly. This doesn't interfere with Kermit
in any way, and you can even do it while Kermit is engaged in file-transfer.
When Kermit is expecting a command, you will see the prompt
QL-Kermit (Local) >
and the cursor should be flashing just after the '>'. (If the cursor is
somewhere else on the screen, e.g. the SuperBasic command window, use
Control-C to switch between tasks until the Kermit cursor begins to flash.)
(3) Kermit commands
Kermit recognises the following commands :
HELP Lists all recognised commands, with
any operands.
HELP SET List all the settable options
EXIT ) End the Kermit task i.e. remove it from
END ) QDOS
SET <parameter> <value> Alter one of the settable options -
see next section.
SHOW Show the values of some of the settable
options.
SERVER Enter server mode operation
CONNECT Open the serial communication line
DISCONN Close the serial communication line
(use this when you wish to change
the line attributes e.g. parity)
TAKE <local filename> Take Kermit commands from a file
SEND <local-file> <remote-file> Send a file to a remote Kermit
GET <remote-file> <local-file> Fetch a file from a remote serving
Kermit
RECEIVE <local-file> Receive a file from a remote Kermit
FINISH Issue a FINISH command to a remote
serving Kermit.
(4) Options of the SET command
The SET command recognises the following options. (*) means that I haven't
yet implemented this option e.g. block-check type. Items in square brackets
[ ... ] are optional. N is any non-negative number. CHAR is a single
character.
Option Values Notes
------ ------ -----
BLOCK-CHECK (*)
DEBUG ON [filename] | OFF [CLOSE] See note 2
DELAY N (less than 60)
8BIT-PREFIX ON | OFF Do we do 8th-bit prefixing
END-OF-LINE CR | LF The character we recognise
as end-of-line
ESCAPE-CHAR F1 | F2 | F3 | F4 | F5 | Key to escape from terminal
ESC | CTRL-ESC emulation back to Kermit
command mode
FLOW-CONTROL (*)
HANDSHAKE CTS | XON | NONE Type of handshaking to do
with the other Kermit. See
note 3.
LOG (*)
MARKER N (0 <= N < 27) Start-of-packet character
PACKET-LENGTH N (30 < N < 93) Largest packet we want to
receive
PADDING N Number of padding chara-
cters we need to receive
PAD-CHAR N (0 <= N < 32) The padding character we
need to receive
PARITY EVEN | ODD | MARK | SPACE | See note 4
NONE
PAUSE N
PREFIX CHAR The character we propose
to use for 8th-bit prefix
REPEAT-COUNT (*)
RETRY N Our retry threshold
TIMEOUT N Interval after which we
should be timed-out
LINE 1 | 2 To select port SER1 or SER2
See note 5
DIR (*)
OVERWRITE (*)
BAUD 75 | 150 | 300 | 600 | 1200 | Baud rate. See note 6
2400 | 4800 | 9600
TERMINAL-TYPE (*)
INTERFACE NONE | RAW | QCONNECT Type of interface hardware
in use. See note 1.
TAKE-ECHO ON | OFF Whether we echo commands
from TAKE files to the
screen.
Notes
-----
1. Kermit includes routines to enable it to communicate via the Tandata
QConnect communications module. This 'little black box' is particularly
useful in implementing XON/XOFF handshaking to allow the QL to work
with mainframes and packet-switch systems (eg Gandalf PACX) that simply
don't use hardware CTS/RTS handshaking. The QL's serial ports only have
CTS/RTS capability, and I haven't written any cunning XON/XOFF-handling
code into Kermit. So if your mainframe uses XON/XOFF, a QConnect box
might be a good investment. As an added bonus, it comes with a rather
good VT100 emulator - Kermit only has glass-teletype at the moment !
2. The debugging facility writes out details of each packet as it is
received or sent, plus timeouts (if they occur) and each attempt to
open a file. By default, debugging reports are sent to the screen
and may be enabled using SET DEBUG ON and disabled using SET DEBUG OFF.
However, if you wish to direct the reports to a file, use the form
SET DEBUG ON file-name
After this, SET DEBUG ON/OFF enables or disables reporting to that file,
which remains open. To close a debugging file, use
SET DEBUG OFF CLOSE
This closes the current debugging file (unless debugging is to the screen -
we don't want to close the screen channel !) and disables debugging. A
subsequent SET DEBUG ON will output to the screen.
You may open a new debugging file without closing the previous one. For
example
SET DEBUG ON flp2_debug_file1
...
...
...
SET DEBUG ON flp2_debug_file2
In this case, flp2_debug_file1 will still be open but Kermit has forgotten
its channel ID so it can't close it. It will remain open until you stop
the Kermit job, whereupon QDOS closes all outstanding open files as part
of its housekeeping.
3. In the absence of a Tandata QConnect module (Note 1 above), the option
SET HANDSHAKE XON cannot be honoured, so you shouldn't use it. When using
raw (i.e. no little black boxes) communications, choose CTS or NONE.
4. The Tandata QConnect box cannot operate using MARK or SPACE parity.
5. The QL has two RS232 ports, SER1 and SER2. One of them is configured
as DTE and the other as DCE. In practical terms this means that you should
use SER2 (SET LINE 2) if you want to communicate with a mainframe and
SER1 (SET LINE 1) if you are Kermitting with another micro which thinks
that it is a terminal. The Tandata QConnect box will only plug in to SER2,
so SET INTERFACE QCONNECT and SET LINE 2 must be issued together.
When I link my QL with a BBC micro, the Beeb's RS423 socket is connected
to the the QL's SER1 socket (via two adaptor leads and a female-female
gender changer - why do I use two micros that have non-standard serial
comms hardware ?!).
6. The QL supports these baud rates : 75, 300, 600, 1200, 2400, 4800, 9600
If you are using a Tandata QConnect box, the baud rates are 150, 300, 600,
1200, 2400, 4800, 9600
(5) General notes about using Kermit
TERMINAL EMULATION
Most people will want to use Kermit to transfer files to/from mainframes.
A simple teletype terminal-emulator is included to allow you to call the
remote system. If you are using a QConnect box, don't worry about the
strange message which appears (in red) when you issue the CONNECT
command. It is simply telling you the command string which it has sent to
QConnect to set up the connection.
The terminal emulator will print out any ASCII character in the range 32 to
126. It interprets a CRLF sequence from the remote system as a single LF,
which is the QDOS newline character. Backspace (ASCII 08 dec) moves the
cursor one space to the left and formfeed (ASCII 12 dec) clears the screen.
Bell (ASCII 07 dec) causes the message '<beep>' to appear (in red) on the
screen. Any other character in the range 0 to 31 is displayed in the form
'<#Xnn>' where nn is the hexadecimal representation of the number.
As far as Bell is concerned, I will probably make this trigger the QDOS
BEEP routine in the next release.
The QL sends all ASCII characters from 0 to 127 (though ASCII 03, CTRL-C,
can never be sent because it is the key used by QDOS to switch from one
task to another). The cursor keys and function keys are ignored, except
for Left and CTRL-Left which both generate ASCII DEL (127 dec) - so
CTRL-Left can be used as the delete key just as it is during QDOS buffered
terminal input.
The key to be used to escape from terminal emulation back to Kermit command
mode can be altered using the SET ESCAPE option. To begin with, it is
the ESC key, but your mainframe might require that you use this key so
the next best alternative is probably F1 or one of the other function keys.
FILE TRANSFER
The status reports during file transfer are fairly basic. Kermit prints
a message to indicate that it is sending/receiving a file, with the
name of the file. During transfer, it prints a full-stop '.' after every
5th packet it receives successfully, but for every packet which it fails
to receive (either because it timed out, or because the received packet
was incorrect in some way) it prints out a percent symbol '%'
A successful file transfer might look like this :
QL-Kermit (Local) > RECEIVE flp2_datafile1
Receiving file flp2_datafile1
......................
QL-Kermit (Local) >
while a transfer which suffered one or two hiccups might appear as
QL-Kermit (Local) > RECEIVE flp2_datafile1
Receiving file flp2_datafile1
.........%....%%.......
QL-Kermit (Local) >
Here, three errors occurred but since there are twenty full-stops, the
average is three errors for 100 packets successfully received so it's
not as alarming as it might appear.
SERVER MODE
Kermit can operate as a server. This is useful when transferring files to
and from another micro. Kermit recognises two generic exit commands,
FINISH and LOGOUT. FINISH returns Kermit to the state where it is waiting
for input from the QL keyboard, while LOGOUT can be used to terminate
the Kermit task from the other micro.
Debugging can be carried out in server mode, and status reporting to the
QL console screen is carried out as in non-server mode.
TANDATA QCONNECT
The QConnect device has a few idiosyncracies which affect Kermit. The
technical information provided by Tandata in the user manual is
brief and difficult to understand. Some of the things that the manual
claims QConnect can do are in error - for example, the QL <-> QConnect
serial line can only operate at 9600 baud. When the QConnect <-> remote
line is working at a lower speed, this causes serious buffering problems
inside the QConnect when the QL sends a burst of more than 20 bytes -
in practise, this means that files can be received by QL-Kermit at any
baud rate (when it only has to send short packets), but QL-Kermit can
only send files via a QConnect at 9600 baud. At lower speeds, data packets
become garbled as they pass through the QConnect.
Terminal emulation works at lower speeds, however. Perversely,
the terminal emulation code is a little slow and operation at
9600 baud sometimes encounters framing errors. I'm afraid that
4800 is the maximum reliable speed for terminal emulation, but
file-transfer can only be done at 9600.
This situation reflects a design flaw in the QConnect and I shall be
taking it up with Tandata in the near future. I hope that a subsequent
release of QL-Kermit will be able to make use of an improved QConnect !
FILES and QDOS
Kermit doesn't (at present) do any clever file-name translation when it
is in server mode and it receives a file name in an R or F packet from
the other Kermit. So the other Kermit must use full QDOS filenames in
its SEND and GET commands. I know that this is contrary to the guidelines
on file nomenclature in the protocol since the file names must contain
underscores - I'll amend the next release so that underscores can be
replaced by full-stops. For example, flp2_data_file ought to be sent in
an R or F packet as flp2.data.file
Kermit will not overwrite an existing file - the transfer is abandoned
as if the file name were unacceptable to QDOS. This is where it is
particularly useful to multi-task Kermit so you can switch to SuperBasic
to check the directory and delete files.
I haven't tried to use Kermit with microdrives - it works very well with
disc drives and RAMdisc, but I will include software buffering in the
next release so that an entire file can be loaded into a buffer on the
QL to avoid having to read repeatedly from microdrives. In an ideal world,
QDOS would be able to do this automatically but the microdrives are
notoriously slow.
CATASTROPHES
Kermit is still imperfect. I'm sure that users can find some way of
crashing it - at least, I hope so because it means that I can (hopefully)
correct the error. One or two QDOS errors will prove fatal to Kermit.
For example, if it is unable to open a serial line (or to close it !),
this will be detected in the software and Kermit will shut itself down
with (usually) a message to explain why.
Some catastrophes are unforeseen by the program, but they may be picked
up by the BCPL run-time system. If this happens, the BCPL routine called
ABORT is called (by BCPL itself, not by Kermit) and a traceback of all
calling routines is printed to the screen. The most useful information
here is the list of the routine names - they appear as the first (non-
numeric) item on each line and are generally 7 characters long. (The
run-time system only stores the first 7 characters of each routine name
for the purpose of error tracing.)
If Kermit stops with an error report, make a note of what is on the screen
and (if possible) what Kermit was supposed to be doing when it failed.
I'd be interested to hear about this.
(On a slightly mischievous note : you can make the BCPL run-time system
do an ABORT by typing ----
SET TAKE-ECHO ON
This is a known bug, but I'm afraid I don't know how to solve it !)
ACKNOWLEDGEMENTS (Not the Kermit kind !)
Several individuals and companies have helped in the production of this
Kermit and deserve credit.
First of all, C.G.Selwyn wrote the original version for the Tripos operating
system. I take responsibility for all of the errors I may have introduced
into his program in the course of converting it to work under QDOS.
My thanks to Mr Selwyn, and to Icarus Sparry of the Microcomputer Unit
at Bath University who sent me the original program.
Dr Alex Finch of the Physics Dept at Lancaster University wrote the
assembler version of the routine 'qtrap' which is needed to compile
Kermit using Metacomco's BCPL Development Kit prior to version 2.0
Thanks also to Tandata Marketing Ltd who provided me with the source code
of their communications package which drives the QConnect device. Their
programs helped me to understand how the device should be used with
Kermit.
Many thanks to Metacomco for sending me a pre-release copy of version 2.0
of their BCPL development system. This includes a very useful library
routine for invoking QDOS traps directly.
Finally, thanks to Mike Lewis of Liverpool University Computer Lab for
arranging the loan of a line-monitor to me while I was trying to
understand why the QL/QConnect couldn't send files properly. The line
monitor proved to be a very useful tool.