5  The filing system commands

The Disc Filing System is an 8K byte program. BASIC programs are stored on a disc or tape, but the filing system is stored in Read Only Memory (ROM) inside the BBC computer. The filing system controls the reading and writing of information to and from the discs and provides a number of useful facilities for maintaining that information. The following pages describe all the filing system commands. They are words which the filing system program will recognise and act on. They can be typed directly on to the keyboard or embedded within your BASIC program. They are all prefixed with the * character which signals the computer that a filing system command follows. Each command is described under a number of sections with heading as follows:

Command
This is followed by a syntax abbreviation and a few words explaining the derivation of the word.

<drv> = drive
<fsp> = file specification
<dir> = directory
<afsp> = ambiguous file specification

The use of square brackets [ ] indicates that a key should be pressed. For example, [ESC] is the Escape key.

Purpose
A plain English description of what the command does.

Example
This section gives a few one-line examples of the use of the commands. These examples are only intended to be illustrative.

Description
A description of the command using normal computer jargon.

Associated commands
This section lists commands which have similar functions or are normally used in conjunction with this command.

Demonstration program
If appropriate a short program is included to illustrate use of the filing system command in a BASIC program.

Notes
Particular points to watch for or special applications of the command are covered by additional notes if necessary.

*ACCESS  <afsp> (L)

Purpose
To prevent a file from being deleted or overwritten. The command 'locks' or 'unlocks' a file. You cannot delete, overwrite or write to a locked file until you unlock it again. If you write to a file which is locked, you will not be able to save it again with the same name. This is because saving a file with the same name as one already on the disc causes the one on the disc to be deleted and replaced with the new file.

Example
*ACCESS HELLO L
This locks the file HELLO
*ACCESS HELLO
unlocks it again so that it can be deleted or overwritten.

Description
Sets or un-sets file protection on a named file. It prevents a number of other filing system commands from acting on the file.

Notes
Once locked a file will not be affected by the following commands:
*SAVE
*DELETE
*WIPE
*RENAME
*DESTROY

If you attempt to use any of these commands on a locked file the message

File locked

is produced.
If you attempt to use *ACCESS on a write protected disc the message

Disc write protected

is produced.

Warning
Locking a file does NOT prevent it from being removed from a disc with *FORM80 or from being overwritten with *BACKUP.

*BACKUP  (source drv) (destination drv)

Purpose
To read all the information on one disc and write it to another, producing two discs with identical information.

Example
*ENABLE
*BACKUP 0 1
copies all the information on drive 0 to drive 1.

Description
Sector by sector copy program.

Associated commands
*COPY
*ENABLE

Notes
*ENABLE must be typed before the command will work, otherwise the message

Not Enabled

is displayed.
If you give 0 as the source and destination drives, e.g:

*BACKUP 0 0

the program will alternately ask you to insert the source and destination discs into drive 0. This makes it possible to copy discs even if you only have a single drive. A 40 track disc is copied in 5 sections.
All information previously on the destination disc is overwritten so be careful not to confuse the source and destination discs. If the source disc is blank, the destination disc will end up blank as well.

Warning
The contents of memory may be overwritten by this command. If you have a program or some data in memory that you want to keep, save it before you use this command.

*BUILD  <fsp>

Purpose
To create a file directly from the keyboard. After typing this command everything else entered will go into the named file. This is useful for creating EXEC files and the !BOOT described in chapter 3.

Example
*BUILD !BOOT
will cause everything subsequently typed in to be entered into a file called !BOOT.
Line numbers are displayed on the screen to prompt you to enter your text as follows:

*BUILD !BOOT
1 FIRST LINE OF TEXT
2 SECOND LINE
3 [ESC]
Typing [ESC] on a line by itself terminates a *BUILD command.

Description
Builds a file from the keyboard.

Associated commands
*EXEC
*LIST
*TYPE

*CAT  <drv>  Catalogue

Purpose
The command displays the catalogue of a disc on the screen, showing all the files present on the disc. (drv) is the number of the drive you want displayed. If (drv) is omitted the current drive is assumed.

Example
*CAT 0
PROGRAM (12)
Drive: 0                 Option: 2 (RUN)
Directory: 0.$           Library: 0.$

   !BOOT                    HELLO
   SUMS                     TABLE
   TEST                     VECTORS
   ZOMBIE

