APPENDIX 2 : OBTAINING, BUILDING AND MODIFYING BBC KERMIT

This appendix describes how you can get hold of BBC KERMIT and build it
from the assembly language sources, or modify an existing version.

A2.1 OBTAINING BBC KERMIT

There are several ways of acquiring a BBC KERMIT, as follows:

1. You can obtain the files from the KERMIT tapes  distributed by Columbia
University in New York, or by anonymous FTP from their CU20B system.

2. You can obtain the files from Lancaster KERMIT distribution by file
transfer over the JANET or PSS networks, by using KERMIT itself, or on
magnetic tape. The files are held online on a VAX 11/780 running VMS and
can be freely accessed by anyone.

3. You can obtain the files on Acorn DFS format discs from Lancaster
KERMIT distribution: the sources and the compiled binaries will need 1
double-sided 80 track disk, and the documentation (in Wordwise Plus and
printable format) needs 2 more.

If you are within the UK you should use option 2 or 3 above: Columbia will
refer all KERMIT supply enquiries from the UK to Lancaster in the first
instance. Also, Lancaster will generally have a more up-to-date release of
BBC KERMIT than is available from Columbia.

Options 2 and 3 will get you the source files exactly as you need them for
the ADE assembler. For reasons of space, though, the sources are
distributed by Columbia as one monolithic file: you will need to process
this file with an editor on your mainframe to split it into its components
at the clearly marked points before moving it to a BBC machine.

However you get the files, you will eventually have a set of assembler
source files from which you need to generate compiled binaries. If you get
BBC KERMIT on disc from Lancaster distribution you will find binary files
already there, called ROMnnn for the sideways ROM version and RAMnnn for
the RAM version (where nnn is the mark and version number). Otherwise you
will find files called BBCROM.HEX and BBCRAM.HEX, which are Intel hex
dumps of the compiled binaries. You should get these onto a BBC disc, then
run the small BASIC program BBCDEHEX.BAS to convert them to binary form.

The binary of the RAM version can be *RUN immediately: that for the
sideways ROM version should either be loaded into sideways RAM at address
&8000 or programmed into a 16K 27128 EPROM. For those sites not possessing
EPROM programming facilities, Lancaster KERMIT distribution is willing to
program a small number of EPROMs for anyone who supplies them.

A2.1.1 The source files

The BBC KERMIT assembler source is held in a fair number of files and is
now very large (and still growing). The source is split by functionality,
and further divided to keep the files small enough to permit easy and
quick editing (we have taken about 800 lines as the limit for a file). The
organisation is not fixed - we shall refine it with experience and as the
system changes, so the names are not guaranteed to be unchanged from one
release to another.

For version 1.40 the files that make up BBC KERMIT are as follows:

a. Files supplied on disc

BBC KERMIT as issued on disc consists of two sets of files. The first set
consists of the assembler source files and two compiled binary files: the
files are

BBCMIT This is the first file to be assembled, containing compilation
	switches and messages.
BBCDEF Various global defines.
BBCWKS Workspace declarations
BBCMAI The entry code to the system.
BBCCPR The command processor.
BBCCMD Command routines for general commands such as TAKE, SEND, etc.
BBCGEN Command routines for generic functions such as BYE, REMOTE etc.
BBCST1 The SET command part 1.
BBCST2 The SET command part 2.
BBCSHW The SHOW command.
BBCREC Code for receiving files.
BBCSND Code for sending files.
BBCCOM Communications handling code.
BBCTM1 Terminal emulation part 1.
BBCTM2 Terminal emulation part 2.
BBCPM1 Packet handling code part 1.
BBCPM2 Packet handling code part 2.
BBCPM3 Packet handling code part 3.
BBCFIL File handling code.
BBCSB1 General subroutines.
BBCSB2 General subroutines.
BBCSB3 General subroutines.
BBCSB4 General subroutines.
BBCTX1 Texts for messages part 1.
BBCTX2 Texts for messages part 2.

ROMnnn The compiled binary file for the sideways ROM version. Here "nnn"
	gives the mark and version number.
RAMnnn The compiled binary file for the version running in RAM.

A.AssemA  Compiled binary file for a 65C02 assembler that you can use as
	an alternative to ADE.
