Decompression Chamber Documentation

Decompression Chamber
Documentation

current as of DC version 0.1.881

The Decompression Chamber License Agreement must be read, understood and agreed to before installation or use of Decompression Chamber.
Copyright © 2001 Gregory S. Gursky d/b/a Bitspring. All Rights Reserved.
DecompressionChamber is a trademark of Gregory S. Gursky d/b/a Bitspring.
Windows, Windows NT, and Windows XP are trademarks of Microsoft Corp.
Other products and companies referred to herein are trademarks or registered trademarks of their respective companies or mark holders.


Contents

Back Table of Contents Next

Decompression Chamber
Documentation

Table of Contents

A) Introduction

B) Installation and Setup Guide

C) Supported Decompression Utility List

D) Getting Started

E) Application Reference

F) Options Reference

G) Glossary

H) Sample Screenshots

Back Table of Contents Next


Introduction

Introduction to Decompression Chamber

Decompression Chamber, or DC as I will call it throughout the documentation, is essentially a "shell" application which wraps the excellent command-line decompression utilities written by several authors. There are three major motivations for this product:

1) To provide a single interface for archive set testing, repair, and extraction of multiple compression types. In particular, support for those compression types popular in the Usenet communities.

2) To enhance the feature sets provided by the graphical user interface (GUI) versions of the command-line products.

3) To improve support for large numbers of large archive sets.

Because this is a shell wrapping other utilities, you must properly license and install the utilities you use with DC. If you are trying to avoid licensing of the products that DC supports, then DC is not for you. Furthermore, because the command-line decompression applications generally are not distributed without their GUI counterparts, you will probably have to install the full Windows versions of their software. Therefore, DC generally does not evade the need to install the GUI version of the supported products.

Due to these limitations, DC is definately not for everyone. But I believe it will become a popular tool for improving the efficiency of multiple archive set testing and extraction.

Included with any licensed distrubution of DC is a file called "DecompressionChamberStatus.txt". This standard text file, often referred to as a version control file, lists both the "todo" list of intended features and bugs and also a list of features and bugs fixed already according to their version number. It is a very good idea to read this file before working with DC as the first section will inform you about features planned for upcoming versions, bugs that you may experience when using DC. Then, the second section will list the latest changes that may not be reflected in the documentation.


Installation and Setup Guide

I) Program Installation

As of the writing of this documentation, there is no "installer application" to automatically install Decompression Chamber (DC) to your hard drive. However, the installation of DC is actually very easy. DC is composed only of a single executable file (DecompressionChamber.exe). This file can be placed in any directory and run from there. I only recommend that if you create a shortcut for the DC application, that you make sure the "Working Directory" (also known as the "Target Directory") is set to the same directory that contains the DC executable program.

The more complex aspect of DC installation is the installation of the supported applications. This must be done BEFORE the next section of these instructions, Program Setup, is attempted. Information on what applications will work with DC and how to obtain and install them can be found on the Supported Decompression Utility List page. You only need to install those applications that you need according to which compression types you wish to support. In general, the command-line version of the decompression utilities does not support other compression types like the GUI versions do. Also, you generally will need to use the compression utility as opposed to the decompression utility (when both exist) because repair support is usually not found in the decompression utility.

II) Program Setup

When you first run DC, you will need to instruct it on the location of the supported command-line applications. To do so:

1) Launch DecompressionChamber.exe
2) Press the Options button or Selection Options... from the Edit menu.
3) In the bottom-left corner of the Options dialog box, you will find three edit boxes accompanied by three buttons. Each of these should be pointed to the executable file for the command-line application you wish to support for that compression type. To set the location, press a Path to <compression type> Application button.
4) An Open dialog box will appear. Navigate this dialog box to the location of the previously installed command-line utility. When two utilities exist, where one is for compression and one is for decompression, you will want to choose the compression utility for full DC support. (You may need to set Files of Type to All Files (*.*) if the utility is named something other than what DC expects.)
5) Press the Open button when the proper utility is selected. (You may also double-click on the file in the listbox.)
6) Repeat this process for each compression type you wish DC to support.

