5 The filing system utilities

There are a number of utilities supplied on the HADFS System disk. Some of these are machine code and some are Basic programs. HADFS allows you to CHAIN Basic programs by calling them as a *Command if they have a load address of &FFFFFBxx, ie file-typed to &FFB. This allows Basic programs to be placed in the library directory along with machine code programs. Programs in subdirectories of the library directory can be run just like the main library programs. This allows you to group collections of similar commands together in subdirectories instead of creating an ever-lengthening library directory. If there is a file %.Progs.RunMe then using *Progs.RunMe will call it. You have to bear in mind that some alphabetic sequences with a full stop directory separator may be interpreted as an abbreviation for a rom-based command. For example,*K.Prog will be matched as *KEY Prog. It is therefore better to use digits for library subdirectories. It is convenient for the Utils directory be renamed to Library.1, allowing the Utils programs to be run with *1.VisCompact, *1.D_Map, etc. A recommended starting list is:

		%.1	Disk/Filing Utilities
		%.2	Text/Word Processing Utilities
		%.3	Programming Utilities

The programs and utilities supplied on the system disk are as follows:

Library: (HADFS utilities) BACKUP, COMPACT, Copy, Disks, Files

Library: (File utilities) CLoad, CSave, ETree, FileInfo, PrList, ScrLoad, ScrSave, SetType, SrLoad, SrSave, Stamp, TreeCopy

Library: (General utilities) Assem, Break, Disp, Explode, lpS, lp, MakeLP, MCode, MDump, Mouse, Repair, Roms, Scroll, VList

Utils: CATALL, COPYFILES, D_Map, H-Edit, H-Utils, MCat, Rescue, S/Intern,  UnArcH, VisCompact

Extras: Examine, FindPath, H_Support, InfoTest, NFSTester, PrInfo, RS_Disk1, RS_Disk2, S/FredDisk, S/NFSFront, S/RamDisk, S/RS-Link, Stats

There may be more than the list given here. Any extra files and programs will be detailed in accompanying text files, and they will be mentioned in a $.!ReadMe text file.

The Library HADFS utilities are for using with HADFS. The Library file utilities can be used on any filing system for accessing or giving information about files. The Library general utilities can be used on any filing system. The Utils and Extras are HADFS programs.

The library commands *Copy, *Disks, *Files, *SetType and *Stamp are detailed in Chapter 4.

HADFS Library Programs

The following are programs designed to run with HADFS.

BACKUP
This program will copy an entire HADFS or DFS disk sector by sector, ignoring the file structure. Any faulty sectors on the source disk are ignored. The destination disk must already be formatted the same as the source disk.

BACKUP can take the following command line parameters:

    BACKUP <src> <dst> <trks> <sides> -s <spt> -t <tries> -quit <name>

If the <src> and <dst> drives are given, both must be given. If the number of tracks and sides are given then both must be given. The single character options must be given in lower case. The <spt> option is the number of sectors per track, currently only 10 is implemented. The<tries> is the number or retries BACKUP uses before abandoning a disk read or write.

The -quit option can give a file to run on exit. If the name starts with a *, then it is called as a *Command, otherwise it is CHAINed.

If no parameters are given, you are prompted for the source and destination drives. These can be the same, in which case you will be prompted to change disks. You are then prompted for the size of the disk, the number of tracks, the number of sides and the maximum number of retries to use. If RETURN is pressed, then the defaults are used.

Once all these are entered, the program waits for a keypress before starting.

COMPACT
As a disk is used, as files are created and deleted, the free space on it may get fragmented until a stage arrives where there may be enough space to save a file, but none of the small areas of space are individually large enough. The COMPACT program tries to move all the files on a disk together so that the free space is in the largest areas possible.

COMPACT can take the following command line parameters:

	COMPACT <drv> -quit <name>

The -quit option can give a file to run on exit. If the name starts with a *, then it is called as a *Command, otherwise it is CHAINed.

If no parameters are given, you are prompted for the drive number to compact. It then looks through the entire disk and moves as much as it can to compact the disk. It can only move files that will fit into memory, so the compaction may not be the maximum possible.

