=>screen Freebie.bbc











!File Freebie.bbc

                            Acorn Computers

                      Advanced VLSI Research Group


                           Terminal software


   This document describes the first internal release of the terminal

software developed by the VLSI group for internal use.  This document

is aimed primarily at users of large computers who wish to make full

use of the file transfer facilities in this software.


   *NOTE* that this software is currently subject to development, and

is in a state of flux.  Likely changes from the current implementation

will be marked in the text below whenever possible.


   The program being distributed is in two parts:  the first is a

*terminal* program, much like any other, which lets you talk to a remote

computer.  The second is a bona-fide BBC Micro *filing system*.


   The filing system aspect is the new feature of this code which makes

it different from previous terminal roms.  The rom implements most of the

filing system entry points defined by the MOS. It accepts commands through

these entry points, and converts the commands into protocol which it sends

across the RS423.


   Each host system runs a program which interfaces to this protocol,

and which converts the BBC file operations into host file opertaions.

Usually, this conversion will be one to one; the operations of

LOAD file and SAVE file are fairly straightforward; BGET and BPUT are

likewise relatively simple.  Operating system obscurities (such as

records in place of lines with <crs>) can be hidden by this program.


   Hosts which cannot directly implement some calls (such as the

PTR# call from BASIC) have the option of either returning an error

string (which will force an error on the micro) or emulating the

operation by implementing a pseudo-disk in some way.


   Storing an open file as an array in ram would be one way of achieving

this effect.



                          Protocol definition


   This describes the exact definition of the protocol which must be

implemented by a host to talk to the current rom.  This software to

implement this should be written in a modular fashion and be easily

alterable, as the likelyhood of these protocols changing is fairly high.




















   A sample implementation is provided (in Modula2 for Unix), but this

should be used only as a rough guide in case of doubt.  We really want

to see new implementations in different languages, to distribute to

others sites along with the rom.  It is intended that the current rom

and any host software should be distributed free.  Acorn may take up

the idea later and support the package, including writing new host

support packages for the more common machines.  If this happens, the

software will be sold by Acornsoft, and implementors of early host

support packages may be approached to see if they are willing to part

with their code for cash.  So, remember to include a copyright string

in anything you write.  Nothing written outside Acorn will be sold

without explicit permission of its authors.


   The current system is predicated upon having single character I/O

on the host system, although fully transparent 8-bit I/O is not required.

The systems uses the ASCII printable set, and the character <esc> (hex1B).

A future version may allow for hosts which can only send and receive data

in buffered lines.  <esc> was chosen, as it almost certain that any system

which can use cursor-addressable terminals (which use <esc>) will be

able to receive this character.  Some systems may use <esc> as an

interrupt character, but these normally have a way of re-defining the

interrupt character to be something else.  If this issue proves

problematic, the final rom will be changed to allow the internal <esc>

character to be re-defined.


   Here is the protocol:


Definitions


   <hex pair>          byte in range ASC("0")..ASC("0")+15 twice

                          (note that this is NOT 0..9, A..F)


   <esc>               byte of decimal 27 (hex 1B)


Error response


   Whenever an <esc> is to be sent from the host to the micro,

an error response may be returned instead.  If the error response

is in the form "*E" <hex pair> <text> <esc>, then it will be passed

to BRK in a way such that the <hex pair> becomes the error number, and

the text will become the error string.


   If it does not start with "*E", subsequent text up to an <esc> character

will be copied to the VDU output stream, and a "General error" BRK

will be generated.


   The "*E" form is not yet implemented.





















Basic operations:


   LOAD                  L

   SAVE                  S

   FILE ENQUIRE          F


   OPEN INPUT            I

   OPEN OUTPUT           O

   BGET                  !

   BPUT                  <hex pair>

   CLOSE INPUT           {

   CLOSE OUTPUT          }


   REMOTE COMMAND        X


   DIR                   D

   LIB                   R

   CAT                   C

   DELETE                K

   RENAME                M

   COPY                  T


   RE-INITIALISE         A

   KILL FILING SYSTEM    .


LOAD


           BBC -> HOST                HOST -> BBC


           L <text> <esc>

                                      <esc>


                                      <16 hex pairs>

           <esc>

                                      <multiple hex pairs>


                                      <esc>


   Notes: 1) <text> is the filename *and* parameters from the *LOAD

call.  Quotes must be skipped and the string truncated immediately after

the file name.

          2) The next version will handshake (in the manner of "SAVE")

