OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / diskutil / eabackup / readme.doc < prev

Wrap

Text File | 1992-07-09 | 33.3 KB | 669 lines

Version 2.01. July 9, 1992 Table of Contents IMPORTANT INFORMATION Read this first. Contains obligatory legal stuff as well as information about how to reach the author. I. Overview General description of programs. II. Installation and Temporary work files (types, space Usage Consider- requirements, relocation, improving ations performance). EA size reported by EABACKUP vs that reported by CHKDSK. Performance tips. III. Command Syntax Syntax of EABACKUP and EARESTOR. Description of required and optional command line parameters. IV. Suggested Step by step instructions for using Procedure for EABACKUP and EARESTOR along with DOS backup backing up and software to back up and restore a disk.. restoring a disk V. Restoring In-Use Booting from floppies to avoid "in-use" Files conditions on a restore. VI. Backup Files Description of backup files produced by EABACKUP. Copying backup files. VII. Selective Explains how to restore selected Restore directories. Describes the directory structure of the backup index. VIII.Environment Environment variables recognized by Variables EABACKUP and EARESTOR. IX. Examples Backup to hard disk directory, list backup index, delete backed up EA's, restore EA's, restore selected EA's. ** IMPORTANT INFORMATION ** This software is freeware. However, If you find the programs useful a contribution of $5 would be very much appreciated. Every little bit helps, especially when it comes time to pay my Compuserve bill. If you already contributed for an earlier version, thanks! No additional contribution is necessary. Contributions should be sent to the author at the mailing address given at the end of this section. The author grants all recipients of this software and documentation permission to freely copy and use it. Permission to distribute the software to others is also granted on the condition that this "IMPORTANT INFORMATION" section is included in its entirety as part of any such transfer and as long as no additional conditions are added. DISCLAIMER : Please note that this software is provided on an as-is basis. The author does not warrant that the functions contained in this software will meet your requirements or that the operation of the software will be uninterrupted or error free. The author will not be liable for any loss of profit, data, or use of the software, or special, incidental, or consequential damages, or other similar claims, even if the author has been advised of the possibility of such damages. With any backup software, it is good practice to test it on your own equipment, using non-critical data, before considering it for day-to-day use. Inquiries, complaints, suggestions for improvement, and contributions may be directed to the author via Compuserve E-Mail or by letter. The appropriate addresses are : Compuserve ID : 71041,736 Mailing Address : David Thorn 4056 NE 86th Street Seattle, WA 98115 ** END OF IMPORTANT INFORMATION SECTION ** I. Overview EABACKUP and EARESTOR are utility programs designed to backup and restore extended attributes associated with OS/2 files. The programs are run from the command line in an OS/2 windowed or fullscreen session. All extended attributes in a single directory or in a directory and its sub-directories may be backed up in one pass. Backups may be made to a fixed disk or to a floppy. Individual files and directories may be restored selectively and an option is provided that allows previously backed up extended attributes to be deleted. Extended attributes (EA's) were introduced with OS/2 1.2. They are objects associated with, but not actually part of, many OS/2 files. OS/2 commands and utilities (such as COPY, XCOPY, BACKUP, and RESTORE) recognize EA's and maintain the integrity of the association between an EA and its parent file. For example, when a file is copied or moved using one of these commands, they copy or move the EA as well. In contrast programs written to run under DOS, including many DOS backup programs, do not recognize the existence of EA's. Indescriminant use of these programs can result in "lost" EA's (a lost EA is one that has become disconnected from its associated file). Often lost EA's are only an annoyance, tieing up disk space to no purpose and causing CHKDSK errors. More serious problems may occur, however, if EA's are disconnected from certain OS/2 system files or files needed by OS/2 applications that recognize and use EA's. In order to use EABACKUP and EARESTOR effectively it is important for you to understand a little about how EA's are connected to their files, where they reside, and what kind of EA related errors can occur. EA's for all files on a FAT drive are contained in a single, hidden file called "EA DATA. SF" in the drive's root directory. A file is connected to its EA through a pointer, contained in the file's directory entry, into "EA DATA. SF". This pointer resides in bytes that are unused in DOS systems. The two most common EA related errors are lost EA's and cross-linked EA's. Files lose their EA's when a program that manipulates directory entries (such as backup/restore software) does not preserve this directory pointer leaving the EA's stranded on "EA DATA. SF". Cross-linking, the second type of error, occurs when two or more files point to the same location in "EA DATA. SF". Deleting "EA DATA. SF", for example, will leave directory entries with pointers into a (now) non-existent EA DATA file. When new files with EA's are subsequently added, the EA DATA file will regrow leading to the likelihood that an old and new pointer will end up pointing to the same (new) EA. Running CHKDSK /F can "fix" lost EA's (the orphaned entries in EA DATA are simply deleted- the file that "lost" the EA still won't have one). Cross linked EA's are not "fixed" by CHKDSK since OS/2 does not know who the legitimate owner is. Cross linking can be prevented by running CHKDSK /F to clean up the pointers whenever "EA DATA. SF" is deleted. In order to avoid problems like these, IBM supplies the EAUTIL.EXE utility with the OS/2 1.x and 2.0 base systems. This utility can split an EA from its parent file and place it in a holding file that a non EA-aware program can recognize and manipulate. It can also reconnect an EA contained in a holding file to its parent. One could conceivably use EAUTIL to allow a non EA-aware backup program to backup EA's. Unfortunately, each invocation of EAUTIL can only process a single file. Thus EAUTIL would have to be invoked a separate time for each file to be backed up. This is clearly impractical when large numbers of files are involved. EABACKUP and EARESTOR are designed to overcome this limitation of EAUTIL. EABACKUP automatically extracts the EA's of every file in a single directory or a directory and its sub-directories. The extracted EA's are copied to a single backup file on a floppy or hard disk. EARESTOR uses this backup file to restore the EA's to their parents. Note that these programs use OS/2 2.0 functions to backup and redstore EA's so they will not run under OS/2 version 1.x or DOS. NOTE: If your drive is FAT and your backup software backs up AND restores an exact image of your directory entries (INCLUDING the "unused bytes" that are really occupied by the EA pointer), backs up and restores empty directories, successfully backs up and restores "EA DATA. SF", and you never do partial backups or restores (ie you do full drive backup/restore only) then you do not need to back up the EA's separately using EABACKUP and EARESTOR. If any of these conditions are not met, however, and you care about your EA's then you will need to use this software (or something like it) until such time as you get OS/2 aware backup software. II. Installation and Usage Considerations 1) EABACKUP and EARESTOR both use temporary work files as part of their processing. There are two types of work files. The first is used to provide a scratch pad area for the backup index and the second is used to provide a temporary holding area for EA's as they are moved to and from the backup disk. The size of the EA holding file should not exceed 64K which is the maximum size of EA's under OS/2 versions 1.x and 2.0. The maximum size of the index scratch pad area varies depending on the number of files and directories processed and the size of the file names. 100K should be more than sufficient for most situations. The default location of EABACKUP's work files is the root directory of the source disk. For EARESTOR it is the root directory of the destination disk. Alternate locations for both types of work files can specified by using the EATEMPW and EATEMPF environment variables or the "/W" and "/F" command line options. EATEMPW and /W relocate the index scratch pad while EATEMPF and /F do the same for the EA holding file. Performance improvements can be obtained by using EATEMPF or /F to relocate the holding file to a virtual (RAM) disk (for information on setting up a RAM disk see the OS/2 command reference). The minimum size of this disk should be the size of the largest possible EA (64K). 2) When backing up all EA's on a FAT based drive, the total length of the EA's reported by EABACKUP will generally be considerably less than the amount of allocated EA space reported by CHKDSK. This is normal. The number reported by EABACKUP represents the amount of the space reserved for EA's that actually contained data. The difference between the EABACKUP and CHKDSK numbers represents space that was allocated but unused. There normally is a large amount of unused space since the minimum allocation for an EA is equal to the cluster size for the disk. The cluster size varies depending on the disk capacity but is usually 2048 bytes or more. A 100 byte EA will allocate 2048 bytes, 1948 of which will be unused (and unusable unless that particular EA expands). 3) A number of things can be done to improve performance. These are listed in decreasing order of efficacy. a) Use the hard disk as the target for EABACKUP files or the source of EARESTOR files. After they are created backup files produced by EABACKUP may be copied to a floppy or backed up using normal DOS backup software (see section V. for more on backup files). b) Use the /F command line option or the EATEMPF environment variable to direct the EA holding file to a RAM disk of 64K in size or more (see VDISK.SYS in the OS/2 Command Reference on setting up a RAM disk). III. Command Syntax In the following, source_path, destination_path, and path_name should be replaced by a valid OS/2 path name (with or without a drive specifier) or a drive specifier alone (eg A:, B:, etc). If a path name is specified without a drive specifier then EABACKUP assumes the source drive and EARESTOR assumes the destination drive. If a drive specifier is specified without a path then the current directory on that drive is assumed. source_path and destination_path are required. All other parameters are optional. EABACKUP.EXE is invoked from the OS/2 command line as follows : |-----------------------------------------------------------------| | EABACKUP source_path destination_path | | | | /S /W=path_name /F=path_name | | | | /Q /I | |-----------------------------------------------------------------| Where : source_path The path name of the highest level (required) directory to back up. destination_path The path name of the directory that will (required) receive the backup files. If backing up to a floppy, only the drive specifier (A:, B: etc) should be used. /S Optional switch which, if specified, instructs EABACKUP to process all sub- directories below the directory indicated in source_path as well as source_path itself. /W=path_name Used to specify location of temporary work /F=path_name files. /W specifies the location of the index scratch pad and /F specifies the location of the temporary EA holding area (see Installation Considerations item 2 for further information). If these parameters are omitted then the directories specified in the environment variables EATEMPW and EATEMPF determine the location of the work files. If those environment variables are not specified then the work files will be located in the root directory of the source drive. /Q Causes EABACKUP to operate in "Quiet" mode. This suppresses attention getting tones generated when an error occurs or when an operator reply is required. /I This causes EABACKUP to continue without interruption when an EAUTIL.EXE error is detected (this normally happens when a file is in-use). If this parameter is omitted EABACKUP will pause and ask the operator for permission to proceed despite the error. EARESTOR.EXE is invoked from the OS/2 command line as follows : |-----------------------------------------------------------------| | EARESTOR source_path destination_path | | | | /S /W=path_name /F=path_name | | | | /D /M=file_mask /B=path_name /L /Q /I /X | |-----------------------------------------------------------------| Where : source_path The path name of the directory containing (required) the backup files. If restoring from a floppy, only the drive specifier (A:, B:, etc) should be used. destination_path The path name of the directory that will be (required) the restore target. /S Optional switch which, if specified, instructs EARESTOR to process all sub- directories below the directory indicated in destination_path as well as destination_path itself. /W=path_name Used to specify location of temporary work /F=path_name files. /W specifies the location of the index scratch pad and /F specifies the location of the temporary EA holding area (see Installation Considerations item 2 for further information). If these parameters are omitted then the directories specified in the environment variables EATEMPW and EATEMPF determine the location of the work files. If those environment variables are not specified then the work files will be located in the root directory of the source drive. /D Instructs EARESTOR to delete EA's on the destination drive that correspond to those contained on the backup file. The EA's on the backup file itself are not affected. Note that an EA that appears on the destination drive but does not appear in the backup file will not be deleted. If /D is not specified EARESTOR will restore the EA's on the backup file to the destination disk. /M=file_mask Instructs EARESTOR to restore only those EA's associated with files whose names match the file_mask. The file_mask should be replaced by a valid OS/2 file name which can contain wild cards (no directory should be specified). If this parameter is not specified then all files will be restored (equivalent to specifying /M=*). /B=path_name Instructs EARESTOR to skip to the backup file directory named in path_name before starting the restore. The path_name should not contain any drive information and should be relative to the first directory in the backup file. Only EA's in the backup directory indicated by path_name (and its children if /S is specified) will be restored. For example if the backup was performed on a disk with the following directory structure : D0 | |---------| | | D1 D2 | |--------| | | D1A D1B then /B=D1 will restore D1, D1A, and D1B to the destination_path. Similarly, /B=D1\D1A will restore D1A. Note that the name of the first backup directory (D0 in this example) is never included as part of path_name. /L Instructs EARESTOR to list the backup index. If this option is specified then the backup index will be listed but no other action will be performed. By default, the listing is directed to the video display. It can be redirected to another device in the normal way. /Q Causes EARESTOR to operate in "Quiet" mode. This suppresses attention getting tones generated when an error occurs or when an operator reply is required. /I This causes EARESTOR to continue without interruption when an EA error is detected (this normally happens when a file is in- use or can't be found). If this parameter is omitted EARESTOR will pause and ask the operator for permission to proceed despite the error. /C This causes EARESTOR to create directories it finds on the backup but not on the target. This is mainly for use if you have DOS backup software that doesn't back up empty directories. If so, EARESTOR can recreate them for you if you specify /C. /X This causes EARESTOR to skip the restore of the EA associated with the starting directory. For example, if you specify : "EARESTOR B: F:\DIR1 /X", the EA associated with DIR1 itself (if any) will not be restored. All EA's associated with files and directories under DIR1 will be restored as usual. IV. Example Backup/Restore Procedure Here's the procedure I use to backup my hard disk (for the purposes of the discussion I'll call it "F:" using EABACKUP & EARESTOR and my DOS backup software : BACKUP 1) Do a CHKDSK F: to make sure everything's OK. 2) Run "EABACKUP F:\ F:\ /s". This will create a EA backup file in the root directory of your F: drive. 3) Boot DOS and run your backup software to back up drive F:. Be sure to back up the EA backup files produced in step 2 (their names are EA@BDATA.EAB and EA@INDEX.EAB). There's no need to back up "EA DATA. SF" but there's no harm in doing so. You are now done. RESTORE 1) Boot DOS and run your restore software. Be sure to restore the EA backup files. 2) Boot OS/2 (from floppies if necesssary). Do a CHKDSK F: /f to get rid of any lost EA's that may have been created by the restore. If you restored "EA DATA. SF" in step 1 then this step is necessary to get rid of the old EA's on "EA DATA. SF" that are no longer connected to their files. If you don't do this then the old EA's will take up space for no purpose and your "EA DATA. SF" file will end up being twice as big as it needs to be (at least until the next CHKDSK /f is run against the drive and the old "lost" EA's are deleted). 3) Run "EARESTOR F:\ F:\ /s" to reconnect the EA's to their files. V. Restoring In-Use Files EARESTOR can not process EA's associated with files that are in use by another process. If you encounter this condition while performing a restore you can choose to ignore it or you can retry the backup or restore after identifying and terminating the process responsible. If termination of the process is not possible, as is the case when the condition is caused by OS/2 itself, and you still wish restore the EA you must use an alternate procedure, described here, that involves booting the system from the OS/2 installation diskettes. The procedure is as follows : 1) Boot OS/2 from drive A: using the OS/2 installation diskette(s). When the boot process is complete (this will involve 1 disk change for OS/2 version 2.0) and the first installation screen is displayed, cancel the installation process by using the Esc key. This should leave you at the A> prompt. 2) Run EARESTOR. Performance can be improved by using the /F parameter to direct the temporary EA holding file to a RAM disk. The version of OS/2 2.0 that I had access to when I wrote this program did not create a RAM drive when booting from the floppy. To create one : 1) Create a working copy of the diskette(s) used in the boot process. 2) Check the CONFIG.SYS file (located on the last diskette used when booting) and look for a "DEVICE=VDISK.SYS..." entry. If one is present then OS/2 is already creating a RAM disk. If the disk is at least 64K in size then you can use it as-is. If it is smaller you should change the parameters to make it 64K (see the VDISK.SYS topic in the OS/2 Command Reference for information on how this is done). If there is no VDISK.SYS then proceed to the next step. 3) Add a DEVICE=VDISK.SYS statement to CONFIG.SYS. Make sure that VDISK.SYS is on the same floppy as CONFIG.SYS. If it isn't you must copy it there from the OS2 directory on your hard drive. 4) Boot from the floppy, determine the drive letter associated with the RAM drive, and point to it using the /F option when the backup or restore is run. VI. Backup Files A backup created by EABACKUP consists of two files, a data component named EA@BDATA.EAB and an index component named EA@INDEX.EAB. If the backup is to a diskette and there is insufficient room on a single diskette to hold all the backup data or the index, additional instances of EA@BDATA.EAB and/or EA@INDEX.EAB are created on overflow volumes. The backup files may be copied using normal commands. A backup on a fixed disk can be copied to a floppy as long as the data and index components are kept together and will fit on a single floppy. Similarly, a backup residing entirely on a single floppy may be copied to a fixed disk. In this case the data and index components must each be copied to the same directory. Backups residing on multiple floppies can not be run from a fixed disk. VII. Selective Restore Backup files produced by EABACKUP preserve information about the directory structure of backed up data. This information consists of the names of any sub-directories that were backed up as a result of using the /S parameter but does not include the name of the source drive or initial directory. This is illustrated by the following example. If the command : EABACKUP E:\DIR0 A: /S is issued, the results are as follows : Original E:\ Structure (no name) Structure | on backup | | file | ------------ ----------------- | | | | | | | | | | DIR0 DIR1 DIR0_A DIR0_B DIR0_C | | | | ---------------- DIR0_BA | | | | | | DIR0_A DIR0_B DIR0_C | | DIR0_BA This relative nature of the backup's structure allows EA's to be restored to any initial directory on any drive as long as the directory structure under the new target location corresponds to that under the original data source. Using the example above, the following command would be successful : EARESTOR A: C:\NEW_DIR /S if the target directory structure was : C:\ | | NEW_DIR | --------------- | | | | | | DIR0_A DIR0_B DIR0_C | | DIR0_BA The /B parameter of EARESTOR allows a restore to selectively restore a directory other than the initial one on the backup. The data in directories hierarchically above the directory specified in the /B option is ignored. Again using the previous example, specifying : EARESTOR A: C:\NEW_DIR\DIR0_B /B=DIR0_B /S would selectively restore EA's in C:\NEW_DIR\DIR0_B and C:\NEW_DIR\DIR0_BA. The /M parameter causes EARESTOR to restore only those EA's whose parent files match the file name mask specified in /M. The file name mask specified in /M can contain wild card characters. For example, specifying : EARESTOR A: C\NEW_DIR /S /M=*.EXE would only restore EA's associated with files with an EXE extension. VIII. Environment Variables EATEMPF and EATEMPW Two environment variables named EATEMPF and EATEMPW are recognized by EABACKUP.EXE and EARESTOR.EXE. They have the same meaning as the /F and /W command line parameters (see the Command Syntax section for a description). To use them, include the following lines in your CONFIG.SYS file or type them on the command line prior to running EABACKUP or EARESTOR : -------------------------------- | SET EATEMPW=path_name | | | | SET EATEMPF=path_name | -------------------------------- Where path_name should be replaced by a valid OS/2 path name. The /W and /F command line options, if specified, override the value of the corresponding environment variable. IX. Examples 1) Backup EA's from current directory on the C drive to a floppy on the A drive using the /S option to back up subdirectories. EABACKUP C: A: /S 2) Backup EA's from C:\DIR0 and its subdirectories to hard disk directory E:\BKUP with the EA holding file being directed to the G: drive and the index work file being directed to the E:\JUNK directory. EABACKUP C:\DIR0 E:\BKUP /S /F=G: /W=E:\JUNK 3) List backup index for data backed up in Example 2. Redirect output to a printer : EARESTOR E:\BKUP C:\DIR0 /S /L > PRN: Pipe output to MORE filter : EARESTOR E:\BKUP C:\DIR0 /S /L | MORE 4) Delete from their parents, EA's that were backed up in Example 2 : EARESTOR E:\BKUP C:\DIR0 /S /D 5) Restore EA's backed up in Example 2 : EARESTOR E:\BKUP C:\DIR0 /S 6) Restore only those EA's backed up in Example 2 whose parent files have an EXE extension : EARESTOR E:\BKUP C:\DIR0 /S /M=*.EXE