3 Filing system

commands

HADFS provides a variety of commands used to access HADFS disks. The following pages describe these commands. They are all * commands, and so must be at the end of a program line, or accessed using OSCLI from BASIC. Some of the commands are provided by HADFS as filing system commands, some of them are provided by HADFS as general utility commands, and some are provided by the MOS, which communicates with the HADFS filing system to implement them. There are also some commands that are in DFS on BBC Bs and in the MOS in Masters. There are also transient commands which are loaded from disk to run them. The commands are labelled as Filing, Utility, MOS, Transient or DFS/MOS. All HADFS commands can be prefixed with H to prevent clashes. Commands can be prefixed with \ to pass it to the filing system only, as with SJ Fileservers. HADFS commands can be terminated by any non-letter, so *DIR $ is the same as *DIR$, but *DIR FRED cannot be shorted to *DIRFRED, this would look for a command file DIRFRED.

Command Syntax

The syntax abbeviations used in these descriptions, and in *HELP messages, are as follows:

<afsp> ambiguous file. A filename or directory name that can include the wildcard characters # and *. <fsp> file specifier. A filename or directory name that does not include the wildcard characters # and *. <src> source filename/dirname/drive. <dest> destination filename/dirname/drive. <dir> a directory. <user> a user number. <drv> a drive number.

If a syntax abbreviation appears in brackets, this indicates that it is optional.

Filenames and pathnames

Filenames can consist of one to ten alphanumeric characters, containing no spaces, and none of the following special characters which are reserved and cannot be used in filenames: ", #, $, &, ^, :, *, . and @.

Pathnames consist of one or more filenames separated by ., optionally including the following absolute directory reference characters:

$ root directory, and disk prefix. Identical to :. : root directory, and disk prefix. Identical to $. % library directory (LIB). A filename can also contain %. & user root directory (URD). @ currently selected directory (CSD). ^ parent directory.

So the pathname %.FREDDY refers to the file FREDDY in the library directory, and :1.HELLO or $1.HELLO refers to the file HELLO in the root directory of drive 1. The $ and : can be used interchangably. The % character on its own refers to the Library, otherwise it can be used as any other character, for instance %PrintQ.

The following wildcard characters are used:

# matches any one character * maches any characters

*/<afsp> (<parameters>) MOS

*/ is an abbreviation for *RUN except that *RUN only checks the current directory and */ checks the current directory and the library directory as with unrecognised *commands. It is normally used to prefix a command to prevent a ROM version being used and force a disk-based version to be used.

*\<command> (<parameters>) MOS

If a command is prefixed with \ it is checked against HADFS's filing system commands and is not passed on to the filing system. They will not be searched for on the disk or passed to other ROMs if they are not matched. This is the same as with SJ Fileservers.

*|<comment> MOS

A command starting with | is a comment and is entirely ignored.

*ACCESS <afsp> <access> Filing

This command changes the access string on a file, eg

*ACCESS MATHS WR/R

Each letter in the access string refers to a different type of access allowed to the file:

L - Locked => The file cannot be deleted or overwritten or renamed. W - Write => The file can be written to using random access. R - Read => The file can be read with LOAD or random access and can be executed with *, */ or *RUN. P - Private => The file cannot be seen by non-owners. E - Execute => The file can be executed with *, */ or *RUN. If there is no Read option, then the file can only be executed, and is a run-only file.

The / character separates the owner's access (on the left) from the public access (on the right). You are the owner of a file if you own the directory that it is in. When a disk is *INSTALLed or *FORMatted, you own the whole disk. Ownership is changed using the *ACCOUNT command, and allows you to segregate files and simulate an network server environment using local disk drives. Saving a file on top of an existing file does not change the file's access setting.

*ACCOUNT <afsp> <acc> (<aux>) Filing