Next, you may want to adjust some of the other options. An explanation of the function of each of these options can be found on the Options page.


Supported Decompression Utility List

Below is a list of command-line applications (also known as console applications) that are tested to work with Decompression Chamber (DC). DC does not work with any of the graphical user interface (GUI) versions of these utilities, however, the GUI version often has to be installed in order to access the command-line application. Applications other than those listed below, and versions other than those tested, may not work with DC.

Tested utilities:

RAR:
RARSOFT’s RAR.EXE (versions 2.70, 2.80, and 2.90 beta 2)

ACE:
ACE Compression Software's ACE32.EXE (version 2.0)

ZIP:
WinZIP's WZZIP.EXE v1.0 (build 3181)
PKZIP's PKZIPC.EXE v4.00 [Limited Compatibility]

Download and installation notes:

RARSOFT’s RAR.EXE:
This application is available from the authoring company's website at http://www.rarsoft.com/. To install the command-line application, you must download and install the WinRAR (more generically known as the RAR Archiver) package from http://www.rarsoft.com/download.htm.

ACE Compression Software's ACE32.EXE (version 2.0)
This application is available from the authoring company's website at http://www.winace.com/. To install the command-line application, you must download and install the "Commandline Ace" product. Mirrors that make the "Commandline Ace" product available are linked to from various places on their website.

WinZIP's WZZIP.EXE (version 1.0 build 3181)
This application is available from the authoring company's website at http://www.winzip.com/. To install the command-line application, you must download and install the "WinZip" product first. Once that is installed, you will need to install the "WinZip Command Line Support Add-On" from http://www.winzip.com/wzcline.htm.

PKZIP's PKZIPC.EXE (version 4.00) [Limited Compatibility]
This application is available from the authoring company's website at http://www.pkware.com/. To install the command-line application, you must download and install the "PKZIP for Windows" package from http://www.pkware.com/products/pkzipwin.html. [NOTE: Due to the lack of any form of "success" message at the end of operations, manual verification of the success of extraction operations is necessary by the user.]

Other Notes:

PKZIP's PKZIP.EXE v2.04g (and earlier) for DOS, and 2.50 for DOS are fully incompatible with “DC”.


Getting Started

The following is a quick-start guide to several generic circumstances. Decompression Chamber (DC) is capable of quite a few other functions which you will discover as you continue to learn to use DC, but this will get you started.

I) Display a list of archive sets in a directory
II) Extract one or more archive sets into the directory in which they reside
III) Test one or more archive sets
IV) Repair a member file

I) Display a list of archive sets in a directory

This will be likely be the first thing you do whenever you run DC. DC is designed around the display of one or more archive sets which you can then perform various operations on (like extraction or testing). To display a list of all archive sets in a directory you must first add that directory to the Recent Directory Dropbox:

1) Press the Add button (to the right of the Recent Directory Dropbox and to the left of the Explore button).
2) Navigate to the intended directory and press OK.

When a directory is added to the Recent Directory Dropbox it is also set as the Current Directory. Once the directory you wish to search for archive sets is listed as the Current Directory, press the Add Directory button on the Primary Toolbar (or select Add Directory from the File menu).

At this point, DC will take a moment to search that directory for all archive sets and, when done, will display them in the main window.

To display all archive sets in the Current Directory and all of its lower-level directories, press Add Branch instead of Add Directory.

II) Extract one or more archive sets into the directory in which they reside

By default, DC extracts archive sets into the directory in which they reside. Therefore, unless you have modified the setting for extraction directory, this is the behavior that you will get.

1) Select the archive set or sets from which you wish to extract the contents.
2) Press the Extract Selected button.

DC will queue the selected archive set or sets for extraction and will perform the extraction on them in the order that they appear in the listing. If no archive sets are selected, DC will extract all listed archive sets.

III) Test one or more archive sets

1) Select the archive set or sets that you wish to test.
2) Press the Test Selected button.

