Cheap Manual for DiskSalv V2.10 Test Release (r11.16) January 7, 1993 Copyright 1992, 1993 by Dave Haynie All Rights Reserved PRE-RELEASE VERSION: NOT FREELY REDISTRIBUTABLE DiskSalv The Original Amiga Disk Salvage Program Recovering your data for over seven years IMPORTANT!!! IMPORTANT!!! IMPORTANT!!! PLEASE DELETE ALL OLDER VERSIONS OF DISKSALV V2.10 THEY ARE NOT CONSIDERED RELIABLE DiskSalv V2.10 (r11.16) Cheap User's Manual COPYRIGHT This manual is copyright 1992, 1993 by Dave Haynie. All Rights Reserved. This document may not, in whole or part, be copied, photocopied, reproduced, translated, or transferred by electronic means without prior consent from Dave Haynie. DISCLAIMER The information and the DiskSalv program are provided "as is" without warranty of any kind, either expressed or implied. The entire risk as to the accuracy of the information herein is assumed by you. Dave Haynie does not warrant, guarantee, or make any representations regarding the use of, or the results of the use of, the information or the DiskSalv program in terms of correctness, accuracy, reliability, currentness, or otherwise. In no event will Dave Haynie be liable for direct, indirect, incidental, or consequential damages resulting from any defect in the information or the DiskSalv program even if he has been advised of the possibility of such damages. CREDITS The DiskSalv program, its code, this manual, the DiskSalv icon, and anything else distributed with this package are the original work of Dave Haynie. Thanks go out to the Commodore-Amiga Software Engineering group for suggestions on the DiskSalv GUI and other Amiga software standards. Other suggestions too numerous to call out individually have certainly gone into these works, the author appreciates them all. -Dave Haynie DiskSalv V2.10 (r11.16) Cheap User's Manual INTRODUCTION DiskSalv V2.10 is a disk recovery program for all Amiga file system devices that use any of the 2.04/2.1 FileSystems. DiskSalv will scan (analyze) a bad disk volume for anything that can be recovered, and will restore these items to any AmigaDOS volume. It can also attempt to fix a bad volume in place under most circumstances. DiskSalv is a complete redesign of the orignal DiskSalv program, with a new AmigaDOS-2.0-compliant command-line interface, new Intuition interface, and tons of new features. This is designed to be a fairly complete, quickly written and minimally edited manual of DiskSalv V2.10's features. The built-in help system works as an adjunct to this, and it works simply -- press the HELP key with the mouse positioned over something, and a short description of that something will pop up in a requester. Better documentation is planned, but it won't be free. I'm currently working on a professional quality manual with pictures, better "how to", "why bother", and "theory of it all" sections. Of course, the operative phrase here is "currently working". It ain't done yet. I hope to complete it by the time I do a general shareware release. Since it will be several megabytes of PostScript output by the time its done, and I really have no philosphical objection to making a little beer money here and there, this will be offered up as a printed manual for a modest fee above the normal shareware price. This is all explained in the "Licensing and Distribution" section. Additionally, the core of that manual will become an AmigaGuide manual, and that will come with the printed version. I just figured I would mention this all here before confusing you with the quick and dirty version to follow. 1. STARTING UP DiskSav V2.10 (from here on referred to as "DiskSalv") is a program designed to "salvage" damaged hard disks. There are two basic classes of salvage operation, "Recover-by-Copy" and "Fix-in-Place". In the former case, DiskSalv analyzes a disk and attempts to restore any files and directories from a damaged AmigaDOS file system device to a good one. In the latter case, DiskSalv attempts to find faulty disk objects and remove them from the disk's directory/file hierarchy so that the disk's FileSystem will validate it. 1.1 CLI-BASED DISKSALV V2.10 In the simplest case, DiskSalv can be used very much like DiskSalv V1.42, the AmigaDOS "DiskCopy" program, or any number of other CLI-based programs. The user simply types a command at the command line, and the program goes to work. For example, to recover files from a bad disk in DH0: and restore them on a good disk DH1:, the user will type: 1> DiskSalv FROM DH0: TO DH1: Here the "FROM" and "TO" required CLI keywords. There are quite a few more keywords, which control a good portion of DiskSalv's operation. DiskSalv V2.10 (r11.16) Cheap User's Manual However, to access every feature, it's necessary to use the program interactively under Intuition. The AmigaDOS template is displayed as follows: DiskSalv V2.10 (*TEST RELEASE*) Copyright (c) 1991-1993 by Dave Haynie FROM/K,TO/K,FUNCTION/K,FILESYSTEM/K,DEFAULTFS/K,TAGCHAR/K,PUBSCREEN/K, MEMCHUNK/N,PATHMAX/N,DISKCACHE/N,LOWMEM/S,NOSIZECHECK/S,QUICKSCAN/S, NOWARNING/S,NODATES/S,NONOTES/S,NOPROTECT/S,KEEPDOS/S,KILLDOS/S, NODEEPSCAN/S,INTERACTIVE/S,REJECTION/N The meaning of these keywords is given below. Note that any keyword can also be used as an ICON variable (tooltype). FROM The "FROM" keyword specifies an input device, the device that will be operated on. This must be a DOS device, not a subdirectory or assignment, and it must be based on one of the standard FileSystems with underlying device driver. TO The "TO" keyword specifies an output device, the device that will receive any recover-by-copy files that DiskSalv finds. This may be any AmigaDOS device, volume, or subdirectory. If a non-existant subdirectory is specified, one will be generated. FUNCTION There are several kinds of functions that DiskSalv will run. The default is "Salvage", which causes DiskSalv to work just like the original DiskSalv. Other functions cause other actions: SALVAGE This is the basic Recover-by-Copy function. DiskSalv attempts to restore every file it finds from the input device to the output device. UNDELETE This is another Recover-by-Copy function. It is used on undamaged partitions to restore deleted files. VALIDATE This is the simplest Fix-In-Place function. It can repair an device that hasn't been severely damaged. On most devices, the scan used in this mode is much faster than other scans, but it can slow down on very large volumes. As with all Fix-In-Place functions, any file that must be eliminated from disk will be displayed in a file list once the fix operation has completed. REPAIR This is a more advanced Fix-In-Place function. It does a traditional DiskSalv scan, and it can find more files than the VALIDATE function can. It can also live with partitions that are more damaged than those VALIDATE will handle. DiskSalv V2.10 (r11.16) Cheap User's Manual UNFORMAT This function runs a Fix-In-Place operation on a disk that has been accidently formatted (hopefully non-destructively). It's similar to REPAIR, but it assumes that the disk root is invalid. FILESYSTEM This allows the user to specify the FileSystem to use on the input device. Normally, DiskSalv will determine a partition's FileSystem from its root block. If for some reason that information is unavailable or wrong, this allows the FileSystem type to be specified by force. OFS Original AmigaDOS FileSystem. FFS 1.3-compatible Fast FileSystem. OFS Intl. International character set aware version of OFS. FFS Intl. International character set aware version of FFS. DC-OFS Directory caching version of OFS. DC-FFS Directory caching version of FFS. Best-Guess DiskSalv will pick one of the FileSystems it knows about, based on an analysis of the disk done during the Scan. This is the standard default FileSystem (eg, default if no alternate default is selected). DEFAULTFS This allows the user to specify the fallback FileSystem to use on the input device. Normally, DiskSalv will determine a partition's FileSystem from its root block, but if that root block is damaged, DiskSalv needs this fallback. TAGCHAR This allows the user to specify which character to use for tagging selected files on the Output screen file browser. PUBSCREEN This specifies the public screen for DiskSalv to start up on. If none is specified, DiskSalv will start up on the Workbench screen (eg, default public screen). DiskSalv V2.10 (r11.16) Cheap User's Manual MEMCHUNK This specifies the memory chunk size for DiskSalv's chunky allocator to use. By default, this is 4K, and can be set between 1K and 128K. PATHMAX This specifies the maximum length of a file path. The default value is 512 bytes, and can be set between 256 bytes and 4K. DISKCACHE This specifies the number of blocks to be used for the disk cache (which is actually a pre-fetch buffer). The default size is 8 blocks, and can be set between 0 (no cache) and 255 blocks. LOWMEM This specifies low-memory mode. If DiskSalv runs out of memory on a system in normal mode, it may be successful in low-memory mode. This automatically causes the chunky allocator, file path buffer, and disk cache to go to minimum sizes. It cuts out a number of other internal things that generally just affect performance rather than success. NOSIZECHECK This inhibits automatic size checking of the output volume. Normally, DiskSalv watches the size of the output volume to have an idea ahead of time that a volume will fill up. Some devices, such as RAM:, are dynamically sized and always indicate full when asked, so this parameter is mainly intended for such devices (DiskSalv actually invokes this automatically for RAM:, but it would have to be specified manually for other such devices). QUICKSCAN This specifies a faster disk scanning mode. The speed of a disk scan is improved by cutting down on the visual display. DiskSalv will still show a "gas-guage" indicator, but it won't list objects as they are encountered. NOWARNING DiskSalv will normally attach a warning or error message, as a FileNote, to any file it restores via a Recover-by-Copy operation that it considers suspect or bad. This option will inhibit such action. NODATES This option will inhibit restoration of the original file date in Recover-by-Copy operations. NONOTES This option will inhibit restoration of the original FileNote in Recover-by-Copy operations (though warning notes will override original notes). NOPROTECT This option will inhibit restoration of the original protection codes in Recover-by-Copy operations. DiskSalv V2.10 (r11.16) Cheap User's Manual KEEPDOS The FileSystem (eg, AmigaDOS) is usually locked out from the input device during scan and recovery operations. This option will prevent such a lockout. Fix-In-Place operations are not affected by this, as they absolutely require a FileSystem lockout since they are modifying the input disk. Note that allowing any writes to the input disk during a DiskSalv operation will almost certainly cause DiskSalv to malfunction. KILLDOS This option forces DiskSalv to do its job without using any device directed DOS functions or FileSystem packets. Normally, DiskSalv This is designed to make DiskSalv safe for use on disks that crash AmigaDOS or the particular FileSystem in use. This is a somewhat dangerous option, since it doesn't lock the FileSystem out of a device (since that requires a FileSystem packet). It works best on devices that can't be given to AmigaDOS because they're too damaged. NODEEPSCAN This inhibits extra low-level processing from being done floppy disks. Such processing can recover data not normally accessable through the trackdisk.device, but it causes extra memory to be used. INTERACTIVE This forces DiskSalv into interactive operation (eg, it waits for user input). When run from the CLI, DiskSalv will by default do as much as it can non-interactively before going into interactive mode. REJECTION This specifies a filter strength, between 1 and 10, that influences DiskSalv's assessment of whether or not a disk block matches a specific block type. This is generally left at the default, 6. 1.2 WORKBENCH-BASED DISKSALV V2.10 DiskSalv can be run from the Workbench by double-clicking on its Icon. Normally, this brings up DiskSalv interactively, where options are set via standard 2.0-level Intuition interface objects. However, any of the command-line parameters may be set as Icon ToolTypes to set DiskSalv up for other-than-standard default conditions and other special things. 1.3 THE DISKSALV GUI No matter how you enter DiskSalv, you're going to wind up seeing some aspect of the program's GUI. If you run interactively either from the CLI or from Workbench, you will start out in the "Input Window". Here is where various parameters are set that control how the program will "scan", or learn about, a given input disk. Once all input information is set up, the program moves to the "Scan Window", which basically monitors disk scan and Fix-In-Place operation, where applicable. If it's appropriate (files are found in a Recover-by-Copy DiskSalv V2.10 (r11.16) Cheap User's Manual mode or damaged files are found during a Fix-In-Place operation), the Scan Window will give way to the "Output Window". This windows accepts input to select the objects that will be restored and the device to restore them to. 2.0 THE INPUT WINDOW The Input Window is where a device is selected. There are a series of gadgets and menu items that can control the way things work here. The gadgets are as follows: Device For Scan This list gadget displays a list of recoverable devices. One of these must be selected to run a scan. These are all listed by physical AmigaDOS name, never by volume or assigned name. FileSystem: This gadget is a cycle gadget that allows any of the six aforementioned FileSystems to be selected. When you select a device, this gadget will be set to DiskSalv's best guess at that device's FileSystem, or the default if DiskSalv can't make a good guess. Therefore, the user is able to pick a different one if DiskSalv didn't make a good choice. See section 1.1, "FILESYSTEM", for a list of these. Function: This cycle gadget lets the user select an appropriate recovery operation. Interlocks are managed here to make certain that the specified operation and specified device will work together. See section 1.1, "FUNCTION", for a list of the FileSystem names. Set Filter... This gadget brings up the "Disk Scan Filter Options" window. This window allows various options to be set to control partial scans of a disk, exclusions by AmigaDOS pattern name or protection bits, etc. See section 2.1 for a full explanation of this window. Device Info... This gadget brings up a "Physical Device Information" requester which gives partitioning and other low-level information on the selected device. Scan This gadget starts the disk analysis phase of the DiskSalv program. Once the other phases are complete, the user may return to the Input Window without having to restart DiskSalv. There are two menus on the Input Window. One of these can call up a variety of miscellaneous functions, the other controls toggling of a few control options, and the ability to save these back to the DiskSalv icon. The mens are as follows: DiskSalv V2.10 (r11.16) Cheap User's Manual Project/About... This item brings up a requester with information on the version of DiskSalv, its distribution license, some Shareware data, and where to write me about DiskSalv. Project/Help... This item brings up a requester with a brief explanation of the Input Window. Project/Log File... This item brings up a file requester for the specification of a log file. This file must be on a device other than the input device. When a log file is specified, DiskSalv will write a record of its activity during all phases out to that file. Project/Restore... This item brings up the "Stream Restoration Options" requester, which allows the user to specify input and output paths for restoration of a DiskSalv archive file. Please see section 3 for information on creating DiskSalv archive files. Project/Custom... This item brings up the "Custom Window". The Custom Window is an advanced option that can be used to search a disk for logical partitions or specify partitions based on the low-level components. Project/Save Device... This item saves the currently selected "Device for Scan" as a description file for the AmigaDOS Mount command. Project/Load Device... This item loads a specified AmigaDOS device description file as a DiskSalv "virtual" device. The name of the device will be the name of the description file. Project/Quit This item closes the DiskSalv program. Its function is identical to that of the Close gadget on the DiskSalv main window. Settings/DOS Lock The FileSystem (eg, AmigaDOS) is usually locked out from the input device during scan and recovery operations. This option toggles prevention of such a lockout. Fix-In-Place operations are not affected by this, as they absolutely require a FileSystem lockout since they are modifying the input disk. Note that allowing any writes to the input disk during a DiskSalv operation will almost certainly cause DiskSalv to malfunction. DiskSalv V2.10 (r11.16) Cheap User's Manual Settings/Low Memory This option toggles low-memory mode. If DiskSalv runs out of memory on a system in normal mode, it may be successful in low-memory mode. This automatically causes the chunky allocator, file path buffer, nd disk cache to go to minimum sizes. It cuts out a number of other internal things that generally just affect performance rather than success. Settings/Deep Scan This toggles extra low-level processing from being done floppy disks. Such processing can recover data not normally accessable through the trackdisk.device, but it causes extra memory to be used. Settings/Save Settings This options saves various Input screen variables to the DiskSalv tools icon. 2.1 THE DISK SCAN FILTER OPTIONS WINDOW The "Disk Scan Filter Options" window allows several modifiers to be set that affect the scan phase of a Recover-by-Copy operations. These modifiers are ignored by Fix-In-Place operations, which must examine a disk in its entirety to perform correctly. The window has standard "Ok" and "Cancel" gadgets, which use and ignore the effect of the current filter options settings, respectively. The other gadgets are as follows: File Pattern The string gadget takes in an AmigaDOS file pattern. During the scan of a disk, any file matching this pattern is recorded, while any file not matching is ignored. This acts on links as well as files, but not on directories, since at the time a directory is scanned, there's no way to tell if it will be needed by a child object that's further into the disk. Disk Scan Range This gadget is composed of two pointers, which can be moved to modify the part of the input disk that is actually scanned. The start and finishing blocks on that disk are indicated next to the gadget. The gadget is hard-wired to make certain that the start of the disk is below the finish. Protection Bits This is a group of gadgets which control matching of each file encountered against the seven defined protection bits. A "Don't Care" setting matches any level, a "Match Set" setting matches a bit that's logically set, and a "Match Clear" setting matches a bit that's logically clear. DiskSalv V2.10 (r11.16) Cheap User's Manual 2.2 THE CUSTOM WINDOW The Custom Window is a fork off the main DiskSalv Input Window that is used for dealing with special device cases. An unknown disk, a disk with lost partitioning information, or other such problems can be solved here. An input device is entered via exec-level device name and unit number. The user can specify the partitioning information or ask DiskSalv to go looking for partitions. In a search, the partition's logical name can be specified as a search target, or DiskSalv can be instructed to find all partitions on the disk. There are fifteen gadgets here: Create The Create gadget builds one "virtual device" based on the information supplied here. This requires the basic partitioning information, exec device name and unit, and a DOS Name which is used in the "Device For Scan" list gadget. Any such virtual device is listed in parentheses, and only the "Salvage" operation can be used on them. Search This function starts a search on the given disk for one volume that matches the given pattern. Analyze This function starts a scan of the defined range of the disk for any partitions. The given DOS name is used as the root for the series of virtual partitions created here. If a volume is found, its volume name will be used instead of a DOS name + number handle in the "Device For Scan" list. Cancel Leave this window without performing any kind of scan. Device Name: This is the Exec device used to manage the disk, such as "scsi.device". Pattern: This is a pattern to apply to a search for a specific volume, or as a volume-name filter for full analysis. DOS Name: A name used for the AmigaDOS device equivalent name for "Created" volumes and any encountered partitions without extractable volume names. Unit: The unit number for the Exec device names in "Device Name". DiskSalv V2.10 (r11.16) Cheap User's Manual Bytes/Block: This is the basic block size for the device. While most things in the system are set up for 512 byte blocks, larger disks may use larger block sizes. These have to be in powers-of-two, 512 bytes or larger. Low Block: This is the starting position on the input device to be searched. Since we're not searching a logical partition but in fact a physical disk, this number is a direct disk block number (this specifies the physical block to map to logical block 0 for the Create operation). High Block: This is the last physical block to scan for all operations. Reserved: This is the number of blocks reserved at the start of the partition. Flags: These are device-driver specific flags. Blocks/Track: This is the number of blocks assigned per disk track. Memory Type: This cycle gadget allows the user to specify by name the type of memory to use for disk buffers. Types include DEFAULT, CHIP, FAST, and DMA-24. There are only two menu items on the single menu attached to the Custom Window. The first is the "Project/Help..." item, which pops up a requester box describing the Custom Window. The other item is "Project/Quit", which will terminate the DiskSalv program. 3. THE SCAN WINDOW The Scan Window is entered once the user selected the Scan gadget of the Input Window. In normal operation, the Scan window will have two gadgets, two menu items, and four informational displays. The "Stop" gadget will cause the scan to stop where it is. This is only available for Recover-by-Copy operations, since Fix-In-Place operations need to scan the entire disk. The other gadget is the "Pause" gadget, which will freeze the scan where it is until told to go on. The two menu items are "Project/Help..." and "Project/Quit". The former will display some information about the Scan Window, while the latter will cause the DiskSalv program to quit, just like the Close gadget will. During Fix-In-Place operations, the Quit function will take some time if invoked during some of the latter fixing phases, since DiskSalv doesn't want to leave the disk in a questionable state. DiskSalv V2.10 (r11.16) Cheap User's Manual The "Current Operation" display indicates what DiskSalv is actually doing at any given time during the scan. To the right of this is the "Device Scan" box, which keeps track of scanning statistics, like the current block and number of Files or Errors encountered. Below this is the "fuel guage", which is always used to indicate the progress of the current phase. Below that is the "Scanning Results" display, which indicates the type and name of each object found, as well as other statistics (this is basically what gets written out to the log file, if there is a log file). On a large display, this is eleven lines long, on a small display its five lines long. The QUICKSCAN option eliminates this part of the display altogether. 4. THE OUTPUT WINDOW All Recover-by-Copy operations and any Fix-In-Place operations with corrupt files end the scanning process and open the Output Window. This is where objects and the output device are selected for the actual Restore (eg, Recover-by-Copy) operation. This window's GUI consists of twelve gadgets and ten menu items. The gadgets are as follows: Salvage File List (etc) The scrolling file list, labelled somewhat differently for each function, is where files are selected for restoration to a new volume. Clicking on a file or link alternately tags or clears that object, and makes it the "current" object (displayed in the text gadget below the list gadget). Clicking on a directory once makes it the current object, but does not tag it. Clicking again on that same directory causes this "browser" to "move" to that directory. Output Path This specifies two gadgets, a disk icon gadget and a string gadget. Clicking on the disk icon brings up a file requester, while clicking on the string requester lets the user enter a path by hand. This path is the place to put any recovered files. It can be a device, directory, or possibly a "stream", depending on the setting of the "Archive Stream" option. If a non-existant directory is specified, it is created. Salvage This gadget begins the file restoration. It won't be selectable until at least something is tagged in the Salvage List and proper output device parameters have been entered. File List Action The remaining gadgets are part of the File List Action group. These control tags on objects, browser navigation, and other aspects of the file list. Note that only tagged files are operated on by "Forget" or "Salvage". Parent This gadget brings the file browser up by one directory level. DiskSalv V2.10 (r11.16) Cheap User's Manual Root This gadget brings the file brower up to the top directory level. Forget This gadget removes any tagged objects from the browser list. It has no effect on the object as it exists on-disk. Info... Statistics on the "current" object are displayed in a requester when this is selected. Select Tree This will recursively tag every object in the hierarchy of the current object, if that object is a directory. Select All This will recursively tag every object at the currently displayed directory and all the way down the hierarchy. Select Files This will tag every file at the currently displayed directory level. Clear All This will recursively untag every object in the currently displayed directory and all the way down the hierarchy. Most of the menu items are designed to support the settings of different Restore-time parameters. The menu items are: Project/Help... This option pops up with a brief description of the Output window. Project/New Device... This option resets DiskSalv and starts over back at the Input Window. Project/Quit This option, like the close gadget, causes DiskSalv to cleanly exit. Settings/Size Check This toggles automatic size checking of the output volume. Normally, DiskSalv watches the size of the output volume to have an idea ahead of time that a volume will fill up. Some devices, such as RAM:, are dynamically sized and always indicate full when asked, so this parameter is mainly intended for such devices (DiskSalv actually invokes this automatically for RAM:, but it would have to be specified manually for other such devices). DiskSalv V2.10 (r11.16) Cheap User's Manual Settings/Warning Notes This toggles whether or not DiskSalv will attach a warning or error message, as a FileNote, to any file it restores via a Recover-by-Copy operation that it considers suspect or bad. Settings/Notes Restored This toggles restoration the original FileNote to any restored object. Warning notes will override original notes). This option will inhibit such an action. Settings/Protection Restored This toggles restoration of the original protection codes on any object. This option will inhibit such an action. Settings/Date Restored This toggles restoration of the original AmigaDOS date to all output objects. Settings/Archive Stream This determines which I/O formation is used for the output device. By default, the OUTPUT device is a directory, and DiskSalv regenerates the specified directory tree as found on the input disk. When Archive Stream mode is set, DiskSalv writes out everything in a structured output stream. This stream is turned back to a directory tree by using the Project/Restore option on the Input Window. Since this formatted stream makes all disk objects appear as a single file, it can be piped though compression tools and processed through other interesting programs as desirable. Settings/Save Settings When selected, this saves the state of the toggle options other than "Archive Stream" out to the DiskSalv.info file. 5. THE RECOVERY WINDOW The Recovery Window looks exactly like the Scan window, mainly because it is the Scan Window just doing something else. This window displays each file as it's restored to the output device. Along the way, if the output device fails or gets full, DiskSalv will prompt the user to skip the file, change the media, or change devices. When a device change is requested, the Output window is called up again to secure a new device input the normal way. At that point, only files left yet-to-be restored will be out on disk. 6. LICENSING AND DISTRIBUTION This program is currently in testing, and may not be passed around. If you have it, you're either part of the testing process or you're not supposed to have it yet. As mentioned, this is copyrighted software. DiskSalv V2.10 (r11.16) Cheap User's Manual If you are a proper test person, please do test it as you get a chance, and please make sure to delete all older versions of DiskSalv V2.10 ASAP. It's dangerous to have those older versions around, they don't know about the current Directory Cache format and have numerous potentially fatal bugs that have been corrected here.