DOCUMENTATION FOR INTERPLAY DESCENT VERSION 1.0=>1.5 PATCH FIX
Version 1.0
2 January 2007
Author:  Stewart Todd Morgan

THE AUTHOR OF THE CONTENTS OF THIS ARCHIVE IS IN NO WAY ASSOCIATED
WITH INTERPLAY ENTERTAINMENT CORP. OR PARALLAX SOFTWARE CORP.  THE
CONTENTS OF THIS ARCHIVE WAS COMPILED WITHOUT THE KNOWLEDGE OR
APPROVAL OF INTERPLAY ENTERTAINMENT CORP. OR PARALLAX SOFTWARE CORP.
DO NOT SEEK ASSISTANCE FROM INTERPLAY ENTERTAINMENT CORP. OR PARALLAX
SOFTWARE CORP. IF YOU REQUIRE ASSISTANCE WITH THE SOFTWARE IN THIS
ARCHIVE.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT
SHALL THE AUTHOR OR HIS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

CONTENTS
     0.0 VERSION INFORMATION
     1.0 WHY DOES THE FIX PROGRAM EXIST?
     2.0 WHAT EXACTLY DOES THE FIX PROGRAM DO?
     3.0 HOW DO I KNOW IF I NEED THE FIX PROGRAM?
     4.0 INSTALLING THE FIX PROGRAM
     5.0 REQUIRED FILE PERMISSIONS
     6.0 EXECUTING THE FIX PROGRAM
     7.0 ERROR MESSAGES/TROUBLESHOOTING
     8.0 GENERAL NOTES ON THE FIX PROGRAM
     9.0 DISTRIBUTION OF THE FIX PROGRAM


0.0 VERSION INFORMATION

     Version 1.0 - CHANGED Documentation
                   CHANGED Linux script internal documentation
     Version 0.9 BETA - Initial Release, not for general
                        distribution


1.0 WHY DOES THE FIX PROGRAM EXIST?

Short Answer:  The Interplay Descent Registered Version 1.0=>1.5
Patch for DOS alters the DESCENT.HOG file in such a way that the
user hears no music after Level 7 in the game.  The fix program
repairs the damage done by this particular patch to the DESCENT.HOG
file.

Long Answer:  In order to understand the question and the answer,
a description of Descent release versions and the history of Descent
patches is in order.

Here is a chart of the DOS Descent versions known to the author:

Package Name               Media    Designation    Version
-------------------------------------------------------------------
Descent                    Floppy   IBM-118-3        1.0
Descent                    CD-ROM   CD-ICD-118-0     1.0
Descent                    CD-ROM   CD-ICD-500-0     1.5
Descent I and II:
The Definitive Collection  CD-ROM   CD-H95-700-3     1.5

Here is a chart of the offical Registered Descent patches in
chronological order:

Patch Version     Comment
-------------------------------------------------------------------
     1.0          Initial Registered Release version
     1.4          First Patch (the jump to 1.4 was to align
                     registered and shareware version numbers)
     1.4a
     1.5          Final Registered Release Version

When Interplay released Registered Version 1.5, they released two
patches.  One (smaller) patch upgraded Registered Version 1.4a
users to Registered Version 1.5.  The second patch was a patch to
upgrade Registered Version 1.0 users all the way to Registered
Version 1.5 with a single patch.  While this is a common way to
release patches for software applications, in this instance the
approach had an unexpected (and unfortunate) result:  upgrading
a Registered Version 1.0 Descent installation directly to
Registered Version 1.5 resulted in a different installation
compared to an installation which was upgraded in two steps from
Registered Version 1.0 to Registered Version 1.4a and then from
Registered Version 1.4a to Registered Version 1.5.  The single-
step Version 1.5 upgrade yielded an installation where no music
could be heard after Level 7 in the game whereas the two-step
Version 1.5 upgrade user could hear music on every level.

If all Descent packages contained a Registered Version 1.0 release,
then the problem could be skirted by encouraging patch archives
and fan sites to simply not make the Registered Version 1.0=>1.5
patch available to the public.  Sites such as
PlanetDescent/Descent Files do not make this patch available.
However, the chart of DOS Descent versions above shows that two of
the released versions contain Registered Version 1.5 on the media.
Sadly, Interplay used the single-patch method to generate both of
the Registered Version 1.5 installations on CD-ROMs marked
CD-ICD-500-0 or CD-H95-700-3.  So users who bought these versions
have no music after Level 7, and Interplay never released any
additional patches that might fix the problem.

