BBC KERMIT USER GUIDE
=====================
This guide describes how to use the implementation of KERMIT for the BBC
Computer produced by the Computing Department's Communications Group at
Lancaster University.  BBC KERMIT may be used on BBC models B, B+ and 
B+128; and also on the Master 128.  It operates with the Acorn DFS, 1770
DFS, ADFS, Econet, and any other Acorn-compatible filing system.

The information in this edition applies to version 1.42

EDITION 4.1 July 1986
  Alan Phillips
    BBC KERMIT User Guide


CONTENTS

1.	INTRODUCTION
1.1	BBC KERMIT capabilities at a glance

2.	AN OVERVIEW OF KERMIT

3.	CONTROLLING BBC KERMIT
3.1	Entering BBC KERMIT
3.1.1	The RAM version
3.1.2	The sideways ROM version
3.2	Leaving BBC KERMIT
3.3	BBC KERMIT command language
3.3.1	Command format
3.3.2	Abbreviating commands and parameters
3.3.3	Numeric parameters
3.3.4	Obtaining help
3.4	Reading commands from a file
3.5	Storing parameter settings
3.6	Setting the command screen width
3.7	Function and cursor keys
3.8	Using an auto-boot file

4.	USING BBC KERMIT AS A TERMINAL EMULATOR
4.1	Running a terminal session
4.1.1	Choosing the terminal emulation required
4.1.2	Setting the line speed
4.1.3  Setting parity
4.1.4  Selecting the flow control method
4.1.5  Specifying an "ignore" character
4.1.6  Starting terminal emulation
4.1.7  Sending a break signal
4.1.8  Using the function keys
4.1.9  Using the cursor keys
4.1.10 Pausing screen output
4.1.11 Returning to command mode
4.2	Logging output to a disc file
4.3	Logging output to a printer
4.4	Sending files to a host without KERMIT
4.5	VT52 keypad emulation

5.	TRANSFERRING FILES WITH KERMIT
5.1	Principles
5.2	File type
5.2.1	Binary files
5.2.2  Printable text (ASCII) files
5.2.3  How to decide on the file type to use
5.3	Sending eight bit data
5.4	Starting up the mainframe KERMIT
5.5	Using BBC KERMIT with a remote server
5.5.1  Sending files to a server
5.5.2  Fetching files from a server
5.5.3  Controlling a remote server
5.5.4  Closing down the server
5.6	Using BBC KERMIT with a remote non-server
5.6.1  Sending files to a non-server
5.6.2  Receiving files from a non-server
5.7	Transferring data to and from memory
5.8	Transferring data to a parallel printer
5.9	Handling problems
5.10	Advanced facilities
5.10.1 Interrupting transfers
5.10.2 Using timeouts
5.10.3 File name translation
5.10.4 Detailed protocol control

Appendices
A1.	BBC KERMIT COMMANDS
A1.1 	Commands for general control of BBC KERMIT
A1.2 	Commands for transferring data
A1.3 	Commands for terminal emulation
A1.4 	Commands for control of remote servers
A1.5 	Commands for detailed protocol control

A2.	OBTAINING, BUILDING AND MODIFYING BBC KERMIT
A2.1	Obtaining BBC KERMIT
A2.1.1	The source files
A2.2	Building BBC KERMIT from a hex file
A2.3	Building BBC KERMIT from source
A2.3.1	Source file layout
A2.3.2	The assembly process
A2.4	Changing KERMIT defaults
A2.4.1	Changing the source
A2.4.2	Patching the object code
A2.4.3	Format of the defaults block
A2.5	The hex to binary converter program
A2.6	Contact addresses

A3.	USING THE EDT EDITOR ON VAX/VMS
A3.1	Setting up the terminal details
A3.2	Edit keypad keys
A3.2.1	Models B, B+ and B+128
A3.2.2	The Master 128



1: INTRODUCTION

This user guide describes the KERMIT implementation on the BBC Micro
produced by the Communications Group of the Computing Department at
Lancaster University. It is intended to provide enough information for a
novice KERMIT user to be able to transfer data to and from his BBC micro
to another KERMIT system. Other KERMIT systems are desribed only in
passing: thus you will almost certainly need to consult the equivalent
user guide for the KERMIT system on the other machine.