A. HELLO L                B.SUMS

Note that the heading part of the catalogue shows the drive number, the title of the disc, the currently set auto-start option of the disc (in this case 2 for RUN), and the currently selected library and directory. The files are displayed in alphabetical order reading across the two columns. In the example above there are nine files on the disc. !BOOT to ZOMBIE are in the current directory $. The current directory's files are always listed first. A.HELLO is in the directory A. It is also followed by L, meaning, that it is a 'locked' file. (See *ACCESS for an explanation.) B.SUMS is in directory B and is not locked.

Description
Displays a disc catalogue.

Associated commands
*INFO
*ACCESS
*TITLE
*OPT 4
*DIR
*DRIVE

Notes
Permitted values of <drv> are 0, 1, 2, 3 or nothing (default directory). Other values will cause the message

Bad drive

to be displayed. The top two lines of the catalog include the disc title, disc option, drive number and current directory.

The catalogue and hence the disc will hold up to a maximum of 31 files.

*COMPACT  <drv>

Purpose
Attempting to SAVE a program or file on to a disc may produce the message 'Disc full' if there is no single space available on the disc big enough for the information. It may be that there is enough space, but it is split into several small sections. This command appends all spare space on a disc to the end. When you delete a number of files, the spaces they had occupied will probably be distributed over the disc with current files in between them. *COMPACT moves all the current files to the 'start' of the disc leaving the spare space in one continuous block at the end.

Example
*COMPACT 1
$.HELLO      1700  801F  0003B  002
$.SUMS       1700  801F  00098  003

As 'compacting' proceeds all the current files are displayed in the order in which they occur on the disc.

Description
Moves all available space on a disc into one continuous block following the current files.

Associated commands
*SAVE
SAVE
OPENIN

Notes
This command will only do anything if there is space between the files on the disc. There will only be such space if a file has been deleted from between two others.

Warning
The contents of memory may be overwritten by this command. If you have a program or some data in memory that you want to keep, save it before you use this command.

*COPY  <source drv> <destination drv> <afsp>

Purpose
To copy a named file or files from one disc to another.

Example
*COPY 0 1 HELLO
This copies a file called HELLO in the current directory on drive 0 on to drive 1.

Description
File copy program.

Associated commands
*BACKUP

Notes
The 'wildcard' facilities may be used to specify a group of files to be copied e.g:
*COPY 0 1 #.MY*
copies all files beginning with MY irrespective of which directory they are in. Information already on the destination disc is not affected.

Warning
The contents of memory may be overwritten by this command. If you have a program or some data in memory that you want to keep, save it before you use this command.

*DELETE  <fsp>

Purpose
To remove a single named file from the catalog of a disc. The space occupied by the file becomes available for other information. Succeeding file names in the catalogue are shuffled up, but not the files themselves. Once a file is deleted you cannot get it back again.

Example
*DELETE FRED
removes a file called FRED from the current directory on the current disc.

Description
Single file deletion.

Associated commands
*WIPE
*DESTROY
*COMPACT

Notes
If the disc is write-protected the message

Disc write protected

is produced. If the file is not found in the directory the message

File not found

is displayed. If the file is locked the message

File locked

appears.
Once deleted a file cannot be restored.

*DESTROY  <afsp>

Purpose
To remove specified files from the disc in a single action. This command takes the ambiguous file specification so that groups of files can be deleted. When you use this command a list of files to be deleted is displayed. A single Yes/No question appears at the end of the list offering you the choice to go ahead and delete all the listed files or not. Use this command with care because its effect is not reversible. It will not attempt to remove locked files. (See *ACCESS).

Example
*ENABLE
*DESTROY *.H*
A.HELLO
$.HELLO

Delete (Y/N)?

If you type Y in reply to the question all the named files will be deleted. The message

Deleted

is displayed when the job is done.
Typing anything else cancels the command.

Associated commands
*ENABLE
*WIPE
*DELETE

Notes
Once destroyed files cannot be restored.

*ENABLE must be typed immediately before *DESTROY or it will not work and the message

Not enabled

is displayed.

*DIR (<dir>)  Set the directory

