MAG Disk (Jan 1990) : DiskSalv / ReadMe


                        D i s k S a l v

                 AmigaDOS Disk Salvage Program

                 Copyright 1989 by Dave Haynie

                  Version 1.42 for AmigaOS 1.3


	DiskSalv V1.42 is a disk recovery program for all Amiga file system
devices that use either the AmigaOS V1.2/V1.3 Standard File System or the
AmigaOS V1.3 Fast File System.  DiskSalv will scan a bad disk volume for
anything that can be recovered, and will restore these items to any
AmigaDOS volume.  It does not make any attempt to fix the bad device in
place; thus, any file that can't be restored with DiskSalv might possibly
be restored with an alternate method. 

	DiskSalv V1.42 fixes all bugs found in DiskSalv V1.40 (there might
still be bugs, but no one found them...).  The main V1.40 bugs was that, on
certain input disks, DiskSalv would generate an out of memory error, even
though there was plenty of memory in the system.  The other errors were an
incorrect reporting of directory loops and a bug in the command-line parser
that caused some CLI options to be set incorrectly.

	Due to popular request, DiskSalv V1.42 also searches the C: 
directory for the Format command it requires for disk formats.  Other than
that, you'll have to wait for DiskSalv V2.00, which is well under way, for
significant enhancements.


	DiskSalv V1.42 (from here on referred to as "DiskSalv") is a
program designed to "salvage" any files and directories from a damaged
AmigaDOS file system device to a good one.  DiskSalv is run from an Amiga
CLI, and in the simplest case is used very much like the AmigaDOS
"DiskCopy" program.  For example, to recover files from a bad disk in DF0:
and restore them on a good disk DF1:, the user will type:

	1> DiskSalv FROM DF0: TO DF1:

Here the "FROM" and "TO" keywords are fully optional if the ordering of the
input and output devices is kept INPUT OUTPUT.  The following line would
also achieve the same result:

	1> DiskSalv TO DF1: FROM DF0:

In either case, DiskSalv will immediately print to the shell's screen:

	DiskSalv V1.42 Copyright © 1989 by Dave Haynie

	Salvage FROM Device DF0: TO Path DF1:

	  DEVICE     =    trackdisk.device   (DF0:)
	  UNIT       =        0    FLAGS      =        0
	  HEADS      =        2    SECTORS    =       11
	  LOCYL      =        0    HICYL      =       79
          LOBLOCK    =        0    HIBLOCK    =     1759
	  RESERVED   =        2    MEMTYPE    =        3
	  ROOT BLOCK =      880    DISK SIZE  =     1760

	Scan Range: START 2, STOP 1759, Expecting Standard FileSystem

	Should I continue [Y]

At this point, a simple RETURN entered will start up the recovery process,
while an "N" followed by a RETURN will abort the recovery. 

1.1 The Scan Phase

	If we proceed with the recovery, DiskSalv will start the first
phase of it's recovery.  At this point, the input device will be scanned
from start to finish (blocks 2 though 1759).  DiskSalv is looking for valid
AmigaDOS file or directory blocks.  A small Intuition window called
"DiskSalv Scan" will open on the Amiga's WorkBench screen.  There are three
columns in this window, BLOCK, NODES, and TYPE.  As each block is read,
it's number is displayed under BLOCK.  This happens pretty quickly;
ordinarily, there's no need to examine individual block numbers anyway. 
The TYPE field indicates whether the block is a file (FILE), root directory
(ROOT), user directory (UDIR), data block (DATA), unused block (FREE),
unknown block type (????), or bad block (ERR!).  Note that under the new
AmigaDOS V1.3 Fast FileSystem, there's no way to distinguish between DATA
and FREE blocks during a scan, so these are always displayed as unknown
blocks.  The final field, NODES, indicates the number of user directory or
file blocks that have been located so far. 

	The other feature of this phase is the file list, which takes place
on the screen.  The shell window will indicate "Building Directory Map...",
and the name of each directory and file that's found will be displayed
under this heading.  Note that at any time during this scanning phase,
clicking the Scan Window close gadget will abort the program.  If the QUICK
or LOMEM operations are selected, no visual account of the block scan
number will be displayed. 

1.2 The Directory Resolution Phase

	The next phase is usually a very short one.  The scanning window
will disappear, and the shell window will indicate that DiskSalv is
"Resolving Stray Directories...".  During the scanning phase, when DiskSalv
finds a file block, it attaches it to a directory in it's directory list. 
To make the scan phase fast, however, DiskSalv only does a single linear
pass over the input disk during that phase.  If the parent directory for a
file or subdirectory isn't available, DiskSalv makes a dummy directory for
it in it's directory list. 

	Normally, all of those dummy directories get changed into normal