This sets the hexadecimal main and auxilary account numbers of a directory. The auxilary account number is specified in brackets, eg *ACCOUNT $ 0 (0). Account numbers are 12-bit numbers, so can be 0 to FFF. When a disk is *MOUNTed, your account number is reset to 0, so to own any objects in directories that have had the account number changed, you must log into them using *I AM.

*BACKUP <src> <dest> Program

*BACKUP makes an identical copy of a disk. It is implemented as a transient program and is described in Chapter 5.

*BUILD <fsp> DFS/MOS

*BUILD opens a new file with the specified name and all subsequent lines of keyboard input are directed to the file. Input is terminated by pressing Escape.

*BYE Filing

This closes any open files and dismounts all the disks. You should always use this (or *MOUNT) before changing a disk.

*CAT (<dir>) MOS

The *CAT command provides a list (catalogue) of the files in the selected directory. The files are currently not listed in alphabetical order, but it is intended that they will be in the future. The top three lines contain information about the directory being catalogued. With the example below, the first line shows that the directory being catalogued is called PROGRAMS and the disk it is on is called MyDiskOne. The CSD is the root ($) and the library directory is called Library.

PROGRAMS (33) Owner 000
MyDiskOne Option 0 (Off)
Dir. $ Lib. Library

MATHS WR/R GAMES DL/
STARTUP LR/R START2 R/E

*CDIR <dir> Filing

This command creates a subdirectory. If the specified subdirectory already exists, then the command returns with no errors. If a file already exists with the same name then a File exists error will be generated. The created directory has its access locked.

*CLOSE MOS/Util

This closes all open files and ensures any data in buffers is written to disk. It is identical to using CLOSE#0 from BASIC.

*COMPACT (<drv>) Program

This compacts a disk creating larger areas of free space. It is implemented as a transient program and is described in Chapter 5.

*COPY <src> <dest> Filing/Transient

On the Master series, this command is implemented in the ROM using the MOS *MOVE command. On the BBC it is run from disk as a library command. It copies a specified file, creating another copy, leaving the original intact, eg:

*COPY Prog1 $.Fred.OldProg1

The *MOVE-based version uses only the private MOS memory, including any unused shadow screen memory, so the user program area is untouched. The disk-based version uses the HADFS buffers and the CFS buffers at &900 to &AFF in the I/O processor, so again the user program area is untouched. For copying multiple files and to other filing systems, use the transient program TreeCopy instead. See Chapter 5.

*DELETE <fsp> Filing

This simply deletes an entry from the directory, eg:

*DELETE FRED

If the file is locked, the error File locked is generated. If you try to delete a directory that has entries in it, the error Dir. not empty is generated. You can only delete files in directories that you own.

*DIR (<dir>) Filing

This command allows you to move between directories, eg:

*DIR PROGRAMS

The example selects PROGRAMS to be the Currently Selected Directory (CSD). Doing *DIR with no name will reset the CSD to the User Root Directory (URD), this usually being $, or the directory selected with *I AM. The CSD can be refered to in pathnames with @, eg:

*RUN @.FRED

This would run the file FRED in the CSD.

*DISABLE <option> Transient

The *DISABLE command allows various features to be disabled.

*DISABLE HADFS disables HADFS in the same was as *FX90,6,1.

*DISABLE DFS disables the DFS filing system, while leaving the OSWORD &7F call available. This will usually drop PAGE by &200.

*DISABLE is reversed with *ENABLE.

After using *DISABLE Ctrl-Break has to be pressed.

*DISKS Transient

This command lists the names of all the disks present in all the available drives, and the amount of free space on them. A typical display would be:

>*Disks
Drv Title Free Used
:0 Documentation 1K 399K
:1 HADFSSystem 22K 378K
:4 IDEDRIVE4 32686K 82K
:I InternalFiles 0K 28K

*DUMP <afsp> DFS/MOS

This command displays a hexadecimal and ASCII dump of the named file, with eight bytes per line, preceeded by the displacement from the start of the file. Non-printable characters are displayed as a . character.

