==============================================================================
                    VXTool, version 2.06.01 patch release v.01
==============================================================================


                        VXTool, v2.06.01, December 1999

                Windows volume maintenance utility for Starsiege

                  Written by Anthony Chou (achou@primary.net)
                         Hurled out to you by MioTech


Addendum (12/26/1999):

     This is the 2.06.01 (patched) version of VXTool.  It was released to
     address erratum numbers 2005, 2006, and 2007.  Erratum 2005 was
     discovered on some systems that VXTool would try to read volume file
     data before the VOLUME.EXE shell was complete writing to and closing
     the DOS data file.  Erratum 2006 was discovered that VXTool was not
     fully compatible for the updated version of VTLIST.EXE (available from
     Starsiegeplayers.com utility downloads page).  This newer version of
     VTLIST.EXE supercedes the version in both 1.003 and 1.004 of
     Starsiege and can list all the 3,258 file names in gameObjects.vol
     file.  Since the previous version of VXTool supported only 2,048
     file names per vol file, it would generate an error when attempting
     to read the gameObjects.vol file or any vol with more than 2,048
     files.  Erratum 2007 effected the build part of VXTool.  It was
     discovered on some systems that VXTool would stop responding if a
     very large number of files were selected to be added to the volume
     list.  These erratum have been corrected with this patch.  VXTool
     can now, in theory, read 10,240 volume file names.  Please take
     note: when extracting all the files in gameObjects.vol the expected
     time for completion is over 50 minutes.

     To help compensate for this lengthily process a new extraction method
     was included.  This is the burst mode extraction process where 15
     files are extracted in multiple sessions simultaneously at a time.
     Afterwards a delay screen dialog box is shown which gives users the
     ability to fire off the next round of bursts after waiting for all
     the extract sessions of the previous burst to close.  This method
     could be faster for extracting files on some systems verses other
     methods, your actual mileage may vary.  There is a setting that
     allows for an automatic delay time to be inserted between bursts but
     this setting generates different results for different systems.
     Depending on your configuration this setting my not be a good option
     for you.  If too short of a delay time is entered, system resources
     could be drained rapidly causing the system to slow down and lockup.
     It is therefore NOT RECOMMENDED except for advance users and
     certainly should never be used when there are large amounts of files
     to extract.  Use the auto delay feature with extreme caution and at
     your own risk.