An examination of the two Registered Version 1.5 installations
shows that there is only one file that is different between the
two:  DESCENT.HOG.  A .HOG file is a very simple, uncompressed
archive of files.  Further examination shows that there is a
single file within the DESCENT.HOG archive which is different
between the two Version 1.5 installations:  DESCENT.SNG.  In a
fully functional Version 1.5 installation, the DESCENT.SNG file
appears as follows in a text editor:

descent.hmp hammelo.bnk hamdrum.bnk
briefing.hmp melodic.bnk drum.bnk
endlevel.hmp intmelo.bnk intdrum.bnk
endgame.hmp intmelo.bnk intdrum.bnk
credits.hmp melodic.bnk drum.bnk
game01.hmp hammelo.bnk hamdrum.bnk
game02.hmp hammelo.bnk hamdrum.bnk
game03.hmp intmelo.bnk intdrum.bnk
game04.hmp melodic.bnk drum.bnk
game05.hmp melodic.bnk drum.bnk
game06.hmp melodic.bnk drum.bnk
game07.hmp melodic.bnk drum.bnk
game08.hmp rickmelo.bnk rickdrum.bnk
game09.hmp melodic.bnk drum.bnk
game10.hmp melodic.bnk drum.bnk
game11.hmp intmelo.bnk intdrum.bnk
game12.hmp melodic.bnk drum.bnk
game13.hmp intmelo.bnk intdrum.bnk
game14.hmp intmelo.bnk intdrum.bnk
game15.hmp melodic.bnk drum.bnk
game16.hmp melodic.bnk drum.bnk
game17.hmp melodic.bnk drum.bnk
game18.hmp intmelo.bnk intdrum.bnk
game19.hmp melodic.bnk drum.bnk
game20.hmp melodic.bnk drum.bnk
game21.hmp intmelo.bnk intdrum.bnk
game22.hmp hammelo.bnk hamdrum.bnk 

All of the data following the line beginning with "game07.hmp" is
missing in a "badly" patched installation where the one-step patch
has been applied, and since these lines specify what music and drum
pieces are to be played in particular levels, this explains why
there is no music on some levels for users with such an installation.


2.0 WHAT EXACTLY DOES THE FIX PROGRAM DO?

The fix program replaces the old, incorrect DESCENT.HOG file with one
which is binary-identical to one in a Registered Version 1.0
installation which has been upgraded to Registered Version 1.5 using
the two step patch process (Version 1.0=>Version 1.4a,
Version 1.4a=>Version 1.5).  This is accomplished by doing two things:

(1) inserting the missing DESCENT.SNG data in the appropriate place in
    the DESCENT.SNG file within the DESCENT.HOG archive.
(2) adjusting the internal DESCENT.SNG file length field in the
    DESCENT.HOG archive to reflect the new (and correct) size of the
    DESCENT.SNG file

As a result of these changes, the user will be able to hear music in
levels after Level 7.  The fix program will not do anything to improve
or alter graphics, sound effects, performance, or any other issues the
user may experience.


3.0 HOW DO I KNOW IF I NEED THE FIX PROGRAM?

If you have the floppy version of the game or if you have a CD-ROM
marked CD-ICD-118-0, then you can simply apply the official Interplay
patches to take you from Registered Version 1.0 to Registered Version
1.4a and then from Registered Version 1.4a to Registered Version 1.5.
These patches are available from the following sites:

Version 1.0=>1.4a Patch
ftp://ftp.interplay.com/pub/patches/desc14a.exe

Version 1.4a=>1.5 Patch
ftp://ftp.interplay.com/pub/patches/dreg14a5.zip

Both of the above patches are also available from PlanetDescent:
http://www.planetdescent.com/site/files/d1/patches/

If you have CD-ROM versions of Descent for DOS which have the
designations CD-ICD-500-0 or CD-H95-700-3, and you would like to hear
the music as the developers intended, then you will benefit from this
fix patch.  If you inadvertently used the Registered Version 1.0=>1.5
patch to upgrade a Registered Version 1.0 installation, and you
prefer not to reinstall using the two-patch sequence, then you can
also benefit from the fix patch.

A "badly" patched Retail Version 1.5 DESCENT.HOG file has the following
attributes:

File size:  6856183 bytes
MD5:  1051170991544a607c3ff686d0760c98
SHA1:  19659f7dc0a464b2778d1274cd136a7a4f02c0ca