*ENABLE (<option>) Filing

This command is used without a parameter to enable the dangerous commands *FORM and *INSTALL with the $ parameter. With a parameter it is a transient program used to reverse the functions disabled with *DISABLE.

It should be given before the command is used, eg:

*ENABLE
*FORM160 0

If a command is not enabled, then you are asked Go? (Y/N) and a keypress is waited for. Pressing anything other than Y or y will result in the command being abandoned, and a Not Enabled error being generated.

*ENABLE HADFS enables HADFS in the same was as *FX90,6.

*ENABLE DFS enables the DFS filing system after being disabled with *DISABLE DFS.

After using *ENABLE with a parameter, Ctrl-Break has to be pressed.

*EX (<dir>) Filing/MOS

This command is similar to doing a *INFO on all the files in the directory. If no directory is given, the CSD is listed. An example would be: >*EX
$ (69) Owner 000
MyDiskOne Option 0 (Off) Dir. $ Lib. $

!ReadMe 67542742 26533684 002DAD WR/R 08/10/1989 00004A
Manual1 65524372 38573523 001029 WR/R 08/10/1989 000078
COMPACT FFFF1900 FFFF8023 00055E LWR/R 17/10/1989 0000A2
COPYFILES FFFF1900 FFFF8023 000652 LWR/ 18/10/1989 0000A8

*EXEC (<afsp>) MOS

This command reads the specified file in byte by byte as if it were being typed in at the keyboard. This is usually used with *OPT4,3 to *EXEC a !Boot file. If a file's execution address is &FFFFFFFF or the load address if &FFFFFFxx, then attempting to do *RUN <afsp> will do *EXEC <afsp> instead. *EXEC without a filename closes any open *EXEC file.

*FILES Util

*Files lists the information on all the currently open files. The display shows each channel's object information, sector start, current pointer, extent, directory sector, disk ID number and allocated space. The object information will be either *CLOSED* or start IN, OT or UP for OPENIN, OPENOUT or OPENUP. The next six bits are the EOF flag, Directory, Write attribute, Read attribute, Output buffer modified, Input buffer present. An example display would be:

>*Files
25 OT..WROI 00:0004E5 PTR=0000002A EXT=00000037 Dir:00004A ID:D951 Alloc=000040
26 IN.D.... 01:000047 PTR=00000000 EXT=00000300 Dir:000047 ID:F01D Alloc=000003
27 UPE.WROI 00:000285 PTR=0000023B EXT=0000023B Dir:0000D3 ID:D951 Alloc=000003
28 *CLOSED* 00:000000 PTR=00000000 EXT=00000000 Dir:000000 ID:0000 Alloc=000000
29 *CLOSED* 00:000000 PTR=00000000 EXT=00000000 Dir:000000 ID:0000 Alloc=000000

*FORMnn <drv> Util

This command, which needs to be *ENABLEd, will format a disk in drive 0 or 1. The number of tracks is specified by nn, this can be from 1 to 255, though sensible values would be 40, 80 and 160. The formatted disk is a blank data disk with the title (Untitled). The command can be used without HADFS selected, and if so, the drive parameter can be 0 to 3 which will create a blank DFS disk. As an example,

*FORM160 0

will format a double-sided 80 track disk. Many disks and disk drives can actually access about 82 tracks, so you could use

*FORM164 0

to format a double-sided 82 track disk.

*FREE (<drv>) Filing

This displays the free space available on the disk, or the disk the CSD is on if no drive is given. An example would be:

>*FREE
000193 Sectors 103,168 bytes free
0004AD Sectors 306,432 bytes used

*HADFS Util

This command selects the HADFS. Once selected, HADFS becomes the current filing system and all filing operations are directed to it. HADFS can also be used as a temporary filing system using the prefix -HADFS-.

*HELP <keyword> MOS

Displays list of helpful information. HADFS responds to *HELP HADFS to list the HADFS Filing commands and *HELP UTILS to list the HADFS utility commands.