A.ReadMe  Notes on the 65C02 assembler, describing its differences from
	ADE.

The second set of the files is that comprising the User Guide. This is
supplied as Wordwise Plus source files, and as a spooled, printable file.

b. Files on the Lancaster VAX filestore

The VAX filestore contains most of the above files apart from the WordWise
Plus source files for the User Guide. The assembler source files have the
same names as those on the discs, but each filename has a suffix ".ADE"
added to it.

The other files are:

BBCKERMIT.DOC A printable copy of the user guide. This contains no printer
	control characters, and uses 66 lines on each printed page.

BBCKERMIT.BWR An up-to-date list of known bugs and problems. (Note that
	this file may not always be present)

BBCROM.HEX The compiled sideways ROM version in Intel hex format.

BBCRAM.HEX The compiled RAM version in Intel hex format.

BBCHEX.BAS The BASIC program used to convert the binary files to Intel
	hex.

BBCDEHEX.BAS  A BASIC program to convert from Intel hex to binary. Note
	that the version supplied with BBC KERMIT release 1.02 is not
	suitable for use with release 1.30 and later versions.

BBCASM.HEX An Intel hex form of the 65C02 assembler that you can use as an
	alternative to ADE.

BBCASM.DOC Notes on the 65C02 assembler.

c. Files on tapes from Columbia

Here the files consist of one large source file BBCKERMIT.ADE, containing
a concatenation of the separate sources, plus the additional files listed
above in (b). The Wordwise Plus format files for the User Guide are not
available from Columbia.


 A2.2 BUILDING BBC KERMIT FROM A HEX FILE

The easiest way to obtain a binary version of BBC KERMIT, apart from
getting one on a disc from Lancaster KERMIT distribution, is to generate
it from one of the Intel hex format files.

The hex files will be found on Columbia tapes and in Lancaster filestore
as BBCROM.HEX and BBCRAM.HEX. They are in completely standard format, so
can be converted with any utility you may already have. However a small
BASIC program is provided to do this for you: this is in file
BBCDEHEX.BAS, and is also listed below.

You will need to get the Intel hex files you require to use onto a BBC
disc in some way to start with. An ordinary terminal emulator with dumb
capture facility will suffice for this. You will also need the
BBCDEHEX.BAS program: you can capture this in the same way, or, since it
is short, type it in from the listing. Note that earlier releases of this
program should not be used with BBC KERMIT version 1.30 and later. If you
capture the program, say into a file called DEHEX, you will need to
convert it from text form into a BASIC program in memory. You can do this
with the commands

  *EXEC DEHEX
  SAVE "BDEHEX"

for example.

Once the program is ready you can simply RUN it. It will ask you to name
the input and output files to use, then will do all the necessary
conversion work.


A2.3 BUILDING BBC KERMIT FROM SOURCE

Generating BBC KERMIT from the assembly sources is a fairly easy process.
You will need to arrange the source files on the discs to match the CHN
directives, as described below.

BBC KERMIT was developed using the ADE assembler/editor ROM, available
commercially (see Appendix 2 section 6 for the address). An alternative to
ADE is now available: a 65C02 macro assembler written at Lancaster is
distributed with BBC KERMIT. This assembler runs either in a 27128 EPROM
or in sideways RAM, and is substantially faster than ADE. From version
1.42 onwards the sources are compatible with both assemblers.

A2.3.1 Source file layout

To compile BBC KERMIT you will need either 2 80track single-sided units,
or 1 80 track double-sided unit if you are using DFS, or an Econet file
server.

The source files are divided into 2 groups, reflecting how they can be
held on 80 track BBC discs. Files from BBCMIT to BBCSND inclusive should
be held on one disc surface. Files BBCCOM to BBCTX2 can be held on either
the reverse side of this disc, or on side 1 of another disc. Questions
output from the BBCMIT file during assembly allow the system to configure
itself to point to the right drives: you should reply "N" to the initial
question "All files on one disc surface?"

There should be space for the object file to be placed on the first of the
two surfaces.

Note that if you are using an Econet file server you can place all the
files on one disc: in this case you should reply "Y" to the question "All
files on one disc surface?".

A2.3.2 The assembly process

