BLib.BBCFile - Read and Write Acorn BBC BASIC data files
	 ========================================================
		         File: Net - Update: 1.01
		 Author: J.G.Harston - Date: 12-Feb-1992


  The BBCFile library provides routines to read and write data files in the
format that Acorn BBC BASICs use for PRINT# and INPUT#. The routines were
originally written to speed up access to serial files on unbuffered filing
systems, such as NFS 3.xx. Non-Acorn versions of BBC BASIC usually do not
use the same data format as Acorn BASICs, so these routines allow you to
access Acorn-format data files regardless of the native format the BASIC
the program is running on actually uses.

Requirements and Dependancies
=============================
  The library requires a global control block of at least 15 bytes in
length to be accessible with X% holding the address of this block, and Y%
holding X% DIV 256, and data% pointing to a block of at least 257 bytes of
memory.

  This can easily be set up with DIM ctrl% 31, data% 256 near the start of
the program and X%=ctrl%:Y%=X%DIV256 at the begining of the major program
code and at the start of any main program loop.

  The library requires the PROCgbpb() function in the FileIO library.

Routine Summary
===============
PROCBBC_WrStr()      - write a string to an open file
PROCBBC_WrInt()      - write an integer to an open file
PROCBBC_WrReal()     - write a real to an open file
  FNBBC_Rd()         - read the next string, integer or real from an open file

DEFPROCBBC_WrStr(out%,str$)
===========================
PROCBBC_WrStr() writes the string to the specified channel in Acorn BASIC
format.

DEFPROCBBC_WrInt(out%,int%)
===========================
PROCBBC_WrInt() writes the 32-bit integer to the specified channel in Acorn
BASIC format.

DEFPROCBBC_WrReal(out%,real)
============================
PROCBBC_WrReal() writes the 40-bit real to the specified channel in Acorn
BASIC format.

DEFPROCBBC_Rd(in%)
==================
FNBBC_Rd() will read the next item from the specified input channel and
return either an integer, a real or a string depending on what the next
item is. If the next item cannot be recognised, then zero is returned and a
single byte is stepped past.

Technical details
=================
BBC BASIC stores data in files with PRINT# in the following format:

Type       Acorn format       Russell format
         -------------------------------------
Integer        &40               b0-b7
              b0-b7              b8-b15
              b8-b15            b16-b23
             b16-b23            b24-b31
             b24-b31              &00

Real           &FF          mantissa b0-b7
         mantissa b0-b7     mantissa b8-b15
         mantissa b8-b15    mantissa b16-b23
         mantissa b16-b23   mantissa b24-b31
         mantissa b24-b31      exponent
            exponent

String         &00               char 1
            length (n)           char 2
            char n               char 3
            char n-1              ...
            char n-2              &0D
              ...
            char 1

INPUT# will also recognise &01 prefixing an integer and any byte >&7F
prefixing a real. PRINT# prefixes an integer with &01 if it is an immediate
byte value, eg PRINT#out%,0.

Bugs
====
PROCBBC_WrReal() and FNBBC_Rd() when reading and writing reals use the |
operator, which is only available on BASIC V or equivalent. If not running
on BASIC V, INPUT#/PRINT# are used, so will only work if the BASIC actually
uses Acorn format data files.

History
=======
       1986 v0.10 Originally written as FastIO to speed up unbuffered file
                  access.
12-Feb-1992 v1.00 Rewritten as BBCFile for Acorn format datafile access.
12-Feb-1992 v1.01 Reading and writing reals implemented.