ones as they are found in the scan.  However, there are some DiskSalv modes
(covered later) that may result in only a partial scan being performed.  In
this case, valid directory entires may be outside of the scanning range. 
In order to get the proper names of such directories, the resolution phase
goes through the directory entires in it's dummy list and tries to find
real directories to match them.  If a directory can't be found, it was
probably located on a bad block.  That's no problem, all that's lost is the
name of that directory, not any of it's contents. 

1.3 The Directory Pruning Phase

	The next pass happens purely in memory, and it attempts to remove
any empty directories from the directory list.  There are rarely any empty
directories that need to be restored, and there are some DiskSalv options
that tend to force a number of empty directories to be created in the
directory list.  This pass can be overridden if empty directories are
deemed important. 

1.4 The Disk Salvage Phase

	In this next phase, the disk structure is actually restored to the
output device.  This proceeds until stopped via ^C, or until the output
device is full.  If the output device fills up, a new one can be inserted
if the device supports removable media.  The most common form of this would
be floppy disk. 

	There are certain output devices which may not return proper volume
sizing information through AmigaDOS.  For instance, the RAM: device always
says it's full.  A DiskSalv option allows output size checking to be turned
off, and it's automatically selected if the output device is RAM:. 

	DiskSalv uses normal AmigaDOS I/O routines to re-create the
recovered files.  Thus, it may restore to a subdirectory instead of the
root of a device.  If a subdirectory is specified that doesn't exit,
DiskSalv will create it.  Similarly, DiskSalv may output to a logical
volume name instead of a device name. 

	On occasion, a file will be found that DiskSalv considers to be
suspect.  The screen output will indicate the problem, but that tends to
scroll by very quickly.  DiskSalv will now add a FileNote to any file that
it suspects, indicating its concern.  This option can be overridden. 

	Finally, there are occasions under which there may be file name
collisions.  If the output device has a file by the same name as one that's
on the input device, such a collision occurs.  DiskSalv won't overwrite
files.  Instead, the colliding file is renamed before it is rebuilt.  An
extension is added to it, starting at "-0" and going on up to "-100" as
collisions continue to occur. 


	The DiskSalv program is run and controlled completely via
command-line arguments.  It should run without problem from all Amiga shell
programs; it currently can't be run from the WorkBench. 

2.1 Command-Line Options

	There are quite a few options in DiskSalv that'll modify in various
ways the recovery action described above.  The syntax for the DiskSalv
command line is given as:

Usage: DiskSalv [FROM] InDev: [TO] OutPath [[NO]FFS] [QUICK] [NOCHECK]
                [NOTAG] [FORMAT] [LOMEM] [NODOS] [NOTD] [FILE pattern]
                [NOPRUNE] [START [-]num[%]|ROOT] [STOP [+]num[%]|ROOT]
                [ASK] [INFO] [MASK [a|A][r|R][w|W][e|E][d|D][p|P][s|S]]

In each case, text in brackets ("[]") indicates an optional parameter, text
outside of brackets indicates a required parameter, and "|" indicates a
choice of parameters.  The options are:


	This options allows the Disk Salvage pass to proceed interactively
	instead of automatically.  The user is prompted at each file or
	directory.  A reply of 'Y' will recover that file or move into that
	directory, a reply of 'N' will skip that item.  Replying '?' will
	list all the valid options.  A reply of 'A' will recover everything
	left at the current directory level; a reply of 'U' will skip
	everything left at the current directory level.  Finally, a reply
	of 'Q' will quit the program completely. 

	This allows the disk's filesystem to be selected.  Normally,
	DiskSalv can tell the difference between a fast and standard
	filesystem disk, and will act accordingly.  However, if that disk
	is badly damaged, this assumption may be incorrect.  In such a
	case, DiskSalv will usually assume standard filesystem.  If it's
	assumption is wrong, the filesystem can be forced with these