Having arranged the files on your BBC discs as described above, you can
compile them very simply.

a. Using ADE
To use the ADE assembler, simply type the command *ASM BBCMIT KERMIT.
Precede this command with CTRL-B if you wish to produce a listing on a
printer. The file BBCMIT will output some questions to you to determine
what it is to do. The first question is whether or not you are using the
ADE assembler: reply "Y" to this. Futher questions will  be on the disc
layout, whether you wish to build the sideways ROM or  the RAM version,
and whether you wish a listing to be output, then will do the assembly.

b. Using the Lancaster 65C02 assembler
To use the Lancaster 65C02 assembler, you will need to either  program the
code into a 27128 EPROM or load it into sideways RAM. Once there, you can
compile BBC KERMIT. To simply check the syntax of the sources, without
producing an object code file, type the command *ASSEMBLE BBCMIT -A. File
BBCMIT will ask you if you are using ADE: reply "N" to this. It then asks
you the same questions on disc layout as described above. To produce
object code, the command you use becomes, for example *ASSEMBLE BBCMIT -A
-O KERMIT where the output code file here is called KERMIT. Both the
commands shown above produce listings to the screen only. To list to a
printer, you should add a "-P" option to the command: thus, for example
*ASSEMBLE BBCMIT -A -O KERMIT -P produces object code in file KERMIT and 
a listing to the printer. Note that the "-A" option is essential if you
use the Lancaster 65C02 assembler for BBC KERMIT.

Whichever assembler you use, the listing is configured to be produced on
an EPSON FX80 or compatible printer, and switches itself into 8 lines per
inch, condensed print mode. If your printer is not EPSON-compatible, you
will need to change the PAGE and SYSVDU commands in file BBCMIT to suit
your requirements.

The output listing from ADE will need up to 132 characters on a line. On
the Lancaster 65C02 assembler the line width is configurable: if your
printer only has 80 byte lines then change the PAGE directive in file
BBCMIT to read

  PAGE88,80

The listing currently takes over 2 hours to print on an EPSON FX80, and
occupies over 200 pages.

If you wish, you can list only some of the source files in a compilation.
File BBCMIT contains a number of boolean switches, one for each source
file, that dictate whether that file is to be listed if "selective
listing" is specified. You should change the switches for the files you
wish to list, then specify "selective listing" to the question that is
output at the start of compilation.

A2.4 CHANGING KERMIT DEFAULTS

There are several ways to arrange for BBC KERMIT to use different control
values. The easiest is to leave the code as it is, and use the LOAD, SAVE
or TAKE commands to reset the values as you want them when you start up.
You can, of course, change the source and recompile: or you can leave the
source alone and patch the object code.

BBC KERMIT maintains the current control values in a RAM table, and the
SET command manipulates the values therein. On start up, or using the
RESET command, KERMIT copies a block of defaults into the RAM table. The
SAVE command writes the RAM table to a file, and the LOAD command reloads
from a file into the table.

A2.4.1 Changing the source

You can change the defaults by altering the values held in the main
defaults table. This is held in the source file BBCMAI, and is clearly
marked. Each value is commented to show which parameter it defines: for
possible values see below.

A2.4.2 Patching the object code

If you do not wish to recompile, you can load the object file to memory
and patch it with a machine-code monitor such as EXMON before programming
another EPROM or saving it to disc. Alternatively, you can use a default
setting program written in BASIC by Dave Walker of University College
Cardiff to do the changes: this is available on disc in file B.Patcher, or
from the Lancaster distribution machine in file BBCPATCHER.BAS. This
program handles the process automatically, so there is no need to consult
the following section.

The defaults block is not in a fixed place in the program image, but the
code contains pointers to let you locate it. You can find the base of the
defaults table in the following way:

a. The sideways ROM version

1. Look at byte $8007. This gives an offset to the copyright text in the
ROM header. Add $8000 to the contents to form the address of the zero byte
preceding the string.