A properly patched Retail Vesion 1.5 DESCENT.HOG file has the following
attributes:

File size:  6856701 bytes
MD5:  c792a21a30b869b1ec6d31ad64e9557e
SHA1:  4d6fb40e943f92574aba2c9fc1574330de89905b

The fix program will only alter DESCENT.HOG files which have a file
size of 6,856,183 bytes.


4.0 INSTALLING THE FIX PROGRAM

The ZIP archive contains four directories or folders.  Each directory
contains a version of the fix program (or script in the case of Linux)
targeted for a specific operating system or set of operating systems
on which the DOS version of Descent can be run.  Copy the fix program
from the appropriate directory in the ZIP archive to the Descent
installation directory which contains the DESCENT.HOG file. The default
installation directory for Descent is C:\GAMES\DESCENT.  Use the
following chart to determine the appropriate version of the fix program
for your Descent installation:

OS on which you
are running         Folder in       Name of fix
DESCENT             ZIP archive     program
-------------------------------------------------------------------
DOS                 DOS             dosfix.exe
WIN 95/98/ME        WIN32           win32fix.exe
WIN NT/2K/XP        WIN32           win32fix.exe
OS/2                OS2             os2fix.exe
Linux               LINUX           linfix.sh (see instructions below)

The Linux directory does not contain any binary executable fix programs.
Instead, it contains a Bash shell script which can be used
to achieve the same result as the executable fix programs for DOS,
Windows, and OS/2 on Linux where the user may be running
the DOS version of Descent in an emulated environment.  This shell
script is a barebones affair, and it lacks many of the features of
the binary programs (basic error-checking, error messages, etc.).
***WARNING***:  Unlike the binary programs for DOS, Windows, and OS/2,
the Linux script does not perform any tests to determine whether it is
being applied to a "badly" patched Registered Version 1.5 DESCENT.HOG
file.  The Linux script can and will mangle a DESCENT.HOG file (and
therefore a Descent installation) if it is applied to anything other
than a "badly" patched Registered Version 1.5 installation.  The user
bears responsibility for insuring that the fix script is only applied
to a "badly" patched Registered Version 1.5 DESCENT.HOG file.

Linux users should copy the linfix.sh shell script from the Linux
sub-directory to the Descent installation directory which contains
the DESCENT.HOG file.  See the comments in the script itself for
more information on using the script.

More than one of the fix programs may work on a given operating system.
For example, the dosfix.exe program may work on many (if not all)
versions of Microsoft Windows and OS/2 as well.


5.0 REQUIRED FILE PERMISSIONS

The following file permissions are required by the fix program:

        (fix program)   EXECUTE
        DESCENT.HOG     READ, DELETE
        ZZTEMPZZ.HOG    CREATE, WRITE, RENAME, DELETE (if fix aborts)
        FIXLOG.TXT      CREATE, WRITE

DESCENT.HOG is part of the original Descent installation.  ZZTEMPZZ.HOG
is a temporary file which is used to build the corrected version of
DESCENT.HOG.  FIXLOG.TXT is a log of messages that mirrors those displayed
on the screen during program execution.


6.0 EXECUTING THE FIX PROGRAM

The fix program requires no parameters, so it can be executed
from a command line using the program name or using the usual technique
for operating systems with graphical user interfaces (left-clicking or
double-clicking as the case may be).  As an example, execution of the
win32fix.exe fix program on a Windows XP Pro system might look as follows
if the program is executed from a command prompt (Start, Run, and execute
the command 'cmd'):

   C:\Documents and Settings\user>cd \games\descent

   C:\Games\DESCENT>win32fix
   WARNING:  BETA VERSION - DO NOT DISTRIBUTE!!!
   Starting Descent Version 1.5 Patch Fix...
   Fix Version 0.9 BETA
   Found DESCENT.HOG...
   Generating new DESCENT.HOG...
   This may take several minutes...

   Descent Version 1.5 Patch Fix Successful!!!

   C:\Games\DESCENT>


Alternately, the win32fix.exe program could be double-clicked in the
C:\GAMES\DESCENT folder with the same result, although the command prompt
window will automatically disappear after execution completes if this
method is used.

A file named FIXLOG.TXT is always generated when one of the fix programs
is executed, and this file contains the same messages that are generated
on the screen during execution.  If a user is reporting difficulty with
the program, the FIXLOG.TXT file can be useful for the troubleshooter.

All of the fix programs and scripts are non-windowing, so there are no
pop-up windows or dialog boxes associated with them (other than the
command prompt interface).