Letter from the author (10/30/99)

     Hello everyone!  Well this is it, VXTool is finally finished and
     complete.  Good thing too since I just got a job and my first day is
     this coming Monday.  Thanks again to all those who tried out and
     tested my earlier versions of this program.  I am still going to try
     to get some personal web space to post this thing but if it never
     happens I am sure it can still be obtained from the Starsiege archives.
     As anticipated, the long awaited Build process is included and working
     in this release.  Much of the whole program forms and flow has been
     changed to accommodate and unify the volume maintenance procedures for
     the building and extraction processes.  As such users should find
     version 2.05 to be more streamlined and logical to use.  I have had to
     strike a balance between complexity and ease of use to provide a
     utility that was both intuitive and informative for the user.  As no
     one has reported any major problems with the extraction routines in
     the beta, I do not suspect anyone should have any difficulties with
     the build process in this version.  So here it is and have at it.  I
     hope this program will be enduringly useful for the life of its
     purpose and that everyone will continue to have fun playing Starsiege.
     Please read this whole documentation, a lot of changes have been made
     and you should know the extent as it applies to you before using this
     very helpful program.


 Introduction:

     This program was designed for all of those Starsiege gamers who have
     wanted and asked for a windows based extraction utility to help them
     edit Starsiege volume files.  With the advent of the 1.003 patch for
     Starsiege (and perhaps earlier), users were gifted with utility files
     that they could use to edit volume files.  These utilities (namely
     VTLIST.EXE, EXTRACT.EXE, and VT.EXE) however are command-prompt based.
     Though they got the job done, many users including myself were left
     longing for some means of automation.  Enter the likes of VXLIST.EXE
     and now, VXTool.EXE version 2.05.

     VXTool is a Win95/98/NT based program written from Visual Basic 5.0
     and is essentially a front-end shell assignment utility that uses
     VTLIST.EXE and EXTRACT.EXE (to list and extract the files inside a
     volume file) and VT.EXE (to build entire volumes).  I originally
     designed this program to temporarily provide a GUI solution for
     modders and scripters until Dynamix could release their own windows
     based utility (if ever) or someone else could provide a better one.
     Unfortunately since the release of VXLIST in July, no new and superior
     window's based volume utility has been released to date.  This has
     pressured me somewhat to upgrade and in many ways revamp the utility
     into now what is called VXTool, what I hope to be a complete volume
     maintenance utility for Starsiege.  As always, I hope this program
     will be useful for those who need it.
 
  
  Notice of copyright, disclaimer, and other potential legal stuff:

     I suppose every program these days be it shareware, freeware,
     or commercial should have some legalese...so I say mine here as well. 
     This software (VXTool.EXE), its accompanying DOS programs, and
     documentation is, for the most part, copyright by me (Anthony Y Chou).
     I license (where applicable) anyone and everyone in all nations
     (where applicable) the right to use this software.  I declare this
     software to be freeware and that it can be freely copied and
     distributed.  Please do not pay anyone for this software and if you
     choose to distribute it, please do not charge beyond a reasonable
     handling fee for media and services.

     As the user, you agree that: I make 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.  I am not selling this
     program nor will I ever claim that it will make money for anyone.  The
     purpose of this program is to provide a free and useful tool for the
     Starsiege community.

     In no event will I be liable for any damages (including damages for
     loss of profits, interruption, loss of information, or other pecuniary
     loss both business and personal) arising out of the use of or
     inability to use this program, even if I have been advised of the
     possibility that such damages could occur.  In no event will I be held
     liable or responsible for providing or not providing any support for
     this software and documentation.

     Starsiege is a trademark of Dynamix, a Sierra Company.  I do not
     work for nor am I affiliated with them.  They probably do not know of
     or perhaps even care about this program.  They of course will not be
     able to provide any technical support for this program in any way
     (please do not contact them in regards for support for this program).
     They can make no warranty and will not be liable any damages this
     program may cause, even as it may function with their commercial
     software product (Starsiege).

     In essence, when used as directed on a stable working system, VXTool
     should never cause a system to crash and loose data.  But neither I,
     Dynamix, nor your pet goldfish will be responsible if it does.

     Windows95, Windows98, and WindowsNT are trademarks of Microsoft Corp.
     Please do not contact them in regard to problems with this software.

     MioTech is a completely fictitious company name provided for the sole
     purpose of humor and entertainment.  Any resemblance to actual
     companies and characters is purely coincidental.

     And all other blah, blah, blah...It is unlawful to use this product in
     a manner inconsistent with its labeling (just kidding) there, I said it.


  Files included:

     In this public beta release version distribution, These files are
     included:

        VXTool.EXE : windows VB5 volume maintenance utility.
        VXTool.TXT <-- This documentation file.
        VOLUME.EXE : dos shell redirection utility for vxtool.exe
        VOLUME.PIF : program information file for windows (important).
	  Volext.bat : example batch extraction file for PIF.
	  VOLEXT.PIF : PIF file of Volext.bat for windows use (important).
	  Build.bat  : example batch extraction file for PIF.
        BUILD.PIF  : PIF file of build.bat for windows use (important).
	
     Except for the text file, these files are required to operate and must
     be installed in a dedicated folder for VXTool.  In addition to the
     included files, VXTool also requires these files to operate:

        VTLIST.EXE  : volume list utility.
        EXTRACT.EXE : volume file extraction utility.
	  VT.EXE      : volume builder utility.	
        *.VOL       : any Starsiege volume file.

     I presume the above four required files to be copyright by Dynamix or
     their affiliates in some way.  As such I do not include them in this
     distribution.  These file can be obtained in the 1.003 version of 
     Starsiege and for those versions should already be in the Starsiege
     application folder.  They are not required to be copied or placed in
     the VXTool folder.

     Other Visual Basic system and DLL files are included in the setup
     distribution for VXTool to run.  Depending on you system, you may not
     need these files.


  Usage:

     Double click on VXTool.EXE to start the program.  The user is given
     the main form window where information about file and path locations
     of VTLIST.EXE, EXTRACT.EXE, VT.EXE must be given before extraction and
     building can proceed.

     Buttons:

       File: allows the user to choose the file and path from a dialog box.
         Optionally, the user can input the information in the space
         provided.

       Extract: if VTLIST.EXE and EXTRACT.EXE are specified, the user can
         click 'Extract' to proceed to the extraction form.

	 Build: If the location of VT.EXE is specified, the user can click
         'Build' to proceed to the volume builder form.

       Save: writes to a data file the filename, path locations, and viewer
         settings for later use when VXTool is restarted again.

       About: Additional information about VXTool.

       Exit: quits VXTool.

     Window form information:

       Extract Form (List of): Displays the volume list in a list window.
         Also displayed is directory information and the number of files in
         the volume as read and reported by VOLUME.EXE.  In all normal
         cases, these two numbers should be the same.  The number of files
         selected is also displayed and reflects the user's input in the
         file list.  The user can select any number of files in the list
         for extraction or only one script type file to view.  A choice for
         batch extraction is now included as well as the option to enable
         file checking during extraction.  Files are extracted to the
         target directory upon command.

	   First select the volume file to extract and the destination
         directory for extracted files to go.  Then click the UPDATE button
         to refresh the list box window.  Files can now be selected for
         extraction from the list window.  If the file is a script file
         (ending in a .cs extension) it can be viewed in prompt by first
         selecting it and then clicking the VIEW SCRIPT button.  Viewer
         options can be obtained by clicking the SET VIEWER button.

	 Set Viewer (View *.cs file settings): displays viewing options to 
         Use when viewing a script file.  Users can choose to use MS
         Wordpad, MS Notepad, or any other viewer of their choice.
         Wordpad is the default and generally a good viewer to use.  If
	   another viewer is used, be sure that it can accept command line
         arguments in a windows shell.  The 'Set' button will save the
	   settings for current VXTool session.  To save the settings for
	   subsequent sessions of VXTool, click the 'Save' button on the
	   main form.
	
	 Build Volume: displays the builder form.  User must first enter
	   volume file information to build and then select files to add to
         the volume.  After this any combination of options and command
         line arguments can be selected and entered to control the build
         process.  The build is executed in either batch mode or by 
         script option both of which occur in a single DOS session.  A
         new volume file can be created using the –CPT option, in for
         which no new files are added but an existing volume file is
         copied.  

	   First select a volume file to build.  This can be a new volume
         file or an existing file.  In both cases the full path and filename
         information needs to be entered.  Be sure the filename does not 
         conflict with a directory or folder.  Next in the choose the drive
         and folder which contains the files you want to add to the volume
         in the right side of the SELECT FILES frame.  The middle list box
         will change to reflect the contents of the selected folder.  From
         this middle box individual files can be selected by clicking them
	   and then the ADD button or by just double-clicking them.  All the
         files in the folder can be add at once by clicking SELECT ALL.
         Adding files copies them with their associated path information
         to the leftmost list box.  This box contains all the files to be
         added to the volume.  Any number of files in the selected box can
         have their order of placement changed by selecting one or more
         files and then clicking the up or down arrows to move them.  This
         moves the files one at a time.  Faster moves can be accomplished 
         by pressing the Ctrl or Shift keys while clicking the arrows
         (clicking the arrow direction once and then holding the ENTER key
         could also work).

         After adding all the files to be build (they need not come from
         the same folder), chose the option and arguments to build the 
         volume with if any.  For the most part, removing the path
         information while building (-sp option) is adequate for most
         users.  The other options should not be used unless you know what
         you are doing.  Be very careful if you use the –LZH or –RLE options.
         Using these options tends to add extra bytes to the internal file
         lengths in certain cases.  It is not understood why this occurs but
         it is suspected of causing numerous volume failures and Starsiege
         crashes.  Other arguments can be entered in via the command line
         user arguments text box.
         
         Next select the type of process to use to build the volume.  Either
         by batch or script file arguments (@File option) can be used.  The
         script method tends to be the faster method particularly when adding
         a large number of files.

         If you want to compact a new volume from an existing volume via the
         -CPT option, that can done as well.  However now no new files can be
         added and the new volume destination and filename must be given.
         It is not know widely to the public why this option was ever put
         into VT.EXE but since it was, it is included here as well.  A word
         of warning: never try to re-compact a volume file that is already
         compressed or else VT.EXE will cause invalid page faults and
         exception errors in windows.
	   	
         Finally click the BUILD button to start building the new volume.
         No type of file confirmation is provided as to the status of the
         volume after the build order is given.  For this reason it is
         important to wait until the DOS session closes before exiting the
         Build Form window.  When the session closes, be sure to check the
         volume (read it in using the extraction form) to make sure it is
         complete before using it.  Failure to do this could result in
         Starsiege locking up and exiting due to unintentional or corrupted
         files and/or scripts.


  How VXTool works and known limitations:

     EXTRACTION

     As stated earlier, VXTool is front-end shell program.  It uses the
     visual properties and environment of Windows to call instances of
     EXTRACT.EXE command line arguments much in the same way a user would
     normally execute it in a command prompt.  The only real difference is
     that VXTool automates the task and so can perform the operations faster
     and easier than the user could do manually.  The maximum number of files
     VXTool can view and extract at the same time is now 2048 files.  However
     the VTLIST.EXE that VXTool uses is limited to 1024 files.  A new release
     of VTLIST will be required for VXTool to display more than 1024 files.

     Starting with v2.01 beta, VXTool can now also perform batch extraction
     procedures.  This feature was added per request as some users reported
     incompatibilities with their systems and the way earlier versions of
     VXLIST handled multi-mode, independent shell instances of EXTRACT.EXE.
     The advantage of batch mode processing is that now only one shell
     instance is called to extract any selected number of files.  EXTRACT is
     executed from a batch file created by VXTool one at time until all the
     files are extracted.  This method effectively eliminates any potentially
     hazardous resource limiting avalanches that could occur with runaway
     shell instances in some systems though rare.  Another advantage is that
     batch extraction is now the fastest method to extract over 20 files at
     once.  This mode is now the default extraction mode.

     The drawbacks of using batch mode is that file checking adds a
     considerably long overhead time to verify successful extraction of
     files as the batch is executed (I can hear many OS programmers singing
     in unison to the tone of "Duh").  Because of this it is usually better
     to disable file checking when using batch extraction mode.  However if
     this is done, it is important to WAIT UNTIL THE BATCH FILE EXECUTION
     WINDOW HAS FINISHED AND CLOSED BEFORE RETURNING TO VXTOOL.
     Specifically you should not exit the Extraction Form (List of:) window
     until the batch has finished execution or else you will cause problems
     as temporary files, including EXTRACT and the batch file, are erased 
     in the clean up procedures.  Also importantly is that the PIF file
     VOLEXT.PIF be in the VXTool application directory.  This file is so
     That windows will know what to do with the batch file once it is done
     Executing (that is, close it).  This file and its batch file are later
     erased from the temporary directory before VXTool exits.
  
     The multi-mode shell extraction option is still provided as for most
     power users it is the fastest way to extract up to 20 files without
     file checking.

     Because of the way VXTool uses the shell functions within Windows for
     shell extraction mode, it possess two unenviable qualities:

        1). It is slow (yet still far faster than manual extraction).

        2). It has the potential to hog Window's resources during the
            extraction process, particularly with multiple extraction
            instances.

     Traditional visual developers will cringe at the brute force yet
     straight-forward method I took for this program to accomplish the task.
     But since I did not have any inside information about the binary
     structure of the volume files, nor the time and energy to reverse-
     engineer it, I had no other choice but to use the tools already given.
     Such is the way earlier versions of VXLIST was born to operate.

     In order to compensate for the slow speed the 'Enable file checking'
     option was added to the extraction form.  With this option disabled,
     VXTool can virtually run up to 20 shell instances of EXTRACT at once.
   
     This provides the fastest way of extracting a short number of files.
     With this option enabled, VXTool will check to see if EXTRACT.EXE is
     finished extracting a file before it opens another shell instance of
     EXTRACT.EXE for the next file.  This option acts as a speed brake to
     Prevent VXLIST from opening potentially hundreds of EXTRACT shells for
     the many files that can be in single volume.  This option is safer and
     typically prevents VTLIST from opening more than two or three shell
     instances at a time (only one is extracting a file, the others are
     finished and waiting for Windows to "mop them up").  With file checking
     enabled it takes approximately 50 seconds to extract all 142 files in
     SCRIPTS.VOL on a Win95 machine w/ a 450 MHz Celeron and 128 MB of ram.
    
     The penalty for this safety is speed.  On the same machine with file
     checking disabled it will take less than 2 seconds for VXLIST to shell
     extract 20 files from a volume.  Given those numbers one might expect
     to extract 142 files in fewer than 15 seconds.  But the thought of
     calling nearly over 100 shell instances simultaneously is quite
     horrifying when one takes into account of the theoretical 1MB maximum
     per shell requirement.  Of course EXTRACT.EXE requires less to work
     with but Windows would not have a clue either way.  Because of this
     the limit was set to 20 files that can be extracted at once with file
     checking disabled.  If more files are selected then extraction is done
     with file checking enabled when in shell extraction mode.

     This combination of speed and safety choices provides the best optimum
     for the audience users.  The above machine may not have any problems
     with 30 or even 50 files at a time.  Typically many users will at
     least have that powerful of a machine just to play Starsiege but it is
     entirely possible that one maybe using a 486 with 16MB of ram and
     win32 just to edit volume files.  I heard them in my dreams ;-)

     During extraction, VXTool will check to see if the extracting filename
     already exists in the target directory before extraction.  If it does,
     it will be erased before the new file is extracted.  For example: if a
     user extracts a given amount of files and then repeats the exact same
     extraction procedure in the same target directory, then all the
     previously extracted files will be erased before the new ones are
     written as the previous files had the same filenames with the new
     files.

     Before going to the view and extraction window forms, VXTool calls the
     file VOLUME.EXE in a window's shell which then in turn calls VTLIST.EXE
     in a 16-bit dos shell to list and create a temporary data file for
     VXTool to work with.  This was done because of visual studio's rather
     crazy non-support of dos redirection schemes in Win32 shells (why I
     have no idea).  Not wanting to go to assembly just yet, I simply made
     the 16-bit VOLUME,EXE program.  For this program to work properly with
     VXTool, it and its accompanying PIF file should be in the VXTool
     application directory.  The PIF file tells Windows to close the 16-bit
     VOLUME.EXE shell when finished.  Preprocessing file work is done in a
     temporary directory where some files are copied to during the list and
     extraction procedures.  These files are later deleted before VXTool
     terminates.

     VIEWING (script files)
     
     VXTool now includes the ability to allow users to view the contents of
     script files before extracting them to the target extraction directory.
     This is more of a convenience than a novel feature as the script file
     will still have to be extracted however this time to the temporary
     directory.  The user can view the file and even edit it (it should then
     be saved to a different location).  The viewer options allows the user
     to choose the viewer and the handling of the viewing events procedure. 

     BUILDING 
	
     Now with the release of version 2.05 users can now build entire volume
     files.  This also works by using a DOS shell session however only one
     is ever call on at a time to build a volume.  Therefore the complexity
     of the build process is not with the execution of the shell but rather
     the correct placement of the syntactic arguments as well as the file
     and path information.  Even so this turned out to be a relatively minor
     challenge compared to the GUI structure and program flow.  The task for
     users now lay with knowing what they want and how VT.EXE and VXTool is
     going to give it to them.

     As can be surmised, the build process works in the opposite manner of
     the extraction process.  Instead of taking one file to obtain one or
     more others, one or more files will be taken and integrated into one
     file.  Though the exact procedure required to do this is simpler than
     extracting, the implications behind the process is more complex.  During
     the extraction process the target file is known and derived from the
     volume.  No special parameters were needed to achieve the results.  For
     building however, there is array of parameters and arguments that can
     be combined together to obtain a vast variety of VT commands...and
     results.  It was initially difficult to conceptualize what role VXTool
     should play for some of the options if any.  At the very least was the
     desire to automate the integration build process so that the ease of
     use was increased and time from individual files to a single volume was
     decreased.

     The solution I settled for was a compromise leaning more towards ease
     of use rather than attempting to provide a complete VT menu suite.  As
     such the user can expect to find the most commonly used options
     available for selection to aid the building process while more complex,
     seldom known, and less often used parameters are not explicitly
     supported.  Even so, they can still be used with VXTool via the user
     arguments text window if they are ever needed.  VXTool builds volumes by
     taking the user's inputs that would normally be given as DOS command
     line arguments and structuring them in the order that VT.EXE needs to
     work with.  These inputs include options, volume file name and path to
     create or append, and files to add to the volume.  When this information
     is given the volume can be build by either a batch process (sequentially
     appending the same volume file one at a time) or by a script file of
     arguments containing the file names (adding all the files to the volume
     in one VT call).  In both cases only one DOS shell session needs to be
     called to invoke VT and the build process.  The result is a tool that
     does much of what it was envisioned to do: help users quickly build
     volume files without sacrificing flexibility.
 
     The limitations involving building volumes is not completely known at
     this time.  This is mostly because that much of VT still remains a 
     mystery.  If volumes are built with just the default option of removing
     the path information of the files, the length of the added files do not
     seem to change.  But if compression is used (-lzh option) the file
     lengths tend to grow with each successive cycle of adding and
     extracting.  Why this occurs is not known however it may present some
     problems for Starsiege when attempting to read the information from the
     compressed volume.  As a result is it practically impossible to fully
     extract and then rebuild an original compressed volume to the same file
     length even if no modifications were made to the contents.  The product
     will always be a large file.  SCRIPTS.VOL is an example of a
     pre-compressed volume file.  If all the contents were extracted and then
     recompressed, the result will be file slightly larger than the original.
     For this reason recompression is generally not recommended until further
     information about its use can be obtained.
 

  Reporting problems:

     Because of the nature of my time and resources, I will not have the
     ability to respond to all the user's request for assistance with this
     program.  If you are having problems with VXTool or would like to voice
     suggestions, complaints, or praises; please direct them to my e-mail
     address above.  As stated earlier, neither Dynamix nor Microsoft can
     help you.  Please understand that I am not getting paid or reimbursed
     in any way for providing this program to the public.  As such I can not
     provide much tech support of any means.  As much as I can hope that
     people will find this program useful I also pray that it would work bug
     free.  But alas, in this life you will have trouble and any suggestions
     or bug reports will be taken into account in the next revision release.


  Version history:

     VXLIST 1.01 : Internal release, proof of concept.

     VXLIST 1.02 : Fixed bugs with the shell routine.
                   Added the View option.

     VXLIST 1.03 : First public release version.
                   Fixed bugs in the directory/file handling.
    
     VXTool 2.00 : Added support for 1024 files.
                   Viewer option included.
                   Removed file only view option form main form.

     VXTool 2.01 : Second public release version (beta).
                   Added batch mode extraction option.
                   Expanded viewer options.
                   Expanded usability of combo boxes.
                   Redesigned form layout.
			 Added internal support to 2048 files.

     VXTool 2.02 : Redesigned forms to accommodate build form.
			 Finish build process.
                   
     VXTool 2.03 : Adjusted flow processes to simplify use.
			 Added and fixed build features to simplify use and
			 increase reliability.

     VXTool 2.04 : QA and more QA up the wazoo...
	
     VXTool 2.05 : Third public release version.
                   Intro screen added.
			 
  Future Works:

     None scheduled as this time...but you know I'll be up to something.	
 

  Immediate thanks go out to:

    Jesus, my friend and then some (oh yeah, still the man!).

    Uncle Bob, for putting me up at his place in California.

    Winslow, for his multitude of support in the battle field and off.

    Tom, for being my companion wuss in combat.

    Jon, for providing me the bandwidth needed to pull this thing off.

    Andy, because programming advice goes a long way.

    Emeric, for reminding me that even I had a big head when I was young.
      Perhaps I still do.

    Those who have promoted this program in the past and all those players
      who taught me the lessons I cherish today.