Rescue
This program can be used to rescue a file that has been corrupted and made inaccessible due to disk errors. You are prompted for the filename of the file to rescue, the new filename to save the rescued file as (don't use the same one!) and the fill byte for bad sectors. You give a decimal number or a hexadecimal number prefixed by '&'.

If you just press return, then the bad sectors are not filled, but the beginning is marked with '!!!!!!!!' and the end is marked with '********', and any control codes other than CR (13) are converted to '|'.

Rescue can only rescue files that are short enough to fit into memory. It goes through the file, loading it sector by sector, listing any bad sectors. After rescuing the file, you can try to repair it. For example, with text files use either fill byte 13 or nothing, and then load or read it into a word processor to edit the damaged section. For BASIC programs, use no fill byte, and then use *REPAIR to repair the bad program, and then edit the damaged section.

After rescuing a file, don't delete it. *RENAME it somewhere out of the way, eg as $.BadSectors.File1. This will hide the bad sectors from other files. If you deleted it, the the free space would be returned to the Free Space Map, and you could attempt to save into the bad sectors again. If you get a lot of bad sectors on a disk, you should copy off the files to another disk and re-format it. If that doesn't solve the problem, you should throw the disk away and replace it. Regular disk-drive cleaning reduces disk errors considerably.

HADFS Utils programs

These programs provide utilities to be used with HADFS. To make it more convenient to run, you can rename the $.Utils directory to $.Library.1.

H-Utils
H-Utils provides some extra utilities for use with HADFS disks. On running, if no date is set, you are asked to enter the date. Then the main menu appears:

		1 : Initialise a new HADFS disk
		2 : Alphabetically sort a directory
		3 : Convert a DFS disk to HADFS
		4 : Extend a directory
		5 : Unextend a directory
		6 : Add a shadow file to DFS
		7 : Remove a shadow file from DFS
		8 : Create a *ReBoot file
		H : HADFS Info        D : Disk info

You can also press '0' to exit, and '*' to enter *-commands.

Option 1: Initialise a new HADFS disk. This option allows you to create a new HADFS disk with a partition for DFS files.

This option also allows you to reserve a partition in the HADFS disk for DFS files. The usual thing to do is, with a double-sided 80 track disk, is have HADFS files on side 2 and DFS files on side 0. You do this by starting the 'hole' in the HADFS map at sector 74, just after the $ directory, and extending it all the way to the end of that side of the disk. The HADFS disk map then continues from sector 800 to sector 1599. You can then save up to 27 other files in the DFS catalogue. The !Boot file is renamed as HADFS and the 'D I S K' file as 'H.D I S K'. TheROM file stays as ROM. This way, you can have other DFS files, including a !Boot, and doing *HADFS from DFS will either select HADFS if it is already loaded, or load the ROM image file, as the HADFS!Boot would do.

Option 2: Alphabetically sort a directory. HADFS disks at present do not store the directories alphabetically. It is intended that in future they will be, but at present you can use this option to alphabetically sort a directory. The case of names is ignored in sorting.

Option 3: Convert a DFS disk to HADFS This will convert a DFS disk to an HADFS data disk. You are asked for the size of the disk, and whether you want to convert both sides. There needs to be some space on the disk on track seven for the HADFS root directory, so if track seven is occupied, the files will be moved out of the way. If they cannot be moved (the disk is too full) you may have to *COMPACT the DFS disk. If that does not free up sufficient space, you will have to remove some of the files. The files from side 0 are put into directory $.Side0, and those from side 1 into directory $.Side1. DFS directories other than $ are pre-pended to filenames in the same way as TreeCopy, so that B.FRED becomes B/FRED.

Option 4: Extend a directory When a directory is created, three sectors are reserved for it. This is enough to hold 31 entries in. However, the structure of the directory allows it to be extended by another 31 files (and extended again, up to 240 files in total). This option asks you for the directory to be extended, and adds another extension to it. It uses the file $.!!!! as a temporary file, so if this file exists, the routine stops.

Option 5: Unextend a directory This is the opposite to option 4. If the very last extension chunk is empty, then you can remove it using this option.

Notes:*INFO <dirname> and OSFILE 5,"dirname" always return &300 as the length, ie only the length of the first chunk of an extended directory.

Option 6: Add a shadow file to DFS You can add a shadow file to the DFS catalogue that points to a file on the HADFS disk. You can only do this on a system disk, and the HADFS file must be on side 0 of the disk. You can check this by seeing if the sector start given by a *INFO command is less than &190. With this, and *ReBoot, see below, you can create archive disks. On some early versions of HADFS (before about v0.35) a *INSTALL will remove any DFS shadow entries.

Option 7: Remove a shadow file from DFS This will remove a shadow file from the DFS catalogue. This is the same as just *DELETEing the file from the DFS catalogue. 

Option 8: Create a *ReBoot file If you boot a system disk created with HADFS after v0.31 on a machine with no sideways ram and no HADFS in rom, then 'No sideways ram' is displayed, and a *ReBoot command is executed. If this *ReBoot command exists, having been created with this option, then it can continue to do something else. If you look at the DFS catalogue on a system disk, you will see a file called SPARE. This is used to create the *ReBoot command. The *ReBoot command can either chain a Basic program, or run another machine code program. The program it runs is a shadow DFS file created with option 6 above. You are asked for the program name, and if it is a Basic program. An example of using would be the following:

* On an HADFS disk, you have a file $.HADFS.UnArcH * You shadow that file using option 6 and create a DFS entry UnArcH * You then create a *ReBoot command using option 8.

The DFS catalogue now shows the following:
		!Boot	 L	D I S K	 L
		ReBoot	 L	ROM	 L
		UnArcH

If the disk is booted in a non-HADFS machine, the boot sequence ends, andUnArcH is entered instead. You can also do this manually by doing *ReBoot yourself. UnArcH is a HADFS unarchiving program that allows somebody without access to HADFS to remove the files from an HADFS disk and copy them somewhere else.

Option H: HADFS Info This option shows various information about the version of HADFS in the machine. It shows the version number and capability bits returned by OSARGS &FD,0. With A=&FD, X=zero page location and Y=0, A returns the version number*100 and zero page holds the following:
	zp+0: capability bits 0 to 7
	zp+1: capability bits 8 to 15
	zp+2: version number x
	zp+3: version number yz for x.yz This function is also contained in the program Extras.PrInfo.

Option D: Disk Info This reads the flag bytes of a disk and shows what type it is.

H-Edit
H-Edit is a DFS/HADFS disk sector editor. When run, it loads either sector zero, or sector &46, the root sector if an HADFS disk.

Keys:	cursors keys move around
	Shift-cursor keys move to next sector
	TAB	swaps between ASCII entry and HEX entry
	COPY	swaps which half of the sector is displayed
	f1	select drive
	f2	select absolute HADFS-style sector number
	f3	select track
	f4	select sector within the current track
	f6	Chain H-Utils program
	Esc	exits program
	Ctrl-D	search for a Directory
	Ctrl-F	display HADFS File information under cursor
	Ctrl-G	Goto file's start sector
	Ctrl-H	display Help information
	Ctrl-O	OS command
	Ctrl-S	Save sector
	Ctrl-U	go Up from a directory

When moving to a different sector or exiting, you are given the opportunity to save the current sector to disk, so Esc can be used as a 'save this sector' key.

D_Map
D_Map graphically shows the layout of all the files on the disk.

VisCompact
A combination of COMPACT and D_Map. Graphically shows the layout of a disk while it is being compacted!  Needs quite a lot of memory, so needs shadow screen memory available. It will take the same command line parameters as COMPACT.

S/Intern
S/Intern creates an internal rom-drive thet can be loaded into sideways ram. It utilises the OSWORD 90 calls implemented by HADFS to allow extra drives to be added. When run, the following prompts are given:

Drive number:
	The drive defaults to drive I. To change this, enter a drive number/letter here.
Disk name:
	To change the default name, enter a new name here.
Make default drive?
  Enter drive number:
	If set to 'Yes', then after a *MOUNT, then the specified drive will be the default drive.
Make default library drive?
  Enter drive number:
	If set to 'Yes', then the specified drive will be looked for for a Library directory before any others.
Make default user drive?
  Enter drive number:
	If set to 'Yes', then the specified drive will be looked at first when doing any *I AM commands.
Boot option:
	This will set the option to use if the drive is booted from.
Make files externally runnable?
	If set to 'Yes', then any file with a public 'r' access will be able to be called as a rom-based *command
	without HADFS being selected as a the current filing system.

Once these are entered, files can be loaded into the rom image. You are given a prompt which shows how much space and directory space is left. *Commands can also be given at this prompt, eg to change directory. The file $.Extras.IntRom is a rom with the supplied Library in it

DemoGbPb
This demonstates calls to OSGBPB to read various information. It runs through all the calls from 5 to 255, and displays the returned information. This will also work on other filing systems to demonstrate what is returned.

General Programs

These programs should work any machine, including Archimedes, and on any filing system.

TreeCopy
TreeCopy will copy files between filing systems, preserving the directory structure and file attributes. The program is quite easy and self- explanatary to use. It has been completely rewritten to be fully error-trapped, allow disk swapping, and it reads as many files as possible before writing, thereby reducing disk swaps. Some notes to bear in mind are:

* The attributes have the 'W' and 'R' options added when copying from DFS.
* Filenames are shortened to seven characters when copying to DFS.
* If a file has no read access, TreeCopy will set the access to 'R', copy it, and then reset the access to what it was. 
	Obviously, the source disk will need to be not write protected if this happens.
* If copying to or from ADFS disks, put the ADFS disk in drive 0. This is because the *ADFS command mounts
	drive 0. Alternatively, use 'FADFS' as the filing system.
* When copying from ADFS disks, *MOUNT them first.
* When copying from Econet, the Execute bit is masked out as it is usually just a copy of the Read bit.
* Answering 'Yes' to the 'Recurse?' question will copy subdirectories.
* The 'Pause to change disks?' option allows you to use the same drive for different disks.
* When copying from DFS the 'Copy all DFS directories?' question allows you to copy the whole disk, creating an
	approximation of the DFS directory structure by putting all the non-$ directories into subdirectories, or
	adding a prefix to the filename. If you answer 'Y' to the subsequent 'Put into subdirs?' question, any
	directory other than the DFS $ directory is put into a subdirectory of the destination directory. Answering
	'N' will put them in the destination directory, prefixed with x/, when x is the directory. Eg, DFS B.Prog
	becomes B/Prog.
* When copying to DFS there is the 'Expand into DFS dirs?' question. This allows you to copy files with a x/ prefix
	saved by answering 'N' to the 'Put into subdirs?' question into the DFS x directory. Eg, B/Prog becomes
	DFS B.Prog.

TreeCopy can take the following command line parameters, which must be in this order:

	(<fs>:)<src> (<fs>:)<dest> CPRE (-dest) (-quit <name>)

The <src> and <dest> directories can be prefixed by a filing system name terminated with a :, eg HADFS::0.$  The single character options control the level of copying:

		C - Confirm
		P - Pause to change disk
		R - Recurse
		E - Expand DFS directories

They can be prefixed with '~' to turn off the option, eg ~C means no confirm. If the -dest option is given, then TreeCopy will terminate with the destination filing system selected. Otherwise, the source filing system remains selected.

The -quit option can give a file to run on exit. If the name starts with a *, then it is called as a *Command, otherwise it is CHAINed.

An example command line would be:

	*TreeCopy HADFS::0.$.Disk1 ADFS::1.$ ~C~PR~E -quit %.MenuProg

If any parameters are not given, they are asked for. The -dest and -quit options must be given in lower case, and only the first letter is significant.

ETree
ETree will display an expanded tree display of the directory structure. When run, ETree asks for the path of the directory to display. At this prompt, you can also give command line option flags. If you did not given any option flags when entering the path, you are then asked whether to show files (or just directories) and file information, and whether to print out the display. If you select printing, then the characters used are those suitable for printing on a printer that has characters 128 to 255 set to PC-8 characters. If there is any information available on the disk root, it is show. At the end, the total space used by the directories and files looked at is show. If you use the -count option, then all directories will have their contents added up and the total shown individually.

ETree can take the following command line parameters, which can also be entered at the 'Path to show:' prompt:

		*ETree [-files] [-info] [-count] [-print] path

or 		*ETree path [-files] [-info] [-count] [-print]

The option flags must be in lower case, and only the first letter is significant. If there are no parameters, ETree asks for them.

Library File Utilities

These transient utilities can be used on any filing system for accessing or giving information on files. Information about these commands is given in the file $.Extras.T/Library.

Library General Utilities

These transient utilities and MCoded Basic programs can be used on any filing system. Information about these commands is also given in the file$.Extras.T/Library.

Printout Programs
Most of the text files supplied on the System Startup disk are extended View files. These are text files created with Acorn's View word processor, using extensions to highlight two to provide easier-to-use printer functions. MakeLP creates the *lp commands to print out the files (replacing View's PRINT command), *lpS can be used to show the effects on the screen (replacing View's SCREEN), and Scroll can be used to scroll though a text file of any length, again showing the effects.

MakeLP
This program creates the lp command to print out View or text files to a printer. The name lp comes from Unix - it's short for Line Printer.MakeLP allows you to create a customised version of lp tailored for your printer and for what effects you wish to use. The default settings are for Epson-compatible printers.

lp extends View's highlight 2 to give the extra facilities. After a highlight 2 you put a letter indicating an effect. A capital letter turns it on and a lower case letter turns it off. As an example: doing *Ihello*i would put the word 'hello' in italics.

Pound symbols are correctly printed (hurray!!) - for this you need your printer set in US mode. This is done by setting some DIP switches somewhere, usually the endmost three to 'off'. Check your manual on this. The pound symbols are printed by switching to UK, printing a '#', and then switching back to US. As with everything else, this can be changed.

The program is fairly simple to use. There is a main menu with a few options. Option 5 - Create View Driver - is not yet implemented. Options 1 and 2 allow you to change the parameters for your printer. Options 3 and 4 allow you to save and load the settings, and option 6 creates anlp command. The actual name can be changed to anything reasonable. I recommend creating a lp directory in the Library, and naming the commands%.lp.nlq, etc. The System Startup Disk has various files supplied in the %.lp directory.

On option 1, you have some Yes/No questions and some value questions. Pressing RETURN leaves them as they are. You may have to experiment a bit to find what the correct values are for your setup. There are some supplied files for different lengths of paper and number of lines on each page.

		             Text lines	Page lines		Supplied files
Continuous A4		70	    70	%.lp.70A4		%.lp.70A4nlq
Standard A4		66	    70	%.lp.66A4		%.lp.66A4nlq
Short A4			60	    70	%.lp.60A4		%.lp.60A4nlq
Continuous Listing		66	    66	%.lp.66		%.lp.66nlq
Standard Listing		60	    66	%.lp.60		%.lp.60nlq

These are the files used by the JGHPD ViewHello View menu system.

On option 2, you select the code string you want to alter with the cursor keys. To change the string, type in the new string. The input is fairly flexible. You can put commas between everything, or not. You can enter in characters or decimal. If you want the number characters "0" to "9", they must be surrounded in quotes, otherwise they are taken as values. Examples are:

		27,S,"0"  \
		27,S,48    }  all the same.
		27,83,48  /