2. Follow to the end of the copyright string (which currently reads "(C)
CUCCA 1986") and find the terminating zero byte.

3. The succeeding bytes are then as follows:
Byte	0 The mark number of this release.
	1 The version number.
     2-3 The address (low-high) of the first byte of the defaults table
	  in the ROM.
     4-5 The address (low-high) of the first unused byte in the ROM.

b. The RAM version

The first bytes of the program are as follows:
Byte 0-2 A JMP instruction to the first executable byte of the image.
	3 The mark number of this release.
	4 The version number.
     5-6 The address (low-high) of the first byte of the defaults table in
	  the program.
     7-8 The address (low-high) of the first unused byte in the program.

Note that if you wish to add patch code to the program, you should place
it after the last byte of the image, then alter the address held in bytes
7-8 to be that of the next byte after your added code. Failure to change
this address will result in your patch being over written by the
dynamically-allocated file buffer when the program runs.

A2.4.3 Format of the defaults block

The data in the defaults block is defined as follows:

Byte	 0 The transmit baud rate. This should be set to a number in the
	   range 1..8, where the value is as for the *FX 7 command. (SET
	   BAUD n TRANSMIT)
	 1 The receive baud rate. This should be set to a number in the
	   range 1..8, where the value is as for the *FX 8 command. (SET
	   BAUD n RECEIVE)
	 2 The local echo flag, set to 0 for off or 1 for on. (SET
	   LOCAL-ECHO)
	 3 No longer used.
	 4 The debug flag, set to 0 for off or 1 for on. (SET DEBUGGING)
	 5 No longer used.
	 6 The timeout value BBC KERMIT will ask the other system to use, in
	   the range 0..94. (SET SEND TIMEOUT)
	 7 The timeout value BBC KERMIT will use on the remote system (if
	   TIMER is on) in the range 0..255. (SET RECEIVE TIMEOUT)
	 8 The TIMER flag, set to 0 for off or 1 for on. (SET TIMER)
	 9 The pause BBC KERMIT uses on packet turnround, in the range
	   0..255 (SET PAUSE)
	10 The delay after the SEND command is issued, in the range 0..255
	   (SET DELAY)
	11 No longer used.
	12 No longer used.
	13 The terminal mode keyclick flag, set to 0 for off or 1 for on.
	   (SET KEY-CLICK)
	14 The quote character BBC KERMIT will send. (SET QUOTE)
	15 The eight-bit prefix BBC KERMIT will use for preference. (SET
	   EIGHT-BIT-PREFIX)
	16 The end-of-line byte that BBC KERMIT uses for the first packet
	   it sends. (SET SEND END-OF-LINE)
	17 The end-of-line byte the remote system will use. (SET RECEIVE
	   END-OF-LINE)
	18 The pad character BBC KERMIT will send. (SET SEND PADCHAR)
	19 The number of pad characters BBC KERMIT will send. (SET SEND
	   PADDING)
	20 The pad character BBC KERMIT will ask the remote system to send.
	   (SET RECEIVE PADCHAR)
	21 The number of pad characters BBC KERMIT will ask the other end
	   to send. (SET RECEIVE PADDING)
	22 The current parity setting. This should be one of:
		0 MARK
		1 SPACE
		2 EVEN
		3 ODD
		4 NONE
	23 The current file type. This should be 0 for ASCII or 1 for
	   BINARY. (SET FILE TYPE)
	24 The  current  end-of-record  type used for ASCII files (SET FILE
	   TYPE ASCII). The value should be one of:
		0 LFCR
		1 CRLF
		2 LF
		3 CR
	25 The current source of data. The value is 0 for FILE or 1 for
	   MEMORY. (SET SOURCE)
    26-27 The base address for the source memory area (low-high). This
	   must be set if byte 25 is 1. (SET SOURCE MEMORY)
    28-29 The top address for the source memory area plus 1 (low-high).
	   This must be set if byte 25 is 1. (SET SOURCE MEMORY)
	30 The current destination for data (SET DESTINATION). Values are:
		0 FILE
		1 MEMORY
		2 PRINTER
    31-32 The base address for the destination memory area (low-high).
	   This must be set if byte 30 is 1. (SET DESTINATION MEMORY)
    33-34 The highest address for the destination memory area (low-high).
	   The value is normally the base of the MODE 7 screen area $7BFF,
	   and must be set if byte 30 is 1 (SET DESTINATION MEMORY).
	35 The start of packet character that BBC KERMIT will send. (SET
	   SEND START-OF-PACKET)
	36 The start of packet character that the remote system will send.
	   (SET RECEIVE START-OF-PACKET)
	37 The maximum packet size BBC KERMIT asks the remote system to
	   send. (SET RECEIVE PACKET-LENGTH)
	38 The size of the file buffer area used in pages. The value must
	   be in the range 1..64. (SET FILE BUFFER-SIZE)
	39 The file warning flag, set to 0 for off or 1 for on. (SET FILE
	   WARNING)
	40 The incomplete file disposition flag, set to 0 for DELETE or 1
	   for KEEP. (SET INCOMPLETE)
	41 The current flow control method, set to 0 for XON/XOFF or 1 for
	   CTS/RTS. (SET FLOW-CONTROL)
	42 The significant size of the file suffix string defined in the
	   next field. The value is 1..8 if a suffix is wanted, or 0 if none is to
	   be added. (SET FILE SUFFIX)
    43-50 The suffix added to a BBC name to generate a remote file name.
	   The number of characters used is defined by byte 42. Note that
	   the suffix does not include the "." character. (SET FILE
	   SUFFIX).
	51 The TAKE-echo flag, set to 0 for off or 1 for on. (SET
	   TAKE-ECHO)
	52 The colour to be used for text in 80 character terminal mode.
	   Colours available are red, green, yellow, blue, magenta, cyan
	   and white, corresponding to values 1..7 (SET VDU-COLOUR)
	53 *TV flag, set to 1 if a *TV is to be done on entry to terminal
	   mode and 0 if it is not. (SET TV)
    54-55 The two *TV parameters to be used if byte 53 is 1. (SET TV)
	56 VDU ignore flag, set to 1 if an ignore character is defined, and
	   0 if it is not. (SET IGNORE)
	57 The incoming terminal-mode character to be ignored if byte 56 is
	   1. (SET IGNORE)
	58 The number of byte periods to wait before testing clear-to-send
	   when transmitting a character. (SET MUX-WAIT)
	59 The character that triggers a help display in command mode. (SET
	   HELP-TRIGGER)
	60 The maximum number of retries BBC KERMIT will make in an attempt
	   to send a packet (SET RETRIES)
	61 The handshake type in use (SET HANDSHAKE). The value should be
	   one of:
		0 NONE
		1 BELL
		2 CR
		3 LF
		4 XON
		5 XOFF
	62 The terminal emulation type to be used (SET TERMINAL). The
	   values currently allocated are:
		0 TT40
		1 TT80
		2 VT52
		3 VT100
		4 TEK
		5 Un-named (A)
		6 Un-named (B)

	   If the value is set to $FF, BBC Kermit will use the default
	   appropriate to the machine it is running in.
	63 Controls how filenames sent by the remote system are handled
	   (SET FILE NAME). Values allowed are:
		0 Translate name from name.type format
		1 Use name exactly as specified


The table format is fixed, and will not be changed by Lancaster in later
releases. Additional facilities will be added to the end of the block
only. Note that it is up to you to make sure that the values you put in
the default block make sense: what BBC KERMIT does with inconsistent ones
is unlikely to be anything you'd like it to.

A2.5 THE HEX TO BINARY CONVERTER PROGRAM

The Intel hex forms of the compiled BBC KERMIT and the Lancaster 65C02
assembler can be converted into binary files using a simple converter
supplied as the file BBCDEHEX.BAS. This can be brought on to a BBC disc
and *EXEC'd to give a BASIC program: alternatively, since the program is
short, it can be typed in directly. For convenience, a listing of the
program is supplied below.

	 100 REM Intel hex to binary converter
	 120 REM Version 2 November 1985
	 140
	 160 CLOSE#0
	 180 DIM image 20480
	 200
	 220 INPUT "Name of input hex file? " in$
	 240 INPUT "Name of output binary file? " out$
	 260 in%=OPENIN(in$)
	 280 IF in%=0 THEN PRINT"Input file does not exist":END
	 300
	 320 imagesize% = 0
	 340 record% = 0
	 360 REPEAT
	 400  REPEAT UNTIL (BGET#in%=ASC(":")) OR EOF#in%
	 420  IF EOF#in% THEN PROCsave:CLOSE#0:END ELSE PROCreadrecord
	 440 UNTIL FALSE
	 460
	 480 END
	 500
	 520
	 540 DEF PROCreadrecord
	 560 LOCAL count%,address%,storedcsum%,type%
	 580 record%=record%+1
	 600 csum%=0
	 620 count%=FNgetbyte
	 640 address%=FNgetbyte*256+FNgetbyte
	 660 IF record%=1 THEN base% = address%
	 680 PRINT"Record ";record%;" : Size ";count%;", address $";~address%
	 700
	 720 type% = FNgetbyte
	 740 IF type%<>0 AND type%<>1 THEN PRINT"*** Unknown record type ";
type%;" detected":CLOSE#0:END
	 760 IF type% <> 0 THEN PRINT"+++ End-of-file record detected":
ENDPROC
	 780 PROCreaddata(count%)
	 800 storedcsum% = FNgetbyte
	 820 IF csum%<>0 THEN PRINT"*** Checksum error":CLOSE#0:END
	 840 ENDPROC
	 860
	 880 DEF FNgetbyte
	 900 LOCAL value%
	 920 value%=FNgetnibble*16 + FNgetnibble
	 940 csum% = (csum% + value%) AND &FF
	 960 =value%
	 980
	1000 DEF FNgetnibble
	1020 LOCAL char%
	1040 char% = BGET#in%
	1060 IF char%>=ASC("A") THEN =char%-ASC("A")+10 ELSE =char%-
ASC("0")
	1080
	1100 DEF PROCreaddata(count%)
	1120 LOCAL I%
	1140 pointer% = address% - base%
	1160 FOR I% = 1 TO count%
	1180  image?pointer% = FNgetbyte
	1200  address% = address% + 1
	1220  pointer% = pointer% + 1
	1240 NEXT
	1260 IF pointer% > imagesize% THEN imagesize% = pointer%
	1280 ENDPROC
	1300
	1320 DEF PROCsave
	1340 loadaddress% = base% OR &FFFF0000
	1360 OSCLI("*SAVE "+out$+" "+STR$~image+" "+STR$~(imagesize%+
image)+" "+STR$~loadaddress%+" "+STR$~loadaddress%)
	1380 ENDPROC

A2.6 CONTACT ADDRESSES

If you wish to use the ADE assembler/editor, you can obtain it from

	SYSTEM
	12 Collegiate Crescent
	Sheffield
	UK

See adverts in Acorn User for the current price. Currently BBC KERMIT is
compiled using version 2.02. ADE will continue to be the primary assembly
method used for BBC KERMIT, but all releases from 1.42 onwards will be
also be fully compatible with the Lancaster 65C02 assembler supplied with
it. The 65C02 assembler does not contain an editor, but you can use any
word processor or other editor to manipulate the source files.

If you wish advice, or have any bug reports or comments on BBC KERMIT, you
can contact me at Lancaster University in several ways.

	Postal address:

	Alan Phillips
	Communications Group
	Department of Computing
	Computer Building
	Lancaster University
	Lancaster UK

	Telephone:	 01524-65201 x 4881

	Electronic mail: SYSKERMIT @ LANCS.VAX1

	JANET address:	 000010404000.FTP.MAIL
	PSS address:	 234252400101.000010404000.FTP.MAIL

Contact by electronic mail is the preferred method if you can manage it:
please remember to specify your name, where you are mailing from, and the
full mail address and NRS name (if you have one) for the reply. I can
reply only with difficulty and no guarantee of success over ARPA, as the
gateway I have to use is of low reliability: I have no authorisation for
uucp so cannot reply at all by this route. A JANET address is preferred if
you can provide one. I will attempt to reply to all enquiries, and will
usually do so within one or two weeks: if you don't hear from me by then,
you should assume that I am unable to get mail to you for some reason and
contact me by another route.

I will be pleased to supply details of our KERMIT distribution service on
request: we have a complete collection of all available KERMIT
implementations, and can distribute these on magnetic tape, over the JANET
or PSS networks, or, for some versions, on floppy disc. Distribution is
free to all educational or research council institutions: commercial
customers are asked to pay a small handling charge. The increasing use of
this service means that we cannot currently undertake distribution to new
customers outside the UK or Eire.
