This file documents the RLSystems VGA Planets I/O Library V3 and
contains a complete documentation of this library.

   This file should always accompany and be accompanied by the rest of
the package of which the VGA Planets I/O library is a part, as
distributed by Dlanor Blytkerchan and/or RLSystems. It may be
re-distributed free of charge by anyone who cares to do so, as long as
the package remains in tact.

   Copyright (c) 2000 Dlanor Blytkerchan <dlanor@dds.nl>

   The VGA planets I/O Library V3 (VPL3) is distributed both as a part
of the RLSystems VGA planets Software Development Kit for DJGPP, and
seporately.  This file should be included in both distributions as of
July 2000.

This file documents *all* methods, variables, etc. in the library -
*even the ones you shouldn't use!* - so be careful when using the
library, and try to stick to the recommended routines as much as
possible: using the methods not recommended for use can result in future
copies of your program to behave differently, as those methods may be
subject to change without prior notice - or any notice for that matter.

   I've tried not to skip anything, and describe each and every method,
but there are a lot of them, and I am only human. Should I have missed
a method somewhere, please notify me at once, so I can document it.

Introduction
************

As you will know as you read this, VGA planets is a multi-player
Play-By-E-Mail (PBEM) game, with two distinct parts: the host-side
software and the player-side software. The host has been designed to
accept extentions to it's own functions, using so-called add-ons
(different from plugins because the code is not executed by the host
itself). In theory, anyone who knows the setup of the data the host
maintains can write an add-on to manipulate that data. Examples of such
add-ons - examples I wrote using this library - are Gators, the
Starbase Enhancer, the Trampoline Device, etc. The biggest drawback to
writing add-ons is, however, that you need to know how the host
operates in order to be able to write your add-ons and have them
interact with the game.

   I have spent quite a few days/weeks/months figuring out how the game
works internally, and I think I have a pretty good grasp of it by now.
This knowledge has helped my win games, but has also enabled me to write
add-ons, and put the code common to all those add-ons together in a
reusable component - this library.

   After some time, I decided to make this library available to the
