Black Box 4

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

/ Black Box 4 / BlackBox.cdr / fileutil / eabk10.arj / README.DOC < prev

Wrap

Text File | 1992-04-21 | 30.4 KB | 610 lines

Version 1.01. April 21, 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 Pointing to EAUTIL.EXE using /P. Temporary Usage Consider- work files (types, space requirements, ations relocation, improving 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. Backing Up In-Use Advice on handling in-use conditions that files arise. V. Backup Files Description of backup files produced by EABACKUP. Copying backup files. VI. Selective Restore Explains how to restore selected directories. Describes the directory structure of the backup index. VII. Environment Environment variables recognized by Variables EABACKUP and EARESTOR. VIII. Examples Backup using the /P option, 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 an ENTIRELY OPTIONAL contribution of $5 would be appreciated. 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 : 71040,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. To operate, EABACKUP and EARESTOR require the use of the IBM program EAUTIL.EXE supplied with your OS/2 version 1.x or 2.0 base operating system. 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 (for a more detailed discussion of EA's see EADAT2.ZIP in library 2 of the Compuserve IBMOS2 forum). To provide a solution to this problem, 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 invokes EAUTIL to extract 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. Since these programs invoke EAUTIL to actually perform the extraction and reattachment of the EA's they should work for any release of OS/2 that provides a version of EAUTIL. II. Installation and Usage Considerations 1) EABACKUP.EXE and EARESTOR.EXE may be run from anywhere but be aware that they must have access to the IBM utility EAUTIL.EXE supplied with OS/2. They locate this utility by searching the directories specified in the "PATH" environment variable or alternatively in the directory specified in the "/P" command line option (see Command Syntax below). 2) 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. Significant performance improvement 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). 3) 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). 4) A number of things can be done to improve performance. These are listed in decreasing order of efficacy. a) 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). b) 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). c) Adjust DISKCACHE parameters to reduce load time for EAUTIL.EXE or copy EAUTIL.EXE to a RAM disk and point to it using the /P command line option or the PATH environment variable. 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 /P=path_name /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. /P=path_name Path name of directory containing EAUTIL.EXE. If this parameter is omitted then EAUTIL.EXE must reside in one of the directories specified in the PATH environment variable. /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 /P=path_name /W=path_name /F=path_name | | | | /D /M=file_mask /B=path_name /L /Q /I | |-----------------------------------------------------------------| 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. /P=path_name Path name of directory containing EAUTIL.EXE. If this parameter is omitted then EAUTIL.EXE must reside in one of the directories specified in the PATH environment variable. /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 EAUTIL.EXE error is detected (this normally happens when a file is in-use). If this parameter is omitted EARESTOR will pause and ask the operator for permission to proceed despite the error. IV. Backing Up In-Use Files EABACKUP and EARESTOR can not process EA's associated with files that are in use by another process. If you encounter this condition while performing a backup or 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 to backup 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) Copy the IBM supplied EAUTIL.EXE from the OS/2 directory of the hard disk on which you installed OS/2 to a drive or directory that will not be involved in the backup. 2) 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. 3) Run EABACKUP or EARESTOR. Use the /P option to point the program to the directory to which you copied EAUTIL.EXE in Step 1. Also, use the /F and /W parameters to relocate the work files to a directory or drive that will not be involved in the backup or restore (an empty directory set aside for this purpose would be ideal). Performance can be SIGNIFICANTLY 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 (but OS/2 1.3 does). 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. V. 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. VI. 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. VII. 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. Examples 1) Backup EA's from current directory on the C drive to a floppy on the A drive using /P to point to a particular version of EAUTIL.EXE in the E:\BIN directory and using the /S option to back up subdirectories. EABACKUP C: A: /P=E:\BIN /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