DC will queue the selected archive set or sets for testing and will perform the test on them in the order that they appear in the listing. If no archive sets are selected, DC will test all listed archive sets.

IV) Repair a member file

1) Double-click on the archive set containing the member file on which you wish to attempt repair.
2) A list of all member files will display under the archive set entry.
3) Right-click on the member file (or files) you wish to repair and select Repair Selected Part(s).

DC will queue the selected member files for repair and will perform the repairs on them in the order that they appear in the listing.


Application Reference

This section has not been written yet. Please use the Getting Started section of the documentation as a basis for experimentation with other features.

NOTE: When experimenting, you should backup any archive sets before doing something undocumented with them. However, known bugs are listed in the DecompressionChamberStatus.txt file which should be relatively comprehensive and list most bugs you may encounter. I make every effort to make sure nothing critical is broken before release, but problems can always arrise with use the of alternate environments, operating systems, and due to compatibility issues with other applications. Therefore, care is recommended.


Options Reference

General Options:

Extract To (radio buttons): The selection determines the preferred directory to which the extraction operation outputs the archive set's contents.
a) Directory containing archive: The same directory in which the archive set resides.
b) Subdirectory name after archive: A directory will be created directly under the directory in which the archive set resides named after the archive set.
c) (a) except (b) when content's titles differ from archive title (A title is an extensionless filename): Not yet implemented.
d) Extraction directory: The directory selected in the Extraction Directory edit box (see below).

Memorize a Directory (dropbox): This dropbox lists all "recent directories". Selection of a "recent directory" in this dropbox will assign that directory as the "current directory".
Browse for Directory... (button): Pressing this button will bring up a "Browse for Folder" dialog box. Select a directory here to add to the list of "recnt directories". The newly added "recent directory" will also become the "current directory".

Extraction Directory (edit box): This edit box displays the directory that extractions performed with Extract To option (d) (see above) will output the archive set contents into. This edit box is for display purposes only. Use the associated button to adjust.
Browse for Directory... (button): Pressing this button will bring up a "Browse for Folder" dialog box. Select a directory here to change the Extraction Directory.

Path to <compression type> Application (3 edit boxes): These edit boxes display the application executable for each compression type that will be used for all operations for that compression type. These edit boxes are for display purposes only. Use the associated button to adjust. These must be set in order to operate on archive sets of the appropriate compression type.
Browse for Directory... (button): Pressing this button will bring up a "Browse for Folder" dialog box. Select a directory here to adjust the location of the associated Path to <compression type> Application.

Max Memorized Directories (numeric edit box): The number in this box determines the maximum number of "recent directories" that can be remembered by DC.

Soft Abort Timeout (numeric edit box): This variable sets the number of milliseconds (ms) before an operation that has been aborted, gets more aggresively aborted.

Ghost Missing Primaries (checkbox): Currently, this should always be on.

Echo Command (checkbox): When checked, the full command-line string that runs the supported compression application is displayed in the results pane. When unchecked, this command is not displayed.

Suppress Comments (checkbox): When checked, any comments contained in the archive set are not displayed in the results pane. When unchecked, they are displayed as usual.

Create and use .ignore 0B files (checkbox): When checked, any archive set that has its status set to "ignored" will have a 0-byte file created in the directory in which it resides named with the archive set title followed by the extension .ignore (e.g. ArchiveTitle.ignore). Also, when an archive set is loaded into the primary pane in the future and it finds a .ignore 0B file, it will automatically toggle that archive set's status to "ignored".

Relaxed incomplete deduction (checkbox): Because DC must make certain assumptions about the completeness of archive sets, it will sometimes make errors. This checkbox determines its behavior in circumstances. When checked, if the last file available in an archive set is either the same size as the primary member file or is 0 bytes, it will assume the archive set is incomplete. When unchecked, in either of those two cases, DC will not modify its assumptions. This could lead to more wasted testing of incomplete sets. (Note: While OFF is technically "playing it safe", it will frequently believe incomplete sets are complete. On the other hand, when ON it will almost never assume a truly complete archive set is incomplete. In such cases one simply has to "force" the operation.)