To remove a setting, press SPACE followed by RETURN. The setting should then disappear. Pressing COPY will allow you to edit the settings for punctuation and numbers.

When lp starts it does a '@' code. This is defined to reset the printer, and can also set it to NLQ if you want. This makes the current position on the paper the top of the form (the place where Form Feeds go to). If you don't want this, set '@' to nothing.

lp ignores View's ruler and embedded commands, etc. Tabs are to 8 character positions, as on the default ruler.

The syntax of lp is:

	*lp (+) <afsp> (<num>)

If the '+' prefix is given, lp double spaces. If a decimal <num> is given, then that number of copies are printed. You can press Escape at any time and the print job will be terminated, but the printer itself may continue for a while as it empties its own buffer. 

Hints
If your printer prints everything on the same line, you need to setAuto linefeed to Yes from option 1. If it doublespaces when you don't ask it to, you need to set Auto linefeed to No.

If your printer form feeds to much, set Form feeds to No.

The following are Highlight 2 extensions that are used in most of the text files, and so I recommend you set them to do a suitable effect on your printer.

	Bb	Bold on/off		 Main bold effect
	Cc	Condensed on/off

	Dd	Double-strike on/off	\  Auxilary
	Ee	Emphasided on/off		/ bold effects
	Hh	Double Height on/off
	Ii	Italics on/off
	Qq	Quad size on/off							This takes 3 lines(That bottom line ^^^^ has to be blank for Quad to work on the LC10/1001)
	Ss	Superscript on/off, as in dates: 3rd March
	Ww	Wide on/off
	Xx	Wide X High
	Yy	Subscript on/off also:
	Highline One is used for underline
	Pound: £	Hash: #