to allow <escape> to be pressed while loading a large file. (Currently,

a load must complete.)

          3) Handshaking is currently only that of the low-level

line driver, i.e. XonXoff. Check that your system allows Xon/Xoff

while in single-character I/O mode.  We reckon that the BBC is actually



















fast enough to do a LOAD without handshaking at all, so the micro

is unlikely to actually send an Xoff to the host.  Xon/Xoff in this

direction has been tested and does work.




SAVE


           BBC -> HOST                  HOST -> BBC


           S <text> <esc>

                                        <esc>

       { repeat while bytes left >= 16

           <16 hex pairs>

                                        <esc>

         end repeat }

           <less than 16 hex pairs> 

                                        <esc>


   Notes: 1) The number of bytes sent between handshaking was

chosen to work on our Vax/Unix.  This number may be different on someone

elses system (i.e. smaller) - so a future version may make this a

parameter too.  If your system sends Xon/Xoff then you should be OK.

(Although the code for Xon/Xoff from host to micro has not been well

tested)



FILE ENQUIRE


         BBC -> HOST                    HOST -> BBC


         F <text> <esc>

                                        <esc>

                                        <16 hex pairs>

                                        <esc>


   Notes: 1) The *INFO command ought to be implemented. It would

parcel up its arguments and call the OSFILE command which we do implement.

Also, when we get round to doing *RUN, the FILE ENQUIRE above will be

used to get the load/exec address.  We intend using the convention

of the Winchester system that an EXEC address of -1 (FFFFFFFF) means that

the file should be *EXECed rather that RUNned.




OPEN INPUT

OPEN OUTPUT




















          BBC -> HOST                  HOST -> BBC


          I (or O) <text> <esc> 

                                       <esc>


   Notes: 1) This system was conceived as a TAPE substitute.  We only

made provision for one file open as input or output at once. 

Consequently, the file handle is implicit and is known to the BBC rom

at the moment.  As the software developed, it came to resemble a

file-server more than a tape, so we really ought to support more

that two file-handles.  The extension will probably be that openin/out

will return a hex pair after the <esc>, followed by another esc.



BGET


          BBC -> HOST                   HOST -> BBC


          ! 

                                        <hex pair>


   Notes: 1) BGET is non-standard in that it has no <esc> response.

A response of


                                        <esc>

and nothing else means "End of file".

and a reponse of

                                        "*E" <hex pair> <text> <esc>

signifies an error.

Unfortunatelty, so does

                                        <text> <esc>

which as the more astute reader will realise means that the

protocol is ambiguous, as the start of the text may contain a valid

hex pair.

         2) A possible extension to cope with the extra channels

mentioned above will be for the handle to be returned by the host

to lie in a printable ASCII range, and for that handle to be used

as the BGET command prompt (in place of "!").  Another alternative

is to use 

         ! <hex pair>

- but the I/O overhead here is just too great, especially if we

decide later to follow all commands with a <cr> for the benifit

of cruddy systems without unbuffered input.

         3) It is almost certain that the data response will

have to be preceded by an <esc> eventually, to remove the ambiguity

above.

         4) It would be nice if ASCII data did not have to be sent

as hex pairs; this would speed up *TYPE etc. quite considerably.



















This may mean that the general text error response will have to

go.  No sad loss.



BPUT


        BBC -> HOST                     HOST -> BBC


        <hex pair> 

                                        <esc>


   Notes: 1) With multiple streams, we can either adopt the policy

that there is a "current" stream; i.e. the BBC remembers the last

file handle used, and changes it with a "CHANGE STREAM" command,

or we can use the protocol

        <hex pair> <hex pair>

                                        <esc>

We cannot, however, use both.  (As opposed to BGET above where

we should be able to find some compromise solution which gives

a reasonable throughput.)



CLOSE INPUT

CLOSE OUTPUT


       BBC -> HOST                      HOST -> BBC


       { (or })

                                        <esc>


   Notes: 1) Obvious extension to


       { <hex pair> 

                                        <esc>



REMOTE COMMAND


       BBC -> HOST                       HOST -> BBC


       X <text> <esc>

                                         <text>

                                         <esc>


   Notes: 1) The text response is copied to the VDU stream up to

the <esc> character.  There is no error response.  If the command

started up expects input, tough cookies.  The <text> may contain

control characters (i.e. <cr> and <lf>).



















          2) This mechanism is intended for passing commands on to

a system CLI.  The host support package may, if its implementor is

feeling nasty, intercept some calls as a way of extending the commands

implemented by the host filing system.  A new command, "*CREATEDIR" for

