Installing and Operating Hercules Version 2

Installation Procedure

Building from source

These instructions apply to the Linux version. Volker Bandke has instructions on how to build the Win32 version at

  1. Download the distribution file hercules-2.16.5.tar.gz


    1. By downloading this file you agree to the terms of the Q Public Licence.
    2. IE4 may report "problem with security settings or file does not exist" when downloading this file. I do not know why. If you experience this problem, use IE5 or Netscape Navigator instead.

  2. Use these commands to unzip the distribution file:
    tar xvzf ../hercules-2.16.5.tar.gz
    cd hercules-2.16.5
  3. Configure Hercules for your system:


    By default, the configure script will attempt to guess appropriate compiler optimization flags for your system. If its guesses turn out to be wrong, you can disable all optimization by passing the --disable-optimization option to configure, or specify your own optimization flags with --enable-optimization=FLAGS

    For additional configuration options, run ./configure --help

  4. Build the executables:


  5. Install the programs: as root:

    make install

Important: You must use the egcs compiler and the glibc2 library. Refer to the Hercules Frequently-Asked Questions page for required compiler and other software levels.

Installing prebuilt RPMs:

  1. Download the RPM file you want:
  2. Install the RPM:
    rpm -Uvh RPMfile
This will leave the Hercules executables in /usr/bin, where you can run them from anywhere. Sample configuration files will be placed in /etc/hercules, and the IPLable card deck for the ZZSA standalone utility will be placed in /var/share/hercules.

Installing Debian packages:

Debian packages are available for "woody" and later releases. As of this writing, "woody" is not yet released.

Configuration Procedure

You will need to amend the configuration file hercules.cnf to reflect your device layout and intended mode of operation (S/370, ESA/390, or z/Architecture). See the Hercules Configuration File page for a complete description.

Creating DASD volumes

The Creating Hercules DASD page describes various methods of creating and loading virtual DASD volumes. The compressed CKD DASD support is described in this page.

Operating Procedure

Note: If you intend to run any licensed software on your PC using Hercules, it is your responsibility to ensure that you do not violate the software vendor's licensing terms.

Loading a standalone program or operating system

To start Hercules enter this command at the Unix shell prompt:

hercules [-f filename] [> logfile]
where filename is the name of the configuration file (the default is hercules.cnf), and logfile is an optional log file which will receive a copy of all messages displayed on the control panel.

Next connect a tn3270 client to the console port (normally port 3270). The client will be connected to the first 3270 device address specified in the configuration file (this should be the master console address). If your master console is a 1052 or 3215, connect a telnet client instead of a tn3270 client.

Now you can enter an ipl command from the control panel.

Panel commands

cpu n   Set target CPU for subsequent commands
psw     Display program status word
gpr     Display general-purpose registers
fpr     Display floating-point registers
cr      Display control registers
ar      Display access registers
pr      Display prefix register
clocks  Display todclock, clock comparator, cpu timer, and interval timer (370 mode only)

rx      Display 64 bytes starting at real address x
rx.n    Display n bytes starting at real address x
rx-y    Display real storage locations x to y
vx      Display 64 bytes starting at virtual address x
vx.n    Display n bytes starting at virtual address x
vx-y    Display virtual storage locations x to y
f-x     Mark storage frame at address x unusable
f+x     Mark storage frame at address x usable

rx=hexvalue   Alter real storage location x
vx=hexvalue   Alter virtual storage location x

t+      Turn on CPU instruction tracing
t-      Turn off CPU instruction tracing
s+      Turn on CPU single-step mode
s-      Turn off CPU single-step mode
g       Go (turn off CPU single-step mode and start CPU)

bx      Set breakpoint at address x
b-      Clear breakpoint

t+ckd            Turn on CKD key tracing
t-ckd            Turn off CKD key tracing
t+xxxx  Turn on CCW tracing for device number xxxx
t-xxxx  Turn off CCW tracing for device number xxxx
s+xxxx  Turn on CCW single-step mode for device number xxxx
s-xxxx  Turn off CCW single-step mode for device number xxxx
ixxxx   Generate an I/O attention interrupt for device number xxxx
kxxxx   Print CCKD internal trace for device number xxxx
dsxxxx  Display subchannel status for device number xxxx