*I AM <dir> Filing

This command is used to log on to a specified directory on a disk. An example would be:

*I AM PROGRAMS

which would set the User Root Directory and the CSD to $.PROGRAMS on the default user drive, normally drive 0. A directory $.Library is looked for on the default library drive and the logged on drive if different, and if found, the library directory is set to it. The autostart command is then executed (see *OPT 4). A drive other than the default user drive may be logged on by prefixing with a drive identifier, and subdirectories can be logged on to, eg:

*I AM :1.WORK.SHEETS

would log into the directory WORK.SHEETS on drive 1, and look for a library directory on drive 1 and then the default library drive. If the specified directory cannot be found, then $ on the default user drive is logged into instead.

*INFO <asfp> Filing

This displays the file information for a particular file, eg:

*INFO MATHS

produces a string of information about the file MATHS. The format is:

<name> <load address> <execution address> <size> <access> <date - dd/mm/yyyy> <system internal name>

For example, the above command may produce the following output:

MATHS FFFF1900 FFFF8023 000734 WR/R 22/05/1988 000092

If the object length is shown as six digits, it is in a Small Directory, if it is shown as eight digits, it is in a Big Directory.

When you do a *INFO on the root directory, the display includes information on that drive, eg:

$ 00064000 00015556 000300 DL/ 22/05/1988 000047

This gives disk size in the load address, the flags and ID in the execution address, and the date the disk was created.

*INSTALL (<drv>) ($) (<name>) (D)(S)(L) (<size>) Filing

This very important command creates an HADFS disk, installing on it the required DFS files to partition it and setting up the root directory ($). *INSTALL can be used on disks that already have HADFS installed on them to install the current version of the software, or to change the disk name.

If the $ parameter is given, then a new root directory is created, effectively deleting everything on the disk. You must give the drive number and a name when using the $ parameter. Also, the command must first be *ENABLEd.

A floppy disk must already be formatted as an HADFS or DFS disk, either 40 or 80 track, single or double sided. You can do this with the *FORM command, which will create a blank HADFS Data disk. HADFS works best with 80 track double sided disks, but you can specify other size disks with the <size> parameter in either number of tracks or number of sectors.

Using the D prefix will create a data-only disk by leaving off the DFS installation files. The <size> parameter can be one of the following:

<dec> number of tracks, eg 160 for 80 track double sided. <dec>K size in K, eg 400K. <dec>M size in M, eg 64M. &<hex> the total number of sectors, eg &640

All of the above examples, except 64M, give a size parameter for a standard 80 track double-sided HADFS disk. If the size is followed by *2, then the disk is a split disk, that is, a disk with less than 80 tracks on one side. An example of this is a 40 track double-sided disk. This would be *INSTALLed with 40*2 as the size parameter. If no size parameter is given, then a size is looked for on the disk. If there is no size already on the disk, ie it has never been *INSTALLed before, a Bad number error will be generated.

The <size> can be prefixed by D, S or L:

D create a Data disk with no HADFSROM file S create a System disk with an HADFSROM file (the default) L create a Large directory structure even if smaller than 16M.

These prefixes can only be used when creating a blank disk. As an example,

*INSTALL 0 $ DataDisk D40

would install a 40 track disk as a 98.5K HADFS data disk. If you use the command

*INSTALL ?

a brief reminder of the size parameters is displayed. The <name> can be one to sixteen characters long, but should be at least two characters and should start with a letter to distinguish it from a drive number.

*LIB (<dir>) Filing

This sets the library directory to the directory given. The library directory is where machine code command files are searched for if they cannot be found in the current directory with * and */. The search path followed to find a file to run is shown below. If a file is found, it is loaded and executed, else the search path is followed onwards towards the end. So *KEY is matched as the MOS command to reprogram a function key, */KEY bypasses the MOS and is sent to HADFS to search for a general command file, and *RUN KEY would look for a machine code file in the current directory only. After a *MOUNT, the LIB is set to $.Library on the mounted disk if it exists, or to $ if it doesn't.

