Simtel MSDOS 1993 May

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

/ Simtel MSDOS 1993 May / SIMTEL_0593.ISO / msdos / archivrs / dwc_a501.exe / DWC.DOC < prev next >

Wrap

Text File | 1988-08-29 | 36.4 KB | 938 lines

DWC Archive Utility Release A5.01 5/31/88 by Dean W. Cooper (C) Copyright 1986,1987,1988 by Dean W. Cooper ALL RIGHTS RESERVED NOTE: The source code to the compressor/decompressor modules of DWC, as of this release, is now considered Proprietary Information and will no longer be distributed. However, the executable version of DWC, and the source code that is not part of the compressor/decompressor modules, is still available free of charge for both private and commercial use and may be distributed provided NO fee is charged. Updates are available by sending a SASE with a floppy disk to: Dean W. Cooper, 18028 Cottage Garden Dr #103, Germantown, MD 20874 Contributions (of any kind) to help improve this program are welcomed. INTRODUCTION: ------------ DWC is an archive utility patterned after ARC, (C) Copyright System Enhancement Assoc., that has many improvements and added features. Please note, however, that DWC is Not file compatible with ARC and cannot be used to add or extract ARC files. Basic improvements include compression speed and size, and error handling. Also, DWC includes all of ARC's commands and options (except the run command) and adds many new ones along with small improvements over the old ones. These are detailed below. DWC attempts to emulate ARC's interface and functionality so Users do not need to learn a new style. New features are added as a super-set to ARC's features. An archive utility is a program that lets a User take a set of files, compresses them, and put them together into one DOS file. This DOS file is called the archive. DWC is an archive utility program that can be used to add files to an archive, extract files from an archive, list the files that are contained in the archive, and to delete one or more files in the archive. USAGE: ----- When DWC is run with No arguments, the following usage information is displayed: DWC <command>[[option]...][g<passwd>] <archive>[/s] [<file>[/s] ...] Commands: Options: a Add files to archive <digits> Max number of entries in directory m Move files to archive s Suppress compression of file u Update files to archive b Retain backup copy of archive f Freshen files to archive n Suppress normal program messages d Delete files in archive w,! Suppress (w)arnings, or all (!) messages e,x Extract files from archive q Query on each add or extract p Extract to standard output o Only extract files with newer dates l List files in the archive i Inquire comment field on each add v Verbose list of files z,y Optimize for size (z), or speed (y) t Test integrity of files = Make archive date equal newest file c Convert files in archive j Merge archives on add h Name header file of archive r Record directory on add, use on extract i,k Edit comment field of files g Encrypt on add, decrypt on extract = Make date equal newest file - Negate the following option /s Extend wildcard expansion to all sub-directories DWC can be run three ways as follows: 1) DWC by itself (displays above usage list) 2) DWC followed by, - An archive file name (implies default command, usually list 'l') 3) DWC followed by, - One of the commands and None, one, or more of the options - An archive file name - An optional list of files Normal DOS-style wildcards are allowed in both the archive's name and all file names in the file list. If wildcards are given in the archive's name and more than one archive is matched, then the given command is simply run once for each archive that matches. All commands work with the specified list of files. This list of files can be only one of two things: either a list of DOS files to add to the archive, or a list of one or more files in the archive to operate on. If no files are given in the file list, then "*.*" is assumed. ADD COMMANDS: ------------ These are commands that "add" DOS files to the archive. They are: a Add - Adds all files in file list to the archive. m Move - Adds all files in file list to the archive and then deletes them from DOS. u Update - Adds only the files in the file list that are not already in the archive or that have a more recent date then the ones in the archive. f Freshen - Adds only the files in the file list that are already in the archive and have a more recent date then the ones in the archive. If "*.*" is given for the the file list (or no files are listed), then all files in the current directory are used for the file list. For instance: DWC a test Adds all files in the current directory to the archive "test.dwc" Paths may also be specified in order to add files from other drives and directories: DWC u test a:*.doc \include\sys\*.h *.c This adds all "doc" files from the current directory on drive A, all "h" files from the directory "\include\sys" on the current drive, and all "c" files in the current directory to the archive test, except for those files that are older than files already in the archive. Adding a file to an archive that already has a file in it with the same name, will cause the file in the archive to be replaced. An archive cannot contain two files in it with the same name. Also, the archive (and its backup) that is being added to is always auto- matically eliminated from the file list and cannot be added to itself. ADD VARIATION COMMANDS: ---------------------- These commands are variations on the "add" command: d Delete - (Negative Add) Deletes all files in the file list from the archive. c Convert - (Internal Add) Temporarily extracts all files in the file list and then re-adds them. i,k Comment - (Attribute Add) Edits the comment field of all files in the file list in the archive. A file list must be given for the delete command as, otherwise, a null file list would cause all files to be deleted. The convert command can be used to convert the files from one storage method to another. Files can be added during the day in un-compressed form and then later converted to compressed form. Or they could be converted from un-encrypted form to encrypted form (note that one cannot convert from encryption using one password to encryption using another password.) The comment command is used to add a short comment to each file stored in the archive. The comments are displayed when the archive is listed with the 'l' command. EXTRACT COMMANDS: ---------------- These are commands that extract files from the archive: e,x Extract - Extract all files in the list from the archive to DOS files. p Print - Extract all files in the list from the archive to standard output (the screen). This can be re-directed to the printer. t Test - Extract all files in the list from the archive to the null output (nowhere) in order to test the integrity of the files. To extract all the files in an archive, just enter: DWC e test This will extract all files in the archive "test". To extract just some of the files in an archive, just list them: DWC t test *.h *.c This will test all the "h" and "c" files in the archive "test". The test command will uncompress the files, checking for valid CRC's and other integrity checks. The extract command can include directory paths to specify where to put the extracted files. For example: DWC x test \some\where\*.txt fred* b:\*.txt sam* This will extract all "txt" files and all "fred" files to the directory "\some\where", and it will extract all "txt" files (a second time) and all "sam" files to the root directory of drive B. Note, that the directory used on one file is remembered until it is overridden by another directory. If you extract a file and the file already exists in DOS, then you will be warned and asked if you want to overwrite the existing file. The warning message tells if the existing file is older, newer, or the same date as the file being extracted. If warnings are suppressed, then it is assumed you want to overwrite the file. However, if there is any error in extracting the file, then you will be prompted if you really want to overwrite the file with a corrupted one. Thus, one does not need to worry about accidentally overwriting a file. LIST COMMANDS: ------------- These are commands that list the files in the archive: l List - Lists all files in the file list along with their comments. v Verbose - A more detailed (verbose) list of the files in the file list. The list command displays as follows: Name Length Date Comment ============ ======== ========= ============================================ CHKDSK.COM 6468 19 Oct 83 System command to check disk integrity DEBUG.COM 12223 19 Oct 83 Machine language debuger DISKCOPY.COM 1703 30 Jan 84 Makes an image copy of one disk to another EDLIN.COM 8080 19 Oct 83 DOS line oriented editor ==== ======== Total 4 28474 "Length" is the size of the file when un-compressed, and "Date" is the date that DOS had for the file when it was added to the archive. "Comment" is the User added comment field for each file. Please note, that the "r" option will make the list command display the directory path saved with each file instead of the comment field. The verbose command displays as follows: Last modified: 18 Dec 86 8:26a Name Length Stowage SF Size now Date Time Pass ============ ======== ======== ==== ======== ========= ====== ==== CHKDSK.COM 6468 Crunched 17% 5419 19 Oct 83 7:51p -- DEBUG.COM 12223 Crunched 13% 10680 19 Oct 83 7:52p Pass DISKCOPY.COM 1703 -- 0% 1703 30 Jan 84 12:59a -- EDLIN.COM 8080 Crunched 52% 3912 19 Oct 83 7:51p -- ==== ======== ==== ======== Total 4 28474 24% 21714 The verbose list includes the method of storage ("Stowage") which is either: -- No compression Crunched Lempel-Ziv compression The stowage factor, "SF", is the percent the file was compressed. "Size now" is the size of the file in the archive. "Pass" is either "--" for not encrypted, or "Pass" for encrypted. The date given for "Last modified" is the date the archive was last added to or modified. ATTRIBUTE COMMANDS: ------------------ These are commands that modify an attribute of the archive: h Header - Names one file in the archive to be the "header" file of the archive. The header file is extracted and displayed before a listing of the archive. There is no restriction to the size or contents of this file. = Equal - Resets the date of the archive to equal the newest file in the archive if No file is specified in the file list. Or resets the date to equal the date of one file given in the file list. ADD OPTIONS: ----------- These are options that modify the "add" commands: s Suppress - Suppresses compression of files when they are added. Just an image copy will be added. (Does not apply to the delete or comment commands.) b Backup - Creates a backup copy of the archive before it is changed by adding to it. i Inquire - Prompts User for comment fields for each file as they are added. (Does not apply to the delete command.) z Size - Optimizes compression of files for smaller size when they are added. The default compression technique is optimized for speed and requires less memory. (Does not apply to the delete or comment commands.) y Speed - Uses the compression algorithm that is designed for speed of compression as compared to size. This algorithm requires less memory then the "size" option. (Does not apply to the delete or comment commands.) = Equal - Makes the date of the new archive equal the date of the newest file in the archive. j Merge - When a file in the file list is an archive, it is merged into the new archive instead of being added like a normal file. (Does not apply to delete, comment, or convert.) EXTRACT OPTIONS: --------------- These are options that modify the "extract" commands: o Only - Causes only the files with more recent dates than the DOS files they would overwrite to be extracted. The warning that a file is going to be overwritten, is automatically suppressed. BOTH ADD & EXTRACT OPTIONS: -------------------------- These are options that modify both the add and extract commands: q Query - Queries the User for confirmation before each add or extract is performed. (Applies to the print command but not the comment command.) r Record - Records what DOS directory the file was in when added to the archive and then extracts the file to that directory when extracting unless overridden. Can be used with the list command to display the directories recorded for each file. (Does not apply to delete, comment, or convert.) g Garble - This option must be the last option listed. The characters following it are interpreted as a password. Using this password, files are encrypted when added and decrypted when extracted. If a file is encrypted and one attempts to extract it without supplying a password, he will be warned. n Notes - Normal screen output is suppressed by sending it to the null output. w Warnings - Warning messages are suppressed such as the warning that an extracted file will overwrite an existing DOS file. Also suppressed is the warning that the directory one is extracting to does not exist. In this case, the directory is automatically created. ! All - All messages will be suppressed including notes, warnings and errors. This is useful in a batch file that can check for any error codes returned by DWC. The only things that can't be suppressed are the query option, the inquire option/command, and the list commands. Examples: DWC agxyz test *.txt This will add all "txt" files in the current directory to the archive "test". They will be encrypted using the password "xyz" (case insensitive). The attribute that the files were encrypted is recorded, but the password is not saved. Thus, care must be taken using this option, as it is unlikely that the file could be recovered if the password was lost. To extract these files, just type: DWC egxyz test The record option is a good way to backup an entire directory including all sub-directories. When restoring, the directories will automatically be created. For example: DWC ar backup \source/s This will add all files in the directory "source", and all of its sub- directories, to the archive "backup". The names of the directories that the files are in will be recorded with the files in the archive. To reproduce the entire directory tree on another drive, one could type: DWC erw backup d: This will extract all the files in the archive "backup" to drive D. The files that have a directory recorded with them will be put in those directories on drive D. If the directories do not exist, they will automatically be created. If the "warning" option was not used, you would be prompted whether or not you want the directories created. If the "record" option was not used, all files would simply be extracted to the current directory of drive D. If the following was typed: DWC erwq backup d:*.c a:\*.c This would extract all "c" files in the archive to drive D, to their recorded directories, and create the directories automatically. Then all "c" files would be extracted (a second time) to the root directory of drive A ignoring what directories were recorded with the files. As each file is extracted, the User would be be prompted for confirmation as to whether or not that file should be extracted. Please note that currently, no two files with the same name can be added to the archive even though they are in different directories. This will be corrected in a future release. MISCELLANEOUS OPTIONS: --------------------- - Negate - Negates or reverses the effect of the option following. This is useful to override options that were prepended automatically when using the DWCADD environment variable. For example: "-b" means don't do backups "-s" means don't suppress compression "-w" means don't suppress warning messages "-z" means don't optimize for size (use speed) .. etc .. <digits> - This number is the maximum number of entries allowed in the archive's directory when loaded into memory. The default is 900 which requires about 30K, but can be set from 100 to 1800. WILDCARDS: --------- Wildcards can be used in both the archive name and all files in the file list. If a name used is the name of a DOS directory, then "*.*" is assumed. For example: DWC a test dos If "dos" is a file, then it will be added as normal. But if "dos" is a directory then all files in that directory will be added just as if the following command was given: DWC a test dos\*.* This is the same for the archive name. If "test" is the name of a directory, then all archives in that directory will be operated on just as if the following command was given: DWC a test\*.* dos\*.* Wildcards in the archive name are more common when listing or extracting. For example: DWC ewo a:* \include\*.h *.lib \doc\*.doc This will extract from all archives on drive A. Only the files with more recent dates, or that do not already exist, will be extracted and all warnings (such as "File not found" warnings) will be suppressed. "h" files and "lib" files will be extracted to the directory "\include", while "doc" files will be extracted to the directory "\doc". The "/s" option may be tacked onto the end of any archive name or file name to extend wildcard expansion to all sub-directories. For example: DWC a test dos\*.txt/s This means to add all "txt" files in the "dos" directory and all directories in the "dos" directory and all directories in those directories, and so on. One can add all files on a drive by giving the command: DWC a test \*.*/s Or even more simply: DWC a test \/s Or: DWC a test a:\/s Which adds all files in all directories on the A drive. PATHNAMES: --------- All file path names may be formed using either back slashes or forward slashes. Thus, the following two commands are identical: DWC a c:\util\save d:\stuff\*.* DWC a c:/util/save d:/stuff/*.* RAMDISK SUPPORT: --------------- When adding to an archive, a temporary archive is created and then re-named to the new archive when the add is successfully completed. This archive is normally put in the current directory, but can be put in any other directory by specifying the path in an environment variable. The following environment variables are searched in order for a path to use: DWCTEMP ARCTEMP TEMP TMP To make DWC put the temporary archive on a ramdisk on drive D, just type: set DWCTEMP=D: Another temporary file that DWC uses is a temporary extract file. When a file is extracted, it is first extracted to a temporary file and, if successful, re-named to the actual extracted file. (Note, this only happens if an existing file is being overwritten.) When re-naming a temporary file from one drive to another, there may be an out of disk space error. In this case, the file is re-named in place and the User is warned what happened to his file. If there is an error re-naming the file in place, then the User is told the name of the temporary file where his data is now at. Also, the control-C interrupt is handled, and all temporary files are deleted before the program terminates. ENVIRONMENT VARIABLES: --------------------- Besides the environment variable used to indicate where the temporary files should be place, there are three other environment variables as follows: DWCDEF - Defines the default command and options to execute when none are given. DWCADD - Defines options to prepend to the ones given on the command line. TZ - Sets the time zone for your computer. (This is a standard MicroSoft C library environment variable.) For example: C>set DWCDEF=x Will cause an archive to be automatically extracted when no command is given as in: C>dwc test Here all files from the archive "test" will be extracted because the default command is "x" as defined be the environment variable DWCDEF. If this environment variable is not set, the default command will be 'l', or the list command. C>set DWCADD=zq Will cause the options "z" and "q" to be prepended to whatever options the user supplies on the command line. The command: C>dwc a test will in effect become, C>dwc zqa test Here, files will be added using the "size" algorithm and the user will be prompted before each file is added. Please note that options are parsed in left to right order, so that the following command: C>dwc ay test would override the effect of the "z" option. Also, options that do not apply for a given command are simply ignored. The environment variable TZ is used to set the time zone that you are in. This effects how a file's time (and possibly date) is displayed when files are listed with the 'v' and 'l' options and effects what date and time the files are given when they are extracted. Say someone who lives in New York adds a file dated Nov 23, 87 - 9:19p to an archive and then gives the archive to a friend in California. Normally, if neither user has set the TZ environment variable, the file when extracted in California would be given the same date and time. However, if both users have set the TZ variable appropriately, then the file extracted in California would be given the time 6:19p, which shows the correct time of its creation. The default time zone is Pacific daylight savings time. This is denoted as follows: SET TZ=PST8PDT The value of TZ must be a three-letter time zone name (such as EST), followed by a signed or unsigned number giving the difference between Greenwich mean time and the local time zone. The number may be followed by a three-letter daylight-saving-time zone name (such as EDT). MEMORY: ------ Memory requirements vary. Given lots of memory, the program will use the following amounts: "size" compression - 410K "speed" compression - 320K decompression - 306K Those figures include two very large buffers that can be as large as 63K each. However, if memory does not permit, then these buffers will be automatically reduced so that memory requirements are as follows: "size" compression - 290K "speed" compression - 198K decompression - 182K Now this assumes the default size of the in-memory directory which at 900 entries requires about 30K. This can be reduced to 100 entries or raised to 1800 entries. Say it's reduced to 300, that would give us: "size" compression - 270K "speed" compression - 178K decompression - 162K Now, the "size" compression is a special case, as it can be reduced even more. If one wants to use the "z" option, but memory does not permit, then the program will automatically reduce the size of the hash table until memory permits. The hash table starts out at 31K and will be reduced down to 26K. This is the number of entries in the hash table each of which requires 4 bytes. Thus, at best this would give us: "size" compression - 250K This as the trade-off requiring more time (shouldn't be more than twice as slow). If memory still doesn't permit, then the string table will be reduced in order to make more room. The string table has 22K entries and will be reduced down to 16K if need be. This will save us 5 bytes per entry, or at best would give us: "size" compression - 220K This has the trade-off of worse compression as the "size" compression gets most of its advantage by using a large string table. However, this is still better than the "speed" option which uses a 12K string table and squashing which uses a 8K string table (ARC uses a 4K table). Please note, that the "l" and "v" commands (the list commands) usually require only about 60K of memory. However, if one is listing an archive that has a header file, then the header file will be extracted during the list, and thus, require the same amount of memory described above for decompression. Also, if one lists more than one archive at a time, then DWC assumes the worst case and allocs memory assuming one of the archives will contain a header file. Also note, that in the case of the "l", "v", "h", and "x" or "e" commands, when used with only one archive, that the size of the in-memory directory is based on the actual number of entries in the archive. Thus, if the archive has more entries than had been specified for the directory to hold, there will be no directory overflow error. Also, the minimum amount of memory will be used. ERROR CODES: ----------- DWC returns error codes to DOS that can be tested for in batch files. If no errors or warnings occur, then DWC will return 0. The following sections list all possible errors and warnings along with the codes returned if that warning or error occurs. Please note that often, DWC will continue as best it can even after a warning or error occurs. In this case, multiple errors or warnings may occur. They are given the following error codes: Multiple errors: 2 Multiple warnings: 3 Also, error codes override any warnings. So if to two warnings occur and only one error with the code of 20, then DWC will return 20. If DWC is terminated by a Control-C, then DWC will return: Control-C: 1 USAGE ERRORS: ------------ These are the possible errors that result in immediate termination of DWC with an error message and the normal usage display. They can only be suppressed with the "!" option. Code Message 10 ERROR: Illegal parameter in argument list. - A character in the command and options argument was not a known command or option. If "!" follows the offending character, this message would not be suppressed. 11 ERROR: No command specified. - Only options but no command was found in the command and options argument. 12 ERROR: Only ONE command allowed. - More than one command was found in the command and options- argument. This is illegal. 13 ERROR: Password required with the 'g' option. - No password was found to follow the "g" option in the command and options argument. 14 ERROR: Missing archive file in argument list. - Archive file listed on command has an extension other than ".DWC", or ".*". ERRORS: ------ These are the possible errors that DWC can report. They can only be suppressed with the "!" option. Code Message 20 ERROR: Out of memory - Ran out of memory. See section on memory requirements. It's possible to run out of memory even if your computer has lots as memory for various reasons. One possible reason is too many files matching the wildcards specified. This error causes immediate termination. 21 ERROR: Files must be specified to be deleted. - The delete command was given but no files specified. This error causes immediate termination. 22 ERROR: No header file specified. - The header command was given but no header file was specified. This error causes immediate termination. 23 ERROR: Can't open NULL output channel - When messages are suppressed, they are redirected to the nul output, but it failed to open. This error causes immediate termination. 24 ERROR: Can't open archive ssss.xxx for writing to. - The header command could not re-open the archive in write mode. This error causes immediate termination. 25 ERROR: Out of disk space on drive X:, giving up. - Ran out of space on the indicated drive. The temporary archive file is deleted. This error causes immediate termination. 40 ERROR: Archive file ssss.xxx does not exist. - Command requires an archive and it cannot be opened. 41 ERROR: Can't create temporary file tttt.xxx ... Skipping ssss.xxx - The temporary extract file could not be created, so the file ssss.xxx is not extracted. 42 ERROR: Unexpected EOF while reading ssss.xxx ... Skipping - An unexpected EOF was encountered while seeking to the position in the archive where the file ssss.xxx was supposed to be. 43 ERROR: File ssss.xxx corrupted, CRC error 43 ERROR: File ssss.xxx corrupted, Stack Overflow 43 ERROR: File ssss.xxx corrupted, Size Mismatch - The extracted file was corrupted as detected by a CRC error, or a Lempel-Ziv un-compress stack overflow, or the extracted file's size does not equal the saved size. 44 ERROR: ssss.xxx not a DWC archive file or is corrupted. - The last three bytes of a DWC archive file must be the letters "DWC". Either this or some other obvious error in the file was found when opening it. 45 ERROR: Directory of archive ssss.xxx corrupted. - The number of directory entries stored with the archive caused a seek past the beginning of the file. 46 ERROR: Can't create temporary DWC file ssss.xxx - Temporary archive file used on a add could not be created. 47 ERROR: Archive ssss.xxx too corrupted to use. - All directory entries in the archive are corrupted. 48 ERROR: Can't create file ssss.xxx - While re-naming a file, the new file could not be created. 49 ERROR: Ran out of disk space. File ssss.xxx is now in the temporary directory dddd - While copying a temporary file from one drive to another, we ran out of disk space, so the file specified is now in the directory specified. 50 ERROR: Ran out of disk space. File ssss.xxx is now in the temporary directory and file ddd\tttt.xxx - While copying a temporary file from one drive to another, we ran out of disk space, so the file specified is now in the directory specified and has the new name specified. 51 ERROR: Drive x: does not exist. - When trying to open the archive file, we found that the drive specified did not exist. 52 ERROR: Can't create archive tttt.xxx. - The archive name includes wildcard characters and cannot be created. WARNINGS: -------- These are the possible warnings that DWC can report. They can be suppress using the "w" option or the "!" option. Code Message none WARNING: Not enough memory to optimize - In order to optimize for size, one needs at least 248K of free memory (up to 410K will be used.) Normal compression requires at least 198K of free. These figures assume the default size of the in-memory directory. 60 WARNING: File ssss.xxx repeated ... Ignoring - One cannot add more than one file with the same name. 61 WARNING: File not found: ssss.xxx - The file specified is not in the archive. 62 WARNING: Can't open temporary file tttt.xxx ... Skipping ssss.xxx - The temporary extract file could not be created, so the file ssss.xxx, that was to be converted, is skipped 63 WARNING: Can't find file ssss.xxx ... Skipping it. - The file that was to be added could not be found, so it is skipped 63 WARNING: Can't open file ssss.xxx ... Skipping it. - The file that was to be added could not be opened, so it is skipped 64 WARNING: File ssss.xxx archived with password ... Skipping - An attempt was made to extract an encrypted file without giving a password, so it is skipped 65 WARNING: Extraction of the archive file ssss.xxx from itself and on top of itself is NOT allowed ... Skipping\n"); - This warning is not likely, but is given to warn the User of a destructive extraction. 66 UNKNOWN compression method ... Skipping - The file was compressed using an unknown method and cannot be uncompressed using this release of the archiver. 67 WARNING: Header file not found in archive. - The header file named does not match any file in the archive. 68 WARNING: More than one header specified. Using ssss.xxx. - More than one archive file was listed in the file list. So DWC will just use the first one. 69 WARNING: File(s) specified not found in archive. - The file (or files) specified for the equal command could not be found in the archive. 70 WARNING: Only xx directory entries out of nn found. - The archive's directory is tacked onto the end of the archive file and EOF was reached before all entries were read in. 71 WARNING: Directory entry # xx, file "ssss.xxx" corrupted .. Ignoring. - The specified directory has corrupted data 72 WARNING: Unexpected EOF, ignoring... - While copying a file, an unexpected EOF was encountered.