Hercules Release Notes and Known Issues

Release notes for release 4.00

Minimum supported Windows platform is now Windows XP x64 or greater

The new minimum supported Microsoft Windows platform is now Windows XP x64 or Windows Server 2003 or greater. Windows 98, Windows NT, Windows 2000 and 32-bit Windows XP are no longer supported.

NOTE: Since neither Windows XP x64 nor Windows Server 2003 are supported any longer by Microsoft either (extended support for both ended on April 2014 and July 2015 respectively), Hyperion support for them will be dropped in the very near future as well. All Hercules users running either of these operating systems are strongly encouraged to upgrade as soon as possible to Windows Vista or Windows 7 Professional SP1 x64 or greater.

"MAXCPU" and "NUMCPU" statements

The combination of NUMCPU and MAXCPU controls the behavior of how many CPU engines will be configured online upon startup and how many can be configured online later. In previous versions this was controlled via the NUMCPU statement and the compile-time constant 'MAX_CPU_ENGINES'.

For compatibility with previous versions of Hercules, if MAXCPU is not specified its value defaults to NUMCPU. If neither is specified it defaults to 1.

New and improved CMPSC Compression Call 2012 instruction implementation is now the default

The default implementation for the CMPSC Compression Call instruction is now the new cmpsc_2012 implementation. The previous legacy implementation is now the alternate implementation implemented as an optional dynamically loadable module called "altcmpsc.dll". Refer to the README.CMPSC document of the source code distribution for more information.

The sequence of certain system parameters may be important

The sequence of certain configuration file system parameter statements may be important. Specifically, the ARCHLVL statement (previously called ARCHMODE and defines the initial architectural mode of the system) should generally precede (come before) any other ARCHLVL statement that enables or disables a given architectural feature.

For example: on certain IBM operating systems the z/Architecture "ASN and LX Reuse Facility" feature must be enabled or the system will not IPL. The facility is enabled in Hercules via the ARCHLVL ENABLE ASN_LX_REUSE configuration file statement, but since the facility is a z/Architecture-only feature, your initial architecture must either be set to "z/Arch" beforehand or else you need to specify the optional [archmode] parameter on your ARCHLVL ENABLE ASN_LX_REUSE statement.

This means the ARCHLVL z/Arch statement must usually come before your ARCHLVL ENABLE ASN_LX_REUSE statement in your configuration file. Otherwise the ASN and LX Reuse Facility would not be enabled.

The ARCHLVL statement is currently the only system parameter whose sequence may matter. The order of all other system parameters does not currently matter. This may change in the future however, so be sure to always carefully read through the RELEASE NOTES (this document) with each new release of Hercules.

More architecturally compliant Channel Subsystem implementation

Hercules 4.0 Hyperion's channel subsystem implementation now more closely adheres to published and unpublished architectural specifications. It does not precisely adhere to the complete specification but it does adhere much more closely than ever before (and definitely more closely than the legacy implementation still used in the older spinhawk 3.xx series of Hercules).

If you experience any anomalies in the behavior of your guest operating system, verify that you are using architecurally valid/correct configuration settings that your guest operating system expects.

Pay particular attention to your LPARNUM, CPUIDFMT, CPUMODEL, CPUSERIAL, CPUVERID, MODEL, PLANT and MANUFACTURER values since they typically have a direct impact on how certain guest operating systems behave.

Configuration file statements and panel commands handled identically

Most configuration file statements are now available as and processed as panel commands. Most valid configuration file statements may now also be entered as a panel command. Most panel commands are now also allowed as configuration file statements. See the documentation for full details.

Integrated Rexx support

Rexx support was first added to Hercules by Jan Jaeger in 2010 and has been gradually enhanced over the years by both Enrico Sorichetti and Jan Jaeger as well as a few other people too.

If you have Rexx installed on your host and Hercules is built with the rexx build option, then rexx scripts can be run from directly within the Hercules environment (i.e. directly from the Hercules HMC command line) via Hercules's "exec" command.

Rexx scripts, when run within Hercules via the 'exec' command, can Address the HERCULES enviroment allowing you to issue Hercules commands and retrieve the results via the builtin 'awscmd' rexx function call.

For more information please see Hercules-REXX Integration, or refer to the README.REXX document and the sample scripts included in the 'scripts' subdirectory of the source code distribution.

Hercules may be built using CMake