Purpose
To change the current directory to (<dir>). The current directory is always set to '$' when you press [BREAK]. To save files in a different directory in the catalogue you must use this command to change the current directory to the one you want and then save them.

Example
*DIR A
This sets the current directory to A. You now have access to any files in the directory A in the catalog. Any files now saved using *SAVE or SAVE will be in directory A.

Description
Sets the current directory to the argument supplied.

Notes
The directory can be set to any character with the following four exceptions
#*.:
This command does not alter the directories written in the catalogue. It merely states which directory in the catalog you have access to by default.

*DRIVE  <drv>  Set the current drive

Purpose
Changes the current drive to <drv>. Any commands which follow will work on <drv> until another drive is specified.

Example
*DRIVE 1
sets the current drive to 1 and
*CAT
will produce a catalog of drive 1
*CAT 0
will catalogue drive 0 but the current drive is still drive 1 until you change it back to 0 or press [BREAK].

Description
Sets the current drive.

*DUMP  <fsp>

Purpose
Produces a hexadecimal listing of a file on the screen.

Example
*DUMP SUMS

Description
Hexadecimal screen dump.

Associated commands
*LIST
*TYPE

Notes
It is useful to use this command in page mode so that the file is displayed one page at a time on the screen.
[CTRL] N selects page mode, [CTRL] O turns it off.

*ENABLE

Purpose
Some of the filing system commands produce irreversible effects. To prevent them from being used accidentally it is necessary to type *ENABLE before they become operational. These commands are:

*BACKUP
*DESTROY

Example
*BACKUP

will not work, the message

Not enabled

is produced.

*ENABLE
*BACKUP

will work.

Notes

*ENABLE must be typed immediately before the command to be enabled. Any FS or MOS command typed in between nullifies the *ENABLE.

*EXEC  <fsp> Execute

Purpose
This command reads byte by byte all the information in a named file as if it was being typed on the keyboard. This is useful when you find that you are repeatedly typing the same sequence of commands. Instead you can build an EXEC file consisting of all these commands and type *EXEC <fsp> each time you want this sequence of commands. *BUILD <fsp> is an associated command used to create an EXEC file.

Example
*EXEC HELLO
takes the contents of the file HELLO and reads it one character at a time as if it were being typed at the keyboard.

Associated commands
*BUILD

Notes
One useful application of the *EXEC command is in association with the auto-start facilities described in chapter 3 and in the section on *OPT4 in this chapter. If you create a !BOOT file containing the BASIC keyword CHAIN followed by the filename of one of your basic programs, the effect of pressing [SHIFT] [BREAK] will be to automatically load and run the BASIC program.

*HELP  <keyword>

Purpose
Displays useful information on the screen. In the disc system this consists of a list of the filing system commands or the utilities depending on the <keyword> used. The two keywords which produce a response in the disc filing system are UTILS and DFS.

Example
*HELP DFS

ACCESS  <afsp> (L)
BACKUP  <src drv> <dest drv>
COMPACT (<drv>)
COPY    <src drv> <dest drv> <afsp>
DELETE  <fsp>
DESTROY <afsp>
DIR     (<dir>)
DRIVE   (<dir>)
ENABLE
INFO    <afsp>
LIB     (<dir>)
RENAME  <old fsp> <new fsp>
TITLE   <title>
WIPE    <afsp>

*HELP UTILS

BUILD   <fsp>
DISC
DUMP    <fsp>
LIST    <fsp>
TYPE    <fsp>

Notes
*RUN, *SPOOL, *SAVE, *EXEC and *LOAD are not included in these lists because they are Machine Operating System commands which operate outside the disc filing system. *HELP is a Machine Operating System command.

*INFO  <afsp>

Purpose
Displays information about a file or group of files. It includes details not given by *CAT such as the length of the file and it's location. It is displayed in the following order across the screen.

Directory  Filename  Access  Load Addr.  Execution Addr.  Length  Start sector

Example
*INFO A.HELLO
Displays
A.HELLO L   001900 00801F 00003B 003

Description
Displays detailed file information.

Associated commands
*CAT

Notes
If the file is not found on the specified (or assumed) drive and directory the message

File not found

is produced.

