MRBackup Professional Version 1.0 A Hard Disk Backup Utility for the Commodore Amiga Mark R. Rinfret 1 MRBackup Professional Introduction Introduction MRBackup is a hard disk backup program for the Commodore Amiga family of computers. It provides a wide range of services to support Amiga file management and backup/restore of files to/from hard disk. Files can be backed up to Floppy disk, in AmigaDOS format Floppy disk, in a special "fast" format SCSI streaming tape A backup set catalog is created for each backup set, allowing quick retrieval of individual files when necessary. MRBackup is designed to behave well in your Amiga's multi-tasking environment. It does not "take over the machine" and will allow you to use your Amiga for other chores while backups are being performed. MRBackup is driven by a flexible set of user- controlled parameters and offers a wide range of backup and restore options. Its Intuition-based user interface is designed for a pleasing appearance and ease of operation. MRBackup uses the Amiga's speech capabilities to provide an effective means for presenting prompts, error conditions and requests for floppy disk insertions, etc. MRBackup provides file compression which will reduce the number of diskettes required for a backup (though more time will be required to do this). 2 MRBackup Professional Requirements Requirements In order to operate properly, MRBackup Professional requires the following: - any Amiga system with at least 1 MB memory and WorkBench 1.3 or higher - The Amiga Replacement Project (ARP) library (arp.library), V39.1 or higher (supplied with MRBackup). - At least 1 floppy disk drive or SCSI streaming tape drive (Wangtek 50XX or equivalent) MRBackup will work with any hard drive supported by the AmigaDOS operating system. 3 MRBackup Professional Installation Installation MRBackup is delivered with an installation program which will automatically copy all required files to default locations on your hard disk. Specifically, the installation copies the following files: Filename Directory MRBackup SYS:Tools MRBackup.info SYS:Tools MRBackupDefaults.info SYS:Tools MRBackup.init S: MRBackup.bflt S: MRBackup.cflt S: MRBackup.dflt S: MRTape-Handler L: arp.library LIBS: To install MRBackup, simply insert the MRBackup program diskette and double-click on the "Install MRBackup" icon. All files will be copied to their proper destinations. If you don't approve of the default installation locations, simply edit the file "Install MRBackup" on the MRBackup program disk to reflect your preferences. 4 MRBackup Professional Operation Operation This manual assumes that you already know the basic operating principles of your Amiga and that you are familiar with its user interface. If this manual refers to a procedure or feature with which you are not familiar, please refer to your Amiga owner's manual. MRBackup may be started from the WorkBench by double-clicking its program icon or from the CLI by typing the appropriate command line. The startup procedures for each environment are presented below. Working Directory MRBackup requires an area for storing certain information during the backup process. This area is called the "working directory". The default area is defined by the logical name "S:", but you may override this setting. The next two sections describe how this is done. CLI Operation To start MRBackup from the CLI (Command Line Interface, also called the "Shell"), you can just type MRBackup at the command prompt. If you wish to override the default working directory, enter MRBackup -d where is the name of a directory MRBackup can use to store temporary information. WorkBench Operation To start MRBackup from the WorkBench, simply double-click its program or project icon. To override the default working directory, you must change a Tool Type entry in the program or project icons, as appropriate. To do this, select the MRBackup program icon (one click), then select the Info command from the WorkBench menu. Find the following entry in the Tool Types list: DIR=S: Replace "S:" with the device name, directory name or logical name that you would like MRBackup to use for its work area. Click the Save gadget when you are done to record your change. The next 5 MRBackup Professional Operation time you start MRBackup, the new work area will be used. You may also direct MRBackup to start up with an initialization file (preferences) other than the default S:MRBackup.init (or MRBackup.init, if it exists in the same directory as MRBackup). This is done by adding a Tool Type entry of the form: INIT= where is the name of the file containing MRBackup preferences settings. This file is usually created with the Save Preferences command in MRBackup's Project menu. Example: INIT=DH0Backup.prefs If you really want to get clever, you can make copies of MRBackup's project icon file (MRBackupDefault.info) and tune the Tool Types entries for each hard disk partition. How is this done? Using the CLI COPY command, make a copy of MRBackupDefaults.info for each partition. Example: (CD to the directory where MRBackup resides) COPY MRBackupDefaults.info MRBackup-DH0.info COPY MRBackupDefaults.info MRBackup-DH1.info (etc.) For each icon, do the following: Select the icon (one click), then choose Info from the WorkBench menu. Edit the Tool entry so that it specifies the correct name for the MRBackup program file. The default is SYS:Tools/MRBackup. Edit the DIR and INIT Tool Type entries as appropriate for the partition that this icon represents. Support Files MRBackup obtains some of its operating parameters from a set of support files. The primary copy of these files is usually stored in the S: directory, but you may create as many new copies as you wish to customize backup and restore parameters on a project-by- project basis. All of these files contain ASCII text and may be edited with any Amiga text editor. Lines beginning with a semi- colon (; comments) are ignored, as are empty lines. Each of these 6 MRBackup Professional Operation files, as delivered, is self-documenting. Use your favorite text editor or text viewer (e.g. More) to view their contents. Note: you may use other filenames (including different extensions) if you desire. It is highly recommended that you adhere to some consistent naming convention to avoid confusion, however. MRBackup.init This file contains your MRBackup operating parameters. It is read by MRBackup when it first starts up to establish its default parameter settings. MRBackup.bflt This is the backup filter file. It is used to specifically include or exclude certain files from a backup operation. See the section titled Filter Files for a detailed description. MRBackup.cflt This is the compression filter file. It allows you to prevent specific files from being compressed during a backup operation. See the section titled Filter Files for a detailed description. MRBackup.dflt This is the decompression filter file. It allows you to prevent specific files from being decompressed during a restore operation. See the section titled Filter Files for a detailed description. 7 The User Interface MRBackup employs the Amiga's Intuition graphical user interface. This result is straightforward user interaction and concise information presentation. MRBackup has its own user-configurable four-color custom screen with a pleasing 3-D appearance. All parameters for backup and restore operations can be controlled from MRBackup's main window. A pull-down menu provides access to MRBackup's set of operations. The Menu MRBackup operations are invoked by menu selections or keyboard shortcuts. MRBackup has one menu, named Project. Its entries are described briefly here. Refer to the section titled MRBackup Operations for a more detailed description. Backup Start a backup operation. Colors Change MRBackup's color settings. Resume Backup Resume a backup which was previously interrupted. Restore Restore files from a backup set. Load Preferences Load MRBackup's operating parameters from a file. The name of the file is specified in the Preferences gadget. Save Preferences Save MRBackup's operating parameters to a file. The name of the file is specified in the Preferences gadget. Utilities Start MRBackup's file management utilities. Quit Terminate MRBackup. MRBackup Main Window 8 MRBackup Professional The User Interface Please refer to Figure 1 for a picture of the MRBackup Main Window. This window contains all of the parameters that control backup and restore operations. All information is managed through Intuition gadgets. As you view this window, you will notice that some have a raised appearance, while others appear to be recessed. The raised gadgets respond to a single mouse click and will either cycle through a set of allowed values or pop up a requester to obtain more information. The recessed gadgets are altered by first clicking the mouse within their rectangle, then typing a value from the keyboard. When altering one of these string gadgets, always complete your change by pressing the RETURN key. Failure to do so might result in MRBackup ignoring your changes. You will also notice several square raised gadgets, labeled with a question mark (?). These are called file requester gadgets. Each of these is associated with another gadget which specifies a device, directory or file name. When you click on a file requester gadget, a file requester window is superimposed on MRBackup's main window (see Figure 2 - The ARP File Requester). With it, you can navigate your file system and easily select the appropriate name for the corresponding gadget. The following paragraphs describe all of the labeled gadgets in MRBackup's main window. Please take the time to read this information carefully, as several important key concepts are presented here. The gadgets are described in top-to-bottom, left- to-right order. Test Date The test date is used by backup operations only. If the test date is set to January 1, 1978 (beginning of AmigaDOS time), it has no effect. Otherwise, only files modified on or after the test date will be selected for backup. To change the test date, just click on the gadget box. A date requester will pop up (see Figure 3- The Date Requester), allowing you to easily change the test date. You may select the new date value either by pointing and clicking on the various date requester gadgets or by typing directly into each of the date fields. For your convenience, MRBackup also supports four (4) date formats (AmigaDOS, U.S., Canadian and International). Home Path 9 MRBackup Professional The User Interface The Home Path describes the device or directory where your files normally reside. During backup operations, files are copied from the location specified by the Home Path. During restore operations, files are copied to this location. You may type the Home Path value directly into the gadget box or you may use the file requester to assist you. The Home Path must specify a device, volume or directory name (not a file name). Backup Path The Backup Path describes the destination (FROM path) for files during a backup or the source (TO path) for files during a restore. Normally, the backup path is the name of one of your floppy disk drives. If one or more of the floppy disk icon gadgets is selected, the Backup Path is ignored. See the section entitled Backup Operations for more details on the Backup Path. Floppy Disk Icons MRBackup supports selection of up to four floppy disk devices (DF0: through DF3:) for backup or restore. This allows you to preload your disk drives, reducing the frequency with which you must insert diskettes. MRBackup will cycle through the selected drives and prompt you for more diskettes only when all have been used or an error is detected. When you click on one of these icons, a check-mark will appear, indicating that the drive is selected. Whenever floppy drives are selected in this fashion, the Backup Path specification is ignored. Formatting This gadget only has meaning when performing an AmigaDOS-compatible backup. It selects the formatting method used to initialize each backup disk. Clicking on this gadget causes it to cycle through its range of values which are Normal, Quick and None, described below: Normal Use this setting for new disks which have never been formatted or when you simply want to completely reformat your backup disks. This method requires the most time. 10 MRBackup Professional The User Interface Quick Use this method for disks which have been previously formatted for AmigaDOS use. Only the filesystem header blocks are initialized, requiring very little time. None This is a special setting which should be used with care. You might wish to use this setting with diskettes which have been preformatted and are known to be empty or when "refreshing" a backup which is known to require only one diskette. Backup Mode The Backup Mode gadget selects the type of Backup or Restore to be performed and cycles through the following range of values: AmigaDOS Fast Disk SCSI Tape The backup modes are described in detail in the section entitled Backup Operations. Compression This gadget specifies the size of the compression codes, in bits, that are to be used when performing a backup. The values range from 12 bits through 16 bits or None (no compression performed). Smaller code sizes allow faster compression and lower memory requirements while compression with larger code sizes yields larger compression ratios but requires more time and more memory. Decompression The setting of this gadget is only meaningful during a restore operation. It specifies the maximum compression code size (in bits) to be decompressed when restoring files. Files that were compressed with larger compression codes will be restored in their compressed state. 11 MRBackup Professional The User Interface Compression Est. This value is a compression estimate, specified as a percentage. Its range is 0 through 99 and it is only meaningful for AmigaDOS-compatible backups. Refer to the section entitled File Compression for details on the use of this setting. Buffer Size (K) When MRBackup performs input or output from/to a file, a certain amount of memory is set aside as a buffer (holding area). This is done to minimize the number of physical disk accesses necessary to move data from/to a file. The bigger the buffer, the fewer the disk accesses that are required to move a file. The default buffer size is 32K bytes (K = 1024). If your system has expanded memory, you can take advantage of it by increasing your buffer size. The maximum buffer size allowed is 512K but the recommended maximum is the smaller of 128K or the largest known file size on your system. Backup Volume Prefix During a backup, MRBackup normally names each backup volume with the word "Backup", combined with the current date and the disk sequence number. You can customize the backup volume names by supplying your own prefix. In this case, MRBackup will simply append the disk sequence number to whatever prefix you supply. As an example, the prefix "DH0Backup." yields "DH0Backup.1", "DH0Backup.2", etc. Preferences This gadget names the file where MRBackup's operating parameters (user preferences) are stored. If MRBackup is started without an explicit "initial file" specification ("- i" option from CLI, "INIT=" Tool Type from WorkBench), the current directory is searched for "MRBackup.init". If the file is not found there, the working directory (default = S:) is searched. You may change MRBackup's parameters (including this one), then use Save Preferences to record your new settings. You may also reinitialize MRBackup with another preferences file by changing this specification. 12 MRBackup Professional The User Interface Backup Filter This gadget specifies a file to be used to assist in selecting (or rejecting) files for a backup. If you don't want to use a backup filter, just clear this gadget (click in the gadget box and press the Right-Amiga and X keys simultaneously, then press RETURN). The backup filter file delivered with MRBackup, "MRBackup.bflt", is self documenting. Compression Filter The compression filter is used during backups to inhibit the compression of certain files (when compression is enabled). The compression filter file delivered with MRBackup, "MRBackup.cflt", is self documenting. There are several built-in compression filter patterns in MRBackup. They are: #?.arc - ARC archives #?.lzh - LHARC archives #?.Z - compressed files #?.ZIP - PKAZIP archives #?.ZOO - Zoo archives Files of these types almost always expand when subjected to additional compression. Decompression Filter The decompression filter is used during restore operations to inhibit the decompression of certain compressed files when decompression is enabled. Files specified with this filter will be restored in their compressed state. The decompression filter file delivered with MRBackup, "MRBackup.dflt", is self documenting. If you prefer not to use a decompression filter, simply clear this gadget. Listing Path MRBackup normally generates a listing during backups. This gadget specifies the file or device to receive the listing. You may type the listing path directly into the gadget or you may use its requester gadget to assist you. To send the listing directly to the printer, you would select "PRT:". To 13 MRBackup Professional The User Interface save the listing to a file on the hard disk, simply select the appropriate directory and file name. Log File MRBackup will optionally generate a log of all of its activities if the Log File gadget contains a valid pathname. This log will contain time-stamped progress reports and error messages. To disable the log, simply clear this gadget. When errors are detected during a backup or restore, it is good practice to check the contents of the log for the cause and severity of these errors. Error Handling MRBackup has several approaches to error handling. The range of values for error handling are: Interactive MRBackup asks how the error is to be handled Retry Upon detecting an error, MRBackup will retry the operation a number of times as specified in the Retries gadget. Ignore MRBackup will count the error but will continue processing. Errors will be reported to the log file. Abort MRBackup will immediately abort a backup or restore upon detecting any error. Normally, you will use the Interactive setting. Voice On / Voice Off This is an ON/OFF button which enables or disables MRBackup's speech capability. Create Listing: Yes or No This is a Yes/No button which enables or disables the creation of the listing file during a backup operation. 14 MRBackup Professional The User Interface Split Big Files: Yes or No This button is only meaningful for the AmigaDOS-compatible backup mode. It is a Yes/No switch which enables or disables MRBackup's handling of big files. A big file is one which is larger than the capacity of an empty diskette. If this gadget indicates Yes, MRBackup will split big files across multiple diskettes. Each diskette will have a special file, MRBackup.bigfile, in addition to its segment of the big file. This special file describes the file segment. Test Archive Bits If this button is enabled, MRBackup will only backup files whose archive bits are clear. AmigaDOS clears a file's archive bit whenever that file is modified. Using the Test Archive Bits option allows you to backup only files which have changed since the last time you did a backup with the Set Archive Bits option (below) enabled. This filtering is done in addition to any other filtering options you may be using. Please note that the AmigaDOS interpretation of the archive bit is reversed from that of the MS-DOS environment where a set bit indicates that the file has not been archived. Set Archive Bits If this button is enabled, MRBackup will set the archive bit on every file that it backs up. The setting of archive bits is deferred until the backup is successfully completed. The Status Display Window The Status Display window is used to inform you of MRBackup's progress during backup and restore operations. The Status Display gadgets are described here in left-to-right, top-to-bottom order. Disk Number This gadget indicates the number of the floppy diskette (or tape cartridge) which is currently being accessed for backup or restore. 15 MRBackup Professional The User Interface Backup Volume Name This gadget reports the name of the backup volume currently being used for a backup or restore operation. Errors This gadget displays the total number of errors detected during a backup or restore operation. Destination Capacity This gadget shows, in relative terms, how much space remains on the current backup volume. As the destination media is filled, the gadget's slider will move to the right, toward the "F" (full) indicator. Blocks This gadget displays the current destination capacity as a number of 512 byte blocks. Bytes In This gadget displays the total number of bytes, in K (1024 byte increments), which have been read into MRBackup. Bytes Out This gadget displays the total number of bytes, in K, which MRBackup has written to the destination media. Ratio This gadget displays, as a percentage of change, the effective compression ratio for backups and decompression ratio for restores. For example, when a value of 35% is displayed during a backup operation, then the cumulative size for all files backed up has been reduced by 35 per cent. 16 MRBackup Professional The User Interface Overhead This gadget displays, as a percentage of total media space available, the amount of backup media space not directly associated with file data storage. Overhead space is used for file and directory headers, etc. Current File or Directory At the start of a backup, this gadget reports the name of each directory being scanned for files. During a backup or restore operation, this gadget reports the name of the file currently being accessed. Status This is a one-line text message which reports the current state of MRBackup or the last significant event or error. STOP This gadget allows you to terminate a backup or restore operation. As a safety measure, a requester will ask you to confirm this action before it takes effect. Please note that when using a large buffer size, there may be a very noticeable delay when clicking the STOP or PAUSE gadgets. Just be patient - MRBackup will recognize the request as soon as the current buffer operation completes. PAUSE / PROCEED This gadget temporarily suspends all backup or restore activity. If you are closely monitoring the progress of a backup or restore and the phone rings, you can click PAUSE and be confident that things won't "get away from you". When you click the PAUSE gadget, its label changes to PROCEED. MRBackup will be suspended until this gadget is clicked again. Chip, Fast, Total 17 MRBackup Professional The User Interface These three gadgets display the amount of CHIP RAM and FAST RAM available, as well as the combined total. They provide you with a means to monitor memory availability. If the combined total should drop below a reasonable threshold (arbitrarily, let's pick 128K), you might want to click the PAUSE gadget, cancel other applications that might be running and then click the PROCEED gadget to allow MRBackup to resume. This action would forestall a failure due to a potential low-memory condition. 18 MRBackup Professional The User Interface The Utilities Window The Utilities Window provides a variety of AmigaDOS file management operations. The top portion of the window contains gadgets for specifying file selection criteria and reporting status. The middle portion is a combined information display and file requester for interactively selecting individual files. The bottom portion of the window primarily contains "command buttons" which select the operation to be performed on the selected file(s). When performing a Utilities operation, the affected files have a source (From) and, where appropriate, a destination (To). The file information display box in the center of this window multiplexes (switches) between the From and To modes, depending upon the settings of the ON/OFF switches affecting the From and To selections. OFF/ON The OFF/ON switches determine whether the source (From) or destination (To) directory is displayed in the file display area. These switches are mutually exclusive and only one can be ON at a time, though both can be OFF at the same time. Clicking on either will cause the display box to be filled with information relevant to the appropriate path specification. From This gadget holds the source device or directory name. To This gadget holds the destination device or directory name. From/To Arrow (Parent) Gadgets The From and To gadgets each have an arrow gadget to the right of their respective text boxes. Clicking on the arrow causes the selection to move up one level in the file hierarchy (the immediate parent). For instance, if the From selection is currently "DH0:Src/Lib/Amiga", clicking its 19 MRBackup Professional The User Interface associated arrow gadget will change the From selection to "DH0:Src/Lib". Drive Clicking on the Drive gadget will cause the currently active selection (From or To, as determined by the OFF/ON switch settings) to cycle to the next disk drive (including RAM:, RAD:). FileSpec The FileSpec gadget (file specification) is applied to the From selection to restrict the files visible in the file information box. Typically, an AmigaDOS/ARP file name pattern is entered here. For instance, "#?" or "*" (default) allows all filenames to be seen. "#?.Doc" would allow only filenames ending in ".Doc" to be seen. The FileSpec does not apply to directory names, which are always visible. Info The Info gadget provides status information related to the current utility operation being performed. All Files Clicking on the All Files gadget will select everything in the file information box (including entries which are out of view). Selected entries are displayed in reverse video. Clear Clicking on the Clear gadget will cause all files in the file display area to be deselected. State (unlabled) There is an unlabeled box centered beneath the file information box. This gadget is used to display the current state of the Utilities "engine". 20 MRBackup Professional The User Interface Utility Command Buttons At the bottom of the Utilities window is a set of gadgets (command buttons) which are labeled with the names of the Utilities processing options. Each one will be discussed separately below. One thing that they all have in common is that the From selection must be active before they may be used. Clicking any command button before the current process has completed will terminate the current process. Compress This command button causes the selected files to be compressed, using the current Compression bit code setting and compression filter file in the MRBackup Parameters window. The From and To path specifications may indicate the same or different pathnames. If they are the same, the original file will be deleted and replaced with its compressed version (having a ".Z" suffix). Decompress This command button causes the selected files to be decompressed, using the current Decompression bit code setting and decompression filter file, as specified in the MRBackup main window. The From and To path specifications may indicate the same or different paths. If they are the same, the compressed file (having the ".Z" suffix) will be replaced by its decompressed version (".Z" suffix removed). Copy The Copy command button requires different From and To specifications. The selected files are copied to the To path. Rename The Rename command button requires that the From and To specifications name different directories on the same device (renaming across devices is not allowed). All selected files will be moved (renamed) from their current location to the To directory. 21 MRBackup Professional The User Interface Delete Only the From specification is required for Delete. All selected files will be deleted from your system. Be careful! SetDate The SetDate command button changes the file modification date for all selected files (the To specification is not required). Upon selecting the SetDate command button, you will be presented with MRBackup's date requester. Simply select the date you wish to apply. Set Bits The Set Bits command button provides the capabilities of the AmigaDOS "Protect" command. Above the Set Bits command button, you will see eight gadgets with the letters "H,S,P,A,R,W,E,D". These letters are defined as follows: H - Hidden file (not currently supported) S - Script (recognized by NewShell, AShell) P - Pure (used by "resident" programs) A - Archived (set => file is archived) R - File is readable W - File is writeable E - File is executable D - File is deleteable Set the appropriate gadgets for the bits you wish to set, then click the Set Bits command button. The bit pattern you have selected will be logically OR-ed with the current bit settings for the selected files. The R, W, E and D indicators are somewhat confusing, as their meaning is inverted. A set bit actually means that the related operation is inhibited. For instance, when "W" is displayed, it actually means that the "W" bit is clear, allowing file write operations. To write-protect a file, then, you must SET its "W" bit. Clear Bits 22 MRBackup Professional The User Interface Clear Bits works in much the same fashion as Set Bits except that the selected bits are turned off. Only the selected bits will be affected - all others retain their current setting. 23 MRBackup Professional File Compression File Compression Compression Method MRBackup employs Lempel-Ziv compression. While this method does not yield the highest compression ratios, it is one of the fastest software compression algorithms available. Its ability to be "tuned" through the use of user-specified code size limits allows you to make certain performance trade-offs. Larger code sizes will make greater temporary demands on system memory but will result in higher compression ratios. When a file is compressed, special codes are written at the beginning of the compressed file to indicate that it is compressed and to record the size of the codes used for compression. Thus, you need not remember what code size was used to compress a particular file. Compression Estimating MRBackup's compression estimating feature is only meaningful for AmigaDOS-compatible backups. MRBackup does not know in advance what a file's size will be after it is compressed. Therefore, when determining whether a file will fit on the current backup diskette, the file's full size is used. This can result in a significant amount of wasted space on each diskette. If you set the compression estimate to a non-zero value, MRBackup will apply this estimate when determining space available. A reasonable value to start with is 35 (%). This means that you expect most files to be 65% of their original size (100%-35%) when compressed. Please note that this may lead to occaisional "disk full" errors, depending on how aggressive your estimate is. In this case, MRBackup will delete the partially copied file and force a new diskette. This is a feature you'll have to develop a "feel" for. Over time, you'll have a pretty good idea of what your typical compression yield is and can make more intelligent estimates. Of course, you can always play "safe" and leave this value at zero. 24 Filter Files The term "filter" may sound strange to you, but you've probably heard and even used it many times without giving it a second thought. Surely you've heard of the coffee filter, which keeps the coffee grounds out of your freshly brewed pot of java. Air filters keep dust and dirt out of your electronic equipment and your environment. Oil filters keep your auto's engine clean. MRBackup employs filename filters to accomplish something quite analogous. A set of filenames is "fed into" a filter and a subset of those filenames is allowed to "pass through" it. Each filter is simply a text file containing zero or more filename patterns. Each filter (backup, compression, decompression) has a specific purpose and operates on a particular set of filenames. Filter File Format Each filter file is simply a text file which can be created with any plain text editor or a word processor which can save plain ASCII text. The file may contain any number of patterns, one per line. You may place comments in the file by placing a semi-colon (;) in the first character position. Empty lines are also ignored. Filter Patterns Filter patterns are expressed "relative" to a device or volume. That is, they don't include a volume or device name (the part preceding and including the colon in a full AmigaDOS filename). What they are relative to is implicit in their use. For instance, the backup filter patterns are relative to the "home" device, as are the compression filter patterns. Since decompression is performed during a restore, decompression filter patterns are implicitly relative to the "backup" device. Filter patterns may be simple filenames, such as Trashcan Trashcan.info or they may be quite exotic and complex patterns with "wildcard" notation, character class specifications, etc. Here is the definition of special characters which can be used in a filter pattern: 25 MRBackup Professional Filter Files Character Meaning ? Match any single character. % Match the null string. #