Search path used to run files

*\name *command */name *RUN name | | | | | MOS looks in MOS ROM | | | | | | | V | | | Look at sideways ROM | | | commands | | | | | | V V | | Look at filing system | | commands | | | | | | | \-----------\ | | | | | | | V V V | HADFS looks in CSD HADFS looks in CSD | | | | V | | Yes Does filename include | | /------ $, %, &, @ or : | | | | | | | | No | V V V V | | HADFS looks in LIB | \------\| | | | | | V V V | Master computers check | | LIBFS | | | | \-----------\ | | V V V Bad command error File not found error

*LIST <afsp> DFS/MOS

This command displays the contents of the named file on the screen, with each line of text preceeded with a line number, starting at line 1.

*LOAD <afsp> (<addr>) MOS

This loads the named file into the computer's memory, starting either at the specified address, or at the file's own load address if no loading address is specified. If the high byte of the load address is &FF, ie addr=&FFxxxxxx, then the file is loaded into I/O memory. If the high byte is not &FF, then the file is loaded into language memory.

A load address of FFFDxxxx will load into shadow screen memory, regardless of which memory is being used to display the screen.

A load address of FFFExxxx will load into whichever memory is currently being used to display the screen

A load address of FFFFxxxx, or if there is no shadow screen, will load into normal I/O memory.

*MAP (<drv>) Filing

This displays the free space map for the selected drive, or the drive of the CSD, if none is given.

*MOUNT (<drv>) Filing

This abandons any open files and dismounts all the disks preparatary to inserting a new disk. You should always use this command, or *BYE, before changing a disk, as directory information is kept in memory to speed up disk accesses. If no drive parameter is given then the default drive, usually drive 0, is mounted. After a *MOUNT, the CSD and URD are set to $ on the mounted drive, and LIB is set to $.Library if it exists on the mounted drive, or $ if is doesn't.

*OPT (<n> (<n>)) MOS

This is used to set various file options. These are:

*OPT 0 - This resets OPT 1,2,3,6 and 7 to their default values. *OPT 0,255 also writes the *OPT6/7 setting to CMOS. *OPT 1 - Sets level of file information messages given on LOAD and SAVE commands: *OPT 1,0 gives no messages (default). *OPT 1,1 gives detailed messages. *OPT 2 - Sets the filing system number returned by OSARGS 0,0. With this you can make HADFS pretend to be a different filing system, eg setting *OPT 2,5 will make it be recognised as NFS. Default is 16, and you cannot set to 4, as that is the value of DFS. *OPT 3 - Sets the auxilary filing system recognition number. A filing system can be selected with service call &12, and HADFS recognises the OSARGS 0,0 number set with *OPT 2 and the number set with this call. *OPT 4 - This sets the autostart action as follows: *OPT 4,0 ignores !BOOT *OPT 4,1 *LOADs !BOOT *OPT 4,2 *RUNs !BOOT *OPT 4,3 *EXECs !BOOT *OPT 4,8+n sets the autostart option and sets the user as a system user. *OPT 5 - unused. *OPT 6/7 - set drive to use internal or external drivers: *OPT 6,d drive d uses internal drivers *OPT 7,d drive d uses external drivers After *HADFS, *MOUNT or *BYE the first access to a drive numbered 0 to 7 first tries to use an external driver with OSWORD 90. If no external driver is found for that drive a flag is set to use internal drivers for that drive. Using *OPT 7 can force a particular drive to always use external drivers, giving the Drive
x not present
error if there is no driver. *OPT 6 returns to allowing internal drivers to be used. The setting is saved in CMOS configuration RAM.

*RENAME <old fsp> <new fsp> Filing

This command renames an entry to give it a new name. If the entry is locked, or the new name already exists, you will get a File locked or File
exists
error. You cannot rename across disks, and you cannot rename the root $ directory. If you try to rename a directory inside itself or a subdirectory, you get a Circular rename error.

*RUN <afsp> (<parameters>) MOS

This command is used to load and run machine code programs. It loads a file into memory, and then jumps to its execution address, unless it is &FFFFFFFF or the load address is &FFFFFFxx when the file is *EXECed instead. If the file's load address and execution address disagree about which memory the file should run in, (ie, the top byte of the addresses should both be &FF or they should both be not &FF), then the error Cannot
run this code
will be generated. Using *<afsp> or */<afsp> is the same as *RUN, except that the library directory is also searched. See *LIB for more information.

*SAVE <fsp> <start> <end>|+<length> (<execute> (<reload>)) MOS

This command takes a copy of the specified section of memory and writes it to a file with the given name. If the execution or reload addresses are not given, then they are set to be the same as the start address. If the start address's high byte is not &FF, ie start<>&FFxxxxxx, then language processor memory is saved. With a machine with no second processor, this will be that same as I/O processor memory. If the start address's high byte is &FF, is start=&FFxxxxxx, then I/O processor memory is saved.

A start address of FFFDxxxx will save shadow screen memory, regardless of which memory is being used to display the screen.

A start address of FFFExxxx will save whichever memory is currently being used to display the screen

A start address of FFFFxxxx, or if there is no shadow screen, will save normal I/O memory.

*SETDATE (dd/mm/yy (d)) Util

When files are created, they are date stamped. On Master computers, the date for this is fetched from the on-board Real Time Clock. The pre-Master BBCs, however, do not have this feature, and so using this command simulates the date part of it. After using the *SETDATE command, you can read the date using the OSWORD 14 call, as on the Master. If there is an on-board Real Time Clock this will take precedence to the date set with *SETDATE as long as the code to access it is in a higher priority ROM than the HADFS. The optional parameter d can specify the day of the week 1 to 7 for Sun to Sat. Using *SETDATE with no date disables the function.

*SETEXEC <afsp> <addr> Util

*SETEXEC sets the specified file's execution address to the supplied hexadecimal address.

*SETLOAD <afsp> <addr> Util

*SETLOAD sets the specified file's load address to the supplied hexadecimal address.

*SETTYPE <afps> <addr> Util

*SETTYPE sets the specified file's load and execution addresses to the RISC OS-compatible filetype. The load address is set to &FFFxxx00 with xxx being the supplied value.

*SHUT MOS/Filing

*SHUT is similar to *CLOSE in that is closes all open files. On Master series computers it closes all open files on all filing systems, leaving the current filing system selected.

*SPOOL (<fsp>) MOS

This command opens a file with the specified name to recieve all the information subsequently displayed on the screen. It is the opposite of the *EXEC command. *SPOOL with no parameter closes any opened spool file.

*STAMP <afsp> Transient

Sets the date attribute on the specified object to the current date.

*STATUS HADFS MOS

This displays HADFS's current configuration status, that is, the number of channels, which drives are using external drivers, and the current time and date setting. On the Master series (or BBC series with suitable support), the settings are saved in CMOS RAM.

*TIME MOS

This command produces a standard display containing the day, date and time, if set. On Master computers, the time will be read from the Real Time Clock. If no RTC is present, then the date can be set with *SETDATE, and the time can be set with TIME=((minutes*60)+hours)*60*100. The format of the display is DDD,dd mmm yyyy.hh:mm:ss, ie Day, date, month, year, hours, minutes, seconds.

*TITLE (<drv>) <title> Filing

This will change the disk title on the currently selected or the specified drive. The title can be one to sixteen characters long, but should be at least two characters long, and should start with a letter.

The *TITLE command is an alias for the *INSTALL command, and will accept *INSTALL parameters.

*TYPE <afps> DFS/MOS

This command displays the contents of the named file, as with *LIST, except that no line numbers are generated.