LZW is a general purpose file archival utility. The original compression code was provided in a series of articles in Dr. Dobbs Journal. The original authors and published dates are: Original Author: Mark R. Nelson (Dr. Dobbs October 1989) Updated by: Shawn M. Regan, January 1990 (Dr. Dobbs June 1990) Please review the "-about" output (and/or license.txt) for licensing restrictions. The majority of the program's features were identified and developed with an HP 3000 in mind, specifically with the MPE file system's operating characteristics. When files are archived, a file-information block is recorded with the data, preserving the original file's characteristics as they are defined under MPE. In the VMS versions, the original file's RMS file characteristics are mapped, to the extent that they can be, to their MPE equivalents. In the Unix and DOS versions, on the other hand, these parameters cannot be determined, and the characteristics must be specified via command-line parameters. Telamon provides this software "as is" and makes no warranty of any kind with regard to this software, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. In no event shall Telamon be liable for any loss of profits, loss of business, loss of use or data, interruption of business, or for indirect, special, incidental, or consequential damages of any kind, even if Telamon has been advised of the possibility of such damages arising from any defect or error in this software. Common LZW options: -about Displays Licensing information. -f[ile] [archive] [default archive -> "lzwfile"] Specifies the name of the archive, one to be either created during a Store operation or updated during an Append/Update/Purge operation or read during a Restore operation. If '-file' is omitted, LZW will prompt for the name of the archive. If '-file' is specified and the archive name is omitted, LZW will use "lzwfile" by default. -verbose [default -> off] Turns on the display of compression/decompression progress. -quiet or -q [default -> on] Turns off the display of compression/decompression progress. -silent or -qq [default -> off] Turns off all messages other than error messages. This will cause LZW to operate with no output whatsoever. -old [default -> off] LZW currently records two "signatures" in the file-information block for each file added to an archive, the first being a record of the version of the LZW program that created the archive and the second being a time-stamp, recording the time the file was added. This is done for the purpose of verifying that the file is indeed one created by LZW. Older versions of the program did not record the time-stamp information, but otherwise used the same archive format. If, when accessing an existing archive, this message "***Missing/invalid date signature - cannot continue" is displayed, try specifying the "-old" option. If, on the other hand, LZW reports "***Missing/invalid version signature - cannot continue", the archive is probably not one created with another version of LZW. Store options: -s[tore] [fileset [fileset] ...] Creates a new archive and adds all files identified by the various filesets to it. -a[ppend] [fileset [fileset] ...] Accesses an old archive (or creates a new one if one doesn't exist) and adds all files identified by the various filesets to the end of the archive. -u[pdate] [fileset [fileset] ...] Accesses an old archive (or creates a new one if one doesn't exist) and replaces all files identified by the various filesets if they are found in the archive. New files are added to the end of the archive. In all of the above forms, 'fileset' can be one or more filenames, a wild-card pattern, an indirect file reference or any combination of the three. For MPE versions, wild-card patterns include the common "@", "#" and "?" characters and for other systems they include "*" and "?". Wild-card expansion is performed by shell-expansion on Unix and VMS machines, by the :LISTF command on MPE machines and by explicit directory searching on DOS machines. Indirect files are indicated by either ^file or !file and may contain simple filenames or wild-card patterns, but not other indirect files. Directories are skipped in the archive process as are other non-"Regular" files, such as fifos, sockets and block special files. If no fileset is specified, the user will be prompted for files or filesets to archive. e.g. Store file name [CR to exit, ? for help]: ? Options: name store file "name" ^name store files listed in file "name" CR exit program Store file name [CR to exit, ? for help]: -m[axbits] n [default -> 14 for large memory, 12 otherwise] The compression algorithm used by LZW makes use of a number of tables which can become quite large. The version of LZW that tries to decompress an archive must be able to handle the same size table as was used during the compression step. If you plan on creating an archive for eventual use by one of the small memory versions of LZW (LZW.MPEV or LZW286PC.EXE), you will have to direct the compressing LZW to use smaller tables, by specifying a smaller value for this option, usually 12. The tables' dimension is set to a prime number somewhat greater than 2 to the maxbit's power. There are two such tables, one consisting of 16-bit values and another consisting of 32-bit values. Thus, with a maxbit value of 14 (the default) and a prime number value of 18,041 (selected at compile- time,) LZW will use at least 108,246 bytes. Sufficient memory must exist for LZW to allocate these tables, and small memory versions of LZW, specifically LZW286PC.EXE and LZW.MPEV (LZWV), must use smaller tables in order to run, with a maxbits value of 12. The DOS versions of LZW allocate memory for these tables dynamically and the remaining versions allocate space for the tables at compile-time. The tables are sized for the maximum maxbits value of 16, resulting in a memory load of 432,534 bytes (12 and 30,126, respectively, for LZW.MPEV and LZW286PC.EXE.) -trim [default -> off] For MPE versions of LZW, this option will cause a created archive's file limit (FLIMIT) to be reset to match the end-of-file (EOF) on completion. This will cause the resulting file to be as small as possible and may be necessary when sending the file to an MPE/V based system. This option will prevent future Append operations. -transport [default -> off] This option is used when creating archives for eventual use on small memory machines. It sets the "-maxbits 12" option on all platforms, and additionally sets the "-trim" option on MPE versions. -binary [n] [default -> off, 256 byte records] MPE-based LZW programs can automatically determine the type of the file being archived by examining the file label. For other systems, this information cannot be easily determined. Binary files should be recorded "as-is" with no modification of the data contained. This switch will cause non-MPE LZW programs to treat the files being archived as fixed-length Binary data, using 'n' as the record size in bytes. Records longer than the indicated record size will be archived as consecutive 'n' byte records. When Restored, records shorter than the indicated record size will be padded with zeros. -text [n] [default -> off, 128 byte records] MPE-based LZW programs can automatically determine the type of the file being archived by examining the file label. For other systems, this information cannot be easily determined. This switch will cause non-MPE LZW programs to treat the files being archived as fixed-length ASCII data, using 'n' as the maximum record size in bytes. Records longer than the indicated record size will be archived as consecutive 'n' byte records. When Restored, records shorter than the indicated record size will be padded with blanks. -stream [default -> on] MPE-based LZW programs can automatically determine the type of the file being archived by examining the file label. For other systems, this information cannot be easily determined. This switch will cause LZW to treat the files being archived as variable-length ASCII data. Short records will _not_ be padded. Restore Options: -r [fileset [fileset] ...] or -restore [fileset [fileset] ...] Accesses an old archive and attempts to restore files from it. The two forms of this command are largely similar. They differ only in their behavior when fileset(s) are specified. The "-r" form will automatically operate in Batch mode, restoring without user interaction any files found to match the filesets specified. The "-restore" form will only operate in Batch mode if the "-batch" switch is also specified. In either form, 'fileset' can be one or more filenames, a wild-card pattern, an indirect file reference or any combination of the three. Matching is case-sensitive on Unix systems. If no fileset is specified, an attempt will be made to restore each file in the archive. For MPE versions, wild-card patterns include the common "@", "#" and "?" characters and for other systems they include "*" and "?". Indirect files are indicated by either ^file or !file and must contain simple filenames only. Filename references can be in the form "name=newname", where "name" is used to match the filename in the archive and "newname" is used as the name of the file created by the Restore process. -b or -batch Batch mode Restores are performed with no user interaction. Non-batch, or interactive mode, Restores will prompt on each restore attempt, seeking confirmation for the operation. For MPE systems, the prompt will be in the form: {file description} (-m {maxbits used}) {time-stamp} Restore file {name} [CR for yes, ? for help]: ? Options: CR restore file as "{name}" newname restore file as "newname" * restore file in logon group .group restore file in specified group @ restore all remaining files as named @* restore all remaining files in logon group @.group restore all remaining files in specified group // skip this file /// exit program Restore file {name} [CR for yes, ? for help]: /// For other systems: {file description} (-m {maxbits used}) {time-stamp} {permissions} Restore file {name} [CR for yes, ? for help]: ? Options: CR restore file as "{name}" newname restore file as "newname" * restore file with no extension .ext restore file with specified extension @ restore all remaining files as named @* restore all remaining files no extension @.ext restore all remaining files with specified extension // skip this file /// exit program Restore file {name} [CR for yes, ? for help]: /// -c or -create (MPE versions) Somewhat similar in function to the :RESTORE;CREATE option. When restoring files to an MPE system, if either of the file's group or account doesn't exist on the system, the Restore operation will fail. This option will cause LZW to first execute the minimum command necessary to create both the group and account, providing the executing user has sufficient capability. LZW does not check the user's capability first, but instead attempts to execute the appropriate command via the COMMAND or HPCICOMMAND intrinsic. Attempts at account/group creation are performed using: :NEWACCT acctname,MANAGER :NEWGROUP groupname.acctname if both appear in the output file's name. If no account is found, the group creation is attempted using: :NEWGROUP groupname In either case, if the account/group creation fail and the indicated account and/or group doesn't exist, the Restore operation will fail. Note that the created group and/or account will have the default access and capabilities and _no_ password assigned. -k or -keep Similar in function to the :RESTORE;KEEP option. By default, when LZW writes an expanded file to disc, it will first purge any previously existing file with the same name. This option prevents this behavior. -l or -local Similar in function to the :RESTORE;LOCAL option. By default, when LZW writes an expanded file to disc, it will use the exact filename as originally specified when the file was archived. On MPE systems, this means that the original group and account will be used. On other systems, this means that the entire specified path will be used. On MPE systems, the Local option will cause the group.account portion of the filename to be ignored and on other systems, any specified path prefix will be ignored. -group [.]groupname (MPE versions) Similar in function to the :RESTORE;GROUP= option. This will cause the group portion of the Restored filename to be replaced with 'groupname'. -acc[oun]t [.]acctname (MPE versions) Similar in function to the :RESTORE;ACCT= option. This will cause the account portion of the Restored filename to be replaced with 'acctname'. -stream (non-MPE versions) For LZW to treat the archived file(s) as though they had been Stored with the -stream option specified. This means that if the files were stored with the '-text n' option specified, short records won't be blank/zero filled. Search Options: -t [search string] or -search [search string] -r [fileset [fileset] ...] or -restore [fileset [fileset] ...] Accesses an old archive and attempts to search the indicated files for the specified search string. The two forms of this command are largely similar. They differ only in their behavior when fileset(s) are specified. The "-t" form will automatically operate in Batch mode, examining files without user interaction any files found to match the filesets specified. The "-search" form will only operate in Batch mode if the "-batch" switch is also specified. In either form, 'fileset' can be one or more filenames, a wild-card pattern, an indirect file reference or any combination of the three. Matching is case-sensitive on Unix systems. For MPE versions, wild-card patterns include the common "@", "#" and "?" characters and for other systems they include "*" and "?". Indirect files are indicated by either ^file or !file and must contain simple filenames only. If 'search string' isn't specified on the command line, LZW will prompt the user for it. String comparisons are performed ignoring case. Purge Options: -p [fileset [fileset] ...] or -purge [fileset [fileset] ...] Accesses an old archive and attempts to remove the indicated files from the archive. The two forms of this command are largely similar. They differ only in their behavior when fileset(s) are specified. The "-p" form will automatically operate in Batch mode, purging without user interaction any files found to match the filesets specified. The "-purge" form will only operate in Batch mode if the "-batch" switch is also specified. Verify Options: -v[erify] File equation format Displays information on each file contained in the archive, in MPE :FILE equation style. The information reported is in the form: {filename}; REC={width},{blkfct},{recfmt},{filefmt}; [NO]CCTL; DISC={eof},{ext} (-m {maxbits}) {timestamp} [{permissions}] where: filename is the name of the file width is the recorded record width, in MPE form. A negative value represents a byte count and a positive value respresents a count of 16-bit words. blkfct is the recorded blocking factor. This parameter is of significance for MPE systems only and is used when rebuilding the file. recfmt identifies the record format: F->fixed length records, V->variable width records and B->byte stream format. Fixed length records, upon expansion, will have records shorter than the specified {width} padded with either ASCII blanks or binary zeroes, depending on the file format (below.) filefmt identifies the file format: ASCII->ASCII data with short fixed length records padded with blanks; BINARY->binary data with short fixed length records padded with zeroes. [NO]CCTL CCTL indicates that the carriage control option was specified when the original file was created. This implies that the first byte of each record is to be interpreted as a carriage control directive. eof Either the number of records (recfmt->F or V) or the number of bytes (recfmt->B) contained in the file ext The maximum number of extents to be specified when rebuilding the file. Set to '0' when no maximum was specified for the original file. Significant for MPE systems only. timestamp The date/time the file was added to the archive. This is one of the "signature" items that LZW uses to validate an archive. permissions For Unix and VMS systems, this represent the file's mode value. -V|-listf LISTF,1 format Displays information on each file contained in the archive, using MPE :LISTF,1 format (:LISTFILE,1 for MPE/iX). Miscellaneous Options: MPE versions only, A.03.24 and higher. The LZW program creates an archive with the following MPE characteristics: REC=256,8,F,BINARY;CODE=665 This format is required as the MPE versions use the File System intrinsics to process the file, specifically FREADDIR and FWRITEDIR. If an archive has been retrieved from another platform and this file structure hasn't been specified (e.g. variable width records and/or different record width), LZW will try to convert the file to the correct format before using it. LZW will read the specified archive and copy the data to a correctly formatted temporary file, named LZWTOLZW, reblocking as necessary. This format conversion will be considered successful only if the number of bytes processed is a multiple of the 512 byte record size. A warning will be displayed at the start of the conversion and a message will appear afterwards indicating the success or failure of the attempt. Once the automatic conversion is finished, LZW will then attempt to process the temporary file. The temporary copy can be saved using: :PURGE LZWFILE :RENAME LZWTOLZW,LZWFILE,TEMP :SAVE LZWFILE It is also possible to force conversion to a permanent file using: -convert filename The specified archive will be converted as above, using {filename} as the destination. Upon completion, no other action will take place.