Mainframe emulator set-up

5 pts.
Assembler language
How do I set-up a mainframe emulator in my PC so I can study Assembler, TPFDF and COBOL at home?

Answer Wiki

Thanks. We'll let you know when a new response is added.

Installation Procedure
Building from source – Windows (without Cygwin)

For building the MSVC version of Hercules on Windows (a version of Hercules that does not require Cygwin), Fish has instructions on his “MSVC Hercules Build Instructions” web page here.
Building from source – Windows with Cygwin

For building the Cygwin version of Hercules on Windows, Volker Bandke has instructions on his “Building Hercules for Windows” web page at
Building from source – Linux and Mac OS X

1. Download the distribution file hercules-3.05.tar.gz
Note: By downloading this file you agree to the terms of the Q Public Licence.

2. Use these commands to unzip the distribution file:

tar xvzf ../hercules-3.05.tar.gz
cd hercules-3.05

3. Verify you have all of the correct versions of all of the required packages installed:


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

5. Build the executables:


6. Install the programs: as root:

make install

Important: You must use at least version 2.95 of the gcc 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:
* hercules-3.05-1.i686.rpm: Intel
2. Install the RPM:
rpm -Uvh RPMfile

This will leave the Hercules executables in /usr/bin and the dynamic libraries in /usr/lib and /usr/lib/hercules, 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.

* Using apt: apt-get install hercules
* Manually with dpkg:
1. Download a .deb package
2. dpkg -i DEB

Installing on Gentoo Linux:

Hercules is installed like any other Gentoo package: do emerge sync if you haven’t done it lately, then emerge hercules.

Do not try to override the optimization flags automatically selected by configure. Hercules stresses the gcc optimizer, and will break in subtle ways if the wrong optimization settings are used.
Installing on Mac OS X:

1. Download the compressed disk image: hercules-3.05-tiger.dmg. This package is a universal binary and requires OS X version 10.4 (Tiger) or later.
2. Mount the image by double-clicking on it in the Finder. Your web browser may have done that for you already.
3. Installation and use instructions are in the file OS X ReadMe.rtf.
4. If you want to use CTC networking on your Hercules system, you will need to install the supplied Tunnel driver.

Installing on Windows (without Cygwin):

1. Download the self-extracting Windows archive or the Windows Installer package.
2. If you downloaded the self-extracting archive, simply execute it to install Hercules on your system. If you downloaded the Windows Installer package, use the Windows Installer to install Hercules. The Windows Installer is included in Windows XP. It may already be on your older Windows system, depending on what other software you’ve installed. If it is, double-clicking on the Hercules package file will install Hercules. If not, you can download the Windows Installer for Windows NT and 2000 by following this link, or the Windows Installer for Windows 98 and ME by following this link.
3. You will probably also want to install Fish’s Hercules GUI for Windows. You can get it from

Installing on Windows with Cygwin:

1. Hercules 3.05 is now supplied as prebuilt binaries only in a native Windows version. This version will work perfectly well under Cygwin, as well as native Windows, and does not require any specific version of the Cygwin libraries. Follow the instructions above to install the native Windows version.

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 ]
[ -d ]
[ -p dyndir ] [[-l dynmod ] ... ]
[ > logfile ]



is the name of the configuration file. The default, if none is specified, is hercules.cnf. The default may be overridden via the HERCULES_CNF environment variable.


specifies that Hercules is to be run in ‘daemon’ mode, wherein it runs invisibly with no attached console.


is the directory from which dynamic modules are to be loaded. The default depends on the host platform on which Hercules is being run. This option overrides the default.


is the name of an additional dynamic module to be loaded at startup. More than one additional module may be specified, although each must be preceded with the -l option specifier.


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

The following is what is displayed on the Hercules harware console (HMC) in response to the ‘?’ command being entered. Please note that it may not be completely accurate or up-to-date. Please enter the ‘?’ command for yourself for a more complete, accurate and up-to-date list of supported panel commands.

Command Description…
——- ———————————————–
? list all commands
help command specific help

* (log comment to syslog)

hst history of commands
log direct log output
logopt change log options
version display version information

quit terminate the emulator
exit (synonym for ‘quit’)

cpu define target cpu for panel display and commands

start start CPU (or printer device if argument given)
stop stop CPU (or printer device if argument given)

startall start all CPU’s
stopall stop all CPU’s

cf configure current CPU online or offline
cfall configure all CPU’s online or offline

.reply scp command
!message scp priority messsage
ssd Signal Shutdown

ptt display pthread trace

i generate I/O attention interrupt for device
ext generate external interrupt
restart generate restart interrupt
archmode set architecture mode
loadparm set IPL parameter

ipl IPL Normal from device xxxx
iplc IPL Clear from device xxxx
sysreset Issue SYSTEM Reset manual operation
sysclear Issue SYSTEM Clear Reset manual operation
store store CPU status at absolute zero

psw display program status word
gpr display or alter general purpose registers
fpr display floating point registers
fpc display floating point control register
cr display control registers
ar display access registers
pr display prefix register
timerint display or set timers update interval
clocks display tod clkc and cpu timer
ipending display pending interrupts
ds display subchannel
r display or alter real storage
v display or alter virtual storage
u disassemble storage
devtmax display or set max device threads
k display cckd internal trace