Match zero or more occurrences of pattern

. * Match any pattern (same as #?). Match pattern followed by pattern . ( ) Parentheses group patterns together. (|) Match if either or match (parentheses are required.). [] Character class (ex: [a-z] or [0-9] ). ~

Negation: match anything BUT pattern

Example: "~*.info" means all files except those ending in ".info" (quotes for illustration only) ' Escape next special character. Useful for filenames which contain any special characters above. The most common mistake that you are likely to make when creating your filter patterns is to omit the "leading context" from your patterns. For instance, if you want to omit all files named "junk.txt" from an operation, you must remember that the simple filename is actually part of a larger specification which includes all higher level directory names. Thus, to omit all files named "junk.txt", we might use the following pattern: (junk.txt|#?/junk.txt) This is a pattern grouping which recognizes "junk.txt" at the top level of a volume or (you can equate the vertical bar | to the word "or") at any level in the directory hierarchy. The pattern #?junk.txt is not "safe" since it will match ANY sequence of characters preceding "junk.txt" (somejunk.txt, myjunk.txt, morejunk.txt, etc.) which is not what we wanted. 26 MRBackup Professional Filter Files Backup Filter The Backup Filter is used to assist in the selection of files that are to be copied during a backup operation. When MRBackup performs its initial scan, the backup filter is applied to each file or directory name as it is encountered. The Backup Filter has a dual personality. By default, its patterns are used to exclude selected files from a backup. However, there are two special patterns which change the meaning of the Backup Filter patterns. These patterns are :INCLUDE: and :EXCLUDE:. If the :INCLUDE: pattern appears in the Backup Filter file, subsequent patterns will be used to include files in the backup. Only files which match these patterns will be included in the backup. This can be a useful mechanism for backing up "disjoint" directory hierarchies without having to provide many exclude patterns. If the :EXCLUDE: pattern appears in the Backup Filter file, subsequent patterns will be used to exclude files from the backup. If the :INCLUDE: pattern is also present in the filter file, the exclude patterns will be applied only to the files which satisfied the include patterns. That is, the include patterns take precedence, regardless of the appearance order of :INCLUDE: or :EXCLUDE:. Compression Filter The Compression Filter is employed during a backup operation to inhibit file compression on certain files. It has no effect if the Compression gadget has been set to None. Over time, you will notice that certain files have a tendency to expand, rather than compress, when subjected to MRBackup's compression scheme. Such strange behavior! The compression algorithm takes advantage of the fact that most files contain data whose values are not evenly distributed. There tend to be many redundant data patterns which can be represented by fewer bits. However, certain files, such as programs, animations, graphics images, etc., do not compress well. MRBackup will detect this condition, abandon compression for that file and perform a straight copy. Unfortunately, this results in a waste of time, 27 MRBackup Professional Filter Files since a significant portion of the file may have been compressed before the condition was detected. MRBackup helps you alleviate this situation by providing you with a Compression Filter. As you detect files for which compression is a problem, enter the appropriate patterns into your Compression Filter file and MRBackup will cease trying to compress them. If you use a reasonable naming convention for certain classes of files (e.g. .ilbm for IFF bitmap files), you can easily omit whole classes of files from compression. Decompression Filter While file compression is a nice backup feature, you may also want to maintain certain files on your hard drive in a compressed state. If you perform a restore operation with decompression enabled, however, files that you wish to remain compressed will be decompressed. The Decompression Filter allows you to specify the files which you would like to restore in their compressed state. That is, patterns in the Decompression Filter inhibit file decompression. 28 Backup Operations The data and programs on your Amiga might well be worth more to you (in terms of cost to replace) than the machine itself. Hard disks fail. Systems "crash", causing irrecoverable damage to hard disk partitions. Backups are insurance against such probabilities. However, they often don't get done. The excuses are many and varied. "I'm too busy", "I meant to, but...", "I don't have enough floppy disks", etc. We are all guilty to varying degrees. Even the author of this backup program has been caught "with his pants down" on a couple of occaisions (excuse #1). Needless to say, backups are not a fun way to use your Amiga and they require discipline to be done on a regular and effective basis. MRBackup goes a long way toward making this chore more pleasant. The Backup Modes In a previous section, we touched briefly on the fact that MRBackup supports three backup modes: AmigaDOS Fast Disk SCSI Tape MRBackup provides you the flexibility to choose the mode that is best suited to your needs (or budget!). AmigaDOS Backup Mode The AmigaDOS backup mode provides full compatibility with AmigaDOS and its tool set. That is, you can manipulate the files in an AmigaDOS backup set with the standard Amiga tools such as DIR, LIST, COPY, TYPE, etc. When backing up to diskette, MRBackup creates disk volumes (currently OFS) which are accessible to the AmigaDOS filesystem. MRBackup also employs no hardware-specific "tricks" in this mode. If the disk hardware is supported by standard Amiga software, MRBackup will handle it (if you find an exception to this, please let us know!). One important item to note is that you are not required to backup files to floppy diskettes. If you are fortunate enough to have a "spare" hard disk or a hard disk with removable media, you can 29 MRBackup Professional Backup Operations use either for your backup destination. You can also perform backups from one directory to another. MRBackup preserves all file attributes when backing up and restoring files. The file protection word (HSPARWED), comment and modification date are all maintained. This is true for all backup modes. Fast Disk Backup Mode The Amiga's original filesystem, while providing a great deal of recoverability, suffers from poor performance. This is especially notable when accessing floppy disks. This can be overcome somewhat by adding more disk buffers via the AddBuffers command or using a floppy disk accelerator (caching program) such as ASDG's Facc-II. MRBackup addresses this problem by providing a new diskette format. In a sense, this format is analagous to a streaming tape drive. Floppy disk head movement is minimized. The diskette is formatted as data is written to it and slightly more data can be written to the diskette (without using any compression techniques). Also, files are automatically split across volumes in Fast Disk mode, meaning that there is no unused space on your backup diskettes. At the same time, a high degree of integrity and recoverability has been designed in. Though this format cannot be read by the AmigaDOS filesystem(s), you will most likely prefer to use it for most general-purpose backups because it is so fast. If you feel uncomfortable about storing your files in a non- standard format, take heed! MRBackup's fast disk backup mode is NOT proprietary! If you would like documentation describing the fast disk backup format, send $5.00 to TTR Development for a diskette containing documentation and C language source files. Another interesting feature of Fast Disk mode is that you can backup TO A FILE OR ANY STREAM-ORIENTED DEVICE! The file, in essense, simulates a very large capacity floppy diskette. You can then manage this backup file as a single entity. If you're fortunate enough to be connected to a networked file server with lots of available disk space, the advantages are tremendous! You can perform a full backup without changing disks, saving your backups in remote files which fully preserve their AmigaDOS attributes. 30 MRBackup Professional Backup Operations SCSI Tape Backup Mode As you might have guessed, this mode supports a streaming tape drive with a SCSI (Small Computer Systems Interface) interface. It is essentially the same as Fast Disk mode, except that additional support and modified error-handling behavior are invoked for the tape drive. A SCSI tape handler is provided with MRBackup. To use it, you must perform the following steps: Copy the tape handler, mrtape-handler to the L: directory: COPY MRBackup:L/mrtape-handler L: Add the supplied device mountlist entry to your DEVS:Mountlist file, using a text editor. The mountlist entry provided with MRBackup is named "mountlist.tape". It contains the following: MRTAPE: Handler = l:mrtape-handler StartUp = "128/scsi.device/4/0" Stacksize = 4000 Priority = 5 GlobVec = -1 # You may need to change the "Startup" line. The expression to the right of the equal sign (=) has the following format: "///" The beginning and ending double quotes are required if you are using the standard AmigaDOS Mount command (not required with the ARP mount command). The parameter is specified in multiples of K (K=1024). The example value of 128, above, provides double-buffering for the WangTek model 5XXX-ES tape drives, which have an internal 64K buffer. The parameter specifies the device driver to be used to talk to the device. Use "scsi.device" with the CBM A2091 SCSI controller. Consult your owner's manual if you are using a non-Commodore SCSI controller. 31 MRBackup Professional Backup Operations The parameter specifies the SCSI device number, usually established by jumpers or DIP switches on your tape drive. The entry is provided for a future compatibility option and should be set to zero. Once the above steps have been performed, you must mount the MRTAPE: device. This is done with the following command: MOUNT MRTAPE: You may then specify MRTAPE: as your Backup Path. You may also automate the device mounting process by placing the above command in your S:Startup-Sequence (or S:StartupII) file. Backup Schemes You may not have even thought of it, but there are several approaches to backing up your system. Each has its advantages and disadvantages. You may use one or more of them, depending upon your use of the Amiga. MRBackup is so flexible that you may come up with several more not detailed here. The Full Backup A full backup is the most desirable method if time and available backup media are not factors. A complete "snapshot" of your hard disk partition(s) is taken, fully reflecting the state of your machine at that point in time. If you are using floppy disks to backup a large partition, however, you may find this approach quite burdensome. Given MRBackup's flexibility however, you will quite likely find a mix of backup techniques that satisfy your needs. Another thing to remember is that much of your commercial software already has a backup - the original disk (or the backup you made of the original disk if you followed typical vendor's instructions). If you have lots of commercial software installed on your hard disk, you should probably consider excluding the files which don't change (programs, examples, etc.) via the backup filter. This will dramatically cut down on the time and media required for a "full" backup. 32 MRBackup Professional Backup Operations Incremental Backups Incremental backups provide a reasonable alternative to the full backup if the proper procedures are followed. The incremental backup consists of a full system backup followed by one or more partial backups. The partial backups record only the files that have changed since the full backup was performed. The "File Modification Date" Incremental Backup Each time a file is written (modified), the AmigaDOS filesystem sets the file's modification date to the current date and time, as set in the Amiga's time-of-day clock. MRBackup can take advantage of this fact by comparing file modification dates against the Test Date setting in the main window. Only files changed on or after the Test Date are selected for backup. A typical backup scenario for a date-sensitive backup might be: 1. Perform a full system backup to backup media set 1. 2. Perform incremental backup to backup media set 2. 3. Perform incremental backup to backup media set "n". 4. Repeat the sequence starting with step 1. In the sequence above, there is an implied delay between steps. Depending upon your requirements and confidence level (degree of self-discipline?), the delay may range from several hours to a week or more (not much more!). You might choose a one month cycle (i.e. step 1 is repeated on the first Saturday of each month). Notice that multiple media sets (tapes, floppies, files, etc.) are required. When performing incremental backups, you must not destroy your previous backup set(s). There is some room for variation here, however. You might want to maintain just two sets of backup media. The first set would contain the full backup, while the second set would contain all files which changed since the full backup was done. In this case, each time you perform the incremental backup, more backup media will be required to hold the additional files, assuming a dynamic system where files are being changed on a daily basis. The "Archive Bit" Incremental Backup 33 MRBackup Professional Backup Operations In addition to maintaining the file modification date, AmigaDOS also maintains an archive indicator bit in each file protection word. Specifically, AmigaDOS clears the archive bit whenever a file is modified. Backup software, such as MRBackup, can set this bit when a file has been successfully backed up. When the Test Archive Bits gadget is set to ON, only files with cleared archive bits will be backed up. If the Set Archive Bits gadget is also on, MRBackup will set the archive bits of all files which have been backed up. The sequence to observe when performing the archive bit backup is similar to that used for the date sensitive backup. However, you MUST use a different set of backup media for each unique step. As an aside, MRBackup does not prevent you from doing a backup which combines date testing with archive bit testing. However, it is advised that you choose one method or the other for desirable results. The Project Backup If you're a developer, you may be concentrating all of your work in a specific directory hierarchy. Likewise, if you're a graphics artist, you may have a specific area in which you work. In these instances, it is recommended that you do daily "full" backups of these selected areas. This can be accomplished by setting the Home Path to the name of the topmost directory for the project area and setting the Test Date gadget to January 1, 1978 and setting the Test Archive Bits gadget to "No". Also, you may wish to define specific backup and compression filters for each special project area. The Backup Process Once you're sure that all backup settings are correct, you may begin the backup process. This is done by selecting the Backup command from the Project menu or by typing the keyboard shortcut, Right-Amiga + B. MRBackup's main window will disappear and a smaller Status Display window will appear. This window informs you of the progress of the backup. As the backup proceeds, pop-up requesters will instruct you to insert/remove media as necessary as well as alert you to other bits of information, error conditions, etc. 34 MRBackup Professional Backup Operations The first backup step performed is a scan of all files specified by the Home Path. While MRBackup is scanning, the Current File or Directory gadget in the Status Display window will display the name of the directory being scanned. Once the scan is complete, MRBackup will present its file selector. The file selector displays the list of files that were considered eligible for backup, according to the backup parameters you have chosen. It then gives you the option to omit certain files (or groups of files) from this list. See the section entitled The MRBackup File Selector for details on its operation. Assuming that you completed the file selection process by clicking the OK button in the file selector window, MRBackup will proceed to backup your files. If you have selected either AmigaDOS or Fast Disk backup mode, you will be prompted to insert/remove diskettes as MRBackup requires your assistance. MRBackup does not currently provide support for the Amiga Floppy Disk Carousel since, according to our knowledge, it doesn't exist - ha ha!. When the backup is complete, make a quick check of the Errors gadget in the Status Display window. If it is non-zero, it would be a good idea to check the backup log to determine the nature of the errors before assuming that the backup set is acceptible. 35 MRBackup Professional Restore Operations Restore Operations The file restoration process is the inverse of a backup. You would most likely do a full restore when rebuilding a disk partition. A partial restore might be done to recover files which were deleted accidentally. The following MRBackup settings come into play when performing a restore operation: Home Path - the target ("to" location) for the restore. Backup Path - the source ("from" location) for the restore. Disk Selection Icons - optional selection of backup path (overrides Backup Path). Backup Mode - indicates the type of backup set we are restoring from. Decompression - sets the upper code size limit for file decompression. Files compressed with code sizes larger than this limit will be restored in their compressed state. Buffer - specifies the amount of memory to be used for file I/O buffering (same as backup). Decompression Filter - compressed files whose names match one or more of the patterns in this file will not be decompressed during a restore. Log File - records errors and progress messages during the restore. Error Handling - establishes the type of error handling employed during the restore. Voice On/Off - enables/disables MRBackup's speech capability. There are some interesting (and important) items to be aware of when performing a file restore operation. During a backup, MRBackup preserves the complete directory hierarchy for the files which are backed up. This may be cause for some confusion. Consider the following example. You perform a backup with the 36 MRBackup Professional Restore Operations Home Path set to "DH0:" (your first hard disk partition). A portion of the files selected might look like ARexx ARexx/Docs ARexx/Examples ARexx/Tools Docs Docs/Amiga Docs/Graphics Docs/Utilities ... etc. If you later restore the backup set with the Home Path again set to "DH0:", your files will be restored to the same level in the hierarchy. When you do a backup and specify a subdirectory as the Home Path, the full directory hierarchy from the "top" of the partition through all levels included by the Home Path is preserved. For levels higher than the Home Path, only the directories are preserved (files are ignored). When you restore such a backup, the Home Path must be changed to the name of the partition (e.g. DH0:, DH1:, etc.) to which you want the files recovered. Of course, if you wish to restore your backup set to a lower-level hierarchy, you are free to select any valid Home Path. It is important to note that MRBackup will not overwrite an existing file with a file which has the same or earlier modification date. During the restore, a message will be displayed to the screen and written to the log file for each file that is skipped because of this condition. If you really intend to restore the older versions, you must first delete or rename the newer files (or rename the directory that they reside in). 37 The MRBackup File Selector The file selector is presented to you during backup and restore operations to enable you to "fine tune" the list of selected files. Before we discuss its operation, let's take a quick look at the graphical objects that make up the file selector. In the discussion that follows the term entry refers to both files and directories. Current Level This gadget reports the nesting level of the directory you are currently viewing. The top level is zero. Up When you click the Up gadget, the next higher directory level is displayed and the Current Level gadget is updated accordingly. Include Pattern This is a string gadget which works in conjunction with any of the Select buttons (later). The Include Pattern is a filename matching pattern (as used in the MRBackup filters) which is applied to each filename when one of the Select buttons is clicked. Only those names matching the pattern will be selected. If the Include Pattern is blank, no include matching is performed. Exclude Pattern This is a string gadget which works in conjunction with any of the Select buttons (later). The Exclude Pattern is very similar to the Include Pattern, except that filenames matching the pattern will be excluded from selection when a Select button is clicked. If both Include and Exclude patterns are specified, the Include pattern is applied first. Select all When the Select all button is clicked, all files in the selector file list are selected. Select all, this level and below This button causes all entries at the current level and lower (higher level numbers) to be selected. Select all, this level only This button causes all entries at the current level to be selected. 38 MRBackup Professional The MRBackup File Selector Deselect all This button has slightly different behavior, depending upon the Current Level setting. When the Current Level is zero (top level), all entries are deselected. When the Current Level is non-zero, all file and directory entries except the parent directories for the current level are deselected. Deselect all, this level and below This button causes all entries at and below the Current Level to be deselected. Deselect all, this level only This button causes all entries at the Current Level to be deselected. Entries This gadget reports the total number of entries (files and directories) contained in the file selector list. No. Selected This gadget reports the total number of entries currently selected. Disk Est. For backup operations, this gadget provides a rough estimate of the number of disks required to hold the files currently selected. If file compression is enabled, the Compression Estimate value (entered by you) is factored into the disk estimate. The disk estimate value is meaningless for restore operations. OK Click this button when your file selection is complete and you wish to proceed with the current operation (backup or restore). CANCEL Click this button when you wish to terminate the current operation (backup or restore). Current Directory (unlabeled) The long gadget at the bottom of the file selector window displays the full name of the current directory. It is empty when the Current Level is zero. 39 MRBackup Professional The MRBackup File Selector The files available for selection/deselection are presented in the large box at the left of the file selector. Just to the right of this box, you will see a scroll bar. When there are more files at a given level than can be viewed in the selection box, the drag bar (rectangle within the scroll bar) will be sized in proportion to the number of visible vs. total entries. You may click and drag this bar to reveal other entries at the current level. You may also scroll the list one item at a time by clicking on either of the small buttons at the bottom which have arrow indicators on them. Each time you click on an entry in the list, it will toggle between selected and deselected. An entry in the selected state is highlighted by a dark background. Directory entries and file entries are represented by different colors. To view the contents of directories (and their subdirectories), position the mouse pointer over a directory entry and double-click (two clicks, in rapid succession) on the entry. The display box will be redrawn with the contents of that directory and the Current Level indicator will be incremented. To return to the previous level, simply click on the Up button. 40 MRBackup Professional The ARexx Interface The ARexx Interface The Amiga's multitasking operating system is one of its distinguishing features. The typical Amiga user is apt to be running several programs at any given time. With the addition of ARexx (the Amiga implementation of the Rexx language), programs equipped with an ARexx "port" can communicate, share resources with one another or be operated under "remote control" of an ARexx program. The MRBackup ARexx Port MRBackup provides an ARexx interface which allows many of its operating parameters and features to be accessed this way. It is possible to run multiple "copies" of MRBackup. Thus, MRBackup creates a unique ARexx port name for each instance of MRBackup that is run. You can determine the ARexx port name by selecting the About item from MRBackup's Project menu. The ARexx port name will always be of the form: MRBackup_# where is the number assigned to a given instance of MRBackup. Typically, with one copy of MRBackup running, the ARexx port name will be MRBackup_#1. Using ARexx with MRBackup This is not an ARexx tutorial. If you are unfamiliar with ARexx, you will have to obtain appropriate documentation. ARexx is bundled with AmigaDOS version 1.4 and beyond. It can also be purchased from William S. Hawes P.O. Box 308 Maynard, MA 01754 (617) 568-8695 MRBackup's implemenation of ARexx requires that the results option be enabled, since many commands return a value. Include the following statement in all of your MRBackup ARexx scripts: options results Commands which don't have a specific return value will set the 41 MRBackup Professional The ARexx Interface result variable to either "OK" or "FAIL" to indicate success or failure. Each MRBackup ARexx script must have a filename extension of ".mrbk" (e.g. DailyBackup.mrbk). Here is an example script which manipulates MRBackup's voice setting (on or off) and demonstrates its effects: /* voice.mrbk */ /* MRBackup: turn voice on and off. */ signal on ERROR signal on BREAK_C /* Enable command results. */ options results /* Make sure that MRBackup is running. */ if ~(Show('P', 'MRBackup_#1')) then do say "You must run MRBackup first." exit 1 end /* Select MRBackup's ARexx port. */ address "MRBackup_#1" /* Bring MRBackup's screen to the front. */ poptofront /* Inform the user as to what is going to happen. */ 'notealert "This test turns the voice option off and on."' /* Turn the voice capability off. */ 'setvoice "no"' /* Check the result of the previous command. */ if result ~= "OK" then do say "I could not turn the voice option off!" exit 1 end /* The following message should be suppressed. */ 'speak "You should not hear this message."' if result ~= "OK" then do say "Attempt to speak failed." exit 1 end call Delay(50) 42 MRBackup Professional The ARexx Interface /* Enable MRBackup's voice capability. */ 'setvoice "yes"' if result ~= "OK" then do say "I could not turn the voice option on!" exit 1 end /* This time, the user should hear the message. */ 'speak "This message is being brought to you by Ay Rexx."' if result ~= "OK" then do say "Attempt to speak failed." exit 1 end exit 0 /*--- Control-C interrupts come here. ---*/ break_c: say "*** Control-C recieved. Stopped by user. ***" exit 5 /*--- ARexx-detected errors come here. ---*/ error: say "Error" exit 6 /*--- End of script. ---*/ You will find a set of example ARexx scripts in the "ARexx Scripts" directory on your MRBackup program diskette. Please refer to them when you need help in creating your own MRBackup/ARexx applications. MRBackup's ARexx Commands This section details each of the ARexx commands supported by MRBackup. In the following discussion, certain notation conventions are adopted: Command parameters (arguments) are often specified with enclosing angle brackets <>. The enclosed word or phrase 43 MRBackup Professional The ARexx Interface connotes the type of value which should be substituted. For instance, a parameter denoted as could take a value such as "DH0:Devs/Printers". Optional parameters are enclosed in square brackets []. In these cases, the command's behavior with the optional parameter specified is contrasted with its behavior when the optional parameter is given. Literal text values (e.g. "OK", "FAIL", etc.) are specified as quoted strings. MRBackup's ARexx commands are listed here, in alphabetical order. command backup result "OK"or "FAIL" description This command starts a backup operation. Prior to issuing the backup command, all backup parameters (filter specifications, compression settings, etc.) should be set to their desired values. command getbackpath result MRBackup's current Backup Path specification. description This command obtains the current Backup Path specification and returns it via the result variable. command getbfilterpath result MRBackup's current Backup Filter specification. description This command obtains the current Backup Filter specification and returns it via the result variable. command getbufsize result The current Buffer Size value. 44 MRBackup Professional The ARexx Interface description The getbufsize command obtains the current Buffer Size value (expressed as a multiple of "K", where "K" = 1024) and returns it via the result variable. command getcfilterpath result The current Compression Filter specification. description The getcfilterpath command obtains the current Compression Filter specification and returns it via the result variable. command getdfilterpath result The current Decompression Filter specification. description The getdfilterpath command obtains the current Decompression Filter specification and returns it via the result variable. command getcompression result "None", "12-Bit", "13-Bit", "14-Bit", "15-Bit", "16-Bit" description The getcompression command obtains the current Compression code size setting and returns it via the result variable. command getdecompression result "None", "12-Bit", "13-Bit", "14-Bit", "15-Bit", "16-Bit" description The getcompression command obtains the current Deompression code size setting and returns it via the result variable. command gethomepath result MRBackup's Home Path specification. 45 MRBackup Professional The ARexx Interface description The gethomepath command obtains MRBackup's Home Path specification and returns it via the result variable. command getlistpath result MRBackup's Listing Path specification. description The getlistpath command obtains MRBackup's Listing Path specification and returns it via the result variable. command getlogpath result MRBackup's Log Path specification. description The getlogpath command obtains MRBackup's Log Path specification and returns it via the result variable. command getformatting result "None", "Quick", "Normal" description The getformatting command obtains MRBackup's current Formatting setting and returns it in the result variable. command gettestdate result the current Test Date value description The gettestdate command fetches the current Test Date value (used for backup operations) and returns it in the ARexx result variable. The date is formatted according to the current date format. command listing result "OK" or "FAIL" description The listing command enables or disables MRBackup's listing output, depending upon the 46 MRBackup Professional The ARexx Interface parameter which must be either "YES" or "NO". Example: listing "YES" command notealert result "OK" or "FAIL" description The notealert command provides access to MRBackup's informational requester. The text of will be presented in a requester. The user must click the requester's OK button before program execution will proceed. The string may contain embedded newline (line feed) characters. command poptofront result "OK" or "FAIL" description The poptofront insures that MRBackup's screen is the frontmost screen. command quit result "OK" or "FAIL" description The quit command instructs MRBackup to terminate. When used, this must be the last command issued to MRBackup. command restore result "OK" or "FAIL" description The restore command instructs MRBackup to perform a file restore operation according to MRBackup's current settings. command setarcbits result "OK" or "FAIL" 47 MRBackup Professional The ARexx Interface description The setarcbits command instructs MRBackup to enable/disable the setting of file archive bits during a backup operation. If the value is "YES", archive bits will be set upon successful completion of a backup. command setbackpath [ ] result "OK" or "FAIL" description The setbackpath command instructs MRBackup to adopt a new Backup Path specification. The parameter, if supplied, must be the name of a valid device, directory or filename (depending upon the current backup mode). If is not given, the user will be presented with MRBackup's file requester. command setbfilterpath [ ] result new backup filter file name description The setbfilterpath command instructs MRBackup to adopt a new Backup Filter specification. The parameter, if given, must be the name of a valid text file containing MRBackup backup filter specifications. If is not given, the user will be presented with MRBackup's file requester so that a file may be selected. Note that this command always returns the backup filter file name in effect upon its return. To test for failure, test the ARexx rc variable for a non-zero result. command setbufsize result new buffer size value description The setbufsize command instructs MRBackup to use a new buffer size for backup/restore operations. The parameter is expected to be a number expressed as a multiple of "K" (K = 1024). For example, a of 64 would result in 65536 bytes being allocated for MRBackup buffering operations. The return value is always the buffer size (again, in K) in effect upon return from this 48 MRBackup Professional The ARexx Interface command. If an error is detected, the ARexx rc variable will contain a non-zero error code. command setcfilterpath [ ] result new compression filter file name description The setdfilterpath command instructs MRBackup to adopt a new Compression Filter file name specification. If is given, it must be the name of an existing text file containing valid MRBackup filter patterns. If is omitted, the user will be presented with MRBackup's file requester so that a file may be selected. This command always returns the name of the Compression Filter file in effect upon its return. To check for command failure, test the ARexx rc variable for a non-zero value. command setcompression result "OK" or "FAIL" description The setcompression command instructs MRBackup to use a new compression code size for subsequent backups. The valid values for are: "None", "12-Bit", "13-Bit", "14-Bit", "15-Bit", "16-Bit" command setdecompression result "OK" or "FAIL" description The setdecompression command instructs MRBackup to use a new decompression code size limit for subsequent backups. The valid values for are: "None", "12-Bit", "13-Bit", "14-Bit", "15-Bit", "16-Bit" command setdfilterpath [ ] 49 MRBackup Professional The ARexx Interface result new decompression filter file name description The setdfilterpath command instructs MRBackup to adopt a new Decompression Filter file name specification. If is given, it must be the name of an existing text file containing valid MRBackup filter patterns. If is omitted, the user will be presented with MRBackup's file requester so that a file may be selected. This command always returns the name of the Decompression Filter file in effect upon its return. To check for command failure, test the ARexx rc variable for a non-zero value. command sethomepath [ ] result new Home Path specification description The sethomepath command instructs MRBackup to adopt a new Home Path specification. If is given, it must be a valid pathname that satisfies the requirements for the Home Path. If is not given, the user is presented with MRBackup's file requester so that a new Home Path may be selected. This command always returns the name of the Home Path in effect upon its return. To check for command failure, test the ARexx rc variable for a non-zero value. command setinfogadget result "OK" description This command provides a means for an ARexx script to place a text in MRBackup's Info gadget. Example: setinfogadget 'I am about to start the backup.' command setlistpath [ ] result new listing pathname 50 MRBackup Professional The ARexx Interface description The setlistpath command instructs MRBackup to adopt a new Listing Path specification. If is given, it must be a valid device name (e.g. PRT:, PAR:, etc.) or file name. If is not given, the user will be presented with MRBackup's file requester to allow a selection. The setlistpath command always returns the Listing Path specification in effect upon its return. To test for an error, check the ARexx rc variable for a non-zero value. command setlogpath [ ] result new log file name description The setlogpath command instructs MRBackup to adopt a new Log Path specification. If is given, it must be a suitable device, console or file specification for MRBackup's log messages. If is not given, the user will be presented with MRBackup's file requester to allow a new selection. The setlogpath command always returns the Log Path specification in effect upon its return. To test for an error, check the ARexx rc variable for a non-zero value. command settestdate [ > result new Test Date specification description The settestdate command instructs MRBackup to adopt a new Test Date specification. If is given, MRBackup attempts to convert it to an AmigaDOS date value (DateStamp). If is not given, MRBackup's date requester is activated to allow the user to enter the new test date. The result will always be the Test Date in effect upon return from this command. If a conversion error occurs, the ARexx rc variable will be set to a non-zero result. 51 MRBackup Professional The ARexx Interface command setformatting result same as getformatting description The setformatting command tells MRBackup what type of floppy disk formatting to employ when doing a backup to floppy disk (AmigaDOS mode only). The must be one of "None", "Quick" or "Normal". The result will always be the formatting option in effect upon return from this command. If a bad is specified, the ARexx rc variable will be set to a non-zero value. command setvoice result "OK" or "FAIL" description The setvoice command enables or disables MRBackup's voice capability, depending upon the value of the parameter. A "YES" value enables voice, while a "NO" value disables it. Example: setvoice "NO" command speak result "OK" or "FAIL" description The speak command requests MRBackup to utter the text contained in the parameter. The is only spoken if MRBackup's voice is enabled (see getvoice/setvoice). Since MRBackup uses the Amiga's translator, you might want to experiment with certain sentences and phrases which aren't handled correctly. For instance, "MRBackup" sounds like "merbackup" while "M R backup" produces more desirable results. command splitfiles result "OK" or "FAIL" 52 MRBackup Professional The ARexx Interface description The splitfiles command enables or disables MRBackup's splitting of "big files", depending upon the setting of the flag. A "YES" value enables file splitting while a "NO" value disables it. Note that this setting is only relevant to the AmigaDOS backup mode. command testarcbits result "OK" or "FAIL" description The testarcbits instructs MRBackup to test or ignore file archive bits during backup operations, depending upon the value of the parameter. If is "YES", only files whose archive bit is clear will be candidates for backup. command utilities result "OK" or "FAIL" description The utilities command activates MRBackup's utilities window. Script execution will be suspended until the user closes the Utilities window. command yesno result "YES" or "NO" description The yesno command provides access to MRBackup's YES/NO requester. The parameter should be a string containing a question. Script execution will be suspended until the user responds by clicking either the YES or NO buttons in MRBackup's requester. Upon return, the result variable will contain the user's response. 53 MRBackup Professional Technical Support Technical Support If you have a problem with MRBackup, think you've discovered an "undocumented feature" or just need help, please call us! We'll do our best to help you get the most out of MRBackup Professional. Please be sure to send in your product registration card! TTR Development, Inc. 1120 Gammon Lane, Madison, Wisconsin (608) 277-8071 54 Table of Contents Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . 4 Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Working Directory . . . . . . . . . . . . . . . . . . . . . 5 CLI Operation . . . . . . . . . . . . . . . . . . . . . . . 5 WorkBench Operation . . . . . . . . . . . . . . . . . . . . 5 Support Files . . . . . . . . . . . . . . . . . . . . . . . 6 The User Interface . . . . . . . . . . . . . . . . . . . . . . 8 The Menu . . . . . . . . . . . . . . . . . . . . . . . . . 8 MRBackup Main Window . . . . . . . . . . . . . . . . . . . 8 The Status Display Window . . . . . . . . . . . . . . . . . 15 The Utilities Window . . . . . . . . . . . . . . . . . . . 19 Utility Command Buttons . . . . . . . . . . . . . . . . . . 21 File Compression . . . . . . . . . . . . . . . . . . . . . . . 24 Compression Method . . . . . . . . . . . . . . . . . . . . 24 Compression Estimating . . . . . . . . . . . . . . . . . . 24 Filter Files . . . . . . . . . . . . . . . . . . . . . . . . . 25 Filter File Format . . . . . . . . . . . . . . . . . . . . 25 Filter Patterns . . . . . . . . . . . . . . . . . . . . . . 25 Backup Filter . . . . . . . . . . . . . . . . . . . . . . . 27 Compression Filter . . . . . . . . . . . . . . . . . . . . 27 Decompression Filter . . . . . . . . . . . . . . . . . . . 28 Backup Operations . . . . . . . . . . . . . . . . . . . . . . 29 The Backup Modes . . . . . . . . . . . . . . . . . . . . . 29 AmigaDOS Backup Mode . . . . . . . . . . . . . . . . . . 29 Fast Disk Backup Mode . . . . . . . . . . . . . . . . . 30 SCSI Tape Backup Mode . . . . . . . . . . . . . . . . . 31 Backup Schemes . . . . . . . . . . . . . . . . . . . . . . 32 The Full Backup . . . . . . . . . . . . . . . . . . . . 32 Incremental Backups . . . . . . . . . . . . . . . . . . 33 The "File Modification Date" Incremental Backup . . . 33 The "Archive Bit" Incremental Backup . . . . . . . . 33 The Project Backup . . . . . . . . . . . . . . . . . . . 34 The Backup Process . . . . . . . . . . . . . . . . . . . . 34 Restore Operations . . . . . . . . . . . . . . . . . . . . . . 36 The MRBackup File Selector . . . . . . . . . . . . . . . . . . 38 55 Table of Contents The ARexx Interface . . . . . . . . . . . . . . . . . . . . . 41 The MRBackup ARexx Port . . . . . . . . . . . . . . . . . . 41 Using ARexx with MRBackup . . . . . . . . . . . . . . . . . 41 MRBackup's ARexx Commands . . . . . . . . . . . . . . . . . 43 Technical Support . . . . . . . . . . . . . . . . . . . . . . 54 56