example, could be added in this way.




DIR

LIB

RENAME

COPY


        BBC -> HOST                     HOST -> BBC


        <command letter> <text> <esc>

                                        <esc>


   Notes: 1) These commands either return quietly, or with an error.

There is currently no provision for affirmative messages.  They will

probably be changed to use


        <command letter>

                                        <esc>

                                        <text>

                                        <esc>



CAT


         BBC -> HOST                    HOST -> BBC


         C <text> <esc>

                                        <text>

                                        <esc>


   Notes: 1)  The <text> parameter is for anyone who wants to allow

a "*CAT Fred" to read other directories.

          2)  The reponse is printed out directly, without formatting

into columns. The quick and dirty way to make this look nice is to

print file names padded to 20 characters with spaces, and NO newlines.

A possible extension will be for a <hex pair> to be sent after the "C"

to tell the host how many lines wide the listing should be. (The BBC

can work this out from the MODE/Window settings.)

          3)  Some hosts may find it easier that others to supply

the catalogue information.  If desperate, an incremental catalogue

could be built up by the system every time it succesfully opens a file

at the users request, or when it save one.  Unsatisfactory, but all we



















can suggest.



We eventually intend getting *RUN to work.  This involves a little

thought about storing load/exec addresses when *SAVEing, (which you

will notice is absent from the above) and has been put off until man~ana.

Its not actually too difficult, but it comes under the "bells & whistles"

category for the project we are currently working on, so there is

no time available.  Making this code into a presentable product is

not going to be too difficult, but this release is going ahead anyway

just to let people try the ideas out.  All feedback will be greatfully

received.  Comments in writing would be preferred, and donations of

host code on 80-track disk would be fantastic.  This software is not

going to be supported at anything higher than a completely informal

level by the author, so don't phone Acorn and expect a reply.


Attached to this are two more documents: One is a wally-guide one-pager

for sticking on walls, the other is an earlier paper submitted to Acorn

as a design proposal.  This software was written mainly to prove that

a shared filing system is an ideal way to implement machine-machine

communications, and is an existence proof of the ideas in the second

paper.





                                PART II


   A few notes on RS423 driving.  The rom replaces the standard RS423

driver in the BBC with one which handles Xon/Xoff in (we hope) both

directions.  It also does a link-level protocol which provides 8-bit

transparency:  You call GET or INKEY and you receive an 8-bit value.

The protocol uses <DLE> (decimal 16, hex 10) as the link-escape code.

The two most useful escapes are


   1) <DLE> + <byte>                Add 128 to <byte>

   2) <DLE> - <byte>                Subtract 64 from <byte>


You will also need

      <DLE> <DLE>                   Single <DLE> as data


1) and 2) above can be combined as in <DLE> + <DLE> - <byte>


   This convention is used in the terminal software, but NOT in

the filing system software.  Complete clean integration of the

two awaits some more detailed thought on filing-system protocols.


   <DLE> = <byte> will re-define the <DLE> character and allow debugging



















of graphical data.  A modula2 code listing of a procedure to generate

the appropriate sequences for all 8-bit values is attached.


This protocol is admittedly not as efficient as could be envisaged,

but it avoids the need for more than one reserved value known to

both ends.  If people find the overhead of this too high (we don't), then

it will be changed in the final issue.




                                Terminal


   The terminal software expects the above conventions to be obeyed

if graphics are to be drawn.


   It also implements a few escape sequences, of the form <esc> <char>.


These are


    <esc> E                  clear to end of line


    <esc> +                  large cursor (takes effect on mode change)


    <esc> -                  small cursor   (ditto)


    <esc> M <Xpos> <Ypos>    Move to X, Y (X & Y encoded as binary+32)


    <esc> * <text> <cr>      Call BBC * command



This latter facility cannot be viewed too highly.  It provides a general-

purpose escape mechanism for future enhancements.  It also allows control

of the BBC from the host, rather than locally as with most terminal

programs.  The BBC obeys the * command then sends an <esc> to the RS423.

   The esc should be read by a "Star" program on the host, in order to

stay in synch with the BBC.  Whenever a * command is executed in this

way, the BBC re-sets the RS423 buffers (which occupy the whole of ram

when in terminal mode) to their normal size of 1 page, and re-sets the

keyboard conventions so that the function keys no longer send escape

sequences.


   These effects are undone when the * command returns to the terminal

program.















VIEW A2.1 


Bytes Free 14395

Editing V.implmnt

Screen Mode 0

Printer default


=>*spool

