€DH/Graham Toal/Mainframe Communications Package/16-Jan-1984/
€DF/VLSIC Design Aids Group//Page |P/

€CEIntroduction

   This document is an attempt at a design specification for a new
terminal emulator for the BBC micro.  The software described by the
document does not exist, however an implementation of all the individual
features does, and the software described could be readied within
roughly two to three weeks.

   The author has had considerable experience in writing software
to assist in communication with mainframes, and some of the code
documented below is now in its fourth iteration.

   The philosophy behind this product is simple:

1) Supply a master ROM which does once and for all the tricky business
of line driving, baud-rate selection etc.

2) Support dynamically loadable plug-in modules which perform the
emulation of any specific terminal.

3) Support file transfer as an activity distinct from terminal IO,
by means of a full & proper filing system on the BBC Micro which
communicates to a host-support-package running on the mainframe.

€PE

€CEProduct specification


   Acorns MCP Rom is designed to support communications between a
BBC micro-computer and a remote mainframe via an RS232 cable.

   The word "communications" is used, rather than "terminal access"
or such, to imply the full range of interactive I/O, file access,
and machine/machine interaction.

   The features offered by the new Rom are these:

1) Line driving facilities, such as 7 bit to 8 bit conversion, and
Xon/Xoff protocol.  These facilities are available permanently; i.e.
not merely during terminal access.  This means that programs which
are split between host and local machine can communicate smoothly
without the need to re-write a notoriously difficult piece of code.

   An example of a program which converses with a mainframe (and
one which has actually been attempted) is a BBC micro teletext
server which reads page request from a Vax/VMS process and returns
pages to a shared spool area.


2) A mechanism for plugging-in alternative keyboard handlers and
VDU drivers.

   The terminal code consists of a simple read/test/write loop; the
emulation being supplied in the form of a non-standard VDU stream.  A
side-effect of making the emulation part of the VDU mechanism is that
programs running on the BBC micro can generate output for the same
terminal as is used by the host machine software.  This allows local
development of software on a personal machine before porting it back to
the host.

   Alternative keyboard handling may be equally easily added by
intercepting the "put in keyboard buffer" vector.  If all that is
required, however, is that each key either sends one character,
or <esc> followed by a character, then a lookup table may be supplied
to the standard keyboard package which will allow just that.

3) The default input buffer is approximately 200 bytes large.
An alternative input buffer may be offered to the system when performance
can be improved by doing so.  For instance, the terminal emulation
code may offer the system the entire user-space memory as a buffer,
or a user program may DIM a large array which could be used as the
input buffer.  The offer would be made via operating system calls
to ensure Tube (tm) portability.

4) As some mainframes (or minis) cannot physically transmit 8 bit
codes, and as some operating systems filter out the odd control
character, a link-level protocol has been provided which assumes
only 64 printable characters.  The data conversion is done completely
transparently to the BBC; a call on OSRDCH will return an 8 bit value -
the user will not be aware of any conversions.  Similarly, the host
operating system should install a terminal driver which converts
8 bit values into the appropriate 7 bit sequences.  If this is not
possible on a particular system, it can be easily added to applications
software.

5) File transfer is implemented in a novel way.  Previous ideas on this
subject have been to include a non-standard protocol escape in a terminal
emulation package which would allow the filtering out of data for
subsequent transfer later to disk.  Another method was to have a local
keyboard escape instructing the system to do likewise.  In the view of
the author, this is considered too restrictive.  An alternative mechanism
is supplied in the new software which is to make the host filing system
appear to be a local filing system to the BBC micro.  The user interface
is similar to that of using an Acorn file-server.  To organise such a
filing system, there needs to be a host-support-program running on the
mainframe to interpret the calls to the BBC MOS.  A trial implementation
of this code (fully debugged) in Modula2 on Vax/Unix took three days
to write, and consists of approximately 400 lines of code.

   In light of experience with the trial implementation, it is seen that
such a filing system interface is an ideal way to implement file transfer.
The added attraction of being able to communicate between machines via
shared files has also been seen as a useful function.

6)  The default VDU driver supplied with the new Rom offers the following
features:

   a) *-commands are implemented by the HOST transmitting the
     sequence <esc>* <line> <cr> to the BBC; NOT by a local entry
     via some 'charmed' key.  This is considerably more powerful
     as it allows operating systems which offer start-up command files
     to control the BBC without user intervention.  It still allows
     users to enter *-commands as they can get their host to echo
     back the appropriate escape sequence.  (Hosts which filter control
     characters from their echo - as most do - can have a command "star"
     which takes its command line and precedes it with the appropriate
     sequence).

   b) A minimal subset of escape sequences, which have been chosen to
     be compatible with as many manufacturers terminals as possible.

             esc - A   cursor up
                   B          down
                   C          left
                   D          right
                   K   clear to end of line
                   H   home
                   ?  <x+32> <y+32>   Move to x,y

      This set should allow the immediate use of the terminal Rom
     with most screen editors on most mainframes.