attach configure device
detach remove device
define rename device
devinit reinitialize device
devlist list device or all devices

qd query dasd

scsimount automatic SCSI tape mounts

cd change directory
pwd print working directory
sh shell command

cache cache command
cckd cckd command
shrd shrd command
conkpalv display/alter console TCP keep-alive settings
quiet toggle automatic refresh of panel display data

t instruction trace
t+ instruction trace on
t- instruction trace off
t? instruction trace query
s instruction stepping
s+ instruction stepping on
s- instruction stepping off
s? instruction stepping query
b set breakpoint
b+ set breakpoint
b- delete breakpoint
g turn off instruction stepping and start CPU

ostailor trace program interrupts
pgmtrace trace program interrupts
savecore save a core image to file
loadcore load a core image file
loadtext load a text deck file

ldmod load a module
rmmod delete a module
lsmod list dynamic modules
lsdep list module dependencies

iodelay display or set I/O delay value
tt32stats (deprecated; use ‘tt32’ cmd instead)
tt32 control/query CTCI-W32 functionality
toddrag display or set TOD clock drag factor
panrate display or set rate at which console refreshes
syncio display syncio devices statistics
maxrates display maximum observed MIPS/SIOS rate for the
defined interval or define a new reporting interval

defsym Define symbol
script Run a sequence of panel commands contained in a file
cscript Cancels a running script thread

evm ECPS:VM Commands (Deprecated)
ecpsvm ECPS:VM Commands

aea Display AEA tables
aia Display AIA fields
tlb Display TLB tables

sizeof Display size of structures

suspend Suspend hercules
resume Resume hercules

herclogo Read a new hercules logo file

traceopt Instruction trace display options

sf+dev add shadow file
sf-dev delete shadow file
sf=dev .. rename shadow file
sfc compress shadow files
sfd display shadow file stats

t{+/-}dev turn CCW tracing on/off
s{+/-}dev turn CCW stepping on/off
t{+/-}CKD turn CKD_KEY tracing on/off
f{+/-}adr mark frames unusable/usable

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.

Some commands also offer additional help information regarding their syntax, etc. Enter “help <command name>” to display this additional help information. (Note: not every command supports help)

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.

The “Hercules Automatic Operator” (HAO) Facility

The Hercules Automatic Operator (HAO) feature is a facility that allows one to automatically issue panel commands in response to certain messages being issued.

To use the Hercules Automatic Operator facility, one first defines a “rule” consisting of a “target” and an associated “command”. The “target” is just a regular expression pattern used to match against the text of the various messages that Hercules issues as it runs. Whenever a match is found, the rule “fires” and its associated command is automatically issued.

The Hercules Automatic Operator facility is only for those messages issued by Hercules to its HMC (hardware console). It cannot be used for whatever messages the guest operating system may issue to any of its terminals. It is only a Hercules automatic operator and not a “VSE”, “MVS”, “VM”, etc, automatic operator.
Defining a Rule

To define a HAO rule, enter the command:

hao target

to define the rule’s “target” match pattern (a simple regular expression), followed by the command:

hao command

to define the rule’s associated panel-command.

The target pattern is a simple regular expression value as defined by whatever regular expression facility your host build platform happens to support. For Windows it must be a Perl Compatible Regular Expression (PCRE). For other supported build platforms it might be some other supported regular expression syntax. Check your host platform’s programming documentation for further details.

The associated command is whatever valid Hercules panel command you wish to issue in response to a message being issued that matches the given pattern target.
Other commands and limitations

To delete a fully or partially defined HAO rule, first use the ‘hao list’ command to list all of the defined (or partially defined) rules, and then use the ‘hao del nnn’ command to delete the specific rule identified by nnn. (All rules are assigned numbers as they are defined and are thus identified by their numeric value). Optionally, one may delete ALL defined or partially defined rules by issuing the command ‘hao clear’.

The current implementation limits the total number of defined rules to 10. If you need to define more than 10 rules you will either have to build Hercules for yourself (increasing the value of the HAO_MAXRULE constant in hao.c) or else beg one of the Hercules developers to please do it for you.

Note that there is currently no way to define a command whose arguments vary based on actual message text. That is to say, there is currently no way to say

“Reply with the command ‘devinit cuu filename’ in response to message text ‘HHCXXnnnI Device cuu intervention required.’ where cuu is whatever cuu was identified in the message.”

The HAO is not that sophisticated (yet). Only simple plain-text commands may be defined and issued. No automatic substitution is done based on message text (although normal ‘DEFSYM’ symbol substitution is supported however, as that is a normal panel-command feature supported separately from the HAO). This may possibly change in the future however, depending on user need/demand.

All defined rules are checked for a match each time Hercules issues a message. There is no way to specify “stop processing subsequent rules”. If a message is issued that matches two or more rules, each associated command is then issued in sequence. Thus the advice to choose your rules’ target patterns carefully very much applies here.

Discuss This Question:  

There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when members answer or reply to this question.

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

To follow this tag...

There was an error processing your information. Please try again later.

Thanks! We'll email you when relevant content is added and updated.


Share this item with your network: