README.VMS for XPilot
=====================

Since release 3.0.6 XPilot also supports VMS thanks to Curt Hjorring.
The directory VMS contains extra code and MMS makefiles for VMS.
Copy all of these files and the vms_include directory to the src
directory and adapt them to your environment.  Read the rest of
this file for more info on how to compile and install XPilot under VMS.

The XPilot authors don't have access to VMS and don't know anything
about VMS (and don't want to know anything about VMS :).  So please
don't send us any mail about VMS related problems.  You are of course
welcome to discuss XPilot ideas with us, contribute new features, etc.
The XPilot-for-VMS guru is Curt Hjorring <c.hjorring@auckland.ac.nz>.
He deserves all credit for porting XPilot to VMS.

The rest of this file is derived from the first VMS patch introduction
file, but still contains important info.


VMS port for XPilot
===================

This is a patch to xpilot 3.0.5 so that it will run under VMS, on VAX
machines and Alphas.  It requires the UCX library.  Not all VMS machines
will have this.  To see if you have the UCX library look in sys$library:
and see if you have either ucx$ipc.olb or ucx$ipc_shr.exe. If you have
you're in luck!  If you are compiling for VAXes you will need a compiler
that handles string concatenation.  I used gcc.

We (Department of Engineering Science, University of Auckland, New Zealand)
have been successfully running VAX/VMS versions of the client and server for
a couple of months now.  Hopefully this patch will work successfully for
others as well.


Description of major changes in this patch:

The majority of changes are to the include statements.  VMS doesn't believe
in subdirectories for includes (probably because path names are formed
differently, e.g. [.dir1.dir2]file.txt instead of ./dir1/dir2/file.txt)

The keyboards on VAXstations and Alpha workstations do not supply correct
key up events.  If you press and hold down say the 'A' key then a key up AND
and key down event will be generated immediately.  This affects all
alphanumeric keys and the spacebar.  Fortunately the function keys work
properly.  This happens if xpilot is run locally or remotely (via X).  Because
of this A and S will not turn the ship and the space bar will only turn the
shield off.  My solution is to remap A and S to F1 and F2 and to change the
server so that space bar toggles the shield.  I have added toggleShield as an
option (the default is off).  If you are using a VAXstation as a display then
to use your shield you need to either remap KEY_SHIELD to a function key, or
else make sure the client is started up with toggleShield enabled.

Added gettimeofday, ioctl, and username emulation.

Removed X11 dependencies in the server.  It should no be possible to compile
and link the server without needing any X11 headers or libraries.

Added include files, to fix up GCC/CC incompatibilities.  These are stored
in src/vms_include

When creating a client/server connection I get errors when trying to set
the socket buffer sizes, something like:
  xpilots.exe;1: Can't set receive buffer size to 1040 (not owner)
This is OK.

There is no make command supplied with VMS.  There is a similar program called
MMS which can be purchased.  I have included descrip_vax.mms (for VAX
machines) and descrip_alpha.mms (for Alphas).  Not all sites will have MMS so
they can use the com files (makexp_vax.com and makexps_vax.com for VAXes,
makexp_alpha.com and makexps_alpha.com for Alphas) supplied by Peter Chang.
These do some dependency checking.


Remaining problems/things to do:
Can't save the X configuration.
Loading of XResources is a bit iffy.  Needs a bit of debugging here.
I couldn't get broadcast to work under VMS, so the client can't search the
network for an xpilot server.  The user has to specify the server.  The old
manual code could be reinstated or else maybe someone else can get the
current search code working under VMS.
For timing purposes the server uses a busy loop.  There is something in VMS
similar to itimer, namely SYS$SCHDWK and SYS$HIBER.  Haven't tried them out
yet.



Instructions for the XPilot VMS patch
=====================================

To install:
  - I used version 1.40 of GCC.  Other versions should work OK.
  - System header such as in.h need to be compiled.  GCC will choke on the
    ones in sys$include (they use #include file statements).  I have
    provided versions that GCC can handle.  These should be in the directory
    vms_include
  - Look at the standard XPilot installation instructions

Running xpilot:
  - To give xpilot and xpilots command line arguments you will have to
    set up some symbol assigns, e.g.
      XPILOT :== "$USER_2:[USER.GRADUATE.HJORRING.X.XPILOT3.SRC]XPILOT.EXE
  - When you start up xpilot or xpilots you will probably get an error message
    like:
      Socket receive buffer size is 9000
      xpilots.exe;1: Can't set receive buffer size to 1040 (not owner)
      Socket send buffer size is 9000
      xpilots.exe;1: Can't set send buffer size to 4112 (not owner)
    This is normal but please tell me what your errors look like.
  - The keyboards on our VAXstations don't work very well.  They don't give
    proper key up/down messages.  Because of this it is impossible for
    xpilot to know if you are holding down one of the alphabetical keys.
    Fortunately the function keys work properly.  Because of this we have
    remapped keys such as left and right to say F1 and F2.  The key bindings
    that I use are:

!--
xpilot*keyLockNext:             Right Next
xpilot*keyLockPrev:             Left Prior
xpilot*keyLockClose:            Up Down
xpilot*keyChangeHome:           Home Select
xpilot*keyShield:               space
xpilot*keyFireShot:             Return
xpilot*keyFireMissile:          backslash
xpilot*keyDropMine:             Tab F4
xpilot*keyTurnLeft:             F1
xpilot*keyTurnRight:            F2
xpilot*keySelfDestruct:         q
xpilot*keyIdMode:               i
xpilot*keyPause:                p
xpilot*keyToggleVelocity:       v
xpilot*keyToggleCompass:        c
xpilot*keySwapSettings:         Escape
xpilot*keyRefuel:               F3
xpilot*keyIncreasePower:        KP_Multiply KP_7
xpilot*keyDecreasePower:        KP_Divide   KP_8
xpilot*keyIncreaseTurnspeed:    KP_Add      KP_9
xpilot*keyDecreaseTurnspeed:    KP_Subtract
xpilot*keyThrust:               Shift_L Shift_R
xpilot*keyCloak:                BackSpace Delete
!--

    Key bindings should be stored in your home directory in the file
    decw$xdefaults.dat.  NB The computer only looks at this data when you
    login, thus if you make a change you will need to logout and log back in
    for the change to take effect.  I have added an option to xpilot so that
    the spacebar works as a toggle.  To enable toggle shield (this is
    necessary if using a VAXstation as a display and you want to use the
    spacebar as the shield key) start the client by typing
      xpilot "-toggleShield" true  <server>


!!!!!!!!!!!!!!!!!!!!!!!!!!!
NB

To send options to xpilot the option name (e.g. toggleShield in the above
example) MUST be enclosed in speech marks "".  This is because the parsing
is case sensitive but VMS converts command line arguments to upper-case
unless the arguments are quoted.
!!!!!!!!!!!!!!!!!!!!!!!!!!!


Miscellaneous notes

VAXstations are pushing it to do 18 frames a second, both for the server and
the client, you may have to reduce the frame rate (a smaller graphics window
will help client speed).

The delay code for the server is currently a busy wait.  I saw the SYS$SCHDWK
and SYS$HIBER routines.  This look like what we want but I haven't had time
to try them out?  Anyone want to give it a go?


Let me know how you get on and GOOD LUCK!

Curt.

-- Curt Hjorring        c.hjorring@auckland.ac.nz
-- Engineering Science, University of Auckland, New Zealand
