home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 166.lha / DiskSalv.README < prev    next >
Text File  |  1988-04-28  |  22KB  |  522 lines

  1.  
  2.  
  3.                         D i s k S a l v 
  4.  
  5.                  AmigaDOS Disk Salvage Program
  6.  
  7.                  Copyright 1988 by Dave Haynie
  8.  
  9.                   Version 1.3 for AmigaOS 1.3
  10.                
  11.  
  12. INTRODUCTION
  13.  
  14.     DiskSalv V1.3 is a disk recovery program for all Amiga file
  15. system devices that use either the AmigaOS V1.2/V1.3 Standard File
  16. System or the AmigaOS V1.3 Fast File System.  DiskSalv will scan a bad
  17. disk volume for anything that can be recovered, and will restore these
  18. items to any AmigaDOS volume.  It does not make any attempt to fix the
  19. bad device in place; thus, any file that can't be restored with DiskSalv
  20. might possibly be restored with an alternate method.
  21.  
  22.     DiskSalv V1.3 fixes some bugs in the release version of 
  23. DiskSalv V1.2.  The worst bug in DiskSalv V1.2 was that it would report
  24. that output devices were full when they weren't.  The NOCHECK option
  25. didn't work, so this checking couldn't be overridden.  DiskSalv V1.2
  26. would also sometime tag an output device as an output volume, an error
  27. in that DiskSalv has better options available for output devices than
  28. output volumes.  
  29.  
  30.     DiskSalv V1.3 also contains some improvements.  The handling
  31. of output device overflows in V1.3 is much more robust than in any
  32. previous versions.  DiskSalv will optionally format output disks for
  33. you, which really helps when recovering hard disks to floppies, for
  34. example.  The DiskSalv command-line processing now also works better.
  35.  
  36.  
  37. 1. THE BASICS OF DISKSALV V1.3
  38.  
  39.     DiskSalv V1.3 (from here on referred to as "DiskSalv") is a
  40. program designed to "salvage" any files and directories from a damaged
  41. AmigaDOS file system device to a good one.  DiskSalv is run from an
  42. Amiga CLI, and in the simplest case is used very much like the AmigaDOS
  43. "DiskCopy" program.  For example, to recover files from a bad disk in
  44. DF0: and restore them on a good disk DF1:, the user will type:
  45.  
  46.     1> DiskSalv FROM DF0: TO DF1:
  47.  
  48. Here the "FROM" and "TO" keywords are fully optional if the ordering of
  49. the input and output devices is kept INPUT OUTPUT.  The following line
  50. would also achieve the same result:
  51.  
  52.     1> DiskSalv TO DF1: FROM DF0:
  53.  
  54. In either case, DiskSalv will immediately print to the shell's screen:
  55.  
  56.     DiskSalv V1.3 Copyright © 1988 by Dave Haynie
  57.  
  58.     Salvage FROM Device DF0: TO Path DF1:
  59.  
  60.       DEVICE     =    trackdisk.device   (DF0:)
  61.       UNIT       =        0    FLAGS      =        0
  62.       HEADS      =        2    SECTORS    =       11
  63.       LOCYL      =        0    HICYL      =       79
  64.           LOBLOCK    =        0    HIBLOCK    =     1759
  65.       RESERVED   =        2    MEMTYPE    =        3
  66.       ROOT BLOCK =      880    DISK SIZE  =     1760
  67.  
  68.     Scan Range: START 2, STOP 1759, Expecting Standard FileSystem
  69.  
  70.     Should I continue [Y]
  71.  
  72. At this point, a simple RETURN entered will start up the recovery
  73. process, while an "N" followed by a RETURN will abort the recovery. 
  74.  
  75. 1.1 The Scan Phase
  76.  
  77.     If we proceed with the recovery, DiskSalv will start the first
  78. phase of it's recovery.  At this point, the input device will be scanned
  79. from start to finish (blocks 2 though 1759).  DiskSalv is looking for
  80. valid AmigaDOS file or directory blocks.  A small Intuition window
  81. called "DiskSalv Scan" will open on the Amiga's WorkBench screen.  There
  82. are three columns in this window, BLOCK, NODES, and TYPE.  As each block
  83. is read, it's number is displayed under BLOCK.  This happens pretty
  84. quickly; ordinarily, there's no need to examine individual block numbers
  85. anyway.  The TYPE field indicates whether the block is a file (FILE),
  86. root directory (ROOT), user directory (UDIR), data block (DATA), unused
  87. block (FREE), unknown block type (????), or bad block (ERR!).  Note that
  88. under the new AmigaDOS V1.3 Fast FileSystem, there's no way to
  89. distinguish between DATA and FREE blocks during a scan, so these are
  90. always displayed as unknown blocks.  The final field, NODES, indicates
  91. the number of user directory or file blocks that have been located so
  92. far.  
  93.  
  94.     The other feature of this phase is the file list, which takes
  95. place on the screen.  The shell window will indicate "Building Directory
  96. Map...", and the name of each directory and file that's found will be
  97. displayed under this heading.  Note that at any time during this
  98. scanning phase, a ^C typed to the shell window will abort DiskSalv.
  99.  
  100. 1.2 The Directory Resolution Phase
  101.  
  102.     The next phase is usually a very short one.  The scanning window
  103. will disappear, and the shell window will indicate that DiskSalv is
  104. "Resolving Stray Directories...".  During the scanning phase, when
  105. DiskSalv finds a file block, it attaches it to a directory in it's
  106. directory list.  To make the scan phase fast, however, DiskSalv only
  107. does a single linear pass over the input disk during that phase.  If the
  108. parent directory for a file or subdirectory isn't available, DiskSalv
  109. makes a dummy directory for it in it's directory list.
  110.  
  111.     Normally, all of those dummy directories get changed into normal
  112. ones as they are found in the scan.  However, there are some DiskSalv
  113. modes (covered later) that may result in only a partial scan being
  114. performed.  In this case, valid directory entires may be outside of the
  115. scanning range.  In order to get the proper names of such directories,
  116. the resolution phase goes through the directory entires in it's dummy
  117. list and tries to find real directories to match them.  If a directory
  118. can't be found, it was probably located on a bad block.  That's no
  119. problem, all that's lost is the name of that directory, not any of it's
  120. contents.
  121.  
  122. 1.3 The Directory Pruning Phase
  123.  
  124.     The next pass happens purely in memory, and it attempts to
  125. remove any empty directories from the directory list.  There are rarely
  126. any empty directories that need to be restored, and there are some
  127. DiskSalv options that tend to force a number of empty directories to be
  128. created in the directory list.  This pass can be overridden if empty
  129. directories are deemed important.
  130.  
  131. 1.4 The Disk Salvage Phase
  132.  
  133.     In this next phase, the disk structure is actually restored to
  134. the output device.  This proceeds until stopped via ^C, or until the
  135. output device is full.  If the output device fills up, a new one can be
  136. inserted if the device supports removable media.  The most common form
  137. of this would be floppy disk.
  138.  
  139.     There are certain output devices which may not return proper
  140. volume sizing information through AmigaDOS.  For instance, the RAM:
  141. device always says it's full.  A DiskSalv option allows output size
  142. checking to be turned off, and it's automatically selected if the
  143. output device is RAM:.
  144.  
  145.     DiskSalv uses normal AmigaDOS I/O routines to re-create the
  146. recovered files.  Thus, it may restore to a subdirectory instead of the
  147. root of a device.  If a subdirectory is specified that doesn't exit,
  148. DiskSalv will create it.  Similarly, DiskSalv may output to a logical
  149. volume name instead of a device name.
  150.  
  151.     Finally, there are occasions under which there may be file name
  152. collisions.  If the output device has a file by the same name as one
  153. that's on the input device, such a collision occurs.  DiskSalv won't
  154. overwrite files.  Instead, the colliding file is renamed before it is
  155. rebuilt.  An extension is added to it, starting at "-0" and going on up
  156. to "-100" as collisions continue to occur.
  157.  
  158.  
  159. 2. DISKSALV REFERENCE GUIDE
  160.  
  161.     The DiskSalv program is run and controlled completely via 
  162. command-line arguments.  It should run without problem from all Amiga
  163. shell programs; it currently can't be run from the WorkBench.
  164.  
  165. 2.1 Command-Line Options
  166.  
  167.     There are quite a few options in DiskSalv that'll modify in
  168. various ways the recovery action described above.  The syntax for the
  169. DiskSalv command line is given as:
  170.  
  171.     DiskSalv [FROM] InDev: [TO] OutPath [FFS|NOFFS]
  172.              [ASK] [NOPRUNE] [NOCHECK] [NOTD] [QUICK]
  173.              [FORMAT] [START block|ROOT] [STOP [+]block]
  174.              [MASK [a|A][r|R][w|W][e|E][d|D][p|P][s|S]] 
  175.  
  176.     or
  177.  
  178.     DiskSalv HELP|INFO
  179.  
  180. The first form actually runs the program; the second form gives the user
  181. a little built-in documentation.  In each case, text in brackets ("[]")
  182. indicates an optional parameter, text outside of brackets indicates a
  183. required parameter, and "|" indicates a choice of parameters.  The
  184. options are:
  185.  
  186. ASK
  187.     This options allows the Disk Salvage pass to proceed
  188.     interactively instead of automatically.  The user is prompted
  189.     at each file or directory.  A reply of 'Y' will recover that
  190.     file or move into that directory, a reply of 'N' will skip that
  191.     item.  Replying '?' will list all the valid options.  A reply of
  192.     'A' will recover everything left at the current directory level;
  193.     a reply of 'U' will skip everything left at the current
  194.     directory level.  Finally, a reply of 'Q' will quit the program
  195.     completely. 
  196.  
  197. FFS | NOFFS
  198.     This allows the disk's filesystem to be selected.  Normally,
  199.     DiskSalv can tell the difference between a fast and standard
  200.     filesystem disk, and will act accordingly.  However, if that
  201.     disk is badly damaged, this assumption may be incorrect.  In
  202.     such a case, DiskSalv will usually assume standard filesystem.
  203.     If it's assumption is wrong, the filesystem can be forced with
  204.     these options.
  205.  
  206. FORMAT
  207.     This forces the output device to be formatted before any output
  208.     files are directed to it.  If the output device isn't a device,
  209.     but instead a handler, DiskSalv will return an error message if
  210.     this option is selected; it only knows how to format devices.
  211.     DiskSalv will also offer the option of formatting the output 
  212.     device if it fills up during a recovery.  An important note on
  213.     all DiskSalv formatting options -- the disk validator MUST be
  214.     accessible for the format to work.  If it's not available,
  215.     DiskSalv will refuse to format an output disk.  If you specify
  216.     the FORMAT option on the command line, DiskSalv will return with
  217.     an error message if the validator can't be located.  If you
  218.     don't specify FORMAT and the validator can't be found, a warning
  219.     will be issued.  If you go on from there, everything will work
  220.     OK, but you'll never be offered the FORMAT option.  The best way 
  221.     to insure that it's present is to have the L: directory with the 
  222.     disk validator in it on the same disk that DiskSalv is run from.
  223.     It may be necessary to Assign L: to that disk.
  224.  
  225. FROM InDev: 
  226.     This option allows an input device to be specified.  The input
  227.     device must be a real device, not a path specification.  The
  228.     FROM keyword is optional, but can be used to allow FROM and TO
  229.     specifications to be given in any order.
  230.  
  231. HELP
  232.     The HELP option lists some information about the various options
  233.     available.  It should be specified in the command line without
  234.     any other options.
  235.  
  236. INFO
  237.     The INFO option lists some information about the program, it's
  238.     distribution, bug reporting, and other stuff.  It should be
  239.     specified in the command line without any other options.
  240.  
  241. MASK [a|A][r|R][w|W][e|E][d|D][p|P][s|S]
  242.     This options allows the user to specify a protection bit mask as
  243.     a filter.  The supported bits are "A" for Archive, "R" for Read,
  244.     "W" for Write, "E" for Execute, "D" for Delete, "P for Pure, and
  245.     "S" for Script.  Specifying the bit in lowercase indicates a mask
  246.     for that bit not set, a bit in uppercase indicates a mask for that
  247.     bit set.  For example, specifying "MASK a" will scan for only
  248.     those files that don't have the archive bit set; "MASK WD" will
  249.     scan only for those files with Write and Delete permission
  250.     enabled.  Any bits not specifically MASKed can be in either state.
  251.  
  252. NOCHECK
  253.     This option prevents the output device's size from being
  254.     checked.  Normally this would only be used with a device that
  255.     doesn't properly report it's size, and it's automatically
  256.     invoked with output to RAM:.
  257.  
  258. NOPRUNE
  259.     This option prevents the directory pruning phase from taking
  260.     place.  If the input device contains empty directories that must
  261.     be restored, use this option.
  262.  
  263. NOTD
  264.     DiskSalv does some special optimizations when it's recovering from
  265.     a floppy disk device based on the "trackdisk.device" driver.  While
  266.     there's currently no real use for this option, a future version of
  267.     "trackdisk.device" might possibly not work with these enhancements.
  268.     This option will turn the enhancements off, making a recovery from
  269.     the "trackdisk.device" work exactly like any other recovery.
  270.  
  271. QUICK
  272.     This option performs a quick scan.  The scan speed is improved
  273.     by not displaying the block number and type information for every
  274.     block.  This doesn't make as much difference as it did in the
  275.     earlier versions of DiskSalv; the "DiskSalv Scan" window routine
  276.     has been greatly sped up this display.
  277.  
  278. TO OutPath 
  279.     This option allows an output path to be specified.  The output
  280.     device can be any valid AmigaDOS file device specification.  The 
  281.     TO keyword is optional, but can be used to allow FROM and TO
  282.     specifications to be given in any order.
  283.  
  284. START block | ROOT
  285.     This option allows the scanning routine to start at any place on
  286.     the input device.  This position is either given as a decimal
  287.     block number, or as the string ROOT.  Since many files are
  288.     clustered after the directory root on most disks, it's often
  289.     possible to get many of a disk's files back starting the scan
  290.     there instead of at the start of the disk.  
  291.  
  292. STOP [+] block
  293.     This option allows the scanning routine to stop at any place on
  294.     the input device.  This position is either given as a decimal
  295.     block number, or (via the optional "+") as an offset relative to
  296.     the START of the disk.  Thus, specifying START ROOT STOP +50
  297.     would scan a disk's root and the next 49 blocks.
  298.  
  299. 2.2 Input Device Specification
  300.  
  301.     DiskSalv requires a DOS name specification for its input device.
  302. Such a name is automatically created by the operating system for each
  303. 3.5" disk drive attached, and for some hardware add-ons during automatic
  304. device binding process initiated by the AmigaDOS BindDrivers command.  
  305. Other DOS names are created by the Mount command and the MountList file.
  306.  
  307.     On occasion, a few problems show up in this theory.  First of all,
  308. a device like a hard disk may store its physical layout, necessary to
  309. create a DOS node, on the disk itself.  If the disk is damaged, this 
  310. special information may not be available any longer, and as a result, the
  311. hard disk's device driver won't be able to create a DOS node.  In this
  312. case, the user will have to create a MountList entry by hand for the 
  313. device.  This device will then be Mount-ed, and DiskSalv can take over
  314. from there.
  315.  
  316.     The other problem I've found is that allowing AmigaDOS to access
  317. a bad volume can occasionally result in a system crash.  With a mounted
  318. volume, that's no big problem; AmigaDOS won't try to access the
  319. device, or even load the device driver, until that drive is actually
  320. accessed.  It's OK, and in fact required by DiskSalv, to just "Mount"
  321. the device.  With floppies, this is a bit harder.  The trackdisk.device
  322. looks for a diskchange signal from all 3.5" floppies, whenever a floppy
  323. is changed.  So as soon as you insert a floppy disk, DOS will look at it.
  324. If that disk causes a crash, it'll take effect as soon as the disk is
  325. inserted.  Fortunately, there's a cure for this.  You can run DiskSalv,
  326. giving it the proper device input, without the floppy actually in the
  327. device.  Once DiskSalv starts up (at the "Should I Continue [Y]" prompt),
  328. it inhibits that drive.  The dangerous floppy can then be inserted
  329. without any problems.
  330.  
  331. 3. WARNINGS AND ERRORS
  332.  
  333.     DiskSalv produces a variety of error messages when it thinks 
  334. something is wrong.  These fall into two basic classes.  First of these
  335. are fatal errors that may result from the program being run incorrectly 
  336. in some way.  This results in the program terminating with a message of 
  337. some kind.  The second class are warning messages that result due to some 
  338. condition DiskSalv reacting to, but don't actually stop the program from 
  339. executing.
  340.  
  341. 3.1 Fatal Errors
  342.  
  343. "Illegal Command Line Option"
  344.  
  345.     You typed an invalid option at the cli.  DiskSalv options are case
  346. independent, but must match exactly letter for letter.
  347.  
  348. "DiskSalv User Abort"
  349.  
  350.     You terminated DiskSalv with a ^C or other user-invoked abort.
  351.  
  352. "Must have input and output objects"
  353.  
  354.     You didn't specify both a "TO" and a "FROM" device on the command
  355. line.  There are no default input or output devices.
  356.  
  357. "Input DEVICE Not Mounted"
  358.     
  359.     The input device specified does not appear in the system device
  360. list.  It's possible that you just forgot to mount the device.
  361.  
  362. "START/STOP flag conflict"
  363.  
  364.     This is usually the result of specifying a START block greater than
  365. your STOP block.  DiskSalv won't scan a disk backwards.  It's also possible
  366. that you specified an out-of-range block.
  367.  
  368. "Out of Memory"
  369.  
  370.     If DiskSalv can't get the memory it needs, this error message will
  371. result.  This will only happen if it can't get memory that's absolutely
  372. necessary.  On systems with lesser memory, some features may no be invoked
  373. if the memory in the system gets too low, but this will not result in an
  374. error message.
  375.  
  376. "DiskSalv cannot format output device\n"
  377.  
  378.     You have requested the FORMAT option for an output device that
  379. DiskSalv doesn't know about, format-wise.  DiskSalv only knows how to
  380. format standard devices, like "trackdisk.device", "ramdrive.device",
  381. "hddisk.device", etc.
  382.  
  383. "Input and output object collision"
  384.  
  385.     You've specified the same device for both input and output; that's
  386. not permitted.
  387.  
  388. "Cannot get 'intuition.library'"
  389.  
  390.     For some reason, the inutition.library cannot be opened by DiskSalv.
  391.  
  392. "Cannot get 'dos.library'"
  393.  
  394.     For some reason, the dos.library can't be opened by DiskSalv.
  395.  
  396. "Cannot create message port"
  397.  
  398.     DiskSalv can't create the message port it needs for using the
  399. input device driver directly.
  400.  
  401. "Cannot find the disk validator"
  402.  
  403.     You have requested the FORMAT option for an output device, but
  404. DiskSalv can't find the disk validator necessary to validate that device
  405. after formatting it.  The disk validator is found in the "L:" directory.
  406. This mistake is most commonly made when recovering your normal system
  407. disk.  
  408.  
  409. "Cannot create I/O port"
  410.  
  411.     DiskSalv can't create the I/O port it needs for using the input 
  412. device driver directly.
  413.  
  414. 3.2 Run-Time Warnings
  415.  
  416. "No formatting, cannot find disk validator"
  417.  
  418.     The disk validator isn't around, but since you may not need it,
  419. we go ahead.  If this warning is printed, you lose the option to format
  420. output disks during a recovery.
  421.  
  422. "Resolving link conflict # <-> #"
  423.     
  424.     This warning results from a condition on there input disk where, for
  425. a data block on that disk, the block's file header link and block chain link
  426. don't match.  DiskSalv tries to resolve this conflict by choosing the best
  427. of the two, but it is possible that neither is the proper choice.  This will
  428. only happen with Standard FileSystem; there is no data block chain link in
  429. the Fast FileSystem.
  430.  
  431. "Bad Extension Block - No More Link Check"
  432.  
  433.     Under Standard file system, an Extension block can't be found.  We
  434. can still proceed.  Under Fast FileSystem, this could never happen.
  435.  
  436. "Possible Disk Fault, File may be incomplete"
  437.  
  438.     This is printed for each file that was recovered from a partially
  439. bad trackdisk sector.
  440.  
  441. "Disk Fault, File may be incomplete"
  442.  
  443.     Means pretty much the same thing as the last one, only that this
  444. time we're certain that a block be sure about that.
  445.  
  446. "Double Disk Fault, File truncated"
  447.  
  448.     There have been serious errors in the current file, to the extent
  449. that the file may not be recoverable.
  450.  
  451.  
  452. 4. LISCENCING AND DISTRIBUTION
  453.  
  454.     This program may be distributed free of charge, provided that no
  455. extra restrictions are placed on it.  Nominal charges for copying or
  456. on-line services are permitted provided that they are only for those
  457. services.  This program was written to help out the Amiga community, not 
  458. to make folks feel guilty.  Thus, no payment is required for its use.  
  459.  
  460.     I certainly don't mind donations, including donations of bug
  461. reports, comments, suggestions for future enhancements, macadamia nuts,
  462. or even software.  BUT PLEASE, DON'T SEND ME ANY PIRATED SOFTWARE.  YOU
  463. WILL REGRET IT.  I wouldn't have thought it necessary to mention this,
  464. given the quality of the people working with the Amiga (intelligent folks
  465. recognize superiority).  But I received several such disks from users of
  466. DiskSalv V1.0.  They all came from out of the country, and served me just
  467. fine as blank disks.  But it really annoys me to see this.  Anyway, I can
  468. be reached at:
  469.  
  470.                 Dave Haynie
  471.         645 Allen Avenue
  472.         Gibbstown, NJ 08027
  473.  
  474.         BIX:    hazy
  475.         PLINK:    D-DAVE H
  476.         USENET:    ...!cbmvax!daveh
  477.  
  478. If you really want to send money, consider sending a donation instead to:
  479.  
  480.         GreenPeace
  481.         1436 U Street NW
  482.         Washington, DC 20009
  483.  
  484. Tell me about it, and I'll include you in my registration files.  I know 
  485. you don't get rich from "ShareWare"; while I got some donations from
  486. DiskSalv V1.0 (which I'm certainly very grateful for), they certainly
  487. didn't pay for the writing of DiskSalv V1.3.  I wrote DiskSalv V1.3
  488. because it's needed, because I like to write programs in my spare time,
  489. and for my ego -- if I didn't write DiskSalv V1.3, someone else out
  490. there is going to write a better disk recovery program, and then mine
  491. won't be the best any more.  Don't know if DiskSalv V1.3 necessarily is
  492. the best these days, but I know it's better than DiskSalv V1.0.  Anyway,
  493. while DiskSalv's saving your disks, maybe the folks at GreenPeace will
  494. get a little extra money to save a few more important things, like clean
  495. air, clean water, and wildlife.  
  496.  
  497.  
  498. 5. CREDITS AND THANKS
  499.  
  500.     My thanks go out to the Amiga community in general, for all the
  501. good stuff they're doing.  And for putting up with mistakes, like
  502. DiskSalv V1.2; sorry, folks.  Special thanks to:
  503.  
  504.     - Jim Goodnow II and Manx, for SDB.  Which is why DiskSalv V1.3
  505.       is out now instead of next year.
  506.     - Bill Hawes for AREXX and WSH, which help make the Amiga the best
  507.       programming environment I've ever used.  
  508.     - Commodore, for letting me build that great 32 bit CPU board
  509.       that makes compiles go so fast.
  510.     - The PLINK National Interactive Debugging Environment, another
  511.       thing only Amigaoids can take advantage of.
  512.     - Brian Neissan, for pushing me along a bit on FFS support, even 
  513.       though I didn't use his code.
  514.     - Michael van Elst, for pushing me along a bit on the low level 
  515.       trackdisk stuff, even though I didn't use his code.
  516.     - All the BETA testers.
  517.     - Iggy and Banzo, for keeping my feet warm.
  518.     - The Arthur Guinness Company.
  519.  
  520.                 -Dave Haynie
  521.                  October 4, 1988
  522.