FILE pattern
	Cause the DiskSalv scanner to only record files that match the
	given pattern, which is a standard AmigaDOS filename pattern.  This
	pattern specification has no effect on any directories that might
	be examined, since DiskSalv won't necessarily know the names of all
	directories until the scan phase is complete. 

	This forces the output device to be formatted before any output
	files are directed to it.  If the output device isn't a device, but
	instead a handler, DiskSalv will return an error message if this
	option is selected; it only knows how to format devices.  DiskSalv
	will also offer the option of formatting the output device if it
	fills up during a recovery.  An important note on all DiskSalv
	formatting options -- the disk validator and the Format command
	MUST be accessible for the format to work.  If they're not
	available, DiskSalv will refuse to format an output disk.  If you
	specify the FORMAT option on the command line, DiskSalv will return
	with an error message if these programs can't be located.  If you
	don't specify FORMAT and they can't be found, a warning will be
	issued.  If you go on from there, everything will work OK, but
	you'll never be offered the FORMAT option.  The best way to insure
	that it's present is to have the L: directory with the disk
	validator in it on the same disk that DiskSalv is run from, and the
	Format command in the same directory as DiskSalv.  It may be
	necessary to Assign L: to that disk.  Depending on the shell you
	use to launch DiskSalv, the return code of the Format command it
	spawns may not be correct.  DiskSalv will notify you if it thinks
	a format didn't work; an "Ignore" option here lets you continue on
	if you believe it did, indeed, work.  Finally, if you have the
	CNC: device from Bill Hawes' mounted, Format will use that for it's
	display instead of a CON: window.

FROM InDev: 
	This option allows an input device to be specified.  The input
	device must be a real device, not a path specification.  The FROM
	keyword is optional, but can be used to allow FROM and TO
	specifications to be given in any order. 

	The INFO option lists some information about the program, it's
	distribution, bug reporting, and other stuff.  It should be
	specified in the command line without any other options. 

	This tells DiskSalv to use as little memory as it can get away
	with.  As with the QUICK option, no scanning display is generated. 
	However, some operations may take longer than the norm.  DiskSalv
	normally uses 2 bits per device block, 8 bytes for each file entry
	loaded into its file lists during a scan, and 52 bytes for each
	directory entry.  This option, among other things, changes that
	fixed block usage to 1 bit per device block, lowers the chunk
	size used by the memory allocator, and lowers the maximum length
	allowed for path names.

MASK [a|A][r|R][w|W][e|E][d|D][p|P][s|S]
	This options allows the user to specify a protection bit mask as a
	filter.  The supported bits are "A" for Archive, "R" for Read, "W"
	for Write, "E" for Execute, "D" for Delete, "P for Pure, and "S"
	for Script.  Specifying the bit in lowercase indicates a mask for
	that bit not set, a bit in uppercase indicates a mask for that bit
	set.  For example, specifying "MASK a" will scan for only those
	files that don't have the archive bit set; "MASK WD" will scan only
	for those files with Write and Delete permission enabled.  Any bits
	not specifically MASKed can be in either state. 

	This option prevents the output device's size from being checked. 
	Normally this would only be used with a device that doesn't
	properly report it's size, and it's automatically invoked with
	output to RAM:. 

	Prevents DiskSalv from accessing DOS at any level on the input
	disk.  Normally, DiskSalv does a DOS inhibit on the input disk to
	prevent any other process from modifying the disk during the
	recovery process, since such modifications could damage the disk or
	interfere with the recovery process.  This option is best used when
	trying to recover from a disk that can crash DOS when accessed. 

	This option prevents the directory pruning phase from taking place. 
	If the input device contains empty directories that must be
	restored, use this option. 

	This option prevents DiskSalv from tagging possibly damaged files
	with a FileNote explaining it's concern. 

	DiskSalv does some special optimizations when it's recovering from
	a floppy disk device based on the "trackdisk.device" driver.  While
	there's currently no real use for this option, a future version of
	"trackdisk.device" might possibly not work with these enhancements. 
	This option will turn the enhancements off, making a recovery from
	the "trackdisk.device" work exactly like any other recovery. 

	This option performs a quick scan.  The scan speed is improved by
	not displaying the block number and type information for every
	block.  This doesn't make as much difference as it did in the
	earlier versions of DiskSalv; the "DiskSalv Scan" window routine
	has been greatly sped up this display. 

START [-]num[%]|ROOT
	This option allows the scanning routine to start at any place on
	the input device.  This position is either given as a decimal block
	number, a percentage of the disk, or as the string ROOT.  The start
	value is normally an absolute disk position, but is instead
	relative to the STOP position if the "-" option is supplied.  If
	relative values for both START and STOP are given, they're taken to
	be relative from the disk's root.  Since many files are clustered
	after the directory root on most disks, it's often possible to get
	many of a disk's files back starting the scan there instead of at
	the start of the disk. 

STOP [+]num[%]|ROOT

	This option allows the scanning routine to stop at any place on the
	input device.  This position is either given as a decimal block
	number, a perentage of the disk, or as the string ROOT.  The stop
	value is normally an absolute disk position, but is instead
	relative to the START position if the "+" option is supplied.  If
	relative values for both START and STOP are given, they're taken to
	be relative from the disk's root. 