Extraction Options:

Rename Generic Files (checkbox & edit box): When checked, DC attempts to detect if any extracted file matches the filename filters listed in the edit box. If they do match, after the operation on that archive set is complete, it will renamed those files by adding the archive set title followed by a dash in front of the extracted filename. This is to prevent same-named files in other archive sets from overwriting each other and to help distinguish them after the extraction is complete. The edit box filter format takes standard filename filters which may contain alphanumeric text plus the * and ? wildcards, with each filter seperated by a semicolon.

Testing Options:

Create .crcok OB Files (checkbox): When checked, whenever an archive set is tested as "CRCOK", a 0-byte file is created in the directory in which the archive set resides to indicate that that archive set has been tested to be error free. The format of the 0-byte filename is the archive set title followed by the extension .crcok (e.g. ArchiveTitle.crcok). This allows "CRCOK" archive sets to be noticable from Windows Explorer and other applications without referring back to the DC primary pane or after DC has been shutdown.

Fill .crcok with results (checkbox, requires Create .crcok OB Files to be checked): When checked, instead of the .crcok file being left "empty", it will be filled with the command-line applications output in plain text for the testing operation. This file can then be opened in any text editor to review the results of the test after DC has been shutdown.

Allow .crcok if A.V. fails (checkbox, requires Create .crcok OB Files to be checked): When checked, if an archive set fails only because of authenticity verification errors, it will still have a .crcok file created for it.

Verify if .crcok present (checkbox): When checked, if a .crcok file exists for an archive set when it is added to the primary pane, the status of that archive set will be automatically set to "CRCOK".

Repair Options:

Backup before Repair (checkbox): When checked, when a repair operation commences on a member file, a backup of that file before the repair is attempted is created in the same directory in which that member file resides. The file is named in the following manner: OriginalFilename.ext.backup (e.g. TestArchive.r01.backup). [Note: Currently, this causes a very short pause while the file is copied.]

Repair in Archive Set Directory (checkbox): Most repair operations actually create a temporary file. When checked, this temporary file is created in the directory containing the archive set. When unchecked, this temporary file is created in the "working directory" that is established when running DC (it is usually the directory in which the DC executable resides).


Glossary

0B File: A file with no contents (0-bytes) that is used as a means of persistent "notes" some of which are designed to point information out to the user when they are browsing their archive sets in Windows Explorer and some of which are designed to enhance DC's capabilities. Generally they use the following naming convention: "<archive title>.<informational extension>" (e.g. TestArchive.ignore, AnotherArchive.crcok).

Archive: An archive is the compression or storage of one or more files (sometimes including a directory structure) by an application into one or more other files.

Archive Set: When an archive is "broken up" into multiple files, the entire grouping of files is called an archive set. If an archive is not "broken up" then the term archive set refers to the single archive file.

Command-Line Interface: Generally, this is a textual environment that, while usually more cryptic and less user-friendly, provides a user with a fast method of inputting options to an application. Due to the textual method of input, command-line applications can often have their use automated. The primary alternative to a Command-Line Interface is the GUI.

Compression: The process of shrinking one or more files into an archive by use of a compression algorithm. This, when used properly, should produce an archive smaller in size than the original file or files.

CRCOK: Term referring to an archive set that has been tested to have no errors.

Current Directory: Much of DC operation is based around the current directory. Directory operations such as Add Directory and Add Branch use the current directory to determine the directory on which to operate. The current directory is listed as the current selection in the Recent Directories dropbox.

Graphical User Interface (GUI): An environment provided by some applications allowing easier use of a program through a graphical visual presentation of the options and data manipulated by that program. Generally, most Windows applications make use of a GUI. The primary alternative to a GUI is the Command-Line Interface.

Member File: When an archive is "broken up" into more than one file (i.e. an archive set containing more than one file) then the individual files are called member files. (e.g. In a RAR archive set, example.rar, example.r00, example.r01, etc. would be the member files.)