The wildcard facilities # and * may be used if you want information about a group of files.

*LIB  :(<drv>). <dir>  Selects the library.

Purpose
Sets the library to the specified drive and directory.

Example
*LIB :1.A
sets the library to drive 1 directory A. After this, typing
*<filename>
will search directory A on drive 1 for the named file and if it is found the file will be loaded and executed just as if you had typed
*RUN :1.A.<filename>

Description
Sets the drive/directory containing the library.

Associated commands
*RUN

Notes
The library can contain files which are utility programs, designed to act on other files e.g. Sorts, Edits and Mergers are all common utility programs. It is then possible to say:
*SORT FRED
where SORT is the name of the file in the library and FRED is the name of another file in the current drive and directory. This makes use of the fact that any text after the <fsp> is stored in memory and is available to your machine code program for interpretation. A pointer to the start address of this text is available to your program via a call to OSARGS with Y=0, A=1 and X=the address of the 4 byte block in page 0 where the text is stored. To read the text stored in this location you must use a call to OSWORD with A=5:

OSWORD call with A=5.
Read I/O processor memory. This call enables any program to read a byte in the I/O processor no matter in which processor the program is executing.
On entry X and Y point to a block of memory as follows

XY    LSB of address to be read
XY+1
XY+2
XY+3  MSB of address to be read
On exit the 8 bit byte will be stored in XY+4.
As this routine reads one byte at a time you may need to use repeated calls to it to recover all of the text following the <fsp>.

*LIST  <fsp>

Purpose
Displays a text file on the screen with line numbers.

Example
*LIST DATA
displays the contents of the file called DATA on the screen, line by line with each line numbered.

Description
ASCII list with line numbers.

Associated commands
*TYPE
*DUMP

Notes
BASIC is tokenised so listing a BASIC program file will display nonsense. (See the User Guide). An ASCII text file of a BASIC program can be obtained using the *SPOOL command.
Files written with the BASIC keyword PRINT# can also be listed with this command.
In page mode the listing will stop after displaying each screen full until you press either [SHIFT] key to make it continue. [CTRL] N selects page mode, [CTRL] O turns it off.

*LOAD  <fsp> <address>

Purpose
Reads a named file from the disc into memory starting at either a specified address or the file's own load address.

Example
*LOAD HELLO
Reads the file HELLO into memory starting at location 1900 (hex), which is the load address of the file when it was saved.
(See example in *INFO)
*LOAD "HELLO" 3200
Reads the file HELLO into memory starting at location 3200 (hex).

Description
Loads a file into memory.

Associated commands
*SAVE
*RUN

Notes
All the above are valid commands. The quotation marks are optional; but either a pair or none should be present. The named file must be in the current directory on the current disc. If the file is not found the message

File not found

is produced.

*OPT 1  (n)

Purpose
This command enables or disabled a message system which displays a file's information (the same as *INFO). Every time a file on the disc is accessed the information is displayed. (n) can be anything from 1 to 99 to enable the feature. (n) = 0 disables it.

Example
*OPT 1 1
or
*OPT 1,1
enables the messages;
*OPT 1 0
or
*OPT 1,0
disables the messages.

Description
Message system to display file information at every access.

Associated commands
*INFO

Notes
A space or a comma between *OPT 1 and its argument (n) is essential.

*OPT 4  (n)

Purpose
Changes the auto-start option of the disc in the currently selected drive. There are four options to choose from: 0, 1, 2 or 3. Each option initiates a different action when you press [SHIFT] and [BREAK] on the computer. The computer will either ignore or automatically LOAD, RUN or EXEC a file called !BOOT which must be in the directory $ on drive 0.

Example
*OPT 4 0 does nothing
*OPT 4 1 will *LOAD the file !BOOT
*OPT 4 2 will *RUN the file !BOOT
*OPT 4 3 will *EXEC the file !BOOT

Description
Changes the start-up option of a disc.

Notes
It is essential to include a space between the command and (n). *OPT40 would produce the message

Bad option

If the disc is write-protected the error message

Disc write-protected

is produced in response to the *OPT 4 command.
If the option 0 is set the !BOOT file need not be there. With any other option the message

File not found

is produced if the !BOOT file is not found in the directory $ on drive 0.