TO OutPath 
	This option allows an output path to be specified.  The output
	device can be any valid AmigaDOS file device specification.  The 
	TO keyword is optional, but can be used to allow FROM and TO
	specifications to be given in any order.

2.2 Input Device Specification

	DiskSalv requires a DOS name specification for its input device.
Such a name is automatically created by the operating system for each
3.5" disk drive attached, and for some hardware add-ons during automatic
device binding process initiated by the AmigaDOS BindDrivers command.  
Other DOS names are created by the Mount command and the MountList file.

	On occasion, a few problems show up in this theory.  First of all,
a device like a hard disk may store its physical layout, necessary to
create a DOS node, on the disk itself.  If the disk is damaged, this 
special information may not be available any longer, and as a result, the
hard disk's device driver won't be able to create a DOS node.  In this
case, the user will have to create a MountList entry by hand for the 
device.  This device will then be Mount-ed, and DiskSalv can take over
from there.

	The other problem I've found is that allowing AmigaDOS to access
a bad volume can occasionally result in a system crash.  With a mounted
volume, that's no big problem; AmigaDOS won't usually try to access the
device, or even load the device driver, until that drive is actually
accessed.  It's OK, and in fact required by DiskSalv, to just "Mount"
the device.  In some cases, the File System (especially FastFileSystem)
will try to access a disk as its being initialized.  This can cause a
problem if the disk is damaged in such a way as to violate important
assumptions the File System makes about the disk.  The NODOS options will
circumvent this by eliminating any File System level access of the device
by DiskSalv.  Floppies can be a bit more dangerous.  A floppy will start 
up the File System's validator nearly as fast as it's inserted.  The
proper damage could crash or lockup the machine, but there's no way to
prevent the floppy's File System, or the DiskChange interrupt from the
trackdisk.device, from being sent until DiskSalv has been started.  Once
DiskSalv reaches the "Should I Continue [Y]" prompt, such damaged 
floppies can be safely inserted.  It's important here not to use the
NODOS option.


	DiskSalv produces a variety of error messages when it thinks 
something is wrong.  These fall into two basic classes.  First of these
are fatal errors that may result from the program being run incorrectly 
in some way.  This results in the program terminating with a message of 
some kind.  The second class are warning messages that result due to some 
condition DiskSalv reacting to, but don't actually stop the program from 

3.1 Fatal Errors

"Illegal Command Line Option"

	You typed an invalid option at the cli.  DiskSalv options are case
independent, but must match exactly letter for letter.

"DiskSalv User Abort"

	You terminated DiskSalv with a ^C or other user-invoked abort.

"Must have input and output objects"

	You didn't specify both a "TO" and a "FROM" device on the command
line.  There are no default input or output devices.

"Input DEVICE Not Mounted"
	The input device specified does not appear in the system device
list.  It's possible that you just forgot to mount the device.

"START/STOP flag conflict"

	This is usually the result of specifying a START block greater than
your STOP block.  DiskSalv won't scan a disk backwards.  It's also possible
that you specified an out-of-range block.

"Out of Memory"

	If DiskSalv can't get the memory it needs, this error message will
result.  This will only happen if it can't get memory that's absolutely
necessary.  On systems with lesser memory, some features may no be invoked
if the memory in the system gets too low, but this will not result in an
error message.

"DiskSalv cannot format output device"

	You have requested the FORMAT option for an output device that
DiskSalv doesn't know about, format-wise.  DiskSalv only knows how to
format standard devices, like "trackdisk.device", "ramdrive.device",
"hddisk.device", etc.

"Input and output object collision"

	You've specified the same device for both input and output; that's
not permitted.

"Cannot get 'intuition.library'"

	For some reason, the inutition.library cannot be opened by DiskSalv.

"Cannot get 'dos.library'"

	For some reason, the dos.library can't be opened by DiskSalv.

"Cannot create message port"

	DiskSalv can't create the message port it needs for using the
input device driver directly.

"Cannot find the disk validator"

	You have requested the FORMAT option for an output device, but
DiskSalv can't find the disk validator necessary to validate that device
after formatting it.  The disk validator is found in the "L:" directory.
This mistake is most commonly made when recovering your normal system

"Cannot find the disk formatter"

	You have requested the FORMAT foption for an output device, but
DiskSalv can't find the disk format command necessary to format that device.
The format command may be located in the current directory or on SYS:System.
This mistake is most commonly made when recovering your normal system

"Cannot create I/O port"

	DiskSalv can't create the I/O port it needs for using the input 