Primary Pane: DC has a potential of three view panes. The topmost is called the primary pane. It lists all archive set entries that have been added using one of the "Add" operations. Most control over the archive sets is performed in the primary pane.

Recent Directory: DC is able to remember a large number of recently used directories. These can then be easily set as the current directory at any time. The recent directories are listed in the Recent Directories dropbox. But selecting a recent directory in this dropbox, that directory will be set as the new current directory.

Results Pane: DC has a potential of three view panes. The second pane is called the results pane. All output from the command-line utilities is displayed here as it is sent back from those applications. The results pane can be hidden by dragging the seperator between the primary pane and the results pane to its bottom-most position.

Storage: The process of combining one or more files into an archive without compressing it to make it smaller. This is usually done to simplify the process of moving multiple files to another location.

Watch Pane: DC has a potential of three view panes. The third pane is called the watch pane. Most of the time (and by default) the watch pane is hidden. To toggle the watch pane between visible and hidden you may press the Watchlist button or toggle the Watch List entry in the View menu.


Sample Screenshots

Primary Window

Options Window


Pre-Release License Agreement

 License Agreement for Decompression Chamber for Windows ("THE SOFTWARE PRODUCT")

This license agreement ("AGREEMENT") is a legal agreement between you (either an individual or a single entity) and Gregory S. Gursky d/b/a Bitspring ("BITSPRING") for THE SOFTWARE PRODUCT. By exercising your rights to download, install, use or distribute THE SOFTWARE PRODUCT, you agree to be bound by the terms of this AGREEMENT. If you do not read, understand or agree to the terms of this AGREEMENT, you may not use THE SOFTWARE.

Should you accept the terms of this agreement, BITSPRING will grant you the personal and non-exclusive right to download, install and use THE SOFTWARE PRODUCT. THE SOFTWARE PRODUCT and any other materials provided in this package may not be modified in any way. THE SOFTWARE PRODUCT may not be redistributed in any format other than as packaged and released by BITSPRING and must be accompanied by this AGREEMENT.

SOFTWARE PRODUCT LICENSE:

The SOFTWARE PRODUCT is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE PRODUCT is licensed, not sold.

COPYRIGHT NOTICE:

THE SOFTWARE PRODUCT and all other materials distributed with this package are Copyright (c) 2001 by Gregory S. Gursky d/b/a Bitspring.

No parts of THE SOFTWARE PRODUCT or other files provided in this package may be reproduced in part or in whole, except as provided in the License Agreement. You may not remove any copyright or other proprietary notice from THE SOFTWARE PRODUCT. You may not modify, translate, reverse engineer, decompile, disassemble (except and solely to the extent an applicable statute expressly and specifically prohibits such restrictions) THE SOFTWARE PRODUCT. You may not charge for distribution of THE SOFTWARE PRODUCT beyond the price of media and shipping.

DISCLAIMER:

THE SOFTWARE PRODUCT is in a pre-release evaluation format and is provided "AS IS". You agree that by accepting this license, you are expressly acknowledging that the use of this software is AT YOUR OWN RISK. This agreement constitutes the entire agreement between BITSPRING and you and supersedes any other communications relating to THE SOFTWARE PRODUCT.

BITSPRING makes no warranty of any kind, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this software and accompanying documentation.

IN NO EVENT SHALL GREGORY S. GURSKY D/B/A BITSPRING BE LIABLE FOR ANY DAMAGES (INCLUDING DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THIS PROGRAM, EVEN IF GREGORY S. GURSKY D/B/A BITSPRING HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

ASSOCIATED APPLICATIONS:

If THE SOFTWARE PRODUCT works in conjunction with any other computer software ("ASSOCIATED APPLICATIONS"), then your license to use the ASSOCIATED APPLICATIONS is governed by your license with the licensor of the ASSOCIATED APPLICATIONS. You must be in compliance with your license to any ASSOCIATED APPLICATIONS in order to use THE SOFTWARE PRODUCT.

TRADEMARKS:

Any product or brand names mentioned in this software and associated manuals and files are trademarks or registered trademarks of their respective owners.

--
Pre-Release