7)  A default keyboard handler is standard, which converts [F0] .. [F9]
  into esc-0 .. esc-9.  F10 (break) remains a soft-key.

    The  cursor keys will send the codes described above for cursor
movement, and pressing [COPY] will enable the traditional BBC local-cursor
editing.

    BBC soft keys will still be available on shift-[softkey].

    Keyboard substitutions are implemented via a 256-byte lookup table,
   so changes to this table may be effected at run-time if desired.


€PE

€CESundry items

   The current Rom as implemented for the Acorn VLSI group offers the
following features.  As these reflect personal preferences on the part
of the author, the may be removed or not by Acorn as desired.

   a)  Cursor auto-repeat is speeded up. (The default is much too slow
      for experienced keyboard users)

   b)  Baud-rate is set to 9600,9600 on hard break.  (The default on
      every mainframe on which I have worked with the exception of GEC)

   c)  The Rom contains extended colour graphics code specifically
      for use by the VLSI group.  It is thought that some sort of
      VDU extensions would be useful in a new Rom, but this particular
      extension is not possible as it was stolen by disassembling a
      commercial product...  (Actually, the code itself contains large
      chunks of the MOS, so we don't feel too guilty about this...)

   d)  *TV 0,1 is executed on hard break.

   e)  The emulator selects non-blinking & small cursor on every mode
      change.  (If you ever meet anyone who actually prefers a blinking
      cursor, please introduce me - GT)

   f)  The econet printer is seleted by default.  (Obviously you cannot
      select the RS423 printer - actually, you might be able to - later
      thoughts on this follow - and most people will not
      have a parallel printer attached locally.)

   g)  The terminal program sends a <cr> ahead on entry, to invoke a
      prompt from the host.  This is safe in almost any context I have
      considered, but users may object to "interfering" by the terminal
      Rom, so it may have to go.

€PE

€CECommands for line control

*shake
*noshake            do/don't send Xon/Xoff to host

*filter
*nofilter           do/don't filter out DLE, or respond to XonXoff
                    from host

*bit8
*bit7
*bit4               select form of line transmission
                    (in 4-bit mode, everything is sent as hex pairs)

*raw
*noraw              ABSOLOUTELY no filtering

*dle  <char>        set DLE char to <char>
*xon  <char>
*xoff <char>        set xon/xoff to <char>


€CECommands for user support


   These commands will most likely be generated by the host.

*SOUND
*ENVELOPE           easy control over sound

*VDU                ultra-simple output of graphics codes

*HIRES
*LORES              alternative standard character sets - 32 to 126 range
                    (useful for high-resolution monitors)
*ULINE
*INVERSE
*BOLD
*APL                alternative character sets - these will be
*GREEK              loaded into the 128..255 range.


€CEFiling system commands


*LOAD
*SAVE
*DIR
*INFO
*LIB
*TYPE
*PRINT
*DUMP
*COPY
*DELETE
*RENAME


€CEMOS calls

OSFILE  (*load etc)
OSARGS  (ptr# etc.)
OSFIND  (openin/openout etc.)


€PE

€CEGeneral: Command loading from the RS423 filing system

   The order of search for * commands when passed to the RS423 filing
system is as follows:

   1) Look in the current DIR
   2) Look in the current LIB
   3) Pass to the host operating system command line interpreter
      via the host-support package

   The order of search for */ commands is as above, with the exception
  that step 3) is not executed.

   A new mechanism is provided whereby commands preceded with a "!"
  are passed ONLY to the host command line interpreter.

   If a *command is issued, and a file is found, the same convention
  is obeyed as is obeyed on the ASADOS filing system, namely that if
  the file has an EXEC address of -1, it should be treated as a
  COMMAND FILE and *exec'ed.

€PE

€CETube (tm) portability.

   All buffer management, IO indirections & Filing systems calls
are Tube (tm) compatible.  This is currently achieved by stealing
sideways service calls with X=&45.  In a production Rom this ought
to be done using an allocated OSBYTE/OSWORD.

   







€CEApplications note on writing a host-support-package
€CEfor the RS423 filing system


   Writing a host support program is a relatively undaunting task.
When a BBC MOS command is issued, it is translated by the filing system
into a simple protocol sequence which is sent to the host.  The host
then either answers back with a response or with an error message.
The only host facility which is assumed is the ability to accept
unbuffered input, and with a minor execution overhead even this
can be put aside.

   It is envisaged that a host support program will map BBC calls
directly onto the calls of its own operating system.  If some calls
are not compatible (e.g. setting the file pointer PTR# as in BASIC)
then a standard error response "Not implemented" is acceptable and
is supported.

   The particular protocol chosen has no great merit except that
it is fairly simple and exceedingly quick to implement.  If Acorn
desire, it may be changed to a greater or lesser extent before release.
It does, howver, work.


€PE
   
€CEGeneral form of filing system protocol:

   BBC   ->   HOST
    
    <1-letter code>
    <optional parameters>
    <esc terminator>
                                 HOST    ->     BBC

                                  <response>
                                  <esc terminator>

                     or
                                 HOST    ->     BBC

                                  "*E" <hex pair> ":" <error string>
                                  <esc terminator>

                     or
                                 HOST    ->     BBC

                                  <esc acknowlegement>

The exceptions to this are

1)   BGET prompts with a single character (the BGET handle in fact)
  and expects a hex pair in return.  No terminators are exchanged.
  This could be altered if an operating system is incapable of
  unbuffered input.

