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. If building with 64 bit pointers, the latest Multinet patches should be applied.
Let me know if you experience any problems and I will try to fix them.
You will need:
Firstly, use VMS UNZIP to unzip the Hercules source zipfile in a suitable location on your VMS system. Use the -a option on unzip to get the file attributes right.
Secondly, unzip hercules-vms-support-v1_3.zip in the same location. This will result in the creation of a [.vms] subdirectory to contain some of VMS specific support files. The files present in hercules-vms-support-v1_3.zip can be browsed here if desired.
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. More details.
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 dynamically loadable device code (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. The procedure for performing the fix is as follows:
Edit hdl.h Locate 'typedef struct _HDLINS'. Move this 8 line structure up above the line containing : '#if !defined(OPTION_DYNAMIC_LOAD)' Exit from the editor to save a new version of the file.
A command procedure UPDATE.COM is provided to ease the process of making most of the other source modifications required. It can be invoked as follows:
$ @update cardrdr.c $ @update hetlib.c $ @update hmacros.h $ @update hostopts.h $ @update hscutl.c $ @update panel.c
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. To build with 32 bit pointers, 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. A linker warning in respect of the THREADNYI warning in softfloat.c is to be expected as follows:
%LINK-W-WRNERS, compilation warnings
in module SOFTFLOAT file SOFTFLOAT.OBJ
This warning cannot easily be avoided. There may also be another linker warning as follows:
%LINK-W-MULDEF, symbol GET_INET_SOCKET multiply defined
in module COMM3705 file COMM3705.OBJ
This warning is benign and can be ignored. If desired, it can be avoided by building from the latest spinhawk source where this issue has hopefully been fixed by now or by editing comm3705.c, locating the line:
"struct sockaddr_in * get_inet_socket(char *host_serv)"
changing "#if 1" immediately above it to "#if 0" and rebuilding. Note however that further tweaks may be required to make 3705 devices usable when running on VMS, depending on the source used to build from.
If building with 32 bit pointers, there will be two more linker warnings:
%LINK-W-WRNERS, compilation warnings
in module CPU file CPU.OBJ
%LINK-W-WRNERS, compilation warnings
in module SIE file SIE.OBJ
These warnings can be avoided by following the steps above to compile with 64 bit pointers.
Hercules be run with command line arguments by setting up a foreign command symbol to point to the HERCULES.EXE built above 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.