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

Since release 3.0.6 XPilot also supports VMS thanks to Curt Hjorring.
The directory VMS contains extra code and makefiles for VMS. 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 Jens Koerber <koerber@ttkax1.ciw.uni-karlsruhe.de>.

VMS port for XPilot (Version 3.5.0, Jens Koerber)
==================================================

This is a patch to xpilot 3.5.0 so that it will run under 
OpenVMS 7.0 or higher (VAX and Alpha). The compilation was 
done by the DECC 5.2 compiler. 

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 your system runs TGV-Multinet, you can find a patch on 
ttkax1.ciw.uni-karlsruhe.de in [ANONYMOUS.PUB.XGAMES.XPILOT] 


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

To install:

  - To install xpilot run the command procedure @INSTALL.COM in
    the Subdirectory [-.-.CONTRIB.VMS]. This command procedure will
    change the configuration file CONFIG.H and will run the COM files
    MAKEXP.COM and MAKEXPS.COM (originally supplied by Peter Chang).
    These do some dependency checking.

  - If you use the GCC compiler, 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.

  - When running under OpenVMS V6.2 INSTALL.COM does not install
    the XPilot Server image. Compilation of sched.c gives multiple 
    errors of the form (or similar to):

        sigset_t    sigset;
................^
%CC-E-NOSEMI, Missing ";".
at line number 103 in file TTKAX1$DKA100:[LIB.XGAMES.XPILOT.SRC]SCHED.C;31

    sigemptyset(&sigset);
.................^
%CC-E-UNDECLARED, In this statement, "sigset" is not declared.

    In order to receive this full fix, in addition to this kit you 
    must also install XPILOT342-VMS-SERVER.TAR-GZ from
    ftp://ttkax1.ciw.uni-karlsruhe.de/pub/xgames/xpilot/vms

  - Look at the standard XPilot installation instructions


Running xpilot:

  - Added the startup file XP_STARTUP.COM. To use this command file run
    @XP_STARTUP in the subdirectory [-.XPILOT.START].

  - To give xpilot and xpilots command line arguments you will have to
    set up some symbol assigns, e.g.
    XPILOT :== "$LIB_DISK:[LIB.XGAMES.XPILOT.SRC]XPILOT.EXE

  - When you start up xpilot or xpilots you may 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 OK.

  - The keyboards on our VAXstations (not the Alpha's) 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 (VAX) 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. 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.  Curt 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>

  - 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. You can define a symbolic name for 
    the character string in your LOGIN.COM, e.g.
      $  XP :== "$XPILOT:XPILOT_AXP -turn""S""peed 50 -sliding""R""adar yes"
    Most of the options can also be set in the XPILOT.DAT file in your home 
    directory. The options that I use are:    
!--
xpilot.name:             Cayenne
xpilot.geometry:         1162x924
xpilot.sparkProb:        0.2
xpilot.slidingRadar:     yes
xpilot.shipShape:        Asteroids
xpilot.turnSpeed:        50
!--
  
  - I have added SHIP_FILE in config.h as an optional file ([.LIB]TKXPI.SHP) 
    where shipshapes can be stored. If this resource is defined and it refers 
    to an existing file then shipshapes can be referenced to by their name.

Description of major changes in this patch:

OpenVMS 7.0/DEC C 5.2 now supports the sigset family (mmh ...)


Remaining problems/things to do:

   - Somehow the implementation of ioctl() on VMS is completely broken!
     Without the compiler option /prefix=(ALL,EXCEPT=(ioctl)) the
     server returns

   > ioctl FIONBIO failed in socklib.c line 856: function not implemented
   > xpilot_axp.exe;4: Can't make socket non-blocking (function not implemented)

     Is there a implementation of fcntl() for VMS ? 

     USE_FCNTL_O_NDELAY should be better than USE_IOCTL_FIONBIO
     
   - BUG in DEC C 5.2-003 with select()

     On _real_ UNIX slow system calls return with the value -1 and
     set the errno variable to EINTR.  VMS does _not_ do this and
     therefore emulates UNIX _inadequate_.

     VMS returns
     -1                                     Indicates an error;  errno is set to
                                            one of the following values:

                                            ·   EBADF - One of the bit
                                                  masks specified an invalid
                                                  descriptor.
                                            ·   EINVAL - The specified time
                                                  limit is unacceptable. One of
                                                  its components is negative or
                                                 too large.
     UNIX has also:
                                            ·   EINTR - A signal was delivered
                                                  before any of the selected
                                                  four events occurred or before
                                                  the time limit expired.

     And this behavior is what we need in sched.c.

     Workaround in sched.c:

     Changed at line 454:
            if (io_todo == 0) {
                tvp = NULL;
            }
     to:
            #ifndef VMS
              if (io_todo == 0) {
                  tvp = NULL;
              }
            #endif

     And then at line 403:
            tv.tv_sec = 0;
            tv.tv_usec = 0;
     to:
#ifdef (VMS)
        if (NumPlayers > NumRobots + NumPseudoPlayers
            || login_in_progress != 0
            || NumQueuedPlayers > 0) {

            /* need fast I/O checks now! (2 or 3 times per frames) */
            tv.tv_sec = 0;
            tv.tv_usec = 1000000 / (3 * timer_freq);
        }
        else {
            /* slow I/O checks are possible here... (2 times per second) */ ;
            tv.tv_sec = 0;
            tv.tv_usec = 500000;
        }
#else
        tv.tv_sec = 0;
        tv.tv_usec = 0;
#endif

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).

Let me know how you get on and GOOD LUCK!

Jens.

--
-- Jens Koerber    koerber@ttkax1.ciw.uni-karlsruhe.de
-- Inst. f. Technische Thermodynamik und Kaeltetechnik,
-- University Karlsruhe, Germany
-- 
