BeebItFS : Version 0.33 (24 May 2005)
=====================================                                   
Filing system written by James Lampard <james_lampard@talk21.com>


QUICK UPGRADE GUIDE
-------------------
(for existing users only, new users read from INTRODUCTION below)

From Version 0.29B:
Don't drag the new !BeebItFS over the old one, as the internal directory structure has slightly changed. Instead rename the old !BeebItFS (say to o!BeebItFS), then copy the new version to the same directory.

You must change the 'ROMs path' icon in the BeebIt options window to
"<BeebIt$Dir>.ROMs.,BeebItExtraROMs:"

From later versions:
The directory structure remains unchanged, so you can just drag the new !BeebItFS over the old one.

QUICK CHANGES GUIDE
-------------------

Added dummy *SHADOW command like Virtual DFS (to make !AquaAttac work)
Changed file handle range from 160-170(&A0-&AA) to 176-191 (&B0-&BF) as A0-AF are used by 65Link's LFS 
OSFIND, trying to open a file that doesn't exist wasn't returning A=0 infact it was generating a null error due to a stack mismatch.

EOF check now works.
Removed Programs directory, BeebItFS now uses !BeebItFS.^ as its default directory
Added obey files to allow switching 'BBC' type files between BFS and 6502Em
Removed debug code from *SRSAVE/*SRREAD (so will now work in modes other than 7)
Now issues correct FSCV call when FS changes (A=6)
0.32
Bug causing failure on Iyonix fixed.
0.33
Use of NULL::$. in paths that was causing failure on RO SELECT fixed.
Message "BFS must be in SRAM" now appears fully again.


INTRODUCTION
------------

BeebItFS is an 8-bit BBC Micro filing system, written so BeebIt can access
files on RISC OS filing systems. It also allows the use of some 6502Em style
'BBC Applications'.

Advantages :

* PAGE is at E00, instead of 1900 with DFS (which should make it easier to
  run programs taken from tape).
  
* Filing operations are much faster than DFS.

* Large numbers of 'BBC Applications' have been converted for 6502Em.

Disadvantages :

* Only one website I know of carries these archives http://www.stairwaytohell.com/bbc/riscos.html


INSTALLATION
------------

(1) Copy !BeebItFS to a suitable place on your hard-disc, which would usually
be the same directory as !BeebIt is in.

(2) Load BeebIt, choose OPTIONS... from the Iconbar menu.
In the dialogue box change ROMs path from '<BeebItDir$>.Roms' to '<BeebIt$Dir>.ROMs.,BeebItExtraROMs:'
Select SAVE then SET which should close the box.
(NOTE you will still be able to load & use all the roms in the !BeebIt.ROMS
directory)

(3) Now choose CONFIGURE >> ROMs from the the Iconbar menu.
Find an empty rom image icon and type 'BFS7' into it, then select it's
Writable tickbox.
I suggest you put BFS7 into a lower numbered slot than your DFS rom image.
If you want to be able to use the sideways ram commands built into BFS then
you should set some empty rom image slots to be writable (4 will provide the
standard 64K sideways ram as on the B+128 & the Master)
Again Select SAVE then SET.

(4) Finally quit BeebIt.

BeebItFS should now be successfully installed, to test it open !BeebItFS by
double-clicking on it, Then run !BFSDemo.
(If you have !6502Em you should run BBC>BFS first)
If you've successfully installed BFS then BeebIt will load, enter BBC
emulation and then draw some owls on a mode 7 Screen.


STARTING BEEBITFS
-----------------

If you start BeebIt normally, without using a 'bbc application' then
BFS will not be selected as the current fs.

Any of the following commands will select BFS
*BFS
*DISK (included for compatibility so any programs containing *DISC or *ADFS
*DISC won't suddenly change over from BFS)
*ADFS
*FADFS

if you still need to use DFS then make sure the DFS rom is in a higher
numbered rom slot than BFS.

To start a bbc application just double click on it and a copy of BeebIt will
load automatically


BASE/CURRENT DIRECTORY & FILENAME TRANSLATION EXPLAINED
-------------------------------------------------------

The base directory is the initial directory on starting BFS, which will
either be !BeebItFS.^ or whichever BBC application you are using.
The current directory is where you are relative to the base directory.
So if you load the following application...

!AdvGame
   !Help
   !Run
   !Sprites
   RunObj
   Cheat
   POSITIONS
     1
     2
     3
     4 
and then do *DIR POSITIONS

*CAT will produce...
ADFS::HardDisc4.$.Games.!AdvGame. <= Base directory
POSITIONS.                        <= Current directory
1       WR/WR 2      WR/WR
3       WR/WR 4      WR/WR

You can then refer to the file "CHEAT" as either
CHAIN ":0.CHEAT"
CHAIN "$.CHEAT"
CHAIN "&.CHEAT"
CHAIN ":2.CHEAT"

So any bbc 'root' reference will override the current directory.
You could of course use the normal relative filename of "^.CHEAT"
You can also use the library symbol "%" as the root in filenames for more
information read the section 'THE LIBRARY' below.

In the current version it isn't possible to change the base directory once
BeebIt has started. 


BBC SCRIPTS
-----------

A BBC Application is similar to a RISC OS app except that the !RUN file
is of type BBC and has a special format.

The first line must be just
BBC Script

The last line is the command that will be entered into BeebIt when the
script is run.
The command line must contain a space or start with CHAIN or *

For example:

BBC Script
CHAIN "CLOGLOAD"

or:
BBC Script
PAGE =&E00 :*SNAPPER

or:
BBC Script
OSCLI "DIR GAMES" :CHAIN "INDEX"

The additional commands that 6502Em understands are currently ignored.

Full documentation of the 6502Em implementation of BBC Scripts is
available from the Internet at http://www.nvg.org/data/bbc/doc/6502Em-scripts.txt


USING WITH 6502EM
-----------------
To make it easier to use BeebItFS alongside 6502Em, two obey files have been supplied
BBC>6502Em and BBC>BFS. These allow you to change which program will recieve double-clicked BBC typed files (and therefore BBC Applications too)
Note these won't work once 6502Em is loaded.


BEEBITFS COMMANDS LISTED
------------------------

BeebItFS provides several additional star commands. 
Note some commands are documented under other sections.

*DIR <afsp>
changes the current directory.

*CDIR <fsp>
creates a new directory.

*DELETE <fsp>
deletes the named file.

*REMOVE <fsp>
similar to *DELETE except no error is generated if the file doesn't exist.

*CAT <afsp>
lists all the files in a directory.

*EX <afsp>
similar to *CAT except more information is listed (ie load/exec addresses and
file length).

*CLOSE
close all the files open on BFS.

*DRIVE <ignored>
doesn't do anything, provided for DFS based programs.

*SHADOW <ignored>
also doesn't do anything, supplied for Model B mode and to improve compatibility with 6502Ems' VDFS.

*PRINT <afsp>
outputs a file to the vdu drivers 'raw', if the file contains control 
characters (0-31) this will have interesting effects.

*TYPE <afsp>
outputs a file in GSTrans format.

*DESKTOP
equivalant to pressing F12.

*QUIT
returns to the desktop, and kills BeebIt.


SIDEWAYS RAM
------------

BeebItFS contains it's own implementation of the B+/Master128 SRAM
utilities. The advantages of these is that 
1. They're very fast and
2. Rather than just loading ROMs from the current directory a search path 
   is used, this makes it easier to share roms between several emulators.

The full SRAM API is quite complex, I can only give an introduction here.
For more information try http://www.nvg.ntnu.no/bbc/doc/BPlus128KAdditionalUserInfo.zip

Firstly,
*ROMS
lists the contents of all the rom slots.
If you have some slots set to be writable you'll note some of them are 
followed by (W) to (Z), these are abstract rom ids which you should use in
preference to the rom no.

The 4 main commands are,
*SRSAVE <fsp> <addr>+<len> <id> [Q]
*SRLOAD <afsp> <addr> <id> [Q][I]
*SRREAD <main>+<len> <addr> <id> [Q]
*SRWRITE <main>+<len> <addr> <id> [Q][I]

SRLOAD & SRSAVE are used for loading/saving rom images.
SRREAD & SRWRITE are used for copying blocks of memory to/from SRAM
<addr> is a sideways rom address, usually 8000 for the start of a rom.
<id> is a rom id either 0-F or W-Z
[I] tells the OS that a rom has been loaded, so it can be used straight away.

I've included a pd rom image called INFORM so you can try out the new
commands straight away.

try
*SRLOAD INFORM 8000 WI

or *LOAD INFORM 3000
*SRWRITE 3000+4000 8000 WI

after loading type
*HELP HELP
to check that it's installed correctly

The search path used for (after checking the BBC's current directory) is the same as the one entered into BeebIts 'ROMs path' icon. Ie by default it is <BeebIt$Dir>.ROMs.,BeebItExtraROMs:
**NOTE the 'pseudo' addressing system is not reliable in this version and
should not be used.


THE LIBRARY
-----------
The BBC micro had a facility whereby all unrecognised star commands can be
searched for in a specified 'library' directory. This wasn't much use on DFS
but was done often on ANFS/ADFS.
BeebItFS emulates this by providing a directory named 'Library' in which
you can put 6502 utilities.

The BeebItFS library can be referred to in filenames as "%", as on ANFS.
For example:
*CDIR %.NEWDIR
LOAD "%.BASPRG"

*LCAT and *LEX catalogue the library
*LIB currently does nothing, in a future version it may also be possible to
set a library that will be used in addition to the BeebItFS one

I've included a selection of PD command line utilities in the
library of varying usefulness.

*SetAddr <fsp> <load addr> <exec addr>
This changes the load/exec address of the specified file
Written by James Lampard

*PrList <fsp>
Lists a BASIC file from a file without loading into memory
Written by J.G.Harston

*bPSAVE <fsp>,<line no>,[<line no>]
Saves a section of the currently loaded BASIC program
Written by ?

*VList
List all the currently defined BASIC variables (but not their values)
Written by J.G.Harston

*CLOAD <afsp> [<char>|X]
Loads font characters starting from character 'char' (specified in hex)
If the 'X' parameter is given, or the file has a load address of &FFFFF7xx
(ie is file-typed to &FF7), then the file is loaded as a
Master 128/Archimedes-type BBC font file.
Written by J.G.Harston

*CSAVE <fsp> <start char> <end char> [X]
Saves the current font between start char and end char (specified in hex)
If the X param is specified then Master128 format is used.
Written by J.G.Harston

*FileInfo [-]<afsp>
Reads the files info with OSFile 5 and displays it all, including any parts
unused by the current FS.
Written by J.G.Harston

*KILL
Totally resets the emulated BBC.
Written by Lars 0sterballe

*LPS [-<lines>] <fsp>
Print's a View file to the screen with Italic/Bold
Written by J.G.Harston

*notape
Any *TAPE commands in a program are ignored.
From EUG magazine

*SCRLOAD <afsp>
Loads a screen file (in the old AU format I think)
Written by J.G.Harston

*SCRSAVE <fsp>
Save the screen to a file.
Written by J.G.Harston

*SRWIPE [Y]
Allows you to selectively clear SRAM banks.
Written by ?

The BeebItFS library "%" is taken from the value of <BeebItlibwrite$Path> on
loading. If you want to add extra directories to be searched you should add
them to <BeebItlib$Path>

ACKNOWLEDGEMENTS
----------------

Thanks to Michael Foot for adding the opcode 7 interface to BeebIt.