2)   *SAVE and *LOAD handshake after 32 bytes sent in either direction,
  as even systems which do not support Xon/Xoff ought to be able to
  buffer 32 bytes type-ahead.



8 bit data sent from host to BBC & vice-versa is encoded in the form
€CE(byte DIV 16) + ASC("0");(byte MOD 16) + ASC("0").
This offers faster decoding than true hex.  In any event, the BBC can
guarantee to keep up with the mainframe when doing a *LOAD, although
the same cannot be said in reverse.


Note that it is possible for a sufficiently foolhardy implementor to
create an entire filing system by using a host file as a pseudo-disk.
This file would be read in at the start of a session and written out
at the end.  A program of this nature (possibly in FORTRAN or PASCAL)
would almost guarantee portability of the host support package.


Openin and Openout have been implemented in a way that makes no
assumptions as to the number of open files an operating system can
support.  On opening a file, the HOST returns a handle, which serves
the dual role of

   1) being the handle used by BBC programs
&
   2) being the prompt used by the RS423 filing system when
      a byte is being requested by BGET.  This allows the
      BBC end to be completely state-free as regards files being
      open or not.

Also, using the handle as an implicit BGET protocol code, means that
the IO overhead involved with a BGET is reduced by 25%.

A range of handles is recommended by Acorn to fit in with its unified
filing system approach.
€PE

€CEError checking and correction.

   The system does NO low-level data-error checking at all.  In the
experience of the author, communications links are either 100% error-free,
or the errors render the medium unusable.  (This may be a slightly
heretical view - but I stick to it in this context.)

   The overhead of error checking, detection & correction is considered
too high for most users.  Higher-level checking is possible under explicit
user control.  (e.g.  post-transfer CRC checking at both ends).

   A fair degree of error detection is offered by the protocols:  If
data is lost or extra characters are inserted, the filing system will halt
or will force a BRK error.  The user can then enter terminal mode and
manually correct the fault.  It ought to be said that this has not
happened in practice at Acorns local site since both ends of the code
were satisfactorily debugged.


€PE

€CESome final notes on various points


Commands:

   It was mentioned under the section on 'loading programs' that
unrecognised commands were eventually passed on to the host's command
line interpreter.  This is possible only on systems which allow
creation of processes, or recursive calling of command procedures.

   Systems which do not support this still have the option of implementing
extra commands locally withing the host support package, e.g. the *crc
program suggested earlier.  This mechanism allows for almost indefinite
extensibility of the RS423 filing system by customer sites without the
need to write BBC micro code.

   Command lines not recognised at all may respond with "Bad command",
or the appopriate host error message if preferred.  Commands executed
in the host must not request any input.  The output from these commands
is copied to the BBC VDU stream until an <esc> is found.  For fundamental
reasons, no input may be sent in return.  (Explanation on request if
not immediately obvious)

   If a command is issued which accidentaly DOES expect input, it may
be satified by entering terminal mode.



Hand-shaking:

   The way Xon/Xoff handshaking works is that whenever the BBC internal
buffer is almost full, a Xoff character is sent.  When the buffer reduces
below a certain trigger, the Xon character is sent to start output again.

   Some systems expect users to control flow themselves by typing
control-S and control-Q (^S and ^Q).  In this Rom, because of the
buffering of output, it could be some time before these commands take
effect.  In order to allieviate this problem, the following solution is
proposed.  The terminal itself will stop VDU output on detecting a ^S at
the keyboard.  Meanwhile, input will still arrive until it is stopped by
the normal buffer tirggering mechanism.  In this way, no data will be
lost.   Typing ^Q will release the terminal output,  and the emptying
buffer will eventually trigger an Xon character to the host.   This should
be completely transparent to the user.  If a user actually needs to send a
^S or ^Q (or ^P...) to the host, say to a word processor, then it can be
sent by preceeding it with a DLE (^P).

   Alternatively, the BBC convention of holding down Control-shift to hold
off output is acceptable and still works even when ^S is enabled.


Convenience commands:

   With the ability to issue *commands from the host, the user has
access to *spool and *exec.  With these, he or she may input command
scripts to a system which does not support command files, or keep a
console log on a system which does not log console IO.

   *FX commands can be issued at log-in to initialise soft keys, along
with their *KEY definitions, and private !BOOT files can be *EXEC'ed on
arrival to enter a users ID and password, or possibly a long routing
sequence to access a machine via a network.

   *VDU can be used with parameters similar to that of the Basic command,
to set the text on a colour monitor to green, or to define inverse video
mode on a black & white monitor.   As usual with Acorn products, the only
limits are those of your imagination.