The guide is divided into several chapters. The next chapter is a general
overview of KERMIT as a whole, and explains its advantages as a file
transfer system over "dumb capture" programs. The succeeding chapter
describes the command language that BBC KERMIT uses. Following that are
chapters that describe how to use BBC KERMIT as a terminal, and how to use
it to transfer data.

The appendices comprise the "reference section". They describe in full
detail the commands available in BBC KERMIT, grouping them by
functionality (i.e. "Commands for file transfer", "Commands for terminal
emulation", etc). They also describe how to obtain BBC KERMIT, and, having
obtained it, how to build it from the assembly language sources or modify
the compiled binary version.

BBC KERMIT is, of course, freely available to anyone who wants it. It can
be obtained from the KERMIT tapes distributed by Columbia University;
alternatively, it can be picked up from Lancaster University's KERMIT
distribution service. This latter option enables it to be acquired either
over file transfer from the Lancaster University VAX 11/780 system, or on
Acorn format discs, or (in small numbers) as programmed EPROMs. The
Lancaster KERMIT distribution service also maintains on-line bulletin
files giving details of new releases of BBC KERMIT and of reported bugs:
these can be consulted in a public-access username.

Lancaster University intend to continue development of the BBC KERMIT
system. We welcome any comments or suggestions that you may wish to pass
on, as well as reports of bugs, problems and deficiencies in the program
or the documentation. The addresses are given in Appendix 2.

1.1 BBC KERMIT CAPABILITIES AT A GLANCE

	 Local operation		Yes
	 Remote operation		No
	 Transfer text files		Yes
	 Transfer binary files		Yes
	 Wildcard send			Yes
	 ^X/^Z interruption		Yes
	 Filename collision avoidance	Yes
	 Can time out			Yes
	 8th-bit-prefixing		Yes
	 Repeat count prefixing		No
	 Alternate block checks		No
	 Terminal emulation		Yes
	 Communications settings	Yes
	 Transmit BREAK			Yes
	 IBM mainframe communication	Yes
	 Transaction logging		No
	 Session logging (raw download)	Yes
	 Raw transmit			Yes
	 Act as server			No
	 Talk to server			Yes
	 Advanced server functions	No
	 Advanced commands for servers	Yes
	 Local file management		Yes
	 Handle file attributes		No
	 Command files			Yes
	 Command macros			No


2: AN OVERVIEW OF KERMIT

KERMIT is a system, devised at the Center for Computing Activities at the
University of Columbia in New York (CUCCA), to permit the simple and
flexible  transfer of data from a microcomputer to a mainframe or another
microcomputer. CUCCA retain the copyright on KERMIT (the programs are not
"public domain"), but have published full information on it and permit
anyone to implement it on their own machines, provided this is not done
for commercial purposes and that copies are sent to them for distribution.
The result is that KERMIT is now available on a very wide range of
machines indeed: very few micros and mainframes do not have a KERMIT of
some sort suitable for them, and the programs can be easily acquired from
the Lancaster University KERMIT distribution service.

The primary design aim of KERMIT is to permit the reliable transfer of any
data whatsoever between systems, and to make the data usable on the system
that receives it if this is possible.  To illustrate why this is
important, and not possible with simple systems, we can consider an
ordinary terminal emulation system that allows data to be captured into
files or sent from them.

Simple terminal emulator systems, such as those commercially available for
the BBC micro, do permit you to transfer files from a mainframe in a
rudimentary way. You would tell the emulator to copy any characters that
appear on the screen into a file, then ask the mainframe to display the
file. The reverse process would let you input data into a mainframe file
from your BBC discs.

The problems arise in the nature of the communications system that connect
the micro to the mainframe, and how the mainframe itself uses this system.
A character of data in a file occupies one byte, which consists of 8
binary digits or "bits". If you regard the pattern of bits representing a
character as a number, this allows numbers ranging from 0 to 255 to be
used. However, many communications systems will allow only 7 of the eight
bits to be transmitted along them. The most significant bit, termed the
"parity bit", is used by the communications system as an error-checking
device. Thus, even though you send a byte of 8 bits to the mainframe, it
may receive only 7 of them. This immediately restricts the range of
characters that can be sent to those whose codes are in the range 0 to
127.

A further restriction may be imposed if the communications system uses
some of those characters for its own control purposes: thus systems often
will use the characters whose codes are 17 and 19 to prevent overloads
occurring. In such systems, you cannot transmit these characters at all.
To make matters even worse, some machines will (apparently arbitrarily)
decide that you could not possibly want to send some characters, so, if
you do send them, it will change them into something else entirely.

As far as the BBC micro is concerned, you could just about live with such
problems. The character range 0 to 127 covers all the printable
characters, so that  transferring text files should just about be
possible. Of course, if the communications line you are using is
unreliable or noisy (a dial up connection over telephone lines, for
instance, can be expected to garble a significant number of characters)
there is nothing to prevent data being corrupted in transmission, so that
you will never be sure that the data that arrives is the data that you
sent.

But although text files are about manageable, those including teletext
control codes or word processor control codes are highly unlikely to be,
since such codes are likely to lie in the range 128 to 255; and tokenised
BASIC programs produced by SAVE haven't a hope of being transferred in any
useful way at all.

KERMIT overcomes all these difficulties by encoding the data it sends
according to a standard set of rules or "protocol". The rules recognise
that many characters cannot be transmitted down a communications line, so
if those characters occur, they will be translated into something that can
be transmitted. The receiving end, of course, will translate them back
again to what they were. This technique enables you to send any data at
all, even SAVEd BASIC files or machine code programs. It further
guarantees that the data you send is the data that arrives, since KERMIT
uses special methods for detecting garbling and will repeat any
transmissions that did not get through correctly. KERMIT's encoding and
checking techniques are more efficient than some other systems that offer
this facility, since only bytes that need encoding actually are encoded,
thus keeping the volume of data sent to the minimum possible.

Besides the problems of actually transferring data corectly, there is the
problem of making it usable on the other end of the transmission link. If
you are sending, say, a SAVEd BASIC program to a VAX, this isn't a
problem, since the VAX can't understand BBC BASIC anyway. Nor does it
matter if you use the VAX system only as an archive: it's irrelevant how
the data is held on the VAX, as long as when it is brought back to the BBC
side it looks the same as when it was sent.

The usability problem does appear, though, if you want to move a file from
a BBC to a VAX and then actually use it on the VAX.  You might, for
instance, word process a file on a BBC, then send it to a VAX to be
printed. In this case, you do not want to transfer the data byte-for-byte,
since the way the BBC and the VAX denote things like the end of each line
of text will almost certainly be different. What you require is that the
file of printable lines on the BBC, which you can process on that machine,
becomes a file of printable records on the VAX, that can be processed
there.

Using a dumb terminal emulator system would probably let you send the
data, but it would appear byte-for-byte as it was on the BBC. And probably
you would get a file on the VAX with extra line-feeds and carriage-returns
that would need laborious editing before you could use the file sensibly.

With KERMIT the problem can easily be circumvented. The KERMIT protocols
define a standard way of indicating the end of a printable line. When you
send a file from the BBC, BBC KERMIT will translate whatever ends the
lines of text in your file into this standard form before sending the
data. The receiving end, seeing this standard end-of-line indicator, will
translate it into however it indicates end-of-line. You thus end up with a
usable file of lines, with no extra characters anywhere.

The requirements you must meet before using KERMIT are simple. You will
need a BBC KERMIT in your BBC micro; a KERMIT program in whatever
mainframe or micro you wish to transfer data to; and a way of linking the
machines, be it a network, an ordinary cable, or a piece of wet string.

For a micro to micro transfer KERMIT is extremely simple to use. You
would, for example, tell one machine that it is going to receive a file,
tell the other to send it, and sit back and let them get on with it. Micro
to mainframe transfers involve an extra step, which is also simple.  BBC
KERMIT includes its own terminal emulator program: you initially use this
to log in to the mainframe as though the BBC micro were an ordinary
terminal. Once logged in, you start the KERMIT program on the mainframe,
and can then flip from giving commands to this mainframe KERMIT, to giving
commands to BBC KERMIT. As before, once you have told each side to
transfer a file, you just sit back and relax while it happens.

And KERMIT provides one further facility to help you spend your time doing
more useful things. As well as sending one file at a time from one machine
to the other, you can send them in groups: thus, you could say "send all
the files on my disc to the VAX" in one command. The KERMIT programs will
send the files one by one until all are gone, quite automatically.