Warning
Do not confuse *OPT 4 with the BASIC keyword OPT or *OPT 1. They are completely different. Refer also to Chapter 11 where it describes how to swap the effects of [BREAK] and [SHIFT][BREAK].

*RENAME  <old fsp> <new fsp>

Purpose
Changes the file name and moves it to another directory if required.

Example
*RENAME SUMS B.MATHS
Assuming that the current directory is $, the file $.SUMS becomes B.MATHS.

Description
Renames a file.

Notes
*RENAME :0.$.SUMS :1.B.MATHS
This is not allowed. The file cannot be moved from drive 0 to drive 1 using *RENAME. Only the directory and filename can be changed.
If the file does not exist the message

File not found

is displayed. If the first file is locked

File locked

is displayed. If the disc is write-protected

Disc write-protected

is displayed. If the <new fsp> has already been used the message

File exists

is displayed.

*RUN  <fsp> (parameters to utility)

Purpose
This command is used to run machine code programs. It loads a file into memory and then jumps to the execution address of that file.

Example
*RUN PROG
will cause a machine code program in the file called PROG to be loaded and executed starting at the execution address of the file.

Description
Runs a machine code program.

Associated commands
*SAVE
*LIB (for an explanation of 'parameters to utility')

Notes
This command will not run a BASIC program.
Typing *<fsp> is accepted as being the same as *RUN <fsp>.
Typing *<filename> results in the file being loaded and executed if it is found in the currently selected drive/directory or the library.

*SAVE  <filename> <start address> <finish address> (<execute address>) (<reload address>)

Purpose
It is important not to confuse this with the BASIC keyword SAVE, they are quite different. This command takes a copy of a specified section of the computer's memory and writes it on to the disc in the current drive/directory. It is put into a file of the given name. You will mostly use this command to record your machine code programs.

Example
*SAVE "PROG" SSSS FFFF EEEE RRRR
*SAVE "PROG" SSSS+LLLL EEEE

where
SSSS = Start address of memory to be saved
FFFF = Finish address
EEEE = Execution address (see below)
RRRR = Reload address
LLLL = length of information

Notes
RRRR and EEEE may be omitted in which case the reload address and the execution address are assumed to be the same as the start address.
If the disc is write protected the message

Disc write-protected

is produced. If there are already 31 files on the disc the message

Directory full

is produced. If the specified filename already exists and is locked the message

File locked

is produced. If the file already exists but is unlocked it is deleted. Then starting in sector 2 track 0 a gap large enough to hold the new information is searched for. If none is found the message

Disc fill

is produced.
If enough space is available, the information is written on to the disc and the filename is entered on to the catalogue in the current directory.

*SPOOL  <fsp>

Purpose
Prepares a file of the specified name on the disc to receive all the information subsequently displayed on the screen. This is a very useful command particularly for producing a text file of one of your BASIC programs. (See notes below)

Example
You can obtain a text file of one of your BASIC programs as follows:
LOAD "MYPROG"
Loads a program from disc into memory.
*SPOOL TEXT
Opens a file called TEXT on the disc ready to receive information from the screen.
LIST
Causes the BASIC program to be displayed on the screen and also written onto the file called TEXT.
*SPOOL
Turn off the 'spooling' and closes the file called TEXT.

Description
Spools subsequent output to the screen to a named file opened for the purpose. Closes the file when spooling is terminated.

Associated commands
*BUILD
*EXEC
*LIST
*TYPE

Notes
BASIC on the BBC microcomputer is 'tokenised'. This means that the lines which you type in your program are abbreviated inside the computer's memory and on the disc. A program file will contain these abbreviated 'tokens' rather than your original program text. Displaying the file using *LIST will therefore produce strange results. The example above shows you how to create a file containing your original program text. If you display that file using *LIST your program will appear just as you typed it in.

*TITLE  <disc name>

Purpose
Changes the title of the disc in the current drive to the first twelve characters after the command. It fills in with 'nulls' if there are less than twelve characters. Any characters are allowed.

Example
*TITLE "MY DISC"
This sets the title to MY DISC with five 'nulls' added on the end.
*TITLE "A DIFFERENT TITLE"
This changes the title to A DIFFERENT. Anything after the first 12 characters is ignored. The quotation marks are only required if the title includes spaces.