Execution of the fix program may take several minutes on older, slower
systems such as those which barely meet the requirements of the Descent
program itself.  Execution on newer systems should be almost instantaneous.
Here are typical execution times on various systems:

Time Required    System Description
  (seconds)
-------------------------------------------------------------------
     82          83 MHz Pentium Overdrive Processor/MS DOS 6.22/
                    AST Advantage! 486SX/33 System/32 MB Memory
     14          83 MHz Pentium Overdrive Processor/OS/2 Warp Version 3/
                    AST Advantage! 486SX/33 System/32 MB Memory
      2          475 MHz AMD K6-2+ Processor/Win98 SE/HP N3215 Notebook/
                    256 MB Memory
      1          866 MHz Intel PIII Processor/WinXP Pro/
                    Soyo SY-7ISA+ Motherboard/512 MB Memory
      1          933 MHz Intel PIII Processor/Win98 SE/
                    Soyo SY-7VCAE Motherboard/256 MB Memory


7.0 ERROR MESSAGES/TROUBLESHOOTING

The fix program does some rudimentary error detection and reporting. If
an error condition is detected, the program will display an appropriate
error message and abort with the following message:

     Aborting Descent Version 1.5 Patch Fix!!!

Error messages include the following:

     Unable to open DESCENT.HOG!!!

The above message is mostly likely caused by execution of the fix program
in a directory which does not contain a DESCENT.HOG file.  The message may
also reflect a file permission problem with DESCENT.HOG.

     Unable to read DESCENT.HOG!!!

The above message probably reflects a lack of 'READ' file permission on
DESCENT.HOG for the fix program.

     Unable to open ZZTEMPZZ.HOG!!!

The above message indicates the fix program was unable to create the
ZZTEMPZZ.HOG intermediate file which is used to build the new copy of
DESCENT.HOG.

     Unable to write ZZTEMPZZ.HOG!!!

The above message probably reflects a lack of 'WRITE' permission on
ZZTEMPZZ.HOG for the fix program.

     DESCENT.HOG is already correct size!!!

Before building a new copy of the DESCENT.HOG file, the program checks to
see if the existing DESCENT.HOG file size matches the size expected in a
Registered Version 1.5 installation where the two-step patch process has
been applied.  If the file is already the proper size, then the above
message is displayed.  This message will also be displayed if the fix
program is applied to a Registered Version 1.4 or 1.4a installation
since these versions have DESCENT.HOG files which are identical to that
of a correctly patched Registered Version 1.5 installation.

     Invalid DESCENT.HOG!!!

The above message indicates that the DESCENT.HOG file size does not
match that of a "badly" patched Registered Version 1.5 installation.
This message might indicate that the user is trying to apply the fix
patch to a Registered Version 1.0 DESCENT.HOG file, to a Shareware
DESCENT.HOG file or perhaps even to a Descent II DESCENT.HOG file.
This message may also indicate a corrupt or possibly modified
Version 1.5 DESCENT.HOG file.

     FIXLOG.TXT write failure!!!

Unlike most error messages generated by the fix program, the above error
message is not fatal.  The message probably indicates a lack of write
permission to the FIXLOG.TXT file for the fix program.  This message may
appear multiple times on the screen during execution of the fix program.


8.0 GENERAL NOTES ON THE FIX PROGRAM

The DOS, Windows and OS/2 binaries are all generated from the same C source
code.  The compiler used to generate the binaries is Open Watcom C/C++
Version 1.6.  More information on the compiler can be found at this URL:
http://www.openwatcom.org .

Because system requirements for Descent itself are minimal (by today's
standards at any rate), care was taken to ensure that the fix program
would execute on a system with no more than 4 MB of memory.  If a system
can run Descent, it should be able to run one or more of the fix programs.

Although OS/2 was not an officially supported platform for the DOS version
of Descent, the documentation from Parallax Software and Interplay indicates
that the game can be run on an OS/2 system with sufficient memory allocated
to the game.  For this reason, a 32-bit native OS/2 version of the fix
program is included in the ZIP archive.

The possibility exists that there are additional Descent release versions
unknown to the author.  The fix programs may or may not work appropriately
on such unknown release versions.


9.0 DISTRIBUTION OF THE FIX PROGRAM

The fix program archive may be freely distributed provided the archive
contents are intact and unaltered.  Under no circumstances shall the archive
be made available for commercial sale.  Beta versions of the fix program
archive should not be distributed under any circumstances.