A CMake build proceduce has been added for open source and UNIX-like systems. The procedure and build options are described in Using CMake to Build Hercules Version 4.0.

Release notes for release 3.06

Tape "AUTOMOUNT" support

Starting with Hercules version 3.06 a new AUTOMOUNT option is available that allows guest operating systems to directly mount, unmount and query tape device filenames for themselves, without any intervention on the part of the Hercules operator.

Automount support is enabled via the AUTOMOUNT configuration file statement.

An example guest automount program for VSE called "TMOUNT" is provided in the util subdirectory of the Hercules source code distribution.

Briefly, the 0x4B (Set Diagnose) CCW is used to mount (or unmount) a file onto a tape drive, and the 0xE4 (Sense Id) CCW opcode is used to query the name of the currently mounted file.

For mounts, the 0x4B CCW specifies the filename of the file to be mounted onto the drive. The file MUST reside in the specified AUTOMOUNT directory or the automount request will be rejected. To unmount the currently mounted file, simply do a mount of the special filename "OFFLINE".

To query the name of the currently mounted file, the 0xE4 CCW is used. Note however that the 0xE4 (Sense Id) CCW opcode cannot be used by itself since the drive may also already natively support the Sense Id CCW opcode. Instead, it must be preceded by (command-chained from) a 0x4B CCW with a data transfer length of one byte. The following 0xE4 command is the one that then specifies the i/o buffer and buffer length of where the query function is to place the device's currently mounted host filename.

In summary:

        MOUNT:      X'4B', filename, X'20', length

        UNMOUNT:    (same thing but use filename "OFFLINE" instead)

        QUERY:      X'4B', buffer, X'60', 1
                    X'E4', buffer, X'20', buffersize

Again please refer to the provided TMOUNT program for a simple example of how automount support might be implmented on a guest operating system.

Release notes for release 3.05

Use 'startgui' if starting GUI program via 'sh' command

The 'conspawn' utility used to process 'sh' commands now recognizes a specially designed keyword "startgui" to accomodate automatic starting of Windows GUI applications via the .RC file or panel command-line.

If the first word following 'sh' is "startgui", then the "ShellExecute" API is used to start the requested program rather than the 'system()' API as otherwise.

The "startgui" keyword must always be used to start any Windows program that is not a command-line program. Hercules, itself being a command-line program, monitors the 'stderr' and 'stdout' pipes so it can log messages received from either pipe directly to the Hercules console log. Programs such as notepad however, because they are not command-line programs, do not use stdout/stderr thus causing Hercules to hang if "start" is used instead.

This rule applies regardless of how Hercules itself is started (i.e. via HercGUI or directly via the command-line) and regardless of whether the "start" command is wrapped in a batch file or not. That is to say, using the Hercules command "sh batchfile foobar" to start your batch file which then does "start notepad %1" still causes Hercules to hang until notepad first exits. Instead, you should ask Hercules to "sh startgui batchfile", and let the batchfile start notepad however it wants.

Real SCSI tape drive support

Real SCSI tape drives used with Hercules must provide a certain minimum set is "IBM compatible" support in their SCSI command set/behavior in order to work properly with Hercules. Furthermore, the Hercules device-type used on your device statement in your Hercules configuration file should match the the level of support/behavior that they provide.

For example, all SCSI tape drives used with Hercules must provide the ability to set variable-length blocks as well as long erase-gaps (long erase-gaps allows new data to be appended to the end of existing data without having to write a tape-mark to separate the new data from the old existing data first).

Another example would be using a model of SCSI tape drive that happens to report physical block-id values in a format different from the way real IBM mainframe tape drives report them. 3480/3490 tape drives for example report their block-ids (used in Read Block Id and Locate CCWs) in a very specific format wherein bits 1-7 of the high-order byte of the reported 4-byte block- id indicates the tape's physical "segment" location of where the lower 22- bit block number is physically located on the tape. (The block-id segment is used to allow the tape drive to quickly position itself to the approximate location where the desired block acually resides on the tape and thus allows high-speed positioning for the Locate CCW).

If the model of SCSI tape drive you are actually using with Hercules does not use this same block-id format however, then it cannot be used with Hercules as a 3480 or 3490 model tape drive with specially defined options.

If the SCSI tape drive you are using reports its block-ids using a 32-bit block-id value (the same way a 3590 model tape drive does), then similarly, it should be defined to Hercules as a model 3590 device-type as well (since that is how it is behaving with respect the format of the returned blockid values). It you wish to define it in Hercules as a model 3480 or 3490, then you will need to use specially defined options before it will work properly as the model drive you wish it to emulate.