device driver directly.

"Cannot set up break trap routine"

	You'll probably never see this one, but it could be an early
indication of severe low memory conditions.

"Invalid AmigaDOS file pattern specified"

	You've specified the FILE option, but supplied an invalid pattern

3.2 Run-Time Warnings

"No formatting, cannot find disk validator"

	The disk validator isn't around, but since you may not need it,
we go ahead.  If this warning is printed, you lose the option to format
output disks during a recovery.

"No formatting, cannot find disk formatter"

	The disk format command isn't around, but since you may not need
it, we go ahead.  If this warning is printed, you lose the option to
format output disks during a recovery.

"Resolving link conflict # <-> #"
	This warning results from a condition on there input disk where, for
a data block on that disk, the block's file header link and block chain link
don't match.  DiskSalv tries to resolve this conflict by choosing the best
of the two, but it is possible that neither is the proper choice.  This will
only happen with Standard FileSystem; there is no data block chain link in
the Fast FileSystem.

"Bad Extension Block - No More Link Check"

	Under Standard file system, an Extension block can't be found.  We
can still proceed.  Under Fast FileSystem, this could never happen.

"Possible Disk Fault, File may be incomplete"

	This is printed for each file that was recovered from a partially
bad trackdisk sector.

"Disk Fault, File may be incomplete"

	Means pretty much the same thing as the last one, only that this
time we're certain that a block be sure about that.

"Double Disk Fault, File truncated"

	There have been serious errors in the current file, to the extent
that the file may not be recoverable.




	The next release of DiskSalv is already in development, so don't
consider this a dead end.  I am actively seeking any and all feedback on
the subject.  Please, if there's something that doesn't work right, or
something DiskSalv isn't doing that you'd like to see it do in the future,
please let me know.  I can't put it in there if I don't think of it.


	This program may be distributed free of charge, provided that no
extra restrictions are placed on it.  Nominal charges for copying or
on-line services are permitted provided that they are only for those
services.  This program was written to help out the Amiga community, not 
to make folks feel guilty.  Thus, no payment is required for its use.  

	I certainly don't mind donations, including donations of bug
reports, comments, suggestions for future enhancements, macadamia nuts,
WILL REGRET IT.  I wouldn't have thought it necessary to mention this,
given the quality of the people working with the Amiga (intelligent folks
recognize superiority).  But I received several such disks from users of
previous DiskSalv releases.  They all came from out of the country, and 
served me just fine as blank disks.  But it really annoys me to see this.
Anyway, at least until the end of June I can be reached at:

                Dave Haynie
		645 Allen Avenue
		Gibbstown, NJ 08027

		BIX:	hazy
		USENET:	...!cbmvax!daveh

My electronic addresses changing.  If you really want to send money, I'm not
going to refuse it or anything, but you may instead consider sending a 
donation instead to:

		1436 U Street NW
		Washington, DC 20009

Tell me about it, and I'll include you in my registration files.  I know 
you don't get rich from "ShareWare"; while I got some donations for 
DiskSalv going all the way back to the beginning (which I'm certainly very
grateful for), they didn't pay enough for me to try treating DiskSalv as
a money-making venture, rather than just a hobby.  I wrote DiskSalv V1.42
because it's needed, because I like to write programs in my spare time,
and for my ego -- if I didn't write DiskSalv V1.42, someone else out
there is going to write a better disk recovery program, and then mine
won't be the best any more.  Don't know if DiskSalv V1.42 necessarily is
the best these days, but I know it's the best DiskSalv so far.  Anyway,
while DiskSalv's saving your disks, maybe the folks at GreenPeace will
get a little extra money to save a few more important things, like clean
air, clean water, and wildlife.  


	My thanks go out to the Amiga community in general, for all the
good stuff they're doing.  Special thanks to:

	- Well, I switched back to Lattice on this one.  Nice going,
	  Mr. Toebes.  
	- Bill Hawes, as always, for AREXX and WShell.
	- The Arthur Guinness Company.
	- The gang at PLINK for continued help.
	- Joseph Armstrong, for restoring my faith in humanity by sending
	  me the first disk I've received from outside the USA in response
	  to DiskSalv that wasn't full of pirated stuff.  Ripper! 
	- Folks who've found the latest round of bugs, the number of which 
	  actually seems to be shrinking; or supplied enhancement ideas
	  (thus opening up room for new bugs...) including:
		  Greg Berlin, Bruce Dawson, Joanne Dow, Marco Papa, 
	          D.C. Murphy, Steve Rosenthal
				-Dave Haynie
				 October 2, 1989