.........*.......*.......*.......*.......*.......*.......*.......*.......*.<
€CEAcorn Computers
€CEVLSI Advanced Research & Development
€CECommunications software



   This document is aimed specifically at that group of people who wish to
use our terminal/filing system rom to the full, but who do not want to
know the internal structure of the code or the implementation details of
the filing system interface.  As such it fills the gap left by the
previous documents on the subject.

   Our rom offers two facilities: a terminal emulation program, and an
interface to a host computer whereby the host's filing-system is used as
if it were local to the BBC, much as a file-server on the Econet (tm) is.

   If you are a new user of this rom, you will need to install it in your
BBC micro.  The position of the rom in the sockets of the BBC is
important.  If you have no other programs in your machine, and are using
it only as a terminal, then you may wish to place our rom in the rightmost
socket.  If you do this, you will be talking to your host computer
immediately on powering on your BBC.  If you choose this option, you will
find it difficult to use your BBC for BASIC, or for playing video games
etc.

   We recommend, however, that you place our rom in the fourth socket from
the right-hand side, i.e. that one immediately to the right of the MOS. If
you already have BASIC in that slot, move it to the right into any of the
other sockets.  At this point, check that the two plastic jumper-plugs to
the north-east of the rom-sockets are both set west.  These jumpers
control whether the rom-slots are addressed for 4k/8k (east) or 8k/16k
(west) roms.

   Having installed your rom, (we will assume from now on that you have
fitted it to the left of your other roms) you start up the terminal
emulator by typing

                            *TERMINAL

which you can abbreviate to *TE. for convenience.  You should now be
able to talk to your host computer.


   This terminal emulator does not have a 'user-friendly' option page to
help you set baud-rates etc.  This does not mean that it is impossible to
do so, however.  It was a design decision that the product would be used
as a simple tool, much in the Unix (tm) style.  The baud-rate at which the
terminal runs is that to which the BBC was set on entry to the terminal
program, which (if you have our rom fitted) is initialised to 9600 Bd on
hard-break.  You may if you wish write a machine code, or even BASIC,
program to initialise the baud-rate and any other MOS parameters you want
to change, and have that program call *TERMINAL as the last thing it does. 

   Although this rom is a 'terminal emulator', it does not in point of
fact emulate any specific terminal.  The history of the control
sequences it accepts and the sequences it generates is that they were
initially copied (incorrectly!) from a document describing the emulator
written by Jeremy Dion at the Cambridge Computer Science Labs. and added
to piecemeal.  The rom does support a common subset of escape sequences
which we have found implemented in nearly every cursor-addressible
terminal we have seen, so could be described as 'sort of VT52 compatible'.

   These cursor-addressing escape sequences are not what our rom purports
to offer, however.  What we have done is supply a mechanism to let
host-computer programs transmit 8-bit binary values to the BBC micro 'VDU'
output stream.  Full details of the VDU stream are to be found in the "BBC
micro Users Guide".  Our mechanism assumes that the only characters you
can generate are <cr>, <esc> and ASCII 32 through 126.  The power of the
BBC graphics more than makes up for the lack of protected fields,
underlining etc.

   It is really intended that with this rom, you can use your BBC as an
intelligent terminal in the true sense of the word, i.e. that you can run
programs locally which interact with your host.  We offer two ways of
doing this.  One way treats the host as master and the BBC as a slave, the
other does the reverse.

   We have added an escape sequence to our terminal program which
effectively describes a remote procedure call.  If you send the characters

       <esc>*command line

then the command line will be executed exactly as if it had been typed in
response to the ">" prompt in BASIC. This is considerably more powerful
than other terminal roms we have seen, where you have to press a reserved
key, and enter your command at the keyboard, in order to execute local
commands.  With our system you can send start-up commands from your host, 
possibly from your login file, which do any configuration of the terminal
you desire.  (The sort of configuration we mean are things like selecting
the parallel printer instead of the default Econet printer)

   As well as being able to call MOS commands, you can use this mechanism
to invoke your own programs off disk. These programs must be executable
machine code, because the MOS does not support automatic loading and
running of BASIC programs. 

   If you load a program from disk, you will be able to talk to your host
computer by writing to and reading from the RS423 port.  Our rom contains
an RS423 Xon/Xoff protocol driver, which remains installed even when the
terminal program is not running.  We made this mechanism available, as the
code necessary to implement Xon/Xoff in the BBC is notoriously tricky.

   The work-space used by the RS423 driver is in a private page in the BBC
workspace area.  When the terminal program is running, however, it offers
the entire rest of memory to the RS423 driver.  This means that the
likelyhood of the BBC needing to send an Xoff to the host is greatly
reduced.  This is particularly useful in screen editors, because such
programs may treat the Xoff character as an editing command.

   It is possible to turn off Xon/Xoff, but if you found that your machine
needed to send them then you will find that your output will get lost if
you disable them.

   The other mechanism we offer for machine-machine communication is a
filing-system interface.  This needs a file-server program to run on your
host, which when you receive this document you will probably not have. 
The file-server interface is documented seperately for the benefit of
system managers and gurus.  The filing system is called up by the command

                       *HOSTFS

   What the filing system offers is a way of saving files on your host and
accessing them from the BBC in a way that is transparent to the program
running, i.e. the program running on the BBC could just as easily be
getting its data from a disk file or a cassete file.

   Although you can use this mechanism as a straight-forward file store,
perhaps to store your VIEW files or to back-up your BASIC programs, it is
much more powerful as a means of communication between two computers: You
can envisage a system in which a program on the BBC (for arguments sake, a
teletext page server) tests for the existence of a file called "Commands"
on its host once every minute, and if it finds it, reads from it.  This
file would contain the channel number and page number of some particular
teletext page (say the one with the Acorn share prices on it...). The
server program would then do whatever is necessary to receive this page
from teletext, and it would write it out to a file (also on the host
filing system) called "Results".

   The advantage of using the filing system interface to do this server is
that the code can be debugged completely without ever using the host (by
using an Econet file-server) and that no machine-machine protocol need be
invented.  Synchronisation is provided automatically by virtue of the
atomicity of file transactions as implemented on the host computer.  (Unix
users will recognise this as the way Unix implements semaphores for
several operations).

   Below follows the various techical details you will need to know in
order to use our rom.  They are in no particular order, and are not
exhaustive.  Much of what you will want to do is probably possible using
the MOS so there will be no specific escape sequences to do it.  Refer to
"The Advanced Users Guide" for details of MOS calls, as it documents them
much better than any current Acorn publication.





Characters sent by the red function keys:

Cursor addressing fuctions:

Eight-bit binary conversion:

Unix 'Termcap' entry:

A program to issue remote commands:

A program to download files:

A program to upload files:

Terminal characteristics:

 (Cursor size)


Unix is a trademark of Bell Laboratories.

Econet is a trademark of Acorn Computers Plc.