With all that being said, it should be noted that PARTIAL support for 3590 device emulation is possible with judicious use the aforementioned special options, but full/complete 3590 support is unlikely due to lack of publicly available documentation. Details regarding 3590 CCW handling is restricted (confidential) IBM proprietary information, and is not normally available outside of IBM. Not long ago IBM was required by US law to publish such information, but unfortunately for Hercules, such is no longer the case.

For further information regarding use of SCSI attached tape drives with Hercules and their associated specially defined options, please refer to the section on SCSI tape drives in the Hercules's Device Configuration documentation.

Internal thread priorities changed on Windows for platform consistency

In order to ensure proper functioning of the TOD clock with older versions of guest operating systems, the default values of Hercules's internal thread priorities for the Windows version of Hercules were changed to be identical to those used by all other supported platforms. Originally, the default thread priority values for the Windows version of Hercules were:

              ***  3.04 (and prior) Default Priorities  ***

              Thread    Priority           Meaning
              -------   --------   ------------------------
              HERCPRIO     0        Normal Process priority

              DEVPRIO     -8        Above Normal  Thread priority
              TODPRIO      0        Normal        Thread priority
              CPUPRIO      0        Normal        Thread priority

which caused acceptable performance/functioning on most, but not all, guest operating systems. Beginning with version 3.05 however, the prioriries now default to:

              ***  3.05 (and later) Default  Priorities  ***

              Thread    Priority           Meaning
              -------   --------   ------------------------
              HERCPRIO     0        Normal Process priority

              TODPRIO    -20        Time Critical  Thread priority
              DEVPRIO      8        Below Normal   Thread priority
              CPUPRIO     15        Lowest         Thread priority

which may on more modern guest operating systems (which handle the TOD clock differently than do older less sophticated versions) cause a slight decrease in overall performance. If such is the case, the original default priorities (and thus the original behavior) can be obtained via addition of appropriate HERCPRIO, TODPRIO, DEVPRIO and CPUPRIO control file statements with values identical to the original version 3.04 default values.

Configuration file usability enhancements and Automatic Operator facility

Additional configuration file usability enhancements have been implemented in the form of a new 'INCLUDE' (and associated 'IGNORE') statement, allowing configuration files to "include" statements from a different named file.

Additonally, a new "enhanced" symbolic substitution syntax is now also supported. Refer to the Hercules "Configuration File" documentation for further information and details.

A rather nifty "Automatic Operator" facility has also been implemented in the current release as well. While not exactly a "configuration file usability enhancement", it is nevertheless something we hope might prove to be more useful/helpful to our many users. See the "README.HAO" document for more information.

Release notes for release 3.03

Release date: 20 December 2005

New device types 1052-C and 3215-C

The new integrated console printer-keyboard is emulated on the hercules console. Commands are sent to the console by means of a command character. (default '/', thus a logon command is sent by /logon)

Message Security Assist

Starting from release 3.03 the glibcrypt library is no longer needed.

Release notes for release 3.02

Release date: 11 December 2004

ASN-and-LX-reuse facility

This is a new feature of z/Architecture which can cause problems with certain versions of operating systems running in ARCHLVL=2 mode without the so-called "Driver 55" fixes. To avoid such problems, specify ASN_AND_LX_REUSE DISABLE in the configuration file.

Release notes for release 3.01

Release date: 30 November 2003

Library modules and HTTP documents default directories

An error in the 3.00 configuration script caused many users to have to override the default modules and HTTP documents directory in the Hercules configuration file, or by setting an environment variable. This error has been corrected. Hercules also now reports the actual directory that it uses by default for these files at startup time. If you specified the MODPATH or HTTPROOT configuration file statements because you encountered problems, you should examine the messages printed at startup to see if the default directories are now correct, and remove the statements if so.

In general, MODPATH and HTTPROOT should not have to be specified except in unusual circumstances.

Windows default directories

In conjunction with the fix above, the default directories of the Windows distributed binaries have been changed. The new directories are under C:\cygwin\usr\local (which is the same as /usr/local under the Cygwin environment). No action is needed unless you have specified the MODPATH or HTTPROOT configuration file entries; if so, see the previous note.

Message Security Assist