*lpS (-<lines>) <afsp>
The lpS command will display a text file to screen, taking account of the following effects: Bold, Italics, Superscript, Wide, Subscript andUnderline. If a <lines> parameter is given, then each page is split with a line of '=' characters.

Scroll
Scroll is a scrolling textfile reader. You can scroll upwards and downwards through text files of any length. Extended View highlight codes as used by *lp and *lpS are acted on to give bold, italics, superscript,wide, subscript and underline ffects. These can be turned off to give plain View extensions of bold and underline. Scroll will also run on the Archimedes.

If there is enough memory, Scroll uses shadow mode 0, otherwise mode 3 is used. Unless a command line file is given, Scroll shows the current directory and asks for a filename. At this prompt you can also give*commands to change directory, etc. Once a file is given, it is loaded and displayed.

The keys are simple. Cursors move up and down. Pressing Shift will jump one screen at a time. Pressing Ctrl will jump to the ends of the file. Pressing COPY will flip between extended highlights and plain highlights. Pressing Escape will leave.

Pressing P and RETURN will let you print out the file. Before you press RETURN a prompt appears telling you the name of the printout command. You can change this here by deleting it and typing in another comand, but Scroll will usually have found a suitable one. The recommended command *lp comand is created with the MakeLP program.

Pressing 4 will display the file in 40 column teletext mode, if Scroll has been told what program to use.