Notes
If the disc is write protected the message

Disc write-protected

appears when you try to use this command.

*TYPE  <fsp>

Purpose
Displays a text file on the screen without line numbers.

Example
*TYPE HELLO

Description
Screen list of a named file.

Associated commands
*LIST
*DUMP

Notes
BASIC programs are not stored on disc as text files when you save them so this command will display nonsense if you use it on a BASIC program file.
It is useful to use this command in page mode so that the file is displayed one page at a time on the screen.
[CTRL] N selects page mode, [CTRL] O turns it off.

*WIPE  <afsp>

Purpose
Removes specified files from the catalogue and rearranges the catalogue. It asks for confirmation that each file conforming to the specification is to be deleted.

Example
*WIPE *.SU*
is a request to delete all files on the current drive beginning with the letters SU. As each file is found the filename is displayed like this:
A.SUM
At this point, only type "Y" if you want to delete the file. Typing anything else leaves the file intact.

Description
Delete with <afsp> and confirmation per file.

Associated commands
*DESTROY
*DELETE

Notes
Once deleted using *WIPE, a file cannot be restored. Locked files are not removed. (See *ACCESS).

6  The filing system utilities

As explained in chapter 5, the filing system commands are, in fact, programs stored in ROM (read only memory) inside the BBC microcomputer.
The utilities are similar programs but they are stored on the utilities disc ("Welcome" disc). They are used in the same way as the commands by typing
* (Utility name)
The utilities disc must be in the disc drive at the time. The utility must be in the current directory on the current drive or in the library (see command *LIB).
There is a 'formatting' utility supplied for 40 track discs, and a similar utility for 80 track discs. On the utilities disc, this is normally in drive 0, directory $, which are the default values on start-up for both the Library and the current drive/directory. (See command *DRIVE and *DIR). the second utility is *VERIFY.

The following pages describe the utilities. You can add utilities of your own by saving machine code programs into the library.

*FORM80  (<drv>)  Format an 80 track disc.

Purpose
This command prepares new discs for use with the filing system on the BBC microcomputer. It marks areas of the disc where information will be stored and sets up a catalog. The catalogue is empty at first but when you store programs and data on the disc the catalog records their position on the disc. They can then be retrieved quickly by reference to the catalog. While formatting the information put onto the disc is verified automatically.

Example
To format a new disc insert the utilities disc into the disc drive and type
*FORM80
The computer asks
Do you really want to format drive 0?
Remove the utilities disc. Insert the disc to be formatted and then answer
Y
The formatting starts immediately and the message
Formatting drive (n)
is displayed. As each track is formatted and verified the track number is displayed as follows:
00 01 02 03 04 05 06 07 08 09
0A 0B 0C 0D 0E 0F 10 11 12 13
14 15 16 17 18 19 1A 1B 1C 1D
1E 1F 20 21 22 23 24 25 26 27
28 29 2A 2B 2C 2D 2E 2F 30 31
32 33 34 35 36 37 38 39 3A 3B
3C 3D 3E 3F 40 41 42 43 44 45
46 47 48 49 4A 4B 4C 4D 4E 4F
disc formatted
Above is the response if the formatting was successful. If not, the formatting will stop and either the message

Verify error

or

Format error

is displayed.
After successful formatting the message
Repeat format (Y/N)
is displayed. You can format another disc straight away.

Description
Initialises discs with track and sector format. Clears the catalog and verifies the sectioning.

Notes
If you find that the verification or formatting fails persistently it could be that either the discs you have are poor quality or that the disc drive needs servicing.
The drive number may be omitted from the command. The current drive will be assumed. If you have a dual drive system you can format a disc in the second drive while the utilities disc remains in the first drive.

*FORM40  (<drv>)  Format a 40 track disc.

This command is the same as *FORM80 except that the disc is formatted with only 40 sectors instead of 80.

*VERIFY  (<drv>)

Purpose
Checks each sector of a disc for legibility. It is done automatically when you use the *FORM40 and *FORM80 commands.

Example
*VERIFY 1
verifies drive 1.

Description
Sector verification program.

Associated commands
*FORM80
*FORM40