general public: this is the third version of the library, and only very
few people have the first two versions, which were written in other
languages, and it is now at a stage at which I think more people can
actually benefit from it. So here it is: a library which allows you
nigh complete access to the databases the host maintains, and some
databases my own add-ons maintain.

   Use this library with DJGPP (http://www.delorie.com), the free GNU
C/C++ compiler by DJ Delorie _et al_. (Look for the ZIP Picker on his
site and download the files you need..).

   The entire library was written in C and consists of two parts: one
"raw" access part, accessed through `<vgap.h>'; and an easier part,
with a lot of dispatchers and background software (most of the library
consists of software for this part) accessed through `<vpl3.h>'.

   If you know for sure you're not going to use that, but will only be
using the "raw" part, use the "raw" version of this library,
`<libVGAPRaw.a>'.  It has been compiled with only what you need for
that part of the library.  (You'll still need the Swing library,
though, because it is needed for the error identification (e.g. if
certain files are missing)).

   This documentation is written for the full version. The part of the
documentation handling the `<vgap.h>' file is all you'll need for the
raw version.

   The other library, `<libVGAPExtentions.a>', contains dispatchers for
RLSystems add-ons I/O. It is not finished yet, but when it is, it will
be documented here.

Quick Start
***********

   To get started with the library as quickly as possible, just remember
these simple steps when writing your program:
   * #include
          #define LSW1_All
          #include <swing.h>
          #include <vpl3.h>

   * Initialize Use initSwing() and initVPL3() like this:
            bool rc = true;
          
          /* ... */
          
            if (rc) rc = initSwing();
            if (rc) rc = initVPL3(USE_ALL, gamePath, basePath, &numships, 0);

   * Read, Write, etc.  Use the proper reads and writers, e.g.
     readRace() for races, writeShip() for ships; etc.

   * let the libraries take care of shutting down..
            if (rc) {
              return(0);
            } else done(errCode);

To install the package, all you need to do is unzip it on your DJGPP
directory.. C'est tout!

Header Files
************

The two main header files for this library are `<vpl3.h>' and
`<vgap.h>'.

`<vpl3.h>' contains the (prototypes of) the VGA Planets I/O
dispatchers. You do not need any more than this to access anything you
might want to access in the host data. Most of the hard work is done
for you, and the data is presented to you in well-documented data
structures, which are filled in by the dispatchers, as you read the data
from several files. These dispatchers require some memory, but are not
all that memory-hogging in that they can run on most machines, and you
can force them to use temp files in stead of keeping the data in memory
(at the expense of speed).

`<vgap.h>' contains the (prototypes of) the raw I/O stuff.  All you
need to access can be accessed with this, but it does substantially
less for you. Nice if you want to do the hard-core programming yourself,
so you know exactly what is being done, but (to my opinion) less
elegant.

   There are several other header files for the library, most of which
you will not need to use. Still, as this documentation is supposed to be
complete, they are listed here:
   * `<vpl3/battle.h>'

     The Battle module of the library contains a port of Tim's VCR
     program, adapted so it can also do battle with Gators, warped
     ships, and potentially other objects as well. Should you have an
     object of your own with which you would like to have ships,
     planets, warped ships or Gators do battle, just tell me the specs
     and I will add it to the engine.

     The doBattle() method is not guaranteed to keep the same interface
     (i.e.: objects may be added to the parameters later).

   * `<vpl3/compilers.h>'

     The Compilers module is internal to the library, and should not be
     used by any other software. (It is documented in more detail
     below).

   * `<vpl3/enh2Structures.h>'

     The Enhancer V2 Structures module contains all the structures used
     by the RLSystems Starbase Enhancer, and the filters to the data as
     it is saved on disk.

   * `<vpl3/enhancerOptions.h>'

     The Enhancer V2 Options module contains the core of the RLSystems
     Starbase Enhancer - you can't actually recreate the add-on with
     this module, because the actual functional dispatchers are not
     included, but you can access al the information.

   * `<vpl3/filters.h>'

     The Filters module is internal to the library and should not be
     used by other software. It is fully documented below.

   * `<vpl3/gators.h>'

     The Gators header is only part of the library because some defines
     in the header are used by other modules. The actual module is not
     included in the library.

     The macros and defines are documented below.

   * `<vpl3/globalVGAPInfo.h>'

     The Global VGAP Info module contains information used by just
     about every add-on written, but not necesarrily by the library
     itself. It is included in the library as an aid, but not required
     for any part of the library.

   * `<vpl3/gtr3FileDispatchers.h>'

     The Gators V3 File Dispatchers module takes care of all file I/O
     for RLSystems Gators V3, and is used by many other add-ons, which
     use Gators.

   * `<vpl3/gtr3Structures.h>'

     The Gators V3 Structures module contains all the structures used by
     RLSystems Gators, and the filters for memory to disk and vice versa
     conversion.

   * `<vpl3/gtr3UFODispatchers.h>'

     The Gators V3 UFO Dispatchers module contains the methods used by
     Gators to put Gators, MiniGates and warped ships in the UFO
     database.

   * `<vpl3/messages.h>'

     The Messages module contains all pre-defined messages sent by
     Gators, The Starbase Enhancer, The Trampoline Device, Spy, The
     Freelan People's add-on, etc. It also contains everything you need
     to access the subspace messages in the game, but the getMessage()
     method has not been fully tested yet.

   * `<vpl3/rlssbenh.h>'

     The RLSystems Starbase Enhancer header file serves roughly the same
     purpose as the Gators header does: the actual module is not part
     of the library.

   * `<vpl3/spy.h>'

     The Spy header file serves roughly the same purpose as the Gators
     header does: the actual module is not part of the library.

   * `<vpl3/spyStructures.h>'

     The Spy Structures module contains all structures used by Spy, and
     the associated filters. THIS ADD-ON IS UNDER CONSTRUCTION! The
     structures WILL NOT remain the same, and the modules may even be
     removed from the library altogether..

More modules will be added to the library - e.g. the Freelan modules
have not been added yet..

VPL3 Dispatchers
================

These are the most important functions in the vpl3-part of the library:
the initialize the library, open the required files, set up the
required memory buffers, and allow you access to all you need.

initVPL3()
==========

Syntax
------

     #include <vpl3.h>
     
     bool initVPL3(int mode, char *gamePath, char *basePath, short *numberOfShips, byte player);

Description
-----------

Initializes the library in mode MODE, which is a combination of:
   * NO_BUFFERING

     Prevents the library from putting all the accessed game data in
     memory - has it use temporary files in stead. This makes your
     program slower, but less memory-hogging.

   * USE_SHIPS

     Tells the library to allow access to ship data. This means you
     will be able to use readShip() and writeShip() from your program.

   * USE_PLANETS

     Tells the library to allow access to planet data. This means you
     will be able to use readPlanet() and writePlanet() from your
     program.

   * USE_STARBASES

     Tells the library to allow access to the starbase data. This means
     you will be able to use readStarbase() and writeStarbase() from
     your program.

   * USE_RACES

     Tells the library to allow access to the race data. This means you
     will be able to use readRace() and writeRace() from your program.

   * USE_CONFIG

     Tells the library to allow access to the host/game configuration
     data. This means you will be able to use readConfig() and
     writeConfig() from your program.

   * USE_MINEFIELDS

     Tells the library to allow access to the minefield data. This
     means you will be able to use readMinefield() and writeMinefield()
     from your program.

   * USE_IONSTORMS

     Tells the library to allow access to the ion storm data. This
     means you will be able to use readIonstorm() and writeIonstorm()
     from your program.

   * USE_UFOS

     Tells the library to allow access to the UFO data. This means you
     will be able to use readUFO() and writeUFO() from your program.

   * DO_VALIDATE

     Tells the library to validate and repair all data before it is
     written to the databases, and before it is presented to your
     program. Currently, this doesn't do anything because the
     validation filters haven't been implemented in this release of the
     library yet (they exist, but are not part of the library yet).

   * PLAYER_DATA

     Tells the library your program is _not_ a host-side add-on, but a
     player-side utility.

   * USE_ALL

     combines the USE_* options.

GAMEPATH should be the complete path to the game data, including the
final slash; BASEPATH should be the complete path to the host - or to
the directory where the host data files are kept (the HULLSPEC.DAT,
ENGSPEC.DAT, TORPSPEC.DAT and BEAMSPEC.DAT files), including the final
slash. NUMBEROFSHIPS should point to a variable where you expect the
maximal number of ships to be returned, or NULL if you're not going to
use it. If you use the `<globalVGAPInfo.h>' header, you can use
`&numberOfShips', which is a variable in the Global VGA Planets Info
module. PLAYER should be the ID of the player, if your program is a
player-side utility, or 0 if it's either a host-side utility, or should
read all player data. For host-side utilities & add-ons, this is
ignored.  Player-side utilities are not supported yet.

Example
-------

     if (rv) rv = initVPL3(NO_BUFFERING | USE_ALL, "y:/honor/process/", "z:/planets.32/", 0);

Return value
------------

true if successful, false if not. If it fails, errCode will be set
accordingly, and done() will have Swing display the proper error
message.

readConfig()
============

Syntax
------

     #include <vpl3.h>
     
     bool readConfig(configType *cfg);

Description
-----------

Reads the entire host/game configuration and presents the data in a
comprehesive structure containing the hconfig settings, which race can
build which ships, and the the hull, engine, beam weapon and torpedo
specifications. In short: everything you might want to know about the
host/game configuration. Races names etc. are available from readRace(),
planet names etc. are available in readPlanet().

Return value
------------

true if successful, false if not.

readShip()
==========

Syntax
------

     #include <vpl3.h>
     
     bool readShip(shipRecordType *p, short record);

Description
-----------

Reads all relevant information about ship ID# RECORD into P. This
includes the owner, name, ID#, fCode, cargo, strength, speed, engine
specs, probable location next turn, mission, etc.

Return value
------------

true if successful, false if not.

readPlanet()
============

Syntax
------

     #include <vpl3.h>
     
     bool readPlanet(planetRecordType *p, short record);

Description
-----------

Reads all relevant information about planet ID# RECORD into P. This
includes the ID, name (which is *not* read-only!!), owner, friendly
code, core contents, mined minerals, mineral density, structures,
climate, population, etc.

Return value
------------

true if successful, false if not.

readStarbase()
==============

Syntax
------

     #include <vpl3.h>
     
     bool readStarbase(starbaseRecordType *p, short record);

Description
-----------

Reads all relevant information about starbase ID# RECORD into P. This
includes the ID, name, owner, friendly code, and what it's doing.

Return value
------------

true if successful, false if not.

readRace()
==========

Syntax
------

     #include <vpl3.h>
     
     bool readRace(raceRecordType *r, short record);

Description
-----------

Reads all relevant information about race ID# RECORD into R. This
includes the ID, name (which is *not* read-only!!), race type (for
SwitchRace hosts: SRace allows any race to act as any other races if the
host chooses so..), alliances, points, etc.

Return value
------------

true if successful, false if not.

readMinefield()
===============

Syntax
------

     #include <vpl3.h>
     
     bool readMinefield(minefieldRecordType *m, short record);

Description
-----------

Reads all relevant information about minefield ID# RECORD into M. This
includes the ID, owner, size, etc.

Return value
------------

true if successful, false if not.

readIonstorm()
==============

Syntax
------

     #include <vpl3.h>
     
     bool readIonstorm(ionstormRecordType *m, short record);

Description
-----------

Reads all relevant information about ion storm ID# RECORD into M. This
includes the ID, size, strength, etc.

Return value
------------

true if successful, false if not.

readUFO()
=========

Syntax
------

     #include <vpl3.h>
     
     bool readUFO(UFORecordType *m, short record);

Description
-----------

Reads all relevant information about UFO ID# RECORD into M. This
includes the ID, owner, etc.

Return value
------------

true if successful, false if not.

readHost()
==========

Syntax
------

     #include <vpl3.h>
     
     bool readHost(hostRecordType *hostRecord);

Description
-----------

Reads the information about the host

Return value
------------

true if successful, false if not.

readPlayer()
============

Syntax
------

     #include <vpl3.h>
     
     bool readPlayer(playerRecordType *playerRecord, short record); // see comment R3

Description
-----------

Reads the information about a player. Can only be used at the
player-side.

Return value
------------

true if successful, false if not.

readIncomingMessage()
=====================

Syntax
------

     #include <vpl3.h>
     
     bool readIncomingMessage(messageRecordType *messageRecord, short record);

Description
-----------

Reads an incoming message - player-side only.

Return value
------------

true if successful, false if not.

readOutgoingMessage()
=====================

Syntax
------

     #include <vpl3.h>
     
     bool readOutgoingMessage(messageRecordType *messageRecord, short record);

Description
-----------

Reads an outgoing message - player-side only.

Return value
------------

true if successful, false if not.

writeConfig()
=============

Syntax
------

     #include <vpl3.h>
     
     bool writeConfig(configType *cfg);

Description
-----------

Stores the configuration data in CFG for later use.

Return value
------------

true if successful, false if not.

writeShip()
===========

Syntax
------

     #include <vpl3.h>
     
     bool writeShip(shipRecordType *p, short record);

Description
-----------

Stores the ship record in P for later use. Assumes RECORD is a correct
indication for the ship ID number.

Return value
------------

true if successful, false if not.

writePlanet()
=============

Syntax
------

     #include <vpl3.h>
     
     bool writePlanet(planetRecordType *p, short record);

Description
-----------

Stores the planet record in P for later use. Assumes RECORD is a correct
indication for the planet ID number.

Return value
------------

true if successful, false if not.

writeStarbase()
===============

Syntax
------

     #include <vpl3.h>
     
     bool writeStarbase(starbaseRecordType *p, short record);

Description
-----------

Stores the starbase record in P for later use. Assumes RECORD is a
correct indication for the planet/starbase ID number.

Return value
------------

true if successful, false if not

writeRace()
===========

Syntax
------

     #include <vpl3.h>
     
     bool writeRace(raceRecordType *r, short record);

Description
-----------

Stores the race record in R for later use. Assumes RECORD is a correct
indication for the race ID number.

Return value
------------

true if successful, false if not

writeMinefield()
================

Syntax
------

     #include <vpl3.h>
     
     bool writeMinefield(minefieldRecordType *m, short record);

Description
-----------

Stores the mine field record in M for later use. Assumes RECORD is a
correct indication for the mine field ID number.

Return value
------------

true if successful, false if not

writeIonstorm()
===============

Syntax
------

     #include <vpl3.h>
     
     bool writeIonstorm(ionstormRecordType *m, short record);

Description
-----------

Stores the ion storm  record in M for later use. Assumes RECORD is a
correct indication for the ion storm ID number.

Return value
------------

true if successful, false if not

writeUFO()
==========

Syntax
------

     #include <vpl3.h>
     
     bool writeUFO(UFORecordType *m, short record);

Description
-----------

Stores the UFO record in M for later use. Assumes RECORD is a correct
indication for the UFO ID number.

Return value
------------

true if successful, false if not.

writeIncomingMessage()
======================

Syntax
------

     #include <vpl3.h>
     
     bool writeIncomingMessage(messageRecordType *messageRecord, short record);

Description
-----------

Writes an incoming message

Return value
------------

true if successful, false if not.

writeUFO()
==========

Syntax
------

     #include <vpl3.h>
     
     bool writeOutgoingMessage(messageRecordType *messageRecord, short record);

Description
-----------

Writes an outgoing message

Return value
------------

true if successful, false if not.

Non-dispatched functions
************************

The following functions are used by the dispatchers and by certain
add-ons. For "normal" VGA Planets software, you will not need these
functions - ever.

Access to standard host files
=============================

_Access to the standard host files through non-dispatched functions
requires extensive knowledge of the setup of the game. Make sure you
have such knowledge, or leave it to the dispatchers!_

   The following is a list of openers, closers, readers and writers.
These are all available in <vgap.h> and provide "raw" access to the
host data. If you have studied the setup of the <vpl3.h> dispatchers
and structures, you will find that the endogenous host structures
contain considerably less data.  You will have to gather all the data
you need for yourself, and will thus often have to do a lot of
programming, while it has already been done for you..

openGen()
=========

Syntax
------

     #include <vgap.h>
     
     bool openGen(char *genPath);

Description
-----------

Opens the file pointed to by GENPATH and assumes it's (the equivalent
of) GEN.HST - the file with the general game info.

Return value
------------

true if successful, false if not

openHConfig()
=============

Syntax
------

     #include <vgap.h>
     
     bool openHConfig(char *hConfigPath);

Description
-----------

Opens the file pointed to by HCONFIGPATH and assumes it's (the
equivalent of) HCONFIG.HST - the file with the host configuration info.

Return value
------------

true if successful, false if not

openPlanetXYDB()
================

Syntax
------

     #include <vgap.h>
     
     bool openPlanetXYDB(char *planetXYPath);

Description
-----------

Opens the file pointed to by PLANETXYPATH and assumes it's (the
equivalent of) XYPLAN.HST - the file with the starmap.

Return value
------------

true if successful, false if not

openPlanetNameDB()
==================

Syntax
------

     #include <vgap.h>
     
     bool openPlanetNameDB(char *planetNMPath);

Description
-----------

Opens the file pointed to by PLANETNM and assumes it's (the equivalent
of) PLANET.NM - the file with the planet names.

Return value
------------

true if successful, false if not

openRaceNameDB()
================

Syntax
------

     #include <vgap.h>
     
     bool openRaceNameDB(char *raceNamePath);

Description
-----------

Opens the file pointed to by RACENAMEPATH and assumes it's (the
equivalent of) RACE.NM - the file with the race names.

Return value
------------

true if successful, false if not

openGreyDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openGreyDB(char *greyPath);

Description
-----------

Opens the file pointed to by GREYPATH and assumes it's (the equivalent
of) GREY.HST - the file with the ion storms etc.

Return value
------------

true if successful, false if not

openTorpDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openTorpDB(char *torpPath);

Description
-----------

Opens the file pointed to by TORPPATH and assumes it's (the equivalent
of) TORPSPEC.DAT - the file with the torpedo specifications.

Return value
------------

true if successful, false if not

openBeamDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openBeamDB(char *beamPath);

Description
-----------

Opens the file pointed to by BEAMPATH and assumes it's (the equivalent
of) BEAMSPEC.DAT - the file with the beam weapon specifications.

Return value
------------

true if successful, false if not

openEngineDB()
==============

Syntax
------

     #include <vgap.h>
     
     bool openEngineDB(char *enginePath);

Description
-----------

Opens the file pointed to by ENGINEPATH and assumes it's (the
equivalent of) ENGSPEC.DAT - the file with the engine specifications.

Return value
------------

true if successful, false if not

openBaseDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openBaseDB(char *basePath);

Description
-----------

Opens the file pointed to by BASEPATH and assumes it's (the equivalent
of) BDATA.HST - the file with the starbase info.

Return value
------------

true if successful, false if not

openHullDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openHullDB(char *hullPath);

Description
-----------

Opens the file pointed to by HULLPATH and assumes it's (the equivalent
of) HULLSPEC.DAT - the file with the hull specifications.

Return value
------------

true if successful, false if not

openMineDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openMineDB(char *minePath);

Description
-----------

Opens the file pointed to by MINEPATH and assumes it's (the equivalent
of) MINES.HST - the file with the general game info.

Return value
------------

true if successful, false if not

openPlanetDB()
==============

Syntax
------

     #include <vgap.h>
     
     bool openPlanetDB(char *planetPath);

Description
-----------

Opens the file pointed to by PLANETPATH and assumes it's (the
equivalent of) PDATA.HST - the file with the planet info.

Return value
------------

true if successful, false if not

openShipDB()
============

Syntax
------

     #include <vgap.h>
     
     bool openShipDB(char *shipPath);

Description
-----------

Opens the file pointed to by SHIPPATH and assumes it's (the equivalent
of) SHIP.HST - the file with the ship info.

Return value
------------

true if successful, false if not

openShipXYDB()
==============

Syntax
------

     #include <vgap.h>
     
     bool openShipXYDB(char *shipXYPath);

Description
-----------

Opens the file pointed to by SHIPXYPATH and assumes it's (the
equivalent of) SHIPXY.HST - the file with the ship coordinat info.

Return value
------------

true if successful, false if not

openUFODB()
===========

Syntax
------

     #include <vgap.h>
     
     bool openUFODB(char *UFOPath);

Description
-----------

Opens the file pointed to by UFOPATH and assumes it's (the equivalent
of) UFO.HST - the file with the UFO info.

Return value
------------

true if successful, false if not

openCloakDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool openCloakDB(char *cloakPath);

Description
-----------

Opens the file pointed to by CLOAKPATH and assumes it's (the equivalent
of) CLOAKC.HST - the file with the ship shield status and cloak status
info.

Return value
------------

true if successful, false if not

closeGen()
==========

Syntax
------

     #include <vgap.h>
     
     bool closeGen(void);

Description
-----------

Closes the file opened by openGen()

Return value
------------

true if successful, false if not

closeHConfig()
==============

Syntax
------

     #include <vgap.h>
     
     bool closeHConfig(void);

Description
-----------

Closes the file opened by openHConfig()

Return value
------------

true if successful, false if not

closePlanetXYDB()
=================

Syntax
------

     #include <vgap.h>
     
     bool closePlanetXYDB(void);

Description
-----------

Closes the file opened by openPlanetXYDB()

Return value
------------

true if successful, false if not

closePlanetNameDB()
===================

Syntax
------

     #include <vgap.h>
     
     bool closePlanetNameDB(void);

Description
-----------

Closes the file opened by openPlanetNameDB()

Return value
------------

true if successful, false if not

closeRaceNameDB()
=================

Syntax
------

     #include <vgap.h>
     
     bool closeRaceNameDB(void);

Description
-----------

Closes the file opened by openRaceNameDB()

Return value
------------

true if successful, false if not

closeGreyDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeGreyDB(void);

Description
-----------

Closes the file opened by openGreyDB()

Return value
------------

true if successful, false if not

closeTorpDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeTorpDB(void);

Description
-----------

Closes the file opened by openTorpDB()

Return value
------------

true if successful, false if not

closeBeamDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeBeamDB(void);

Description
-----------

Closes the file opened by openBeamDB()

Return value
------------

true if successful, false if not

closeEngineDB()
===============

Syntax
------

     #include <vgap.h>
     
     bool closeEngineDB(void);

Description
-----------

Closes the file opened by openEngineDB()

Return value
------------

true if successful, false if not

closeBaseDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeBaseDB(void);

Description
-----------

Closes the file opened by openBaseDB()

Return value
------------

true if successful, false if not

closeHullDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeHullDB(void);

Description
-----------

Closes the file opened by openHullDB()

Return value
------------

true if successful, false if not

closeMineDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeMineDB(void);

Description
-----------

Closes the file opened by openMineDB()

Return value
------------

true if successful, false if not

closePlanetDB()
===============

Syntax
------

     #include <vgap.h>
     
     bool closePlanetDB(void);

Description
-----------

Closes the file opened by openPlanetDB()

Return value
------------

true if successful, false if not

closeShipDB()
=============

Syntax
------

     #include <vgap.h>
     
     bool closeShipDB(void);

Description
-----------

Closes the file opened by openShipDB()

Return value
------------

true if successful, false if not

closeShipXYDB()
===============

Syntax
------

     #include <vgap.h>
     
     bool closeShipXYDB(void);

Description
-----------

Closes the file opened by openShipXYDB()

Return value
------------

true if successful, false if not

closeUFODB()
============

Syntax
------

     #include <vgap.h>
     
     bool closeUFODB(void);

Description
-----------

Closes the file opened by openUFODB()

Return value
------------

true if successful, false if not

closeCloakDB()
==============

Syntax
------

     #include <vgap.h>
     
     bool closeCloakDB(void);

Description
-----------

Closes the file opened by openCloakDB()

Return value
------------

true if successful, false if not

readActive()
============

Syntax
------

     #include <vgap.h>
     
     bool readActive(bool *isActive, short record);

Description
-----------

Reads whether or not race RECORD is active. Sets ISACTIVE accordingly
(true if the race is still alive, false if not).

Return value
------------

true if successful, false if not

readAllianceStatus()
====================

Syntax
------

     #include <vgap.h>
     
     bool readAllianceStatus(allianceType *alliances);

Description
-----------

Reads the alliances in the game.

Return value
------------

true if successful, false if not

readKillPoints()
================

Syntax
------

     #include <vgap.h>
     
     bool readKillPoints(short *PBP, short record);

Description
-----------

Reads the priority build points (aka killpoints) of race RECORD into
PBP.

Return value
------------

true if successful, false if not

readCrewExperience()
====================

Syntax
------

     #include <vgap.h>
     
     bool readCrewExperience(short *experience, short record);

Description
-----------

Reads the crew experience of ship number RECORD.

Return value
------------

true if successful, false if not

readIonStorm()
==============

Syntax
------

     #include <vgap.h>
     
     bool readIonStorm(ionType *ionRec, short record);

Description
-----------

Reads the information about ion storm number RECORD

Return value
------------

true if successful, false if not

readTorpRecord()
================

Syntax
------

     #include <vgap.h>
     
     bool readTorpRecord(torpSpecType *torpRec, short record);

Description
-----------

Reads the torpedo specifications for torpedo (tube) RECORD

Return value
------------

true if successful, false if not

readBeamRecord()
================

Syntax
------

     #include <vgap.h>
     
     bool readBeamRecord(beamSpecType *beamRec, short record);

Description
-----------

Reads the beam weapon specifications for beam weapon RECORD

Return value
------------

true if successful, false if not

readEngineRecord()
==================

Syntax
------

     #include <vgap.h>
     
     bool readEngineRecord(engineSpecType *engineRec, short record);

Description
-----------

Reads the engine specifications for engine type RECORD

Return value
------------

true if successful, false if not

readBaseRecord()
================

Syntax
------

     #include <vgap.h>
     
     bool readBaseRecord(baseType *baseRec, short record);

Description
-----------

Reads the starbase at planet ID# RECORD

Return value
------------

true if successful, false if not

readHullRecord()
================

Syntax
------

     #include <vgap.h>
     
     bool readHullRecord(hullSpecType *hullRec, short record);

Description
-----------

Reads the hull specifications of hull type number RECORD

Return value
------------

true if successful, false if not

readMineRecord()
================

Syntax
------

     #include <vgap.h>
     
     bool readMineRecord(mineType *mineRec, short record);

Description
-----------

Reads the info about mine field number RECORD

Return value
------------

true if successful, false if not

readPlanetRecord()
==================

Syntax
------

     #include <vgap.h>
     
     bool readPlanetRecord(planetType *planetRec, short record);

Description
-----------

Reads the info about planet number RECORD

Return value
------------

true if successful, false if not

readShipRecord()
================

Syntax
------

     #include <vgap.h>
     
     bool readShipRecord(shipType *shipRec, short record);

Description
-----------

Reads the info about ship number RECORD

Return value
------------

true if successful, false if not

readShipXYRecord()
==================

Syntax
------

     #include <vgap.h>
     
     bool readShipXYRecord(shipXYType *shipXYRec, short record);

Description
-----------

Reads the coordinats and mass of ship number RECORD

Return value
------------

true if successful, false if not

readUFORecord()
===============

Syntax
------

     #include <vgap.h>
     
     bool readUFORecord(UFOType *UFORec, short record);

Description
-----------

Reads the info about UFO number RECORD

Return value
------------

true if successful, false if not

readHConfig()
=============

Syntax
------

     #include <vgap.h>
     
     bool readHConfig(hConfigType *hConfigRec);

Description
-----------

Reads the host configuration

Return value
------------

true if successful, false if not

readPlanetXYRecord()
====================

Syntax
------

     #include <vgap.h>
     
     bool readPlanetXYRecord(planetXYType *planetXYRec, short record);

Description
-----------

Reads the location of planet number RECORD

Return value
------------

true if successful, false if not

readPlanetNameRecord()
======================

Syntax
------

     #include <vgap.h>
     
     bool readPlanetNameRecord(char *planetNMRec, short record);

Description
-----------

Reads the name of planet number RECORD

Return value
------------

true if successful, false if not

readRaceNames()
===============

Syntax
------

     #include <vgap.h>
     
     bool readRaceNames(raceNameType *raceNames);

Description
-----------

Reads the names of all races in all allowable forms

Return value
------------

true if successful, false if not

readShipShieldStatus()
======================

Syntax
------

     #include <vgap.h>
     
     bool readShipShieldStatus(shipShieldStatusType *S, short record);

Description
-----------

Reads the shield and cloak status of theip ID# RECORD

Return value
------------

true if successful, false if not

writeActive()
=============

Syntax
------

     #include <vgap.h>
     
     bool writeActive(bool *isActive, short record);

Description
-----------

Sets whether or not race RECORD is active.

Return value
------------

true if successful, false if not

writeAllianceStatus()
=====================

Syntax
------

     #include <vgap.h>
     
     bool writeAllianceStatus(allianceType *alliances);

Description
-----------

Writes the alliances

Return value
------------

true if successful, false if not

writeKillPoints()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeKillPoints(short *PBP, short record);

Description
-----------

Writes the priority build points for race RECORD

Return value
------------

true if successful, false if not

writeCrewExperience()
=====================

Syntax
------

     #include <vgap.h>
     
     bool writeCrewExperience(short *experience, short record);

Description
-----------

Writes the crew experience for ship number RECORD

Return value
------------

true if successful, false if not

writeIonStorm()
===============

Syntax
------

     #include <vgap.h>
     
     bool writeIonStorm(ionType *ionRec, short record);

Description
-----------

Writes the information of ion storm RECORD

Return value
------------

true if successful, false if not

writeTorpRecord()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeTorpRecord(torpSpecType *torpRec, short record);

Description
-----------

Writes the torpedo specifications of torpedo type RECORD

Return value
------------

true if successful, false if not

writeBeamRecord()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeBeamRecord(beamSpecType *beamRec, short record);

Description
-----------

Writes the beam weapon specifications for beam weapon type RECORD

Return value
------------

true if successful, false if not

writeEngineRecord()
===================

Syntax
------

     #include <vgap.h>
     
     bool writeEngineRecord(engineSpecType *engineRec, short record);

Description
-----------

Writes the engine specifications for engine type RECORD

Return value
------------

true if successful, false if not

writeBaseRecord()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeBaseRecord(baseType *baseRec, short record);

Description
-----------

Writes the information of the starbase as planet number RECORD

Return value
------------

true if successful, false if not

writeHullRecord()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeHullRecord(hullSpecType *hullRec, short record);

Description
-----------

Writes the hull specifications of hu

Return value
------------

true if successful, false if not

writeMineRecord()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeMineRecord(mineType *mineRec, short record);

Description
-----------

Writes mine field RECORD

Return value
------------

true if successful, false if not

writePlanetRecord()
===================

Syntax
------

     #include <vgap.h>
     
     bool writePlanetRecord(planetType *planetRec, short record);

Description
-----------

Writes info of planet RECORD

Return value
------------

true if successful, false if not

writeShipRecord()
=================

Syntax
------

     #include <vgap.h>
     
     bool writeShipRecord(shipType *shipRec, short record);

Description
-----------

Writes info of ship RECORD

Return value
------------

true if successful, false if not

writeShipXYRecord()
===================

Syntax
------

     #include <vgap.h>
     
     bool writeShipXYRecord(shipXYType *shipXYRec, short record);

Description
-----------

Writes coordinats and mass of ship RECORD

Return value
------------

true if successful, false if not

writeUFORecord()
================

Syntax
------

     #include <vgap.h>
     
     bool writeUFORecord(UFOType *UFORec, short record);

Description
-----------

Writes info of UFO RECORD

Return value
------------

true if successful, false if not

writeHConfig()
==============

Syntax
------

     #include <vgap.h>
     
     bool writeHConfig(hConfigType *hConfigRec);

Description
-----------

Writes the host configuration

Return value
------------

true if successful, false if not

writePlanetXYRecord()
=====================

Syntax
------

     #include <vgap.h>
     
     bool writePlanetXYRecord(planetXYType *planetXYRec, short record);

Description
-----------

Writes the coordinats of planet RECORD

Return value
------------

true if successful, false if not

writePlanetNameRecord()
=======================

Syntax
------

     #include <vgap.h>
     
     bool writePlanetNameRecord(char *planetNMRec, short record);

Description
-----------

Writes the name of planet RECORD

Return value
------------

true if successful, false if not

writeRaceNames()
================

Syntax
------

     #include <vgap.h>
     
     bool writeRaceNames(raceNameType *raceNames);

Description
-----------

Writes the names of all races

Return value
------------

true if successful, false if not

writeShipShieldStatus()
=======================

Syntax
------

     #include <vgap.h>
     
     bool writeShipShieldStatus(shipShieldStatusType *S, short record);

Description
-----------

Writes the shield and cloak status of ship RECORD

Return value
------------

true if successful, false if not

Access to Gators files
**********************

RLSystems Gators V3 keeps a number of files, linking parts of the Echo
Cluster together, as well as different games. The third version of
Gators is also compatible with some earlier versions of Gators - as of
version 2.0.8 F. This library provides access into all those files, and
lets you know whether they exist or not. It also lets you convert V2
Gators to V3 Gators, but not the other way around.

existGTR2GatorDB()
******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool existGTR2GatorDB(void);

Description
===========

Checks whether or not the GATOR.HST file exists in the game path.  It
does not check inside the file to see whether or not it is actually a V2
Gators database.

Return value
============

true if the file exists, false if not. Will normally return false.

existGTR2GatorConfig()
**********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool existGTR2GatorConfig(void);

Description
===========

Checks whether or not the V2 Gators configuration file exists.  This
does not look inside the file to see what the actual version number is.

Return value
============

true if the file exists, false if not.

existGTR3GatorDB()
******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool existGTR3GatorDB(void);

Description
===========

Checks whether or not the GATORS.HST file exists in the game directory.
This file always exists if Gators is being used, and is thus a good
indication for whether or not Gators is being used.

Return value
============

true if the file exists, false if not. This will usually return true if
Gators is being used, false if not.

existGTR3GatorConfig()
**********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool existGTR3GatorConfig(void);

Description
===========

Checks whether or not the Gators configuration file exists in the game
path. It does not look inside the file for which version of Gators is
being used.

Return value
============

true if the file exists, false if not.

readGTRVersion()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     short readGTRVersion(void);

Description
===========

Gets the version number of the file setup of the Gators files from the
configuration file.

Return value
============

a representation of the version of Gators being used. The upper byte is
the main version number (0x02 or 0x03); the lower byte is the version
of the file setup (usually 0x08, 0x00 or 0x11).

   This version number only changes when the setup of the Gators files
changes and is then changed to the version number of the version
implementing the new setup. The last change up til now (July 13th 2000)
was with version 3.1.1 of Gators, at which time the setup was adjusted
to allow for a lot of new options.

   Gators V3 is compatible with data files from version 2.0.8 and later.

openGTR2GatorDB()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool openGTR2GatorDB(void);

Description
===========

Opens the V2 Gators database - should only be used if you _know_ that
it exists, and that the version is V2. normally, you just shouldn't use
it.

Return value
============

true if successful, false if not.

openGTR2Config()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool openGTR2Config(void);

Description
===========

Opens the V2 configuration file. Normally, you won't have to use this
function.

Return value
============

true if successful, false if not.

closeGTR2GatorDB()
******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool closeGTR2GatorDB(void);

Description
===========

Closes the file opened by openGTR2GatorDB()

Return value
============

true if successful, false if not.

closeGTR2Config()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool closeGTR2Config(void);

Description
===========

Closes the file opened by openGTR2Config()

Return value
============

true if successful, false if not.

readGTR2GatorRecord()
*********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool readGTR2GatorRecord(GTR2_GatorType *gator, short record);

Description
===========

Reads V2 Gator record RECORD

Return value
============

true if successful, false if not.

readGTR2Config()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool readGTR2Config(GTR2_ConfigType *config);

Description
===========

Reads the configuration of Gators V2

Return value
============

true if successful, false if not.

writeGTR2GatorRecord()
**********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool writeGTR2GatorRecord(GTR2_GatorType *gator, short record);

Description
===========

Writes V2 Gator record RECORD

Return value
============

true if successful, false if not.

writeGTR2Config()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool writeGTR2Config(GTR2_ConfigType *config);

Description
===========

Writes the Gators V2 configuration

Return value
============

true if successful, false if not.

GTR2Gtr2GTR3Gtr()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool GTR2Gtr2GTR3Gtr(gatorType *gtr3, GTR2_GatorType *gtr2);

Description
===========

Converts a V2 Gator GTR2 to a V3 Gator GTR3

Return value
============

true if successful, false if not.

GTR2Cfg2GTR3Cfg()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool GTR2Cfg2GTR3Cfg(gatorConfigType *cfg3, GTR2_ConfigType *cfg2);

Description
===========

Converts V2 Gator configuration to V3 Gator configuration

Return value
============

true if successful, false if not.

renameGTR2ConfigFile()
**********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool renameGTR2ConfigFile(void);

Description
===========

Prior to conversion, V2 files may have to be renamed to their original
V2 counterparts, as V2 files sometimes had names now associated with V3
of Gators. This method renames the Gators configuration.

Return value
============

true if successful, false if not.

renameGTR2GatorDB()
*******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool renameGTR2GatorDB(void);

Description
===========

Prior to conversion, V2 files may have to be renamed to their original
V2 counterparts, as V2 files sometimes had names now associated with V3
of Gators. This method renames the Gators database.

Return value
============

true if successful, false if not.

initGatorDB()
*************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool initGatorDB(void);

Description
===========

Initializes the Gators database and destroys all existing Gators.

Return value
============

true if successful, false if not.

initGatorConfig()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool initGatorConfig(void);

Description
===========

Initializes the Gators configuration to the defaults.

Return value
============

true if successful, false if not.

initShipUFODB()
***************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool initShipUFODB(void);

Description
===========

initializes the database with the warped ships

Return value
============

true if successful, false if not.

initLinkShipDB()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool initLinkShipDB(void);

Description
===========

Initializes the database with the ships between universes. This
database is used when a ship is warped into a parallel universe -
another game - to store the ships that haven't arrived yet.

Return value
============

true if successful, false if not.

openGatorDB()
*************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool openGatorDB(void);

Description
===========

Opens the Gators database

Return value
============

true if successful, false if not.

openGatorConfig()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool openGatorConfig(void);

Description
===========

Opens the Gators configuration file

Return value
============

true if successful, false if not.

openShipUFODB()
***************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool openShipUFODB(void);

Description
===========

Opens the database with the warped ships

Return value
============

true if successful, false if not.

openLinkShipDB()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool openLinkShipDB(void);

Description
===========

opens the database with the ships between universes

Return value
============

true if successful, false if not.

closeGatorDB()
**************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool closeGatorDB(void);

Description
===========

Closes the file opened by openGatorDB()

Return value
============

true if successful, false if not.

closeGatorConfig()
******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool closeGatorConfig(void);

Description
===========

Closes the Gators configuration file opened by openGatorConfig()

Return value
============

true if successful, false if not.

closeShipUFODB()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool closeShipUFODB(void);

Description
===========

Closes the database with the warped ships opened by openShipUFODB()

Return value
============

true if successful, false if not.

closeLinkShipDB()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool closeLinkShipDB(void);

Description
===========

Closes the database with the ships between universes opened by
openLinkShipDB()

Return value
============

true if successful, false if not.

getGatorRecord()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool getGatorRecord(gatorType *gator, short record);

Description
===========

Reads a Gator record directly from the database. You won't normally
have to use this function, but should use readGatorRecord() in stead.

Return value
============

true if successful, false if not.

readGatorRecord()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool readGatorRecord(gatorType *gator, short record);

Description
===========

Reads Gator record RECORD into GATOR.

Return value
============

true if successful, false if not.

readGatorConfig()
*****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool readGatorConfig(gatorConfigType *config);

Description
===========

Reads the configuration of Gators

Return value
============

true if successful, false if not.

readShipUFORecord()
*******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool readShipUFORecord(shipUFOType *shipUFO, short record);

Description
===========

Reads warped ship RECORD into SHIPUFO.

Return value
============

true if successful, false if not.

readLinkShipRecord()
********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool readLinkShipRecord(linkShipType *linkShip, short record);

Description
===========

Reads info about a ship between universes, number RECORD into LINKSHIP

Return value
============

true if successful, false if not.

putGatorRecord()
****************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool putGatorRecord(gatorType *gator, short record);

Description
===========

Writes a gator record directly to the database. Normally, you should
use writeGatorRecord() in stead of this function.

Return value
============

true if successful, false if not.

writeGatorRecord()
******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool writeGatorRecord(gatorType *gator, short record);

Description
===========

Writes Gator record RECORD

Return value
============

true if successful, false if not.

writeGatorConfig()
******************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool writeGatorConfig(gatorConfigType *config);

Description
===========

Writes the configuration of the Gators add-on

Return value
============

true if successful, false if not.

writeShipUFORecord()
********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool writeShipUFORecord(shipUFOType *shipUFO, short record);

Description
===========

Writes warped ship number RECORD.

Return value
============

true if successful, false if not.

writeLinkShipRecord(),
**********************

Syntax
======

     #include <vpl3/gtr3FileDispatchers.h>
     
     bool writeLinkShipRecord(linkShipType *linkShip, short record);

Description
===========

Writes ship between universes number RECORD

Return value
============

true if successful, false if not.

Access to Starbase Enhancer files
*********************************

The Starbase Enhancer uses a relatively novel way to store some of it's
information, designed to enable almost any amount of objects to be
stored.

   The components being towed by ships are stored in an unindexed
array, of which the order is subject to change and irrelevant. The
array is stored in a file as a whole, and loaded into memory as such.
It's end is marked by an impossible record, and access to it's data is
managed by "surrounding" software designed to keep track of the array
by itself. Thus, the components have no unique ID code, nor is there
any other way to distinguish them from any other component save by the
tags they carry. The ID of the component is stored in the database, but
is completely arbitrary and may change between runs of the add-on.

   This method of storing towed components ensures that the component
database is never larger than it needs to be, and it is always possible
to create another towed component. Theoratically, there could be
2.147.483.648 components in tow without any problems at all - save
perhaps a lack of hard disk space on the host computer, as each
component does take 32 bytes of storage space and most computers don't
have 64 GB of free disk space.

   This method is applied to both the components and the starbases
being towed.  Enhanced starbases are stored in an indexed array, with
the index being the planet ID# of the planet the base is orbiting.

openEnhancedBaseDB()
********************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool openEnhancedBaseDB(void);

Description
===========

Opens the database with the enhanced starbases

Return value
============

true if succesful, false if not

closeEnhancedBaseDB()
*********************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool closeEnhancedBaseDB(void);

Description
===========

Closes the database with the enhanced starbases

Return value
============

true if succesful, false if not

readEnhancedBaseRecord()
************************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool readEnhancedBaseRecord(enhancedBaseRecordType *ESB, short record);

Description
===========

Reads the information about enhanced starbase ESB around planet RECORD.

Return value
============

true if succesful, false if not

writeEnhancedBaseRecord()
*************************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool writeEnhancedBaseRecord(enhancedBaseRecordType *ESB, short record);

Description
===========

Writes the information about enhanced starbase ESB around planet RECORD

Return value
============

true if succesful, false if not

getComponentTable()
*******************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool getComponentTable(void);

Description
===========

Reads the table of towed components into memory, so it can be accessed.

Return value
============

true if succesful, false if not

getTowedBaseTable()
*******************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool getTowedBaseTable(void);

Description
===========

Reads the table of towed starbases so it can be accessed.

Return value
============

true if succesful, false if not

putComponentTable()
*******************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool putComponentTable(void);

Description
===========

Writes the table of towed components to file, when done with the
components.

Return value
============

true if succesful, false if not

putTowedBaseTable()
*******************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool putTowedBaseTable(void);

Description
===========

Writes the table of towed starbases to file.

Return value
============

true if succesful, false if not

countComponents()
*****************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     int countComponents(void);

Description
===========

Counts the number of components being towed. This number is needed if
you want to know when to stop asking for more components.

Return value
============

the number of components being towed, or -1 if an error occured.

newComponent()
**************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     int newComponent(void);

Description
===========

Creates a new, empty towed component.

Return value
============

the number of the new component, or -1 if an error occured

loadEngines()
*************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool loadEngines(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);

Description
===========

Loads all engines of type TECHLEVEL from the STARBASE onto the SHIP

Return value
============

true if succesful, false if not

loadBeamWeapons()
*****************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool loadBeamWeapons(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);

Description
===========

Loads all beam weapons of type TECHLEVEL from the STARBASE onto the SHIP

Return value
============

true if succesful, false if not

loadTorpedoes()
***************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool loadTorpedoes(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);

Return value
============


Description
===========

Loads all torpedo tubes of type TECHLEVEL from the STARBASE onto the
SHIP

true if succesful, false if not

loadHulls()
***********

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool loadHulls(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);

Description
===========

Loads all hulls of type TECHLEVEL (actually the index of the hull type
being loaded in the list of hulls the starbase can build) from the
STARBASE onto the SHIP

Return value
============

true if succesful, false if not

countTowedBases()
*****************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     int countTowedBases(void);

Description
===========

Counts all starbases being towed.

Return value
============

the number of starbases being towed

newTowedBase()
**************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     int newTowedBase(void);

Description
===========

Creates a new starbase being towed

Return value
============

the index number of the new starbase

hookStationaryStarbase()
************************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool hookStationaryStarbase(shipRecordType *ship, starbaseRecordType *starbase);

Description
===========

Hooks the STARBASE onto the SHIP, which will then tow it.

Return value
============

true if succesful, false if not

makeUFOTowedBase()
******************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool makeUFOTowedBase(towedBaseRecordType *T);

Description
===========

Makes a UFO record for the starbase T being towed.

Return value
============

true if succesful, false if not

unmakeUFOTowedBase()
********************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool unmakeUFOTowedBase(towedBaseRecordType *T);

Description
===========

Removes the starbase T from the UFO database

Return value
============

true if succesful, false if not

makeUFOComponent()
******************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool makeUFOComponent(componentRecordType *T);

Description
===========

Creates a UFO record for a towed component T

Return value
============

true if succesful, false if not

unmakeUFOComponent()
********************

Syntax
======

     #include <vpl3/enhancerOptions.h>
     
     bool unmakeUFOComponent(componentRecordType *T);

Description
===========

Removed towed component T from the UFO database

Return value
============

true if succesful, false if not

Data filters and compilers
**************************

Because of the differences between the various compilers used to make
VGA Planets software, it is necessary to filter _all_ data used by this
library from the structures used to store them in memory to the way
they are stored on disk. The only data that does not need to be
filtered - and isn't filtered - is the temporary data which is only
used during the run of the program itself. Part of the filters employed
by this library may seem slightly redundant, but I have found that in
order to have the code always behave the same, I should not depend on
the compiler it is compiled on to sort out how my data is aligned, so I
don't.

   The list below is a list of all filters and compilers used by the
library.  The difference between a filter and a compiler is simple: a
filter converts one data type to another, and lets all useable data go
through. A compiler compiles the required information from the
available sources and returns the end result. A decompiler does the
exact opposite of a compiler, and stores the compiled information it is
given in the sources of the original information.

compileConfig()
***************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool compileConfig(configType *config);

Description
===========

Compiles the configuration information in configType CONFIG.

Return value
============

true if successful, false if not

decompileConfig()
*****************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool decompileConfig(configType *config);

Description
===========

Decompiles the configuration information in configType CONFIG and
stores the data on disk.

Return value
============

true if successful, false if not

compileMinefieldRecord()
************************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool compileMinefieldRecord(minefieldRecordType *minefieldRecord, short record);

Description
===========

Compiles the mine field information for mine field RECORD

Return value
============

true if successful, false if not

decompileMinefieldRecord()
**************************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool decompileMinefieldRecord(minefieldRecordType *minefieldRecord);

Description
===========

Decompiles the mine field information in MINEFIELDRECORD. Assumes
Read-Only fields were only read.

Return value
============

true if successful, false if not

compileRaceRecord()
*******************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool compileRaceRecord(raceRecordType *raceRecord, short record);

Description
===========

Compiles the race information for race RECORD

Return value
============

true if successful, false if not

decompileRaceRecord()
*********************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool decompileRaceRecord(raceRecordType *raceRecord);

Description
===========

Decompiles the information in RACERECORD. Assumes the Read-Only
information was only read.

Return value
============

true if successful, false if not

compileShipRecord()
*******************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool compileShipRecord(shipRecordType *shipRecord, short record);

Description
===========

Compiles the ship information for ship RECORD

Return value
============

true if successful, false if not

decompileShipRecord()
*********************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool decompileShipRecord(shipRecordType *shipRecord);

Description
===========

Decompiles the ship information in SHIPRECORD

Return value
============

true if successful, false if not

compilePlanetRecord()
*********************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool compilePlanetRecord(planetRecordType *planetRecord, short record);

Description
===========

Compiles the planet information for planet RECORD

Return value
============

true if successful, false if not

decompilePlanetRecord()
***********************

Syntax
======

     #include <vpl3/compilers.h>
     
     bool decompilePlanetRecord(planetRecordType *planetRecord);

Description
===========

Decompiles the planet information in PLANETRECORD.

Return value
============

true if successful, false if not

planetXY2buffer()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool planetXY2buffer(void *buffer, planetXYType *planetXY);

Description
===========

Converts planetXYType to the way it is stored on disk.

Return value
============

true if successful, false if not

buffer2planetXY()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2planetXY(planetXYType *planetXY, void *buffer);

Description
===========

Converts the data in BUFFER to planetXYType

Return value
============

true if successful, false if not

planet2buffer()
***************

Syntax
======

     #include <vpl3/filters.h>
     
     bool planet2buffer(void *buffer, planetType *planet);

Description
===========

Converts planetType to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2planet()
***************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2planet(planetType *planet, void *buffer);

Description
===========

Converts the data in BUFFER to planetType

Return value
============

true if successful, false if not

buffer2ship()
*************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2ship(shipType *ship, void *buffer);

Description
===========

Converts shipType to the way it is stored on disk

Return value
============

true if successful, false if not

ship2buffer()
*************

Syntax
======

     #include <vpl3/filters.h>
     
     bool ship2buffer(void *buffer, shipType *ship);

Description
===========

Converts the data in BUFFER to shipType

Return value
============

true if successful, false if not

shipXY2buffer()
***************

Syntax
======

     #include <vpl3/filters.h>
     
     bool shipXY2buffer(void *buffer, shipXYType *shipXY);

Description
===========

Converts the shipXYType to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2shipXY()
***************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2shipXY(shipXYType *shipXY, void *buffer);

Description
===========

Converts the data in the buffer to shipXYType

Return value
============

true if successful, false if not

base2buffer()
*************

Syntax
======

     #include <vpl3/filters.h>
     
     bool base2buffer(void *buffer, baseType *base);

Description
===========

Converts the data in baseType to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2base()
*************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2base(baseType *base, void *buffer);

Description
===========

Converts the data in BUFFER to baseType

Return value
============

true if successful, false if not

raceName2buffer()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool raceName2buffer(void *buffer, raceNameType *raceNames);

Description
===========

Converts the raceNameType info to the way it is stored on disk.

Return value
============

true if successful, false if not

buffer2raceName()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2raceName(raceNameType *raceNames, void *buffer);

Description
===========

Converts the buffer data to raceNameType

Return value
============

true if successful, false if not

hullSpec2buffer()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool hullSpec2buffer(void *buffer, hullSpecType *hullSpec);

Description
===========

Converts the hullSpecType to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2hullSpec()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2hullSpec(hullSpecType *hullSpec, void *buffer);

Description
===========

Converts the BUFFER data to hullSpecType

Return value
============

true if successful, false if not

engineSpec2buffer()
*******************

Syntax
======

     #include <vpl3/filters.h>
     
     bool engineSpec2buffer(void *buffer, engineSpecType *engineSpec);

Description
===========

Converts the engineSpecType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2engineSpec()
*******************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2engineSpec(engineSpecType *engineSpec, void *buffer);

Description
===========

Converts the BUFFER data to engineSpecType

Return value
============

true if successful, false if not

beamSpec2buffer()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool beamSpec2buffer(void *buffer, beamSpecType *beamSpec);

Description
===========

Converts the beamSpecType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2beamSpec()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2beamSpec(beamSpecType *beamSpec, void *buffer);

Description
===========

Converts the BUFFER data to beamSpecType

Return value
============

true if successful, false if not

torpSpec2buffer()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool torpSpec2buffer(void *buffer, torpSpecType *torpSpec);

Description
===========

Converts the torpSpecType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2torpSpec()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2torpSpec(torpSpecType *torpSpec, void *buffer);

Description
===========

Converts the BUFFER data to torpSpecType

Return value
============

true if successful, false if not

hConfig2buffer()
****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool hConfig2buffer(void *buffer, hConfigType *hConfig);

Description
===========

Converts the hConfigType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2hConfig()
****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2hConfig(hConfigType *hConfig, void *buffer);

Description
===========

Converts the BUFFER data to hConfigType

Return value
============

true if successful, false if not

VCR2buffer()
************

Syntax
======

     #include <vpl3/filters.h>
     
     bool VCR2buffer(void *buffer, VCRType *VCR);

Description
===========

Converts the VCRType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2VCR()
************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2VCR(VCRType *VCR, void *buffer);

Description
===========

Converts the BUFFER data to VCRType

Return value
============

true if successful, false if not

mine2buffer()
*************

Syntax
======

     #include <vpl3/filters.h>
     
     bool mine2buffer(void *buffer, mineType *mine);

Description
===========

Converts the mineType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2mine()
*************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2mine(mineType *mine, void *buffer);

Description
===========

Converts the BUFFER data to mineType

Return value
============

true if successful, false if not

UFO2buffer()
************

Syntax
======

     #include <vpl3/filters.h>
     
     bool UFO2buffer(void *buffer, UFOType *UFO);

Description
===========

Converts the UFOType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2UFO()
************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2UFO(UFOType *UFO, void *buffer);

Description
===========

Converts the BUFFER data to UFOType

Return value
============

true if successful, false if not

ion2buffer()
************

Syntax
======

     #include <vpl3/filters.h>
     
     bool ion2buffer(void *buffer, ionType *ion);

Description
===========

Converts the ionType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2ion()
************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2ion(ionType *ion, void *buffer);

Description
===========

Converts the BUFFER data to ionType

Return value
============

true if successful, false if not

alliance2buffer()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool alliance2buffer(void *buffer, allianceType *alliance);

Description
===========

Converts the allianceType data to the way it is stored on disk

Return value
============

true if successful, false if not

buffer2alliance()
*****************

Syntax
======

     #include <vpl3/filters.h>
     
     bool buffer2alliance(allianceType *alliance, void *buffer);

Description
===========

Converts the BUFFER data to allianceType

Return value
============

true if successful, false if not

UFORecord2UFO()
***************

Syntax
======

     #include <vpl3/filters.h>
     
     bool UFORecord2UFO(UFOType *UFO, UFORecordType *UFORecord);

Description
===========

Converts the UFOType data to UFORecordType data

Return value
============

true if successful, false if not

UFO2UFORecord()
***************

Syntax
======

     #include <vpl3/filters.h>
     
     bool UFO2UFORecord(UFORecordType *UFORecord, UFOType *UFO);

Description
===========

Converts the UFOType data to UFORecordType data

Return value
============

true if successful, false if not

ion2ionstormRecord()
********************

Syntax
======

     #include <vpl3/filters.h>
     
     bool ion2ionstormRecord(ionstormRecordType *ionstormRecord, ionType *ion);

Description
===========

Converts the ionType data to ionRecordType data

Return value
============

true if successful, false if not

ionstormRecord2ion()
********************

Syntax
======

     #include <vpl3/filters.h>
     
     bool ionstormRecord2ion(ionType *ion, ionstormRecordType *ionstormRecord);

Description
===========

Converts the ionRecordType data to ionType data

Return value
============

true if successful, false if not

base2starbaseRecord()
*********************

Syntax
======

     #include <vpl3/filters.h>
     
     bool base2starbaseRecord(starbaseRecordType *starbaseRecord, baseType *base);

Description
===========

Converts the starbaseRecordType data to baseType data

Return value
============

true if successful, false if not

starbaseRecord2base()
*********************

Syntax
======

     #include <vpl3/filters.h>
     
     bool starbaseRecord2base(baseType *base, starbaseRecordType *starbaseRecord);

Description
===========

Converts the baseType data to starbaseRecordType data

Return value
============

true if successful, false if not

buf2Cmp()
*********

Syntax
======

     #include <vpl3/enh2Structures.h>
     
     bool buf2Cmp(componentRecordType *C, char *B);

Description
===========

Converts the buffer B to componentRecordType

Return value
============

true if successful, false if not

cmp2Buf()
*********

Syntax
======

     #include <vpl3/enh2Structures.h>
     
     bool cmp2Buf(char *B, componentRecordType *C);

Description
===========

Converts the componentRecordType data to the way it is stored on disk

Return value
============

true if successful, false if not

buf2Tsb()
*********

Syntax
======

     #include <vpl3/enh2Structures.h>
     
     bool buf2Tsb(towedBaseRecordType *T, char *B);

Description
===========

Converts the buffer B to towedBaseRecordType data

Return value
============

true if successful, false if not

tsb2Buf()
*********

Syntax
======

     #include <vpl3/enh2Structures.h>
     
     bool tsb2Buf(char *B, towedBaseRecordType *T);

Description
===========

Converts the towedBaseRecordType data to the way it is stored on disk

Return value
============

true if successful, false if not

buf2Esb()
*********

Syntax
======

     #include <vpl3/enh2Structures.h>
     
     bool buf2Esb(enhancedBaseRecordType *E, char *B);

Description
===========

Converts the buffer B to enhancedBaseRecordType data

Return value
============

true if successful, false if not

esb2Buf()
*********

Syntax
======

     #include <vpl3/enh2Structures.h>
     
     bool esb2Buf(char *B, enhancedBaseRecordType *E);

Description
===========

Converts the enhancedBaseRecordType data to the way it is stored on disk

Return value
============

true if successful, false if not

GTR2_gtr2Buf()
**************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool GTR2_gtr2Buf(char *buffer, GTR2_GatorType *gator);

Description
===========

Converts a V2 Gator (GTR2_GatorType) to the way it is stored on disk

Return value
============

true if successful, false if not

GTR2_buf2Gtr()
**************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool GTR2_buf2Gtr(GTR2_GatorType *gator, char *buffer);

Description
===========

Converts the BUFFER data to GTR2_Gatortype

Return value
============

true if successful, false if not

GTR2_cfg2Buf()
**************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool GTR2_cfg2Buf(char *buffer, GTR2_ConfigType* config);

Description
===========

Converts the V2 Gators Configuration (GTR2_ConfigType) to the way it is
stored on disk

Return value
============

true if successful, false if not

GTR2_buf2Cfg()
**************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool GTR2_buf2Cfg(GTR2_ConfigType* config, char *buffer);

Description
===========

Converts the BUFFER data to GTR2_ConfigType

Return value
============

true if successful, false if not

gtr2Buf()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool gtr2Buf(char *buffer, gatorType *gator);

Description
===========

Converts gatortype information to the way it is stored on disk

Return value
============

true if successful, false if not

buf2Gtr()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool buf2Gtr(gatorType *gator, char *buffer);

Description
===========

Converts the BUFFER data to gatorType

Return value
============

true if successful, false if not

cfg2Buf()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool cfg2Buf(char *buffer, gatorConfigType *config);

Description
===========

Converts gatorConfigType to the way it is stored on disk

Return value
============

true if successful, false if not

buf2Cfg()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool buf2Cfg(gatorConfigType *config, char *buffer);

Description
===========

Converts data in BUFFER to gatorConfigType

Return value
============

true if successful, false if not

spu2Buf()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool spu2Buf(char *buffer, shipUFOType *shipUFO);

Description
===========

Converts shipUFOType to the way it is stored on disk

Return value
============

true if successful, false if not

buf2Spu()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool buf2Spu(shipUFOType *shipUFO, char *buffer);

Description
===========

Converts BUFFER data to shipUFOType

Return value
============

true if successful, false if not

lnk2Buf()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool lnk2Buf(char *buffer, linkShipType *linkShip);

Description
===========

Converts linkShipType to the way it is stored on disk

Return value
============

true if successful, false if not

buf2Lnk()
*********

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool buf2Lnk(linkShipType *linkShip, char *buffer);

Description
===========

Converts BUFFER data to linkShipType

Return value
============

true if successful, false if not

validateGatorRecord()
*********************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     valid validateGatorRecord(gatorType *gator, short record);

Description
===========

Checks validty of GATOR number RECORD

Return value
============

v_error if an erro occured, v_true if the record was valid, v_yellow if
it was fixed, v_red if it could not be fixed and was cleared in stead.
In case of v_yellow and v_red, it should be saved as it was returned.

explodeGator()
**************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool explodeGator(gatorType *gator);

Description
===========

Destroys GATOR

Return value
============

true if successful, false if not

explodeShip()
*************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool explodeShip(shipRecordType *ship);

Description
===========

Destroys SHIP

Return value
============

true if successful, false if not

explodeShipUFO()
****************

Syntax
======

     #include <vpl3/gtr3Structures.h>
     
     bool explodeShipUFO(shipUFOType *shipUFO);

Description
===========

Destroys warped ship SHIPUFO

Return value
============

true if successful, false if not

The Battle Engine
*****************

The Battle Engine is designed to emulate Tim's VCR code as closely as
possible, when having warped ships and/or Gators do battle with
eachother, or with planets or ships. It can also emulate ships fighting
eachother, in which case it should produce the same results as Tim's own
VCR. It does not use Tim's VCR setup, so it doesn't produce VCR??.DAT -
type records and can not be used to create Visual Combat Recordings
from the host data: it simply calculates the battle between two
opposing objects.

doBattle()
**********

Syntax
======

     #include <vpl3/battle.h>
     
     bool doBattle(shipRecordType *ship1, shipRecordType *ship2, planetRecordType *planet, starbaseRecordType *starbase, gatorType *gator, shipUFOType *shipUFO);

Description
===========

Calculates the battle between two opposing objects - the rest of the
parameters should be set to NULL.

Example
=======

     shipRecordType ship;
     gatorType gator;
     bool rv = true;
     
     if (rv) rv = readGatorRecord(&gator, 2);
     if (rv) rv = readShip(&ship, 32);
     
     if (rv) rv = doBattle(&ship, (shipRecordType*)NULL, (planetRecordType*)NULL, (starbaseRecordType*)NULL, &gator, (shipUFOType*)NULL);
     
     if (rv) rv = writeGatorRecord(&gator, 2);
     if (rv) rv = writeShip(&ship, 32);

Return value
============

true if successful, false if not.

   The message engine of this library is designed for use by RLSystems
add-ons only, but will be made available to other applications at a
later date. As is, you will not be able to use them, because parts of
the actual module are not available. Should you use them any message
you send will have the content "You should not have received this
message".

   You _can_ use the putMessage() method, which is used by the engine to
store the messages in the host data files. The getMessage() method has
not been tested yet, and should not be used.

setMessage()
************

Syntax
======

     #include <vpl3/messages.h>
     
     void setMessage(short messageType, messageDataType *message, shipRecordType *ship, planetRecordType *planet, starbaseRecordType *starbase, raceRecordType *race, gatorType *gator);

Description
===========

Sets the message parameters for message MESSAGETYPE, based on the other
passed info. _Do not use_.

Return value
============

none

getMessagePointer()
*******************

Syntax
======

     #include <vpl3/messages.h>
     
     bool getMessagePointer(messagePointerType *ptr, short record);

Description
===========

Gets the message information about message RECORD. _not tested_

Return value
============

true if successful, false if not

putMessage()
************

Syntax
======

     #include <vpl3/messages.h>
     
     bool putMessage(short cc, char xzstr[], short ID, char gG[]);

Description
===========

Sends a subspace message to race CC, content XZSTR, sender ID,
pre-string GG.

Example
=======

     if (rv) rv = putMessage(1, "<< TEST MESSAGE >>\rThis is a test message\r", 0, "-m0");

Return value
============

true if successful, false if not

issueMessage()
**************

Syntax
======

     #include <vpl3/messages.h>
     
     bool issueMessage(messageDataType *message);

Description
===========

Sends a message with message parameters stored in MESSAGE, set up by
setMessage. _Do not use_

Return value
============

true if successful, false if not

Internal methods
****************

There are a number of methods in this library which are definatly *not*
intended for use outside of this library. However, I said I'd document
everything, and that includes the internal methods.

   *None of these methods should be used outside this library!*

vpl3_openFiles()
****************

Syntax
======

     bool vpl3_openFiles(void);

Description
===========

Opens the files with the requested information.

Return value
============

true if successful, false if not

vpl3_closeFiles()
*****************

Syntax
======

     bool vpl3_closeFiles(void);

Description
===========

Closes the opened files

Return value
============

true if successful, false if not

downVPL3()
**********

Syntax
======

     void downVPL3(void);

Description
===========

Shuts down the library

Return value
============

true if successful, false if not

vpl3_getConfig()
****************

Syntax
======

     bool vpl3_getConfig(void);

Description
===========

Gets the configuration directly from the files, compiles it and stores
it in the buffer for readConfig() and writeConfig()

Return value
============

true if successful, false if not

vpl3_getShips()
***************

Syntax
======

     bool vpl3_getShips(void);

Description
===========

Gets the ships directly from the files, compiles it and stores it in
the buffer for readShip() and writeShip()

Return value
============

true if successful, false if not

vpl3_getPlanets()
*****************

Syntax
======

     bool vpl3_getPlanets(void);

Description
===========

Gets the planets directly from the files, compiles it and stores it in
the buffer for readPlanet() and writePlanet()

Return value
============

true if successful, false if not

vpl3_getStarbases()
*******************

Syntax
======

     bool vpl3_getStarbases(void);

Description
===========

Gets the starbases directly from the files, compiles it and stores it
in the buffer for readStarbase() and writeStarbase()

Return value
============

true if successful, false if not

vpl3_getRaces()
***************

Syntax
======

     bool vpl3_getRaces(void);

Description
===========

Gets the Races directly from the files, compiles it and stores it in
the buffer for readRace() and writeRace()

Return value
============

true if successful, false if not

vpl3_getMinefield()
*******************

Syntax
======

     bool vpl3_getMinefield(void);

Description
===========

Gets the mine fields directly from the files, compiles it and stores it
in the buffer for readMinefield() and writeMinefield()

Return value
============

true if successful, false if not

vpl3_getIonstorms()
*******************

Syntax
======

     bool vpl3_getIonstorms(void);

Description
===========

Gets the ion storms directly from the files, compiles it and stores it
in the buffer for readIonstorm() and writeIonstorm()

Return value
============

true if successful, false if not

vpl3_getUFOs()
**************

Syntax
======

     bool vpl3_getUFOs(void);

Description
===========

Gets the UFOs directly from the files, compiles it and stores it in the
buffer for readUFO() and writeUFO()

Return value
============

true if successful, false if not

vpl3_getHost()
**************

Syntax
======

     bool vpl3_getHost(void);

Description
===========

Gets the host info directly from the files, compiles it and stores it
in the buffer for readHost() and writeHost()

Return value
============

true if successful, false if not

vpl3_putConfig()
****************

Syntax
======

     bool vpl3_putConfig(void);

Description
===========

Puts the configuration directly into the files

Return value
============

true if successful, false if not

vpl3_putShips()
***************

Syntax
======

     bool vpl3_putShips(void);

Description
===========

Puts the ships directly into the files

Return value
============

true if successful, false if not

vpl3_putPlanets()
*****************

Syntax
======

     bool vpl3_putPlanets(void);

Description
===========

Puts the planets directly into the files

Return value
============

true if successful, false if not

vpl3_putStarbases()
*******************

Syntax
======

     bool vpl3_putStarbases(void);

Description
===========

Puts the starbases directly into the files

Return value
============

true if successful, false if not

vpl3_putRaces()
***************

Syntax
======

     bool vpl3_putRaces(void);

Description
===========

Puts the races directly into the files

Return value
============

true if successful, false if not

vpl3_putMinefield()
*******************

Syntax
======

     bool vpl3_putMinefield(void);

Description
===========

Puts the mine fields directly into the files

Return value
============

true if successful, false if not

vpl3_putIonstorms()
*******************

Syntax
======

     bool vpl3_putIonstorms(void);

Description
===========

Puts the ion storms directly into the files

Return value
============

true if successful, false if not

vpl3_putUFOs()
**************

Syntax
======

     bool vpl3_putUFOs(void);

Description
===========

Puts the UFOs directly into the files

Return value
============

true if successful, false if not