The bottom line of the screen shows the filename of the file being scrolled, a percentage figure showing how far through the file you are, and a reminder of the keys used.
Scroll will take the following command line arguments:

    *Scroll (-lp <name>) (-4 <name>) (-p <pagelen>) <afsp> (-quit <name>)

<afsp> is the file to display. 

The -lp option gives a command to use to print out the file. If this option is not given, then a default printout command is looked for as detailed below.

The -4 option gives a command to use to display the file in 40 column teletext mode.

The -p option gives a pagelength to use when displaying page breaks.

The -quit option gives a command to run on exit.

If the <name> starts with a *, then it is called as a *Command, otherwise it is CHAINed, with any parameters passed via the keyboard buffer. The options must be in lower case, and only the first letter is significant.

So, for instance, to call Scroll from another program, you could use the following:

	CHAIN "Scroll -4 $.4to7 "+name$+" -quit Menu"

This would run Scroll and display the file name$, and CHAIN the program $.3to7 to display in teletext mode. On exit, it would return to the program Menu.

On starting, if no -lp option is given, Scroll looks for an *lp printout program. The order it looks for one is: lp, %.lp, %.lp.#,%.lp.*, $.lp, :0.$.lp. The recommended place to put the *lp command is in the library in a subdirectory %.lp, with a file 1 being a default general purpose printer. With DFS, the best place would be in the $ directory.

Scroll consists of the following files:
	Scroll 	- The program
	disp	 - Controls screen output giving display effects
	T/Scroll	- This text file.