Support for z990 crypto instructions is conditional on the presence of the glibcrypt library. When Hercules is BUILT, the development files for glibcrypt should be available. When hercules is RUN, the runtime files for glibcrypt should be installed.

Depending on the level of glibcrypt used to *build* hercules, the associated level of glibcrypt should also be present on the target machine. On systems supporting shared library versioning, multiple levels of the glibcrypt runtime libraries can be installed simultaneously, ensuring availability of the z990 crypto instructions, regardless of the level of glibcrypt with which hercules was initially built.

CTC and LCS device numbers

CTC and LCS devices now MUST specify ALL addresses on the configuration statement. Previously (i.e. with version 3.00), only the first (even numbered) device needed to be defined and Hercules would automatically define the odd numbered device for you. Starting with Hercules version 3.01 however, you now need to define BOTH devices, just like you did with versions prior to 3.00. Once again, starting with version 3.01, you **MUST** define BOTH DEVICES.

Release notes for release 3.00

Release date: 3 October 2003

CTCI device changes

Both of these will go away in a future release.

In addition, you must not define both even/odd CTCI device pairs in your configuration file. You should only define the first even numbered device. Hercules will automatically define the odd numbered device for you. If you define the odd numbered device by mistake, an open error will occur on that device. This is by design. See the README.NETWORKING document for further details.

Hercules Dynamic Loader support

Starting with version 3.00, Hercules now contains support for the dynamic loading of certain modules upon startup on Linux, Windows, and Mac OS X. This support should also work on any platform supported by GNU libtool. As a result of this new feature, Hercules itself now no longer consists of just the 'hercules.exe' module by itself, but rather consists of both the 'hercules.exe' program as well as whatever dynamic modules (DLLs) that accompany it.

As a result of this change, whenever you install a new version of Hercules, you must ensure that you ALSO install the accompanying new versions of the new dynamic modules as well. Attempting to use a version of Hercules with a dynamic module that was not specifically built for that version will cause loading of that dynamic module to fail.

You cannot mix versions of Hercules with differing versions of dynamically loaded modules.

Ensure that your library path (set by the environment variable LD_LIBRARY_PATH) set correctly such that it includes the directory of your Hercules dynamic load libraries. If you see message HHCCF042E, which indicates that the system is unable to locate necessary loadable modules, this is likely your problem. This should not be necessary if you have a binary download, but if you're building from source, especially if you've previously installed a binary package, this should be the first thing you do.


Do not use ECPS:VM (See README.ECPSVM) in an AP or MP environment in VM/370. If AP=YES or MP=YES is coded in DMKSYS and the AP/MP control file is used to build the CP nucleus and NUMCPU is set to more than 1 in the hercules.cnf file, any of LOK001, LOK003 or other abends will occur. This occurs because the Hercules ECPS:VM CP Assist implementation is not MP safe, and particularly, attempts VM dispatching without holding necessary AP or MP locks.

Memory allocation on Windows

Due to the change in the "mainstor" memory allocation technique used by Hercules to address a "double memory consumption" bug in Cygwin's malloc implementation, some Windows Hercules users may experience an "out of memory" error whenever Hercules is started with a large MAINSIZE configuration file value:

HHCCF031S Cannot obtain nnnMB main storage

This error will most likely occur (if it does at all) for those users who have manually adjusted their Cygwin heap_chunk_in_mb Windows registry setting value (in order to allow them to specify a large MAINSIZE value when running Hercules). If this problem does occur (i.e. if you do happen to experience the above mentioned error with this new release of Hercules), then either reduce your heap_chunk_in_mb value (yes, that's correct: reduce it, as in change it to a smaller value) or else remove it altogether (so as to let it default).

A complete discussion of this issue is in the RELEASE.NOTES file in the source distribution.

Thread priority and other problems

There is a known problem with thread priority handling under Mac OS X. The OS X threading model is different from the one classically used in Linux. This causes failures to set the timer thread priority, and slow performance as all of Hercules is set to a low execution priority. This will be fixed in a future release. A workaround, for now, for slow performance is to add the statement


to your Hercules configuration file.

A possibly related problem is that Hercules fails in random ways when using the NPTL (new POSIX threads library) library under Linux. This library is used by default in Red Hat 9, and possibly other systems. If problems are encountered on a very recent version of Linux, try issuing the command

export LD_ASSUME_KERNEL=2.4.1

before starting Hercules.

If you have a question about Hercules, see the Hercules Frequently-Asked Questions page.


Last updated $Date$ $Revision$