.=================================.
                      |    H  o  l  d  Q  u  e  u  e    |
                      |                                 |
                      |           Version 0.2           |
                      `================================='

What is HoldQueue?
~~~~~~~~~~~~~~~~~~

HoldQueue is a tool for the off-line netgame VPA Planets (c) Tim Wisseman.

HoldQueue can be used in connection with CPlayers under PHost. It controls
their ship build orders after the ship limit and keeps the orders fixed
until the ship is finally built. This is necessary with some CPlayers which
change their build order every turn. Consequently, with each change PHost
shifts the base concerned to the end of the ship build order so that these
CPlayers can never build any ships. With HoldQueue these CPlayers can build
ships as other players can. (Don't use HoldQueue when you are playing with
Priority Build Points and your CPlayer can handle them. I don't know any
CPlayer that can handle PBPs, but there may be some in the future.)


How to install HoldQueue
~~~~~~~~~~~~~~~~~~~~~~~~

Put the HoldQueue files in any directory of your choice. Nothing more to do.


How to use HoldQueue
~~~~~~~~~~~~~~~~~~~~

HoldQueue is a command line program. In takes the same command line
swiches CPlayers usually take (because Tim's original CPlayer uses them):

   HoldQueu <GameDir> /<Races> [[/]u]

Example: With "HoldQueu MyGame /3b" HoldQueue will work for the Bird Men
and the Colonies in MyGame.

'u' (or '/u') is an upgrade switch that allows CPlayers to upgrade their
ships under construction under certain conditions. For details see below.

If HoldQueue is run without a command line parameter or with one that
contains a '?', it will print some information to the screen.

HoldQueue can be run from any directory. Just take care to add the
correct game path.

Since HoldQueue is to correct CPlayer orders, it should be run after
the CPlayer(s) ran. It needs its own copy of BData.Hst (one of the host
files) which it creates when it is run for the first time on a new game.
Thus, when you want to use HoldQueue for the first time, run HoldQueue
once before the CPlayers, then run the CPlayers, then run HoldQueue again.
In all following turns you may run HoldQueue after the CPlayers only.
(If you ever happen to meddle this up, don't worry and read the section
on 'What HoldQueue does'.)

When HoldQueue works, it prints out on which bases it rearranges the
build order. HoldQueue also writes a log file called HOLDQUEU.LOG in
the game directory with more detailed information. Have a look at the
log file after you ran HoldQueue. It starts with the actual day and
time so that you can be sure to look at the right log file. When it
finishes with "Operation successfully completed" you are pretty safe
that all went well. If you use a host batch you can also test the error
code. HoldQueue returns the error number, or zero if no error occurred.

HoldQueue can run before the ship limit is reached. It has no effect, then.

If run between phase 1 and 2 of PHost, HoldQueue can work on human
players' bases too if you really want to tease them ;-) . If run before
PHost, HoldQueue should normally not interfere in the human players'
orders, but it will in case of an NMR. So better take care of the
race switch.


The Upgrade Switch
~~~~~~~~~~~~~~~~~~

CPlayer tends to build Small Transports at first, and you prefer it
to build Gorbies ;-) ? No Problem. This is what the upgrade switch
is for. With the upgrade switch HoldQueue will still cancel by far most
of the ship construction order changes, but it allows CPlayers to
upgrade the orders if the new ship is much better than the old one.
To be exact, it allows the upgrade if all of the following conditions
are met:

- The hull number of the new ship is greater than that of the old ship.
- The engine tech level is at least the same.
- If the old ship has beams, the new ship must have more and the beam
  tech level must be at least equal.
- If the old ship has bays or launchers, the new ship must have more,
  but it may have bays instead if launchers or vice versa.
- If both ships have launchers, the torp tech level of the new ship
  must be at least as high as that of the old ship.

Examples (all ships warp 9 unless otherwise mentioned):

1. You cannot upgrade a warp 7 LDSF to a warp 9 LDSF because the
   hull number is the same, not higher.

2. You cannot upgrade an LDSF to a Nebula because the hull number
   is lower.

3. You cannot upgrade a Nebula to an LDSF because the Nebula has
   weapons, the LDSF has not.

4. You cannot upgrade a Nebula to an Arkham or Thor because the
   Arkham lacks Launchers and the Thor lacks Beams.

5. You cannot upgrade a Nocturne to a Nebula because they have
   the same number of beams. The new ship must have more beams.

5. You cannot upgrade a warp 9 LDSF to a warp 5 Merlin because
   of the lower engine tech level.

6. You cannot upgrade a Mark 7 Nebula to a Mark 4 Nova, but a
   Mark 7 or 8 Nova is okay if the beam tech level of the Nova
   is the same or better.

7. You can update an MDSF to an Eros, an Eros to a Brynhild,
   a Brynhild to a Diplomacy and a Diplomacy to a Nova if all
   tech levels remain the same or increase.

8. You can update a Loki to a Kittyhawk and a Kittyhawk to a Nova
   although the Kittyhawk has bays and the other ships have launchers.
   In this case it is okay when the Loki has Mark 8 launchers and
   the Nova has Mark 4 launchers. Engine and beam tech level, however,
   matter.

9. You can never upgrade any hull-tech 10 battleship. You cannot
   upgrade a Merlin except to a Virgo. (Don't beat me. It's a question
   of the hull number.)


What HoldQueue does
~~~~~~~~~~~~~~~~~~~

The host data on star bases stand in BDATA.HST. This file contains
information on the equipment of all bases, tech levels and stored
ship parts, but also the hull number, number of weapons and weapon
and engine tech levels of the ships to be built. CPlayers access these
data directly and change them as they want. So does HoldQueue :-) .

HoldQueue keeps a copy of BDATA.HST, BDATA.CPY, which is created when
HoldQueue runs first and is updated each time HoldQueue runs. Using
this copy, HoldQueue searches all star bases in BDATA.HST for changes
in the ship build order. When it detects a change, HoldQueue controls
if the old ship parts still exist in the base. If they don't exist,
the ship was probably built, and HoldQueue will not interfere. If they
do exist, HoldQueue will undo the CPlayer's changes unless they are
accepted as an upgrade.

Finally, HoldQueue copies BDATA.HST to BDATA.CPY and exits. When it
exits without an error, it returns error code 0, otherwise the number
of the error. (The error is also written to the screen and to the
log file.)


History
~~~~~~~

Version 1.0:
- First public release. No changes.

Version 0.2:
- Log file added.
- Error beeps added.
- Own file copy routine used instead of DOS copy routine.

Version 0.1ß:
- First version.


Disclamer
~~~~~~~~~

I took care to make the program as safe as possible. However you use
it completely on your own risk. I cannot be made responsible for any
kind of damage this program might do to your software, your hardware,
yourself or anyone or anything else.


Status Quo
~~~~~~~~~~
HoldQueue is Freeware. You may give it to anyone else, upload it to
mailboxes or servers if
- you distribute it free of charge (and only free of charge) and
- you distribute it together with this documentation.
You are not allowed to make any changes to the program or the documentation.

For questions or comments please contact Michael_Herrmann@m2.maus.de