This document describes a method for building version 3.13 and later production versions of the Hercules IBM mainframe emulator on VMS.
Some of the less portable Hercules features are not implemented such as SCSI tape support, TUN/TAP based networking, FBA block device support and dynamically loadable modules. Hercules devices which are implemented using HDL only will not work. This includes integrated consoles such as the 1052-C and 3215-C. These features could probably be included given some porting effort, however there does not seem to be sufficient requirement for them at present to justify the effort required.
Compilation can be done with the default (32 bit) pointer size which allows Hercules to access memory sizes not greater than one to two GB or with 64 bit pointer size which allows access to much larger memory sizes.
A hack is performed to get the "softfloat" floating point package to compile with least effort. This means that binary floating point operations may not work correctly if more than one CPU is configured in Hercules on VMS. This is because of lack of support in the current DECC compilers for thread specific data structures as used by the softfloat package.
This procedure has been developed and tested on OpenVMS Alpha V8.4 with HP C V7.3-009 and Multinet V5.5 Rev A. It should work on other comparable versions of VMS / C / Multinet / TCPIP Services on Alpha, Itanium or later platforms without modifications or with minor tweaks. Let me know if you experience any problems and I will try to fix them.
You will need:
If you want to compile Hercules with BZIP2 and ZLIB support, the bzlib.h, zconf.h and zlib.h header files and libbz2.olb and libz.olb object libraries built from the source should also be placed in the [.vms] subdirectory. I am not going to go into the detail of building these packages here as there are too many variables involved. If you run into any difficulties with them, let me know and I will help sort them out. If BZIP2 and ZLIB support is not required, comment out or remove the 5 lines referencing ZLIB, LIBZ, BZLIB and BZIP2 in [.vms]config.h and the 2 lines referencing libz and libbz2 in hercules.opt.
Eight of the source files supplied with Hercules should be modified as described below.
If using the release version of Hercules 3.13, it is necessary to modify hdl.h to fix a bug which causes a compilation error when compiling without HDL (which is the path of least resistance on VMS). This is not required if downloading the latest code from Github as this bug has been fixed there.
It is necessary to modify hmacros.h to avoid very poor performance and DBG error messages on the Hercules console due to calling select() with a non-socket file descriptor. The other changes are not essential but recommended, otherwise different parts of Hercules may fail to work.
If panel.c is not modified, the control panel does not accept keyboard input and Hercules can only be controlled using it's web interface (which is tricky to configure correctly but can be done. See controlling Hercules on VMS via the web interace.)
If cardrdr.c is not modified, card readers do not work. If hetlib.c is not modified, HET tapes do not work. If hscutl.c is not modified, use of 2703 communication adaptors may cause Hercules to hang.
If hostopts.h is not modified, there will be many warnings that default host options are being used but few consequences. The changes to hdlmain.c avoids 2 undefined symbols at link time due to lack of TUN/TAP support. However, there do not appear to be any ill effects if this issue is ignored.
A command procedure UPDATE.COM is provided to ease the process of making most of the required source modifications. It can be invoked as follows:
$ @update cardrdr.c $ @update hetlib.c $ @update hmacros.h $ @update hostopts.h $ @update hscutl.c $ @update panel.c
Next, only if using the release version of Hercules 3.13 or earlier, edit hdl.h and fix a minor bug which prevents compiling without dynamically loadable module support, which we want to do on VMS:
Locate 'typedef struct _HDLINS'. Move this 8 line structure up above the line containing : '#if !defined(OPTION_DYNAMIC_LOAD)'
Finally, edit hdlmain.c and comment out the following two lines. This step may be omitted if you are not worried about linker warnings due to unresolved symbols.
HDL_DEVICE(CTCI, ctci_device_hndinfo ); HDL_DEVICE(LCS, lcs_device_hndinfo );
If it is desired to compile with support for 64 bit pointers, some more file modifications are required. A command procedure, 64BITPOINTERS.COM is provided to make this easier. It can be invoked as follows:
$ @64bitpointers hexterns.h $ @64bitpointers httpserv.c $ @64bitpointers htypes.h $ @64bitpointers impl.c $ @64bitpointers logger.c $ @64bitpointers panel.c
That's it. All source modifications are now done and compilation can begin. Issue these commands:
$ @compile vms $ @compile floating $ @compile hercules
Expect one THREADNYI warning when compiling softfloat.c and three MAYLOSEDATA2 warnings each when compiling cpu.c and sie.c. There may also be one or two informational messages.
If 64 bit pointer support is desired, use the following commands instead, assuming the six files have already been modified as required using 64bitpointers.com:
$ @compile vms /pointer_size=64 $ @compile floating /pointer_size=64 $ @compile hercules /pointer_size=64
In this case, only one warning is expected, the THREADNYI warning from softfloat.c. Be sure not to compile some modules with 64 bit pointers and others without 64 bit pointers. See comments at the top of compile.com for other compilation options.
If all went well, all the hercules source should now be compiled. If so, issue this command:
$ @link hercules
and HERCULES.EXE should be generated. This can be run with command line arguments by setting up a foreign command symbol or a simple RUN HERCULES will run it with no command line arguments and it will look for a configuration file called hercules.cnf in the current default directory.
Further information about running Hercules on VMS can be found here.
If you also wish to build the Hercules support utilites such as dasdinit, hetinit etc., use the commands below. If building without LIBZ and BZIP2 support, comment out or remove the references to libz and libbz2 from cckd.opt, dasd.opt and het.opt before performing the link step.
$ @update dasdls.c $ @compile utilities $ @link utilities
If Hercules was already built with 64 bit pointers, then 64 bit pointers should also be specified when compiling the utilities:
$ @compile utilities /pointer_size=64
as some of the modules compiled for Hercules are also used in building the utilities.
Please note that I have not tested all the support utilities for correct operation but if any problems are found, I am happy to look into them.
Mail _software_@_beyondthepale_._ie_ (without the underscores) for further information or help with any problems building or running Hercules on VMS.