archmode S/370|ESA/390|ESAME  Set architecture mode
loadparm [xxxxxxxx]           Display or set the IPL parameter
loadcore xxxxxxxx [address]   Load core image from file xxxxxxxx
savecore xxxxxxxx [start/*] [end/*] save core to file xxxxxxxx
loadtext xxxxxxxx [address]   Load object deck xxxxxxxx
ipl xxxx                      IPL from device number xxxx

ext       Generate an external interrupt
stop      Stop CPU
start     Start CPU
stopall   Stop all CPUs
startall  Start all CPUs
restart   Generate a restart interrupt and start CPU
store     Store status
ipending  Display pending interrupts
quit|exit Terminate Hercules
quiet     Toggles panel quiet mode

devlist  Display configured devices
attach xxxx type [ args ]  Create device xxxx
detach xxxx  Delete device xxxx
define xxxx yyyy  Rename device number xxxx to yyyy
devinit xxxx [ args ]  Reinitialize device xxxx

.text   Enter an SCP command via the HMC system console
!text   Enter an SCP priority message via the HMC system console

toddrag [n]  Display or set TOD clock drag factor

pgmtrace n   Turn on program interrupt tracing for interrupt code n
pgmtrace -n  Turn off program interrupt tracing for interrupt code n

panrate slow | fast | n   Set panel refresh rate to n milliseconds

The ipl command may also be used to perform a load from cdrom or server. For example if a standard SuSE S/390 Linux distribution CD is loaded and mounted on /cdrom for example, this cdrom may then be ipl-ed by: ipl /cdrom/suse.ins

The attach and detach commands are used to dynamically add or remove devices from the configuration, and the define command can be used to alter the device number of an existing device.

The devinit command can be used to reopen an existing device. The args (if specified) override the arguments specified in the configuration file for this device. The device type cannot be changed and must not be specified. This command can be used to rewind a tape, to mount a new tape or disk image file on an existing device, to load a new card deck into a reader, or to close and reopen a printer or punch device.

In single-step mode, pressing the enter key will advance to the next instruction.

There is also an alternate semi-graphical control panel. Press Esc to switch between the command line format and the semi-graphical format. Press ? to obtain help in either control panel.

The  hercules.rc  (run-commands)  file:

Hercules also supports the ability to automatically execute panel commands upon startup via the 'run-commands' file. If the run-commands file is found to exist when Hercules starts, each line contained within it is read and interpreted as a panel command exactly as if the command were entered from the HMC system console.

The default filename for the run-commands file is "hercules.rc", but may be overridden by setting the "HERCULES_RC" environment variable to the desired filename.

Except for the 'pause' command (see paragraph further below), each command read from the run-commands file is logged to the console preceded by a '> ' (greater-than sign) character so you can easily distinguish between panel commands entered from the keyboard from those entered via the .rc file.

Lines starting with '#' are treated as "silent comments" and are thus not logged to the console. Line starting with '*' however are treated as "loud comments" and will be logged.

In addition to being able to execute any valid panel command (including the 'sh' shell command) via the run-commands file, an additional 'pause nnn' command is supported in order to introduce a brief delay before reading and processing the next line in the file. The value nnn can be any number from 1 to 999 and specifies the number of seconds to delay before reading the next line. Creative use of the run-commands file can completely automate Hercules startup.

Technical Support

If you have a question about Hercules, please refer to the Hercules Frequently-Asked Questions page first. If your question and/or concern is not addressed in the FAQ, please feel free to post your question to the Hercules-390 forum:
Community email addresses:
  Post message:
  List owner:

Files and archives at:

The Hercules-390 forum is in fact your primary source for Hercules support, and you are strongly encouraged to subscribe. We have a vibrant, active community of over 2400 members, many of which are very knowledgeable in many different areas of mainframe technology, both from a hardware point of view as well as from an operating system and software point of view.

In addition to the main Hercules-390 forum, other more specialized Hercules forums also exist to provide more focused support for a variety of popular IBM mainframe operating systems, such as DOS/VS, VM (VM/370, VM/SP, and VM/ESA), and MVS.

Note! the use of Yahoo! as host for the Hercules-390 and related forums should in no way be interpreted as an endorsement of the Yahoo! service.


Last updated 8 July 2002