3 Filing systemcommands

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. 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. 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 specifier. 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 @. The following characters are valid in filenames and will be valid in future versions: A-Z, a-z, 0-9, !, _, (, ), ?, +, -. Any other characters not specifically mentioned in this list may in future not be recognised.

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).
	&	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 following wildcard characters are used:

	#	matches any one character
	*	maches any characters
*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, RUN or random access.
	P - Private => The file cannot be seen by non-owners.
	E - Execute => The file can be executed with *, */ or *RUN. When you use this option, the read and
			write options are disabled to make the file a run-only file.

Setting the R option allows you the same access as the E option, but does not make the file run-only. 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 Econet 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 account number of an entry. Currently, the only entries that can be set are directories; if a file is specified it is ignored for future compatability. Also, any auxilary account number in brackets is currently ignored. When a disk is *MOUNTed, your account number is reset to 0, so to own any 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 currently 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 intented 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 calledPROGRAMS 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 currently implemented as a transient program and is described in Chapter 5.

*COPY <src> <dest>					             Filing/Transient
On the Master series, this command is supplied 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 and soft key buffers at &900 to &CFF in the I/O processor, so again the user program area is untouched. Later versions of the command will use spare shadow memory to speed up the operations. For copying multiple files and to other filing systems, use the Basic programs COPYFILES or 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.

*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 Space
	:0 Documentation      016D00
	:1 HADFS_System       018300
	:I Internal_Files     000000
*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							Filing
This command is used to enable the dangerous commands *BACKUP, *COMPACT and *INSTALL with the $ parameter. 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.

*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 00
	MyDiskOne           Option 0 (Off)      Dir. $              Lib. $

	!ReadMe    67542742 26533684   002DAD   WR/R       08/10/89 004A
	Manual1    65524372 38573523   001029   WR/R       08/10/89 0078
	COMPACT    FFFF1900 FFFF8023   00055E   LWR/R      17/10/89 00A2
	COPYFILES  FFFF1900 FFFF8023   000652   LWR/       18/10/89 00A8

*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							Transient
*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 bit 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:04E5 PTR=&00002A EXT=&000037 Dir:004A ID:D951 Alloc=&0040
26  IN.D.... 01:0047 PTR=&000000 EXT=&000300 Dir:0047 ID:F01D Alloc=&0003
27  UPE.WROI 00:0285 PTR=&00023B EXT=&00023B Dir:00D3 ID:D951 Alloc=&0003
28  *CLOSED* 00:0000 PTR=&000000 EXT=&000000 Dir:0000 ID:0000 Alloc=&0000
29  *CLOSED* 00:0000 PTR=&000000 EXT=&000000 Dir:0000 ID:0000 Alloc=&0000

*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 10 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. Most 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
	0193 Sectors =   103168 bytes free
	04AD Sectors =   306432 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-.

*HAD-OFF							Util
This command completely disables the HADFS rom, in effect unplugging it. This can also be done by pressing Ctrl-CapsLock-H-Break. It can be turned back on with *FX90,6 or by Shift-Breaking an HADFS disk. 

*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.

*HSETDATE (dd/mm/yy (d))					Util
When files are created, they are date-stamped. On the 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 *HSETDATE 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 *HSETDATE 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 *HSETDATE with no date disables the function.

*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/yy> <system internal name>

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

   MATHS      FFFF1900 FFFF8023  000734   WR/R       22/05/88 0092

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

   Drive 0: WordProcessing   06/2/91      Size: 400K ID: 7632 HADFS 0.44

This gives the disk title, the date is was created, its size and ID code, and what version of the HADFS rom is installed on it.

*INSTALL (<drv>) ($) (<name>) (D) (<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. The 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.
	&<hex>	the total number of sectors, eg &640

All of the above examples 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. Using the D prefix can only be used when creating a new disk. You cannot use it to change a system disk to a data disk, or vis versa!  As an example, 

	*INSTALL 0 $ DataDisk D 40

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.

There are a couple of non-fatal bugs in the *INSTALL command with versions of HADFS before 0.44. If the disk title given is exactly 16 characters long, the command hangs. To get out of that, you have to press Break. Also, when *INSTALLing a new disk for the first time, the Rom image is not correctly written. You can tell this as the disk drive activity is over very quickly. To solve this, do the *INSTALL command twice.
*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			|
		|	HADFS looks in &.Library (*)	|
		|		|			|
		V		V			V
		|	Master computers check		|
		|	      LIBFS			|
		|		|			|
		\-----------\	|			|
			    V	V			V
			Bad command error	File not found error

(*) - Searching in &.Library has not yet been implemented.

*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 reads 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 high byte 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. If there is shadow screen memory available and the load address is &FFFDxxxx, then the file is loaded into the shadow memory, regardless of which memory is being used to display the screen. If the load address is &FFFExxxx, then the file is loaded into whichever memory is currently displaying the screen. If the load address is &FFFFxxxx, or there is no shadow screen, then the file is loaded 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 OPT1, OPT2 and OPT3 to their default values.
*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 additional 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 5    - set the maximum number of channels used. Default 5.
*OPT 6    - sets the floppy drive status flags:
	*OPT 6,0/1	drive 1 is internal/external
	*OPT 6,2/3	drive 0 is external/internal (nb: opposite to 0/1)
	If the drive is set as internal, the access is provided by the DFS Rom. If external, an external routine must
	be provided. If drive 0 is set to external, and there is no external support routine, it resets back to internal.
	These settings are remembered in the CMOS settings on the Master. The *OPT6,0/1 setting can be set
	with keyboard link 2 on the BBC B.
*OPT 7    - currently unused.

*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 orFile 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, or the load address is &FFFFFBxx where it boot-straps BASIC and CHAINs the program. 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 I 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 into 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. If shadow screen memory is available, then a start address of &FFFDxxxx will save the shadow memory, regardless of whether is is being displayed or not. A start address of &FFFExxxx will save the memory currently being displayed, and a start address of &FFFFxxxx will always save the normal I/O memory, whether it is being used to display the screen or not.

*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, whether drives 0 and 1 are external or internal, and the current time and date setting. On the Master series, the settings are saved in CMOS ram. On the B/B+, the settings are forgotten after power-off, except for the drive 1 status which is defined by keyboard link 2.

*TIME							MOS/Util
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*HSETDATE, and the time can be set 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.

In some versions of HADFS, 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.