HADFS Text Files Display

Harston Advanced Disk Filing System =================================== Reference Manual ================ for Version 0.32 ================ Introduction ------------ The HADFS is a full hierarchial filing system similar to the NFS and ADFS systems. It runs on any 6502 based BBC computer, with any disk hardware. It is independent of the hardware configuration, adapting its operation to different requirements. HADFS formatted disks contain the Rom image for the system, allowing it to be easily distributed. The only requirements needed are a DFS (any sort) that supports Osword &7F to read and write sectors of the disk, and 16k of sideways ram. As an alternative to the sideways ram, the Rom image can be blown into an Eprom and permanently installed in the machine. HADFS was written and is under continuing revision by: Jonathan Harston 70 Camm Street Sheffield S6 4QR and remains wholly copyrighted, (C) 1990. The program is Public Domain, and can be freely distibuted, as long as the code is not modified, and all copyright and authorship messages remain, and no charge is charged, other than legitimate disk purchase and copying costs. Ownership can be registered by writing to the above address, enclosing 10. This entitles you to a full printed reference manual and to immediate code updates. You are under no obligation to register, and you can probably manage with the manual contained in this file. Definitions ----------- Within this text, the following terms are used: 'press' means press, ie put your finger on the key, push down, and then release, as in: 'Press "X"' 'type' means a succession of 'press'es, ie pressing each individual key, as in: 'Type "fred"'. It does not mean press Return at the end. 'enter' means 'type', and then 'press' the Return key, ie enter in something, as in: 'Enter the filename'. 'Return' refers to the key labelled 'RETURN' (or sometimes 'ENTER'). 'Shift' refers to the key labelled 'SHIFT' 'Ctrl' refers to the key labelled 'CTRL', and is called the control key. 'Delete' refers to the key labelled 'DELETE' 'Break' refers to the Break key. 'Shift-Break' means press the Break key while holding down the Shift key. The Shift key on its own does not do anything, so don't be afraid to hold it down longer than neccessary. In fact, this is to be recommended. 'Ctrl-Break' means press the Break key while holding down the Ctrl key, similar to above. Startup ------- There are two types of HADFS disk. These are an HADFS data disk, which just contains data, and an HADFS system disk. An HADFS system disk contains three things. A DFS !Boot file to bootstrap the HADFS Rom, the HADFS Rom image, and the HADFS disk data. There is also a 'SPARE' file which is currently unused, but may be used in future versions. On booting up an HADFS disk for the first time with Shift-Break (or Shift-D-Break), the HADFS Rom image is loaded in and the machine is reset again. This only needs to be done if the Rom image is not present in an Eprom. If it is, then it is already present at power-on. Unless otherwise stated, the manual will assume that the Rom image is in the machine, either in sideways ram, or in an Eprom. If a second processor is attached when loading in the Rom image, then the message 'Press Break to reset Tube' is given, and the Break key should be pressed to reset the second processor. There is no way to universally reset a second processor from software, so you have to press the Break key yourself. An HADFS data disk does not have the rom image on, thereby releasing 16k of space for extra files. In all other respects, HADFS data and system disks are identical. On power-up, or a simulated power-up caused by *FX151,78,127 followed by a Break, the authorship and copyright message is displayed. On all other resets this message is not displayed, so giving the standard startup display. Once HADFS is in your machine, it can be selected by *HADFS or by H-Break. Filenames --------- In the following section and in the *HELP messages, the following abbreviations are used: <afsp> ambiguous file specifier. A filename that can include the wildcard characters '#' and '*'. <fsp> file specifier. A filename that does not include the wildcard characters '#' and '*'. <src> source filename/drive. <dest> destination filename/drive. <dir> a directory. <user> a user number. <drv> a drive number. 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 Filing Commands --------------- *ACCESS <afsp> <access> 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, you own the whole disk. Ownership is changed using the *SETUSER 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. *BACKUP <src> <dest> This command has not yet been implemented, and you should use the supplied Basic program 'COPYFILES' or 'TREECOPY' or 'BACKUP' instead. *BYE This closes any open files and dismounts all the disks. You should always use this (or *MOUNT) before changing a disk. *CDIR <dir> 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. *COMPACT (<drv>) This command has not yet been implemented, and you should use the supplied Basic program 'COMPACT' instead. *COPY <src> <dest> This command has not yet been implemented, and you should use the supplied Basic program 'COPYFILES' or 'TREECOPY' instead. *DELETE <fsp> This simply deletes a file 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, the error 'Dir. not empty' is generated. You can only delete files in directories that you own. *DIR (<dir>) 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 *ENABLE 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 *BACKUP 0 1 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>) 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 *FREE (<drv>) 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 04AD Sectors = 306432 bytes used 0193 Sectors = 103168 bytes free *INFO <asfp> 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: 0640 ID: 7632 HADFS 0.27 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>) 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 disk is not an HADFS one, then a new root directory is created. If the disk is an HADFS one, and the '$' parameter is given, then a new root directory is created, effectively deleting everything on the disk. If no name is given, and a new root is being created, then the disk title is set to '(UntitledDisk)', else the supplied name is used. If a new root is to be created, the command must first be ENABLEd. The disk must already be formatted as a standard DFS disk, either 40 or 80 track, single or double sided. 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. Recognised values are: 640 or 160 - 80 track, double sided 320 or 80 - 80 track, single sided 190/2 or 40/2 - 40 track, double sided 190 or 40 - 40 track, single sided You can also specify the size as a the total number of sectors on the disk by using '=xxxx', where 'xxxx' is the total number, in hexadecimal. This is especially useful for INSTALLing disks on the non-floppy drives (2 to 7), or INSTALLing disks with more than 80 tracks. As an example, *INSTALL 4 $ FRED'S_DISK =0800 would initialise a disk in drive 4 with &800 sectors, and the following: *INSTALL 0 $ LargeDisk =0668 would initialise an 82 track disk. If no size is given, then the default of '160' is used. Using the 'D' parameter makes the disk a data-only disk, leaving off the DFS installation files, and giving you a bit of extra space on the disk. You can only use this option 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. Note: there are a couple of non-fatal bug in current version of HADFS. If the disk title given is exactly 16 characters long, the command hangs. To get out of that, just 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. *I AM <dir> 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 drive 0. A directory $.Library is looked for on drive 0 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 drive 0 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 drive 0. If the specified directory cannot be found, then :0.$ is logged into instead. *LIB (<dir>) 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 is: *command */name *RUN name MOS looks in MOS rom Look at sideways rom commands Look at filing system commands ----------------- ------- ------- HADFS looks in CSD HADFS looks in CSD ----------- Does filename include --Yes---- $, %, &, @ or : No HADFS looks in LIB V HADFS looks in &.Library (*) V Master computers check LIBFS ------------- 'Bad command' error 'File not found' error If a file is found, it is loaded and executed, else the search path above 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 :0.Library if it exists, or to :0.$ if it doesn't. (*) - Searching in &.Library has not yet been implemented. *MAP (<drv>) This displays the free space map for the selected drive, or the drive of the CSD, if none is given. *MOUNT 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. After a *MOUNT, the CSD and URD are set to :0.$ and LIB is set to :0.Library if it exists, or :0.$ if is doesn't. *RENAME <old fsp> <new fsp> This command has not yet been implemented and will either generate a 'Bad rename' error or a 'File not found' error. *SETUSER <dir> <user> This sets the user number of a directory. When a disk is *MOUNTed, your user number is reset to 0, so to own any directories that have had the user number changed, you must log into them using *I AM. *OPT 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 15, 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 max. number of channels used. Default 5. *OPT 6 Sets the drive 1 status flag. If zero, then drive 1 is provided by the DFS rom. If non-zero, then an external routine is used. *OPT 7 Currently unused. *CAT (<dir>) 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 be 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 00 MyDiskOne Option 0 (Off) Dir. $ Lib. Library MATHS WR/R GAMES DL/ STARTUP LR/R START2 R/E *FORMnn <drv> 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 and it 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. *HADFS (#) This command selects the HADFS. When selected, the HADFS checks to see if it can find a DFS which it needs to perform the disk accesses. If it cannot find a DFS, then the error 'DFS not present' is generated, after selecting itself. If you use the '#' parameter, then this checking is missed out, and so no error can be generated. The (now obsolete) Acorn DFS 0.90 fails to respond to the call used to check if the DFS is present, and so *HADFS # should be used. *HAD-OFF This command completely disables the HADFS rom, in effect unplugging it. It can be turned back on be a *FX90,6 command or by Shift-Breaking an HADFS disk. *HSETDATE (dd/mm/yy) 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. Using *HSETDATE with no date disables the function.