Hercules - Installation Guide: Hercules System/370, ESA/390, Z/architecture Emulator

Hercules System/370, ESA/390, z/Architecture Emulator
Hercules - Installation Guide

Version 3 Release 07
Contents
Contents ........................................................................................................................................................2
Figures...........................................................................................................................................................4
Tables ............................................................................................................................................................7
1. Preface ...............................................................................................................................................8
1.1 Edition information ..........................................................................................................................8
1.2 What this book is about...................................................................................................................8
1.3 Who should read this book .............................................................................................................8
1.4 What you need to know to understand this book............................................................................8
1.5 How to use this book.......................................................................................................................8
1.6 Revision Notice ...............................................................................................................................8
1.7 Readers Comments ........................................................................................................................9
1.8 Legal Advice....................................................................................................................................9
1.9 Trademarks .....................................................................................................................................9
1.10 Acknowledgements ...................................................................................................................10
2. Related Publications .........................................................................................................................11
2.1 Hercules Emulator – General Information ....................................................................................11
2.2 Hercules Emulator – Installation Guide ........................................................................................11
2.3 Hercules Emulator – User Reference Guide ................................................................................11
2.4 Hercules Emulator – Messages and Codes .................................................................................11
2.5 Hercules Emulator – Reference Summary ...................................................................................11
Part I: Hardware and Performance..............................................................................................................12
3. Hardware Prerequisites ....................................................................................................................13
3.1 PC Hardware.................................................................................................................................13
4. Performance .....................................................................................................................................16
4.1 MIPS .............................................................................................................................................16
4.2 I/O Rate.........................................................................................................................................17
4.3 Hercules Performance Measurements .........................................................................................17
Part II: Windows Installation ........................................................................................................................28
5. Software Prerequisites .....................................................................................................................29
5.1 Operating System .........................................................................................................................29
5.2 Drivers...........................................................................................................................................30
5.3 Runtime Environments..................................................................................................................30
5.4 Hercules Emulator.........................................................................................................................31
5.5 Additional required and optional Software ....................................................................................36
6. Component Compatibility Tables......................................................................................................38
6.1 Hercules V 3.07.0 (Release date: March 10, 2010)......................................................................38
6.2 Hercules V 3.06.0 (Release date: January 11, 2009)...................................................................39
6.3 Hercules V 3.05.0 (Release date: June 23, 2007)........................................................................39
6.4 Hercules V 3.04.0 (Release date: February 24, 2006) .................................................................40
6.5 Hercules V 3.03.1 (Release date: December 31, 2005) ...............................................................40
6.8 Hercules V 3.01.0 (Release date: November 30, 2003) ...............................................................42
6.9 Hercules V 3.00.0 (Release date: October 2, 2003).....................................................................42
7. Installation WinPcap .........................................................................................................................43
7.1 WinPcap Packet Capture Driver ...................................................................................................43
7.2 Installation Steps (Windows Setup) ..............................................................................................43
8. Installing the Hercules Emulator.......................................................................................................52
8.1 Downloading the Binaries .............................................................................................................52
8.2 Choosing a Package.....................................................................................................................52
8.3 Installation Steps (MSVC Windows Installer Package) ................................................................52
8.4 Installation Steps (MSVC Self-Extracting Archive) .......................................................................59
8.5 Customization Steps .....................................................................................................................60
9. Installing the Hercules Windows GUI ...............................................................................................65
9.1 Downloading the Binaries .............................................................................................................65
Hercules Emulator - Installation Guide Page 2

9.2 Installation Steps...........................................................................................................................65
9.3 Customization Steps .....................................................................................................................65
9.4 Main Screen ..................................................................................................................................66
9.5 Preferences...................................................................................................................................67
9.6 System Configuration....................................................................................................................75
9.7 Device Settings .............................................................................................................................81
9.8 Display / Alter Memory..................................................................................................................84
9.9 Load Card Reader, Load Tape, Unload Tape ..............................................................................85
9.10 Device List Bar ..........................................................................................................................86
9.11 Utilities Menu .............................................................................................................................88
9.12 Registry Tweaks ........................................................................................................................88
10. Installation of CTCI-W32 ..................................................................................................................91
10.1 Downloading the Binaries..........................................................................................................91
10.2 Installation Steps .......................................................................................................................91
10.3 Customization Steps .................................................................................................................91
11. Installation of Vista tn3270 ...............................................................................................................99
11.1 Vista tn3270...............................................................................................................................99
11.2 Downloading the Installation Routine ........................................................................................99
11.3 Install Vista tn3270 ....................................................................................................................99
11.4 Activation of the Software........................................................................................................105
11.5 Create Sessions ......................................................................................................................105
12. Installation of XMIT Manager..........................................................................................................108
12.1 XMIT Manager Basics .............................................................................................................108
12.2 Downloading the Binaries........................................................................................................108
12.3 Installation Steps .....................................................................................................................108
13. AWS Browse...................................................................................................................................114
13.1 AWS Browse Basics................................................................................................................114
13.2 Downloading the Binaries........................................................................................................114
13.3 Installation Steps .....................................................................................................................114
14. Hercules “MSVC” Build Instructions ...............................................................................................116
14.1 Introduction..............................................................................................................................116
14.2 Setting up the Hercules build environment .............................................................................116
14.3 Setting up ZLIB Support ..........................................................................................................117
14.4 Setting up BZIP2 Support........................................................................................................118
14.5 Setting up PCRE Support........................................................................................................118
14.6 Building Hercules using the Visual Studio IDE........................................................................120
15. Maximizing Hercules Available Memory.........................................................................................121
15.1 Introduction..............................................................................................................................121
15.2 Windows Memory Layouts ......................................................................................................121
15.3 The "VADUMP" Report ...........................................................................................................123
15.4 Using "REBASE" .....................................................................................................................124
15.5 Rebasing DLLs which are in use.............................................................................................129
15.6 Bottom Line .............................................................................................................................130
Part III: Linux Installation ...........................................................................................................................131
16. Linux Installation .............................................................................................................................132
Part IV: Mac OS X Installation ...................................................................................................................133
17. Mac OS X Installation .....................................................................................................................134
Appendix A. Links......................................................................................................................................135

Figures
Figure 1: Hercules Emulator Performance ................................................................................................. 18
Figure 2: DASD Emulation Type Performance........................................................................................... 19
Figure 3: Hercules CPU-based Performance............................................................................................. 20
Figure 4: Disk Transfer Rates..................................................................................................................... 21
Figure 5: Host Disk Performance (IPL in seconds) .................................................................................... 22
Figure 6: Hercules Hardware Console - Console window.......................................................................... 32
Figure 7: Hercules Hardware Console - Device and status display ........................................................... 33
Figure 8: Hercules web browser interface.................................................................................................. 34
Figure 9: Hercules Windows GUI Main Panel ............................................................................................ 35
Figure 10: Hercules Utility Window ............................................................................................................ 36
Figure 11: WinPcap Logo ........................................................................................................................... 43
Figure 12: WinPcap Setup - Information Screen........................................................................................ 44
Figure 13: WinPcap Setup - Welcome Screen........................................................................................... 45
Figure 14: WinPcap Setup - License Agreement ....................................................................................... 46
Figure 15: WinPcap - Setup Status ............................................................................................................ 47
Figure 16: WinPcap Setup - Installation Complete .................................................................................... 48
Figure 17: Run Program msinfo32 ............................................................................................................. 49
Figure 18: System Information Main Window............................................................................................. 49
Figure 19: NPF - NetGroup Packet Filter Driver......................................................................................... 50
Figure 20: NetGroup Packet Filter Driver Status........................................................................................ 51
Figure 21: Welcome Window (MSVC Installer Package)........................................................................... 53
Figure 22: License Agreement (MSVC Installer Package)......................................................................... 54
Figure 23: Installation Directory Selection (MSVC Installer Package) ....................................................... 55
Figure 24: Disk Space Information (MSVC Installer Package) .................................................................. 56
Figure 25: Installation Confirmation (MSVC Installer Package) ................................................................. 57
Figure 26: Installation Progress Bar (MSVC Installer Package) ................................................................ 58
Figure 27: Installation Complete (MSVC Installer Package) ...................................................................... 59
Figure 28: Specifying Target Directory (MSVC Self-Extracting Version) ................................................... 60
Figure 29: Confirmation Message (MSVC Self-Extracting Version) .......................................................... 60
Figure 30: Hercules Startup Batch File ...................................................................................................... 61
Figure 31: Hercules Windows GUI Startup Batch File ............................................................................... 62
Figure 32: Hercules Run-Commands File .................................................................................................. 63
Figure 33: Terminal Batch File ................................................................................................................... 64
Figure 34: Hercules Windows GUI Main Panel .......................................................................................... 66
Figure 35: Preferences Directory Tab ........................................................................................................ 67
Figure 36: Preferences Extensions Tab ..................................................................................................... 68
Figure 37: Preferences Logging Tab.......................................................................................................... 69
Figure 38: Advanced Logging Options Memory Tab.................................................................................. 70
Figure 39: Advanced Logging Options Disk Tab........................................................................................ 70
Figure 40: Advanced Logging Options Format Tab ................................................................................... 71
Figure 41: Preferences Console Tab ......................................................................................................... 72
Figure 42: Preferences Misc Tab ............................................................................................................... 73
Figure 43: Preferences Misc2 Tab ............................................................................................................. 74
Figure 44: Architecture Settings Tab.......................................................................................................... 76

Figure 45: O/S Tailor Settings Tab............................................................................................................. 77
Figure 46: PGMPRDOS LICENSED Acknowledgment.............................................................................. 78
Figure 47: Other / Misc Tab........................................................................................................................ 79
Figure 48: HTTP Server Parameters.......................................................................................................... 79
Figure 49: CCKD Parameters .................................................................................................................... 80
Figure 50: Advanced Tab ........................................................................................................................... 81
Figure 51: Device Configuration................................................................................................................. 82
Figure 52: Edit Device Configuration Statement ........................................................................................ 82
Figure 53: Add New Device........................................................................................................................ 83
Figure 54: Reinitialize Device..................................................................................................................... 84
Figure 55: Display / Alter Memory Dialog................................................................................................... 85
Figure 56: Reinitialize Card Reader Dialog ................................................................................................ 86
Figure 57: Device List Bar .......................................................................................................................... 87
Figure 58: DASDINIT Utility Window.......................................................................................................... 88
Figure 59: Windows TCP/IP Properties...................................................................................................... 92
Figure 60: Windows 2000 / XP "IP Forwarding" Registry Key ................................................................... 93
Figure 61: Windows 98 / ME "IP Forwarding" Registry Key....................................................................... 93
Figure 62: Sample CTCI definition for static IP addresses ........................................................................ 93
Figure 63: Sample CTCI definition for dynamic IP addresses ................................................................... 94
Figure 64: Sample TCP/IP Configuration for CTCI-W32............................................................................ 95
Figure 65: Sample LCS Configuration for CTCI-W32 ................................................................................ 96
Figure 66: CTCI-W32 Tuning Parameters.................................................................................................. 96
Figure 67: tt32 Statistics ............................................................................................................................. 98
Figure 68: Vista tn3270 Logo ..................................................................................................................... 99
Figure 69: Vista tn3270 – Welcome Screen............................................................................................. 100
Figure 70: Vista tn3270 – Select Destination Directory............................................................................ 101
Figure 71: Vista tn3270 – Select Program Group .................................................................................... 102
Figure 72: Vista tn3270 – Ready to Install Screen................................................................................... 103
Figure 73: Vista tn3270 - Installation Progress ........................................................................................ 104
Figure 74: Vista tn3270 – Setup Completed ............................................................................................ 105
Figure 75: Vista tn3270 - New Terminal Session Dialog.......................................................................... 106
Figure 76: Vista tn3270 - Connection Error.............................................................................................. 107
Figure 77: XMIT Manager Logo ............................................................................................................... 108
Figure 78: XMIT Manager Setup – Software License Agreement ........................................................... 109
Figure 79: XMIT Manager Setup – Destination Location ......................................................................... 110
Figure 80: XMIT Manager Setup – Select Program Folder...................................................................... 111
Figure 81: XMIT Manager Setup – Review Settings ................................................................................ 112
Figure 82: XMIT Manager Setup – Setup Complete ................................................................................ 113
Figure 83: AWS Browse - Initial Screen ................................................................................................... 115
Figure 84: ZLIB directory layout ............................................................................................................... 117
Figure 85: BZIP2 directory layout............................................................................................................. 118
Figure 86: PCRE directory layout............................................................................................................. 119
Figure 87: Windows 9x Memory Layout ................................................................................................... 121
Figure 88: Windows NT Memory Layout .................................................................................................. 122
Figure 89: Memory Layout before Rebase............................................................................................... 123
Figure 90: Memory Layout after Rebase.................................................................................................. 124

Figure 91: Windows 2000 Server Virtual Machine Memory Layouts ....................................................... 127
Figure 92: Production System Memory Layout ........................................................................................ 129

Tables
Table 1: DASD Device Capacity ................................................................................................................ 15
Table 2: Disk Configurations ...................................................................................................................... 21
Table 3: Performance Test Scenarios........................................................................................................ 23
Table 4: Emulated Instruction Performance ............................................................................................... 25
Table 5: IMON Instruction Performance Data ............................................................................................ 26
Table 6: Real Work Performance ............................................................................................................... 27
Table 7: Hercules Release V 3.07.0 Component Compatibility Table ....................................................... 38
Table 10: Hercules Release V 3.04.0 Component Compatibility Table ..................................................... 40
Table 16: Hercules Windows GUI Registry Keys ....................................................................................... 90
Table 17: CTCI-W32 Buffer Sizes .............................................................................................................. 97

1. Preface
1.1 Edition information

This edition applies to the Hercules S/370, ESA/390 and z/Architecture Emulator Release 3.07.0 and to
all subsequent versions, releases and modifications until otherwise indicated in new editions. Make sure
you are using the correct edition for the level of software you are using.
1.2 What this book is about

This book is a guide to installing the Hercules Emulator and related additional products (both required and
optional) under the Microsoft Windows, Linux and Mac OS X operating systems. For guidance in opera-
ting or debugging Hercules or for a general overview additional manuals are available.
Please note that some information can be found in more than one manual. This redundancy is not inten-
ded to unnecessarily expand the manuals, rather to help to find all necessary information in one place.
1.3 Who should read this book

This book is mainly intended for people who are responsible for installation and maintenance of the Her-
cules Emulator. It may also be useful if you are responsible for operating the Hercules Emulator.
1.4 What you need to know to understand this book

To understand this book you should be familiar with installing software under the Windows, Linux or Mac
OS X operating systems. You should also have some experience in using command shells under the
mentioned operating systems. Some knowledge of TCP/IP configuration in a small network is required to
configure network connectivity.
Last but not least you should be familiar with IBM mainframe environments (hardware and software) and
the underlying ideas and concepts as Hercules emulates IBM mainframe hardware.
1.5 How to use this book

This book is designed as a step by step installation guide for the Hercules Emulator and related products.
You should go through the book chapter by chapter and follow all the instructions given. This should lead
to an easy and fast installation without major problems.
1.6 Revision Notice

Hercules Release: Version 3 Release 07 Modification 0
Publication Number: HEIG030700
SoftCopy Name: HerculesInstallation
Revision Number: HEIG030700-00
Date: March 10, 2010

1.7 Readers Comments
If you like or dislike anything about this book please send an email to the address below. Feel free to
comment on any errors or lack of clarity. Please limit your comments on the information in this specific
book and also include the “Revision Notice” just above. Thank you for your help.
Send your comments by email to the Hercules-390 discussion group:

hercules-390@yahoogroups.com
1.8 Legal Advice

Hercules implements only the raw S/370, ESA/390, and z/Architecture instruction set, it does not provide
any operating system facilities. This means that you need to provide an operating system or standalone
program which Hercules can load from an emulated disk or tape device. You will have to write the opera-
ting system or standalone program yourself unless you possess a license from IBM to run one of their
operating systems on your PC or use IBM programs and operating systems which have been placed in
the public domain.
NOTE: It is YOUR responsibility to comply with the terms of the license for the operating system
you intend to run on the Hercules Emulator.
1.9 Trademarks
The following is a list of trademark acknowledgments and copyright notices for product and company
names mentioned in this book. Other product and company names in this book that are not listed below
may be the trademarks or registered trademarks of their respective owners.
 IBM, System/370, ESA/390, z/Architecture, MVS, OS/390, z/OS, VM, VM/ESA, z/VM, VSE,
VSE/ESA, z/VSE are trademarks or registered trademarks of International Business Machines
Corporation (IBM).
 Windows 95, Windows 98, Windows ME, Windows NT, Windows 2000, Windows XP, Windows
Vista, Windows Server 2000, Windows Server 2003, Visual C++ Toolkit 2003, Visual C++ 2005
Express are trademarks of Microsoft Corporation.
 Linux is a trademark owned by Linus Torvalds. The Linux Mark Institute is the exclusive licensor
of the Linux trademark on behalf of its owner Linus Torvalds.
 WinPcap is copyrighted by NetGroup, Politecnico di Torino (Italy).
 Cygwin is copyrighted by Red Hat, Inc.
 Vista tn3270 is copyrighted by Tom Brennan Software.
 Pentium, XEON are trademarks or registered trademarks of Intel Corporation.
 Athlon, Opteron are trademarks or registered trademarks of Advanced Micro Devices (AMD), Inc.
 Xmit Manager is copyrighted by Neal Johnston-Ward.
 FLEX-ES is a registered trademark of Fundamental Software, Inc.
 UMX Virtual Mainframe is a registered trademark of UMX Technologies.

1.10 Acknowledgements
The Hercules manuals would not have been possible without the assistance of many people and I would
like to thank all those who helped me. In particular I would like to thank:
 The Hercules developers for their documentation on various websites from which I derived a
great deal of information.
 Roger Bowler and Fish for proof-reading the manuals.
 Loris Degoianni for allowing me to use parts of the original WinPcap documentation.
 Tom Brennan for allowing me to use parts of his Vista tn3270 documentation.
 My colleagues for working with early previews of the documentation, beginning with just a few
pages.
 Mike Cairns for reviewing and editing the manuals.
If anyone feels they have been forgotten on this list please let me know.
Peter Glanzmann

2. Related Publications
2.1 Hercules Emulator – General Information

The Hercules “General Information” manual provides an overview of the ideas and concepts of the
Hercules Emulator as well as documentation of the emulators functionality. It explains what Hercules
does and does not and helps you decide if the software fits to your needs and if it can fulfill all your re-
quirements.
2.2 Hercules Emulator – Installation Guide

The installation guide shows you how to install Hercules and all related optional and required software
components under the Microsoft Windows, Linux and Apple MacIntosh OS X operating systems.
After going through the installation guide you will have a working emulator environment ready to IPL a
S370, S/390 or z/Architecture mainframe operating system.
2.3 Hercules Emulator – User Reference Guide

The Hercules “User Reference” leads you through all aspects of the emulator’s operation. It provides
instruction in the operation of the Hercules Emulator with and without the Windows GUI. The usage
details for all Hercules utilities are also covered in this guide.
After reading this manual you should be able to work with Hercules and the Hercules console, create
virtual devices, understand backup / restore procedures and general housekeeping within the Hercules
environment.
2.4 Hercules Emulator – Messages and Codes

The “Messages and Codes” manual provides a detailed explanation of all Hercules related messages. It
is the primary source for troubleshooting and debugging when you experience problems with Hercules.
2.5 Hercules Emulator – Reference Summary

The Hercules "Reference Summary" booklet lists all the system parameters, device definitions, console
commands, Hercules utilities etc. along with their arguments.
This booklet is intended as a quick reference guide for experienced users. Consult the Hercules "User
Reference Guide" for more detailed and additional information.

Part I: Hardware and Performance

3. Hardware Prerequisites
3.1 PC Hardware
The following section lists the requirements for various hardware components within the context of the
following categories:
 Minimal (minimum required equipment)
 Moderate (average older PC equipment)
 Average (typical current PC equipment)
 Good (fast, newer PC environment)
 Optimal (recommended server equipment for best performance)
It is possible to run Hercules with less than the minimal recommended hardware but performance of any
operating system executing under the emulator will be severely constrained. For acceptable performance
you will need a configuration categorized as “average” or better. If you have access to PC hardware
categorised as “optimal” the performance of installed OS’s will be adequate for most practical purposes.
Most modern PC systems are delivered with adequate RAM, Processor and Disk for Hercules use. It has
been stated in previous Hercules documentation that a Pentium 200 MHz with 32 MB of RAM would be
sufficient for the emulator, however today such a system is no longer practical.
3.1.1 Processor
Hercules does not necessarily depend on the Intel Pentium architecture. It also has been built, installed
and run successfully on an Alpha 21164, SPARC and on z/Architecture Linux/390 systems. One of the
most extravagant implementations for testing purposes has run OS/360 under Hercules under Linux/390
under Hercules under Linux/390 under VM/ESA. This is of course an extreme example of emulation
layers. This document however only describes the implementation of the Hercules Emulator on an Intel
based or compatible PC system.
Hercules will benefit greatly from a fast processor, the faster the processor the better Hercules will run. If
you can employ a multiprocessor or dual-core system, so much the better. The Hercules Emulator makes
extensive use of multithreading to overlap I/O with CPU activity. A multiprocessor board with two slower
processors will in most cases outperform a uniprocessor board with a faster processor.
 Pentium with 500 MHz or equivalent processor (minimal)
 Pentium with 1 GHz or equivalent processor (moderate)
 Pentium with 2 GHz or equivalent processor (average)
 Pentium with 3 GHz (Dual or Quad Core) or equivalent processor (good)
 2 or more Pentium Quad Core processors with 2.66 GHz or equivalent processors (optimal)
3.1.2 RAM
The more RAM installed in the system the better Hercules will perform. For maximum throughput you
should set your main and expanded storage sizes in the Hercules configuration file high enough to elimi-
nate installed operating system paging operations as much as possible. The S/390 guest system storage
is allocated out of the Linux or Windows host operating system storage so try to provide enough RAM to
your system to eliminate Linux or Windows paging as well.

 128 MB RAM (minimal)
 512 MB RAM (moderate)
 1024 MB RAM (average)
 2048 MB RAM (good)
 4096 MB RAM (optimal)
There is a limit to the memory that the 32-bit version of Hercules can allocate under Windows (usually
around 1 GB), therefore normally 2 GB of installed RAM in the machine should be sufficient to allow for
both Hercules and the host OS. If however you plan to run more than one instance of Hercules on the
same machine, each instance can allocate 1 GB of RAM for its own use. In this case it makes sense to
install more than 2 GB RAM. This limitation does not apply when using the 64-bit version of Hercules.
Please note that you still can allocate more RAM than is physically available on the PC to the Hercules
emulator for use of the installed operating system(s). But in this case the Linux or Windows host opera-
ting system has to page out the missing physical RAM to its own swap files which will seriously degrade
Hercules performance.
3.1.3 Disk Storage

The disk storage requirements for Hercules depend entirely on your requirements. The runtime Hercules
system requires only small amount of disk space. You will need a little more space if you plan to build
Hercules from source code. But still the requirements are quiet modest.
Although Hercules and the necessary software components do not require very much disk storage, you
need enough hard disk space to accommodate the emulated DASD volumes for the operating system
you choose to run under Hercules.
For a minimal z/OS system with CICS, IMS, DB2, WAS etc., without any user data, you need at least 15
disks of type 3390 model 3 which requires 42.5 GB hard disk space. If you extend such a system with
some user data for software development etc you may need 10 to 15 additional 3390 model 3 disks. This
could lead to a total hard disk requirement of 85 GB. If you plan to do uncompressed backups of all the
DASD volumes you can double this number.
The following table shows how much space is occupied for each virtual DASD volume on your PC hard
disk(s) for some of the supported device types. If you make use of the compressed CKD DASD feature of
Hercules these sizes will shrink dramatically, usually to about 20 to 30 percent of the original size. Space
savings depend on the actual used capacity within the virtual DASD volumes.

Model Cylinder Bytes/Track Bytes/Cylinder Bytes/Volume
3380-J 885 47’476 712’140 630 MB
3380-E 1’770 47’476 712’140 1.26GB
3380-K 2’665 47’476 712’140 1.89 GB
3390-1 1’113 56’664 849’960 946 MB
3390-2 2’226 56’664 849’960 1.89GB
3390-3 3’339 56’664 849’960 2.83 GB
3390-9 10’017 56’664 849’960 8.51 GB
3390-27 32’760 56’664 849’960 27.84 GB
3390-54 65'520 56'664 849'960 55.68 GB
9345-1 1’440 46’456 849’960 1.0 GB
9345-2 2’156 46’456 849’960 1.5 GB
Table 1: DASD Device Capacity

4. Performance
As described previously the performance of the Hercules Emulator depends heavily on the underlying PC
hardware. It is therefore not possible to give exact performance specifications of any particular operating
system running under Hercules. Some practical values from user experiences across several machines
presented here provide some guidelines though.
The performance of Hercules is measured in two values, MIPS and I/O rate. Both of these values are pre-
sented on the Hercules console and are refreshed every second independently of the PANRATE control
statement. See Hercules User Reference for details on the PANRATE statement.
4.1 MIPS
MIPS is an abbreviation of “Million Instructions Per Second” and presents a measure of the number of
instructions the CPU is executing in one second. MIPS is a measure of a computer's processor speed.
However this measure is useful only among processors with the same instruction set as different instruc-
tion sets take different numbers of instructions to do the same job. Many of the reported MIPS values
represent 'Peak' execution rates on artificial instruction sequences with few branches, whereas realistic
workloads consist of a mix of instructions some of which take longer to execute than others.
The performance of the memory hierarchy greatly affects processor performance, an issue also not con-
sidered in simple MIPS comparisons. In an attempt to address these issues researchers have created
standardized tests such as "SpecInt" to measure the real effective performance in commonly used
applications. The use of raw MIPS as a measure of overall system performance has fallen into disuse.
MIPS is sometimes pejoratively referred to as "Meaningless Indicator of Processor Speed" or "Meaning-
less Information Provided by Salespeople".
The Hercules console reports the MIPS rate for the emulated S/370, ESA/390 or z/Architecture instruc-
tions, not the underlying executed instructions of the hardware. As implied previously the MIPS rate can
vary significantly depending on the executed instruction and whether the instructions can be processed
entirely in cache, as can happen in a tight loop.
It is difficult to determine how the speed of the Hercules emulation corresponds to a real mainframe. This
is due to difficulties in comparing real mainframe hardware to PCs (or servers) as well as the actual per-
formance measurement itself. Hercules shows its processing speed in MIPS. Compared to the earlier
IBM System/360 and System/370 hardware, it is safe to say that Hercules will outperform them when it is
running on moderately powerful hardware, whereas newer IBM System/390 and z/Series hardware still is
much faster than the emulation.
On a Celeron 300 you should see an execution speed of 1 to 2 MIPS, which is enough to run OS/360
(MFT or MVT) or MVS 3.8 with a response time better than that of a 3033 from the 1970's. It's also fast
enough to run VSE/ESA with an acceptable response time. On a more recent system with a 2 GHz
Pentium processor, you may see the system peak at around 30 MIPS which is enough to run Linux/390
or z/OS with a light workload.
Performance on server class machines is now fairly respectable. For example, on a dual-core Intel Xeon
with "Hyperthreading" (4 CPUs) running at 3.46 GHz, you might expect to see a sustained MIPS rate of
40 to 60 MIPS. A dual-processor quad-core Mac Pro (8 cores, 3 GHz) will sustain over 150 MIPS. For
anyone who is prepared to spend a considerable amount of money on their Hercules system, there are
reports that a sustained 300+ MIPS rate has been achieved on an Intel Core i7 processor running at 3.75
GHz using all four cores plus "Hyperthreading" (8 CPUs).
The speed however depends greatly on the executed instructions. Instructions that are very expensive to
emulate can even on fast systems still be around 1 - 2 MIPS, see the tables further below for details.

4.2 I/O Rate
The second value that gives us performance data is the I/O rate. This is the average number of SIOs
(Start I/O per second) occurring to active devices, including DASD, TAPE, CTC (channel-to channel
adaptor), local SNA and non-SNA devices etc.
This value also varies depending on the underlying hardware. A RAID system will easily outperform a
non-RAID system. Many PC systems today can be ordered with a RAID-0 (Striping) or RAID-1 (Mirroring)
adapter. While disk mirroring (RAID-1) gives fault tolerance it does not improve performance. However
Data striping (RAID-0) spreads blocks of each file across multiple disks and can nearly double the per-
formance of a single disk.
On a recent PC system as described above, incorporating two Serial-ATA (SATA) disk drives connected
to a RAID adapter card with activated RAID-0 has shown peak I/O rates of more than 3250 SIOs per se-
cond. The sustained I/O rate delivered from such a system was more than 1500 SIOs per second.
4.3 Hercules Performance Measurements

The following sections show some performance index tables under various system configurations. Indi-
vidual measured performance may vary from the figures shown as performance depends heavily on the
hardware used and the Hercules release level.
All tests have been performed with the following measurement tools:
 IMON (Rate CPU Instruction Speed)
 CPU Instruction Timing Tool (INSTRATE program)
Tests showing the performance of Hercules itself include measurements of the Hercules Emulator soft-
ware and the difference between working with CKD or CCKD (compressed CKD) DASD emulation. Other
tests, like the host CPU on which Hercules runs or the disk types of the host system, show the influence
of the hardware used. The last test ("Hercules Overall Performance") represents the practical perfor-
mance growth of the Hercules Emulator as both hardware and software have improved.
4.3.1 Hercules Emulator Performance

The following diagram shows the software related performance index of the Hercules Emulator software.
The graphic shows the performance improvements that have been made over recent releases. The base
version (index = 100%) for all measurements was Hercules V3.00.
All these tests were performed using the same hardware configuration. The results therefore demonstrate
the influence of the improvements in the performance of the Hercules Emulator software only.

Figure 1: Hercules Emulator Performance
Although there have been massive performance improvements in the Hercules Emulator software in re-
cent releases, the current rate of improvement cannot be expected to continue. On one hand, the maxi-
mum performance improvements available via software improvements will be reached, on the other hand
the developers of Hercules have architectural frameworks that impose certain limitations, as explained
below.
Firstly the Hercules software should be portable and is therefore written entirely in "C". The use of assem-
bler to give additional performance is not exploited. Secondly the developers try to emulate real hardware
as exactly as possible in accordance with IBM's "Principles of Operations" documentation. This leads to
code that may be not optimal for the underlying hardware, but provides perfect emulation of real main-
frame hardware, avoiding problems when running mainframe operating systems.
The performance of the Hercules Emulator software depends heavily on the set of executed (mainframe)
instructions as detailed in below ("Emulated Instruction Performance").
4.3.2 Emulated CKD / CCKD DASD Performance

The type of the emulated DASD devices, either CKD or CCKD, has direct influence on performance. If
using CKD devices there is more data to be read from the disk and transferred to memory, but the data is
directly usable and no further processing needs to be done. Using CCKD (compressed CKD) devices the
amount of data to be read from the disk and transferred to memory is greatly reduced but once in memory
the data has to be uncompressed before it can be processed.
The performance characteristics of DASD types are irrelevant if host disk space limitations impose the
choice of using compressed CKD only.
On a fast machine with fast disks CKD is the best choice. On a fast CPU with slow disks however, CCKD
can give better overall performance. A fast processor can uncompress the data in less time than that
saved by transferring the data uncompressed. In the less common case of a slow CPU with fast disks

CKD DASD can perform better as the uncompressed data is transferred faster than the processor could
uncompress it. In the case of a slow machine with slow disks and possibly space constraints it is recom-
mended to work with CCKD DASD.
Another point to consider is reliability. Although Hercules itself is very stable, occasional machine crashes
such as the Windows "Blue Screen of Death" can occur. The CKD DASD emulation in these cases is very
stable; it is usually possible to just restart the machine with no problems. However when working with
CCKD DASD emulation, after a crash the CCKD routines have to perform a recovery during the restart of
Hercules. This recovery takes from seconds to several minutes depending on what happened and the
number of defined DASD devices. Although this recovery is normally successful cases have been repor-
ted where the recovery failed. In this case the only option is to restore DASD images from previously
saved backups.
The following figure shows a performance comparison of compressed DASD (CCKD) versus CKD de-
vices. The IPL time with CKD devices was 75 seconds. The IPL time with CCKD devices is only slightly
higher (about 80 seconds).
Figure 2: DASD Emulation Type Performance
Both tests were performed on the same machine (2 x Opteron 280, 2.4 GHz with a Software RAID-0 hard
disk configuration). The measured performance degradation using CCKD emulation over CKD is only
approximately 7.0 percent.
4.3.3 Host CPU Performance

The following diagram shows the CPU related performance results for Hercules. The base CPU at index
= 100% is an Intel Pentium 3 with 500 MHz clock speed.

All these tests were performed with the same Hercules release (V3.05) and therefore show only the
influence on performance of the real CPU and I/O devices.
Figure 3: Hercules CPU-based Performance
The figures shown above are influenced by the I/O configuration used. As mainframe operating systems
running under Hercules are often heavily I/O based, bare CPU speed is not the only relevant performance
factor. An additional performance boost is achieved using RAID-0 striping and / or using several physical
disks in the host system under which the emulator is running, as discussed in the following section.
4.3.4 Host Disk Performance

The following table shows the different disk and controller configurations that have been used for testing
the disk transfer rates. The comparison of the reached transfer rates is visualized in the figure following
the configurations table.

Test Scenarios Scenario 1 Scenario 2 Scenario 3 Scenario 4
Western Western Hitachi Hitachi

Disk Type Digital Digital Ultrastar Ultrastar
WD1500ADFD WD1500ADFD 15k300 15k300
Nvidia Nvidia Adaptec Adaptec

Disk Controller
nForce4 SATA nForce4 SATA RAID 3405 RAID 3405
RAID
none RAID-0 none RAID-0
Configuration
Table 2: Disk Configurations
These configurations reached the transfer rates as shown in the following figure.
Figure 4: Disk Transfer Rates
While these measurements only show the “raw speed” of the disks without direct relationship to Hercules,
the next diagram shows the impact on the IPL time depending on the used disk configuration. Both tests
have been run using the same hardware (2 x AMD Opteron 280, 2.4 GHz), the only change being the
type of disk employed.

The first test was made with a non-RAID disk configuration (Scenario 1, see above) which reached a
transfer rate of 85 MB/s. The second IPL was done with a RAID-0 disk configuration (Scenario 2, see
above) with a transfer rate of 169 MB/s. The IPL with the RAID-0 disk configuration needed only 75 se-
conds compared to 81 seconds with the non-RAID setup.
Figure 5: Host Disk Performance (IPL in seconds)
These tests demonstrate that fast disks and RAID-0 configurations provide a performance boost from
which Hercules will benefit.
4.3.5 Emulated Instruction Performance

As previously stated, Hercules Emulator performance depends heavily on the mainframe instructions
being executed. While some S/3xx instructions are relatively easy to implement and require only a few
"C" instructions in the emulator, others are quite complicated and require a lot of instructions to emulate
the real hardware. Due to this fact the performance of each individual S/3xx instruction can vary greatly.
There is a variance of more than 450 times between the fastest and slowest emulated instructions.
It is known though, that in mainframe operating systems, a small subset of the available instructions are
employed to do most processing. In Hercules, if most of these instructions are emulated slowly, the over-
all performance of the emulator will be poor. Alternatively, if the most commonly used instructions are
emulated quickly the performance of the emulator will benefit greatly.
An analysis of mainframe operating systems has shown that only 5 different instructions are responsible
for up to 50% of the executed code. Expanding this analysis to 10-15 instructions will cover up to 75% of
executed code and 15-20 instructions will cover more than 80% of all mainframe code.

The following tables list some different test scenarios and the performance ratios of individual instructions
and real work tests under the Hercules Emulator. The used hardware for each scenario is listed in the
following table. All test jobs have been run three times under each scenario. The average MIPS rate of
these three runs has been taken into the table.
These tests are not meant to provide a definitive MIPS rating (your own measurements may be some-
what different), but serve as a repeatable test for comparing the relative speeds of different hardware.
Test Scenarios Scenario 1 Scenario 2 Scenario 3
PC Model
08/2003 09/2006 06/2008
(month/year)
CPU Type Intel Pentium P4 AMD Opteron 280 Intel QX9775 EE
CPU Clock Rate 3.2 GHz 2.4 GHz 3.6 GHz
Number of
1 2 2
physical CPUs
Number of CPU
2 4 8
Cores
RAM 2 GB 8 GB 8 GB
Operating System Windows XP Pro Windows XP Pro x64 Windows XP Pro x64
Hercules Release V 3.05 V 3.05 V 3.05
Table 3: Performance Test Scenarios
The first table of performance results shows the reachable MIPS rates of various single instructions. The
test is based on a modified INSTRATE program, originally written by Gary Brabiner.
Executed Instruction Scenario 1 Scenario 2 Scenario 3
BCT Rx,LOOP 99.55 MIPS 84.06 MIPS 82.14 MIPS
BCTR RX,RLOOP 109.10 MIPS 93.86 MIPS 137.74 MIPS
NOP R0 154.84 MIPS 144.52 MIPS 431.59 MIPS
LR R1,R0 66.33 MIPS 58.07 MIPS 101.75 MIPS
LTR R1,R0 64.76 MIPS 58.12 MIPS 102.03 MIPS
L R1,0 10.09 MIPS 12.43 MIPS 18.97 MIPS
L R1,DATA 39.00 MIPS 33.87 MIPS 42.65 MIPS
L R1,DATA+1 37.95 MIPS 33.44 MIPS 41.11 MIPS

LH R1,DATA 37.74 MIPS 33.93 MIPS 49.96 MIPS
ICM R1,15,DATA 35.50 MIPS 33.85 MIPS 39.89 MIPS
ICM R1,1,DATA 20.28 MIPS 20.96 MIPS 29.53 MIPS
IC R1,DATA 37.59 MIPS 33.77 MIPS 51.27 MIPS
LD F0,DATA 13.95 MIPS 25.23 MIPS 51.50 MIPS
LM 8,6,SAVEREGS+(8*4) 18.78 MIPS 17.98 MIPS 19.34 MIPS
STM 1,14,DATA 24.01 MIPS 19.21 MIPS 20.12 MIPS
ST R1,DATA 37.77 MIPS 32.91 MIPS 44.73 MIPS
STH R1,DATA 36.84 MIPS 34.04 MIPS 44.61 MIPS
STCM R1,15,DATA 35.87 MIPS 28.04 MIPS 40.87 MIPS
STC R1,DATA 39.97 MIPS 34.02 MIPS 46.95 MIPS
MVI DATA,CHAR 39.77 MIPS 35.70 MIPS 56.72 MIPS
MVC DATA(8),DATA 19.72 MIPS 15.57 MIPS 28.47 MIPS
MVC DATA(32),DATAB 2.25 MIPS 6.05 MIPS 30.65 MIPS
MVC DATA(32),0 1.94 MIPS 4.74 MIPS 14.68 MIPS
MVC DATA(256),DATAB 0.31 MIPS 1.16 MIPS 15.45 MIPS
XC DATA(4),DATA 17.58 MIPS 19.12 MIPS 37.05 MIPS
XC DATA(4),DATAB 22.61 MIPS 22.12 MIPS 26.97 MIPS
CLI DATA,CHAR 39.73 MIPS 32.00 MIPS 46.08 MIPS
CLC DATA(8),DATA 26.42 MIPS 23.25 MIPS 36.16 MIPS
CLC DATA(32),DATAB 22.53 MIPS 17.80 MIPS 36.51 MIPS
CLC DATA(32),0 10.01 MIPS 10.43 MIPS 15.78 MIPS

CLC DATA(256),DATAB 8.88 MIPS 7.90 MIPS 19.37 MIPS
AR R1,R0 49.39 MIPS 37.65 MIPS 78.44 MIPS
ALR R1,R0 59.98 MIPS 56.69 MIPS 78.85 MIPS
A R1,F1 36.09 MIPS 32.92 MIPS 41.32 MIPS
AH R1,H1 35.57 MIPS 30.76 MIPS 41.28 MIPS
LA R1,1(,R1) 55.35 MIPS 45.18 MIPS 71.40 MIPS
LA R1,1(R1) 55.46 MIPS 48.94 MIPS 63.86 MIPS
AP PL4,PL4 1.67 MIPS 1.69 MIPS 2.61 MIPS
AP PL4,PL4B 1.87 MIPS 1.80 MIPS 3.02 MIPS
AP PL16,PL16 1.46 MIPS 1.52 MIPS 2.27 MIPS
AP PL16,PL16B 1.64 MIPS 1.69 MIPS 3.02 MIPS
CVD R1,DATA 2.82 MIPS 3.09 MIPS 21.44 MIPS
CVD R15,DATAB 6.60 MIPS 7.12 MIPS 26.17 MIPS
AER F0,F4 32.26 MIPS 30.40 MIPS 40.82 MIPS
ADR F0,F4 25.78 MIPS 25.75 MIPS 45.64 MIPS
AXR F0,F4 16.69 MIPS 17.78 MIPS 43.74 MIPS
Move 256 Bytes by MVC 0.31 MIPS 1.16 MIPS 15.84 MIPS
Move 256 Bytes by MVCL 3.25 MIPS 4.84 MIPS 11.48 MIPS
Clear 256 Bytes by MVC 0.93 MIPS 1.32 MIPS 15.23 MIPS
Clear 256 Bytes by MVCL 3.63 MIPS 6.11 MIPS 16.54 MIPS
Table 4: Emulated Instruction Performance
The next table shows some performance data from the "CPU Speed Rating Monitor" of IMON (Interactive
Monitor IMON/370 and IMON for OS/390 and z/OS, see http://www.prycroft6.com.au).
The eight tests of IMON run the following instructions:

 RR instructions (fast):
ALR, AR, BCTR, LCR, LR, NR, OR, SLR, SR and XR.

 RR instructions (slow):
ALR, AR, BCTR, DR, LR, MR, NR, OR, SR and XR.
 RX instructions (fast):
A, AL, BCT, IC, L, N, O, S, SL and X.
 RX instructions (slow):
A, BCT, CVB, CVD, D, L, M, O, S and X.
 SS instructions (fast):
AP, CLC, ED, MVC, NC, OC, SP, TR, UNPK, XC and ZAP.
 SS instructions (slow):
CLC, DP, ED, MP, MVC, NC, OC, TR, UNPK and XC.
 Floating Point instructions (E-format, 32-bits wide):
AE, AER, CE, DE, DER, HER, LCER, LE, ME, MER, SE and SER.
 Floating Point instructions (D-format, 64-bits wide):
AD, ADR, CD, DD, DDR, HDR, LCDR, LD, MD, MDR, SD and SDR.
For the RR instructions tests, the operation codes listed form 10% of the instruction mix. The main
slowing factors of test 2 compared to test 1 are the presence of the Divide instruction (DR) and the
Multiply instruction (MR). Something similar holds true when looking at the differences between tests 3
and test 4. In tests 5 and 6 again, Divide and Multiply are used to slow test 6 as well as increasing the
length of data processed by the MVC, ED, UNPK, CLC and TR instructions (one byte in test 5, maximum
length in test 6).
According to IMONs help text, the "official" MIPS rating of a CPU model is usually about 20% faster than
the results of test 2 (RR Slow).
IMON RR (Fast) 41.98 MIPS 67.90 MIPS 165.78 MIPS
IMON RR (Slow) 36.80 MIPS 49.16 MIPS 138.11 MIPS
IMON RX (Fast) 37.17 MIPS 40.87 MIPS 64.85 MIPS
IMON RX (Slow) 11.20 MIPS 13.11 MIPS 40.21 MIPS
IMON SS (Fast) 6.65 MIPS 7.03 MIPS 12.52 MIPS
IMON SS (Slow) 0.90 MIPS 0.95 MIPS 3.95 MIPS
IMON FP (Extended) 22.81 MIPS 20.73 MIPS 41.46 MIPS
IMON FP (Double) 3.35 MIPS 4.93 MIPS 21.60 MIPS
Table 5: IMON Instruction Performance Data
The last table shows the results of tests consisting of a tight loop. These tests show the influence on raw
processor speed (only one job running) as well as the influence of having a multi-processor system and
running several jobs in parallel.

The last test shows the time used for an IPL of a mainframe operating system from the actual IPL com-
mand until logon to the system is possible. The IPL only contains the mainframe operating system itself,
without any optional subsystems.
Loop 1 (1 Job) 116.04 MIPS 105.92 MIPS 473.27 MIPS
Loop 1 (2 Jobs) 61.30 MIPS 210.92 MIPS 654.23 MIPS
Loop 1 (4 Jobs) --- 420.39 MIPS 1261.85 MIPS
Loop 1 (8 Jobs) --- --- 1676.32 MIPS
IPL time 03:10 (mm:ss) 01:15 (mm:ss) 00:57 (mm:ss)
Table 6: Real Work Performance
These tests show that, although the raw instruction speed of the four processor machine of scenario 2
compared to the two processor machine of scenario 1 is somewhat slower as shown in table 2 above, the
system greatly benefits from the four processors when doing real work, because it can handle more tasks
in parallel.

Part II: Windows Installation

5. Software Prerequisites
5.1 Operating System

Hercules is an open source software implementation of the mainframe System/370, ESA/390 and z/Archi-
tecture hardware. Hercules itself is not an operating system nor does it emulate a mainframe operating
system. The Hercules Emulator runs under Linux on several hardware platforms including the Intel Pen-
tium PC, under various flavours of Microsoft Windows and under MAC OS X. From the point of view of
the underlying operating system the Hercules Emulator is just an application program.
Part II of this guide focuses solely on the installation of Hercules under Microsoft Windows. Details of
other host operating systems are covered in Part III (Linux) and Part IV (Mac OS X) in this book. The
installation of any hosted operating system and software utilities is beyond the scope of this book.
5.1.1 Windows Versions

The Hercules Emulator runs under Windows 98, Windows NT, Windows 2000, Windows XP, Windows
Vista, Windows Server 2000 and Windows Server 2003. Although Windows 98 and Windows NT are
possible candidates for running Hercules, their use is not recommended because of limitations in stability
(especially Windows 98), limited networking capabilities and lack of support. It is generally a good idea to
have a current operating system maintained with the latest fixes i.e. Windows XP / Vista or Server 2003.
Some users experienced problems with TCP/IP functionality when running under Windows XP with Ser-
vice Pack 2 while other users did not encounter these issues. The presenting problem with this configu-
ration is: It is possible to connect from the Host operating system to the Hercules machine and vice versa,
however it is not possible to get a connection to another workstation on the LAN or the Internet. Most of
these issues are related to configuration problems with the Windows XP firewall, introduced with Service
Pack 2. Creating correct rules in either the Windows internal firewall or an alternative firewall product
solves these problems.
5.1.2 Stability
As Hercules appears to Windows as just another application program, it is possible to run other applica-
tions simultaneously with Hercules, however this is not recommended. While the Hercules Emulator is
extremely stable software it is impossible to guarantee that other applications will not degrade Hercules
performance or even crash the Windows system. The less software you have installed on your system
the more stable your emulated mainframe will be.
Intensive tests have proven the stability of Hercules, one of the test suites is repeated with every new
Hercules release. The tests run a mixed online and batch workload continuously and at high volumes.
The base system consists of a MVS 3.8J operating system with additional components. During the test
the system is loaded with between four and eight self submitting (therefore continuous) batch jobs exe-
cuting in parallel. These jobs consist of a mix of large sorts, assemblies, compilation and link jobs.
Additionally there are some TSO sessions active (up to ten sessions) on which a simulated user presses
enter once a second in a performance monitor application.
This workload keeps the system (emulated mainframe as well as Hercules and the base operating sys-
tem) busy at nearly 100% CPU and a produces a continuous I/O rate of more than 750 SIOs. In this state
the machine runs 7x24 hours during several days. One of these tests was stopped after more than 12
weeks with the system still running perfectly.

5.1.3 Installed Software on a Hercules System
It was recommended earlier to have only a minimum of software installed on a Hercules host machine.
Additional to the software for the Hercules Emulator presented in this guide, it is recommended to have
the following software installed:
 Windows 2000, Windows XP, Windows Server 2003 with latest service packs and hot fixes
 Software firewall, especially if there is no hardware firewall in the LAN
 Antivirus software with on demand and on access checks active
Depending on your requirements other commonly used utilities include:

 Network sniffer
 Performance monitor / Task monitor
 FTP program
In general though the less software is installed the better the emulated mainframe will run.
5.2 Drivers
This Chapter describes the device drivers that are necessary specifically for the Hercules Emulator. A de-
vice driver is a routine or a set of routines that implement the device-specific aspects of generic I/O ope-
rations. Generally the Hercules Emulator does not need any special device drivers other than those provi-
ded by the operating system. An exception is WinPcap, which is required under the Microsoft Windows
operating systems to enhance networking capabilities of the native operating system.
5.2.1 WinPcap Packet Capture Driver

WinPcap is an architecture for packet capture and network analysis for the Win32 platform developed at
Politecnico di Torino in Italy. The packet filter is a device driver that adds to Windows 95, 98, ME, NT,
2000, XP and Server 2003 the ability to capture and send raw data from a network card with the possi-
bility to filter and store the captured packets in a buffer.
WinPcap includes an API that can be used to directly access the functions of the packet driver offering a
programming interface independent from the Windows operating system. It also exports a set of high le-
vel capture primitives that are compatible with libpcap, the well known Unix capture library. These func-
tions capture packets in a way independent from the underlying network hardware and operating system.
WinPcap is a free, public system and is released under a BSD-style license. It can be downloaded from
www.winpcap.org where the necessary documentation can also be found.
5.3 Runtime Environments

This chapter describes special runtime environments which act as a base for running the Hercules Emu-
lator. Under a Linux-like operating system no additional runtime environment is needed. Under Microsoft
Windows however, the necessary Linux POSIX threads support may be emulated as explained below.

5.3.1 Cygwin
Until release 3.02.0 the Hercules Emulator was designed to run only under a Linux system with POSIX
threads (pthread) support. To be able to run Hercules releases below 3.03.0 under Windows it is neces-
sary to install a runtime environment to provide this Linux compatible layer. This is where Cygwin steps
in.
Cygwin is a Linux-like environment for Microsoft Windows. It consists of several DLLs which act as an
emulation layer providing substantial POSIX system call functionality and a collection of common Linux
tools. The Cygwin environment works with all x86 versions of Windows since Windows 95.
Cygwin is available from www.cygwin.com. The Cygwin development began 1995 at Cygnus Solutions
which is now owned by RedHat Software.
Cygwin is mentioned in all current Hercules manuals for support purposes only. Since release 3.02.0 of
Hercules it is recommended that Windows users install the Microsoft Visual C native binaries or Microsoft
Installer (MSI) package.
Beginning with Release 3.03.0 the Hercules Emulator no longer requires Cygwin in order to run under
Windows. It is highly recommended that Windows users of Hercules begin using this new MSVC Win-32
version instead of the Cygwin versions.
5.4 Hercules Emulator

The Hercules Emulator consists of the following mandatory and optional components:
 Hercules Emulator (mandatory)
 Hercules Windows GUI (optional)
 CTCI-W32 (optional)
 Additional utilities (optional)
5.4.1 Hercules
The Hercules executables are the heart of the emulator and a mandatory component. This is the software
implementation of the System/370, ESA/390 and z/Architecture mainframe hardware and processor
machine code instruction set.
Hercules runs as a DOS program and comes with a semi-graphical display in a DOS window (the Her-
cules Hardware Console - HMC) consisting of two screens, switched between using the ESC key. When
the Hercules HTTP server is running then Hercules can also be operated via a web browser interface.

The following figure shows the initial display, the Hercules console window:
Figure 6: Hercules Hardware Console - Console window

The next figure shows the Hercules device and status display accessed with the ESC key:
Figure 7: Hercules Hardware Console - Device and status display

The last figure shows the Hercules web browser interface which can be accessed when the Hercules
HTTP server is configured and running:
Figure 8: Hercules web browser interface
5.4.2 Hercules Windows GUI

The Hercules Windows GUI (WinGUI) provides an optional graphical user interface to the Hercules Emu-
lator replacing the native DOS console window of Hercules. The Windows GUI program interfaces with
Hercules Emulator directly. It provides an easier way to work with the Hercules Emulator including inter-
faces to create / change the Hercules configuration files and the handling of log files.

The following figure shows the Hercules WinGUI main panel:
Figure 9: Hercules Windows GUI Main Panel
Using the GUI all of the Hercules DOS utilities are available, it is no longer necessary to know the exact
syntax of each utility. Instead of having to issue cryptic command lines in native DOS such as
HETUPD -2 -b D:/MVS/TAPE/TLEV009.HET D:/MVS/TAPE/TLEV002.HET
a standard Windows dialog box can be used to call the utility. The following figure shows the pop-up
window, used to provide information to one of the Hercules utility programs (HETUPD).

Figure 10: Hercules Utility Window
The WinGUI has been developed by David B. Trout (Fish). More detail about the functionality provided by
the WinGUI can be found in the "User Reference Guide" and in Chapter 10 – Installing the Hercules
WinGUI.
5.4.3 CTCI-W32
Since Hercules runs as a user process under the control of the host Windows system it does not normally
have direct access to the driving system's network adapter. Until recently this presented a problem in
establishing connectivity between the network and the TCP/IP stack of an operating system running un-
der Hercules.
Since the development of device drivers by Fish, employing of the WinPcap's device driver, it is now
possible to establish a virtual point-to-point link between the TCP/IP stack running under Hercules and
Window's TCP/IP stack. This allows you to use Windows as a router to pass Ethernet frames between the
Hercules TCP/IP stack and the rest of the network.
5.5 Additional required and optional Software

As well as the components described above other software, either required for practical use of Hercules
(eg: tn3270 client) or that makes common tasks easier (eg: XMIT Manager, AWS Browse, ZZSA etc) may
be used.

5.5.1 tn3270 Client (required)
For virtual 3270 consoles and 3270 terminals a tn3270 client software application is required. The tn3270
client can run on the same machine as Hercules or on any Unix or Windows box with a TCP/IP connec-
tion to the Hercules machine. The supported and recommended tn3270 client for Hercules under Win-
dows is Vista tn3270.
Vista tn3270 can be obtained from www.tombrennansoftware.com. The license fee charged by the deve-
loper of the software, Tom Brennan, is very modest. A 30 day trial version can be downloaded from his
web site.
Other tn3270 clients, such as QWS3270, IBM Personal Communications, Attachmate Extra, etc., should
also work in most cases. Be aware that some tn3270 clients have a bug that makes them unusable as an
MVS console.
Because the tn3270 client is an independent piece of software there are no version requirements. You
can use any stable release of a tn3270 client although it is recommended to always run with a current
release.
5.5.2 XMIT Manager (optional)

The XMIT Manager is a Windows based tool that allows for the manipulation of IBM mainframe created
Xmit format files. With XMIT Manager you can open Xmit files and view or extract the data within them,
whether binary or text, using a graphical interface. Xmit files containing partitioned or sequential datasets
are supported.
5.5.3 AWS Browse (optional)

The AWS Browse Utility is used to view the contents of tapes from the Windows desktop without having
to start a mainframe operating system and run tape reading utilities. There are currently two implemen-
tations of AWS browse.
The original one was created by Rob Storey. The second is an enhanced version written by Fish, which is
faster and has more features.

6. Component Compatibility Tables
The various components under the Windows operating system that together make the full Hercules en-
vironment have some inter-dependencies on each other. It is recommended that these components be at
a certain release level for every version of Hercules. The following tables list the combinations of com-
ponents for several releases that have been successfully evaluated as working together.
If a combination is not listed in these tables this does not necessarily mean that it will not function. How-
ever you must asses this yourself and at your own risk. Although the listed combinations shown below
have been thoroughly tested and proven to provide a stable environment, there is no guarantee that the
components work in every environment and in any case.
Components that have been updated during the lifetime of a specific Hercules release are shown with
their highest release level in each table. In general it is recommended to work always with the most cur-
rent stable release of each component. Beta releases are not shown here. The date(s) in parenthesis
show the release dates of the respective components. If there was no release of Hercules but updated
components, then the word “Components” can be found before the release date.
In the case of Cygwin the release shown here is the one that Hercules was built with, rather than the
highest. As Cygwin is a runtime environment, its release level must be the same or higher than the ver-
sion Hercules was built with. Therefore the Cygwin release level listed for any level of Hercules is the
minimum level needed for that Hercules release. Any higher level of Cygwin should also run but ex-
perience has shown that this is not always the case.
Please note that obsolete components, e.g. Cygwin, or components that were subsequently included in
other packages, e.g. FishPack, TunTap32 and tt32info are mentioned in the table immediately after the
release where the change occurred and are then removed from the tables.
6.1 Hercules V 3.07.0 (Release date: March 10, 2010)
Component Release
Hercules Emulator V 3.07.0
WinPcap V 4.1.1
HercWinGUI V 1.11.1.5265
CTCI-W32 V 3.2.1.160
FishLib V 2.7.1.564
AWS Browse V 1.5.1.1805
HercPrt V 1.1.0.545
Table 7: Hercules Release V 3.07.0 Component Compatibility Table

6.2 Hercules V 3.06.0 (Release date: January 11, 2009)
Component Release
WinPcap V 4.0.2
CTCI-W32 V 3.2.1.160
FishLib V 2.7.1.564
6.3 Hercules V 3.05.0 (Release date: June 23, 2007)
Component Release
WinPcap V 4.0.1
CTCI-W32 V 3.2.1.160
FishLib V 2.7.1.564

6.4 Hercules V 3.04.0 (Release date: February 24, 2006)
Component Release
WinPcap V 4.0
CTCI-W32 V 3.2.1.160
FishLib V2.7.1.564
6.5 Hercules V 3.03.1 (Release date: December 31, 2005)
Component Release
WinPcap V 3.0
FishPack V 1.3.0.323
TunTap32 V 2.1.0.404
tt32info V 1.0.2.133

Component Release
Hercules Emulator V 3.03
Cygwin No longer needed!
WinPcap V 3.0
TunTap32 V 2.1.0.404
tt32info V 1.0.2.133
Component Release
Cygwin V 1.5.12
WinPcap V 3.0
TunTap32 V 2.0.3.379
tt32info V 1.0.2.133

6.8 Hercules V 3.01.0 (Release date: November 30, 2003)
Component Release
Cygwin V 1.5.5
WinPcap V 3.0
TunTap32 V 2.0.3.379
tt32info V 1.0.2.133
6.9 Hercules V 3.00.0 (Release date: October 2, 2003)
Component Release
Cygwin V 1.5.5
WinPcap V 3.0
TunTap32 V 2.0.3.379
tt32info V 1.0.2.133

7. Installation WinPcap
Figure 11: WinPcap Logo
7.1 WinPcap Packet Capture Driver

The first component you are required to install after the operating system is the WinPcap Packet Capture
Driver. This can be downloaded from the website of the Politecnico di Torino (http://www.WinPcap.org)
where you will also find comprehensive documentation. Save the executable in a directory of your choice.
Be sure to only use the latest version of WinPcap that is supported by CTCI-W32 supplied with the re-
lease of Hercules you are using. The most recent release of WinPcap may not be compatible with your
version of Hercules. See chapter 0 (Component Compatibility Tables) for details of the supported release.
7.2 Installation Steps (Windows Setup)

The installation program for WinPcap creates and then initiates a kernel driver service. Please note that
you need to have administrator privileges in order to create and to start the Netgroup Packet Filter (NPF)
kernel driver service. You must be logged onto your Windows system as an "administrator" when you run
the TESTAPP program for the first time and create the NPF service entry, or whenever you run a pro-
gram that starts the NPF service. Once the NPF service has been created and / or started however, any
non administrator user may use the service.
As with every installation under the Windows operating system, you should stop all running programs
prior to starting the installation process. To start the installation wizard just double-click on the executable
WINPCAP_v_r.EXE (where “v” is the version and “r” is the release) in the directory where you previously
have saved the file.

The information screen of the WinPcap installation appears.
Figure 12: WinPcap Setup - Information Screen
This screen gives you an informational about WinPcap. Click on “Next >” to continue with the installation.

The welcome screen of the installation wizard appears.
Figure 13: WinPcap Setup - Welcome Screen
This screen gives you the usual information presented when starting installation programs under
Windows. Click on “Next >” to continue with the installation.

On the following screen you are presented with the license agreement. Read the license agreement
carefully. You have to accept the license agreement in order to continue with the installation process.
Figure 14: WinPcap Setup - License Agreement
After reading the license agreement, accept it by clicking on the “I Agree" button to continue the
installation process.

The installation process now automatically begins. You do not have to select a target directory and there
are no other decisions to make. A progress bar in a new window will appear. On a fast machine it is
possible that the progress window just flickers for a short time, or that you will not see the window at all as
the installation process is very fast.
Figure 15: WinPcap - Setup Status
As soon as all files are copied to their default destination and the installation process is complete the final
screen shown below is displayed.

Figure 16: WinPcap Setup - Installation Complete
If an older version of WinPcap was installed on the machine it is strongly recommended that you reboot
the system. Click on "Finish" to complete the installation process, then continue with the customization
steps.
7.2.1 Customization Steps

Unfortunately the WinPcap installation routine sometimes fails to successfully create the packet driver
service (NPF) required by any program using WinPcap. In early CTCI-W32 implementations the FishPack
DLL simply tried to start the driver service that it needed assuming that the WinPcap installer had been
successful in creating the NPF service. In the current release of CTCI-W32, FishPack now makes a
dummy call to the WinPcap DLLs “PacketOpenAdapter” function at startup to force WinPcap to finish its
installation process and create the needed kernel driver service. This can be done by either starting Her-
cules using CTCI-W32 or can be forced with the stand-alone CTCI-W32 utility “tt32info”.
Therefore the customization steps described below should not be required, however it is a good idea to
verify that the WinPcap installation did complete successfully. To see if the kernel driver service is instal-
led properly, perform the following steps.

From the Windows desktop click on “START” then select “RUN…”, the run window will appear. Type the
name of the Windows System Information program (“msinfo32”) and click on “OK”.
Figure 17: Run Program msinfo32
The System Information program starts and presents the main window shown below.
Figure 18: System Information Main Window
In this window select “Software Environment” and then “System Drivers”. After a few moments a list of all
installed system drivers is presented.

Scroll through this list looking for the WinPcap kernel driver service which will be called “npf – NetGroup
Packet Filter Driver”. If this driver is found in the list then WinPcap has successfully installed its service. If
this entry is missing from the list it can be created using the CTCI-W32 utility “tt32info” (see chapter 10 for
details).
Figure 19: NPF - NetGroup Packet Filter Driver
The status of the NPF service is seen by scrolling to the right.

After WinPcap installation the column “started” should be set to “No”, the column “Start Mode” should
show “Manual” and the column “State” shows that the service is “Stopped”. As soon as CTCI-W32 is
active the values in these columns will change to “Started=Yes” and “State=Running”.
Figure 20: NetGroup Packet Filter Driver Status
Although the service will be started automatically on request of Hercules via CTCI-W32, some users may
wish to have the service running automatically after Windows bootup. This behaviour can be controlled
using the following registry setting:
HKLM\System\CurrentControlSet\Services\NPF\Start
The key (REG_DWORD) may be one of the following values:
 0x0000001 (Disabled, the service is never running)

 0x0000002 (Manual, the service is started on manual intervention)
 0x0000003 (System, the service is started automatically on request)
By default this key is set to 0x00000003 and the service is started automatically on request by CTCI-W32.

8. Installing the Hercules Emulator
8.1 Downloading the Binaries

The "ready-to-run" binaries can be downloaded from http://www.hercules-390.org. For Windows users
there are currently two varieties available:
 MSVC Windows installer package (filename "hercules-v.rr-native.msi")
 MSVC self-extracting archive (filename "hercules-v.rr-native.exe")
Where ‘v.rr’ in the filename specifies the version and release of the Hercules Emulator contained and
‘xxxx’ in the Cygwin version specifies the CPU type for which the package has been built.
The difference between these binaries and how each is installed are described in the following sections.
8.2 Choosing a Package

Which of these packages is the right one for you depends on your needs. The former Cygwin package is
no longer available because since Hercules release 3.03.0 Cygwin is no longer a pre-requisite.
The new MSVC packages, the self-extracting archive (.exe) and the Windows installer package (.msi),
are very similar. The main difference being that the Windows installer package provides the standard
Windows installation dialog for both installation and removal of the emulator. The Windows installer
package also creates Start Menu entries for both the documentation and to start the DOS command
prompt in the Hercules binary directory.
Some people want to have the full control over the whole installation process and therefore prefer the
self-extracting archive (.exe). On the other hand however, some people prefer to have a simple instal-
lation routine, similar to other Windows software packages.
Note: Installing the .msi Windows Installer package ensures the required Microsoft Runtime components
are installed and also provides convenience shortcuts in the programs menu. If the required components
are already present and the shortcuts are not needed on the target system, the self-extracting or .zip
archive may be used instead. The required component for this build is the x86 version of the C runtime at
level 8.50727.762.
8.3 Installation Steps (MSVC Windows Installer Package)

The "MSVC Windows Installer Package" is a standard Windows installation dialog as used for most Win-
dows application installations. Using this method the 'C' runtime library files are installed if needed in a
separate directory structure under the Windows system directory (i.e. "%windir%\WinSxS").
This new Windows technique (SxS means "Side by Side") allows multiple versions of the same DLL to
coexist in the same system. For example should application “A” need foobar.dll version 1.12 and appli-
cation “B” needs foobar.dll version 1.14, both DLLs can coexist in the same system.

To start the installation dialog run the .MSI executable file. A welcome window is presented first.
Figure 21: Welcome Window (MSVC Installer Package)
Clicking on "Next" continues the installation process.

Now a license agreement window is presented. It explains in detail the "Q Public License". Please read
the license agreement.
Figure 22: License Agreement (MSVC Installer Package)
After reading the license agreement if you accept the terms confirm this using the radio button "I agree"
then click on "Next" to continue with the installation.

The next window lets you specify the installation folder. You can use the default or specify any directory
of your choice.
Figure 23: Installation Directory Selection (MSVC Installer Package)
If you plan to run different Hercules versions in parallel then the default naming convention which con-
tains the version and release levels in the directory name is useful. If your intention is to run one Hercules
version at a time then you may prefer to shorten the directory name to simply "hercules" as in the
example above.

Before installing the package you can examine your available disk space by clicking on the button "Disk
Cost". This will display all available disk partitions on which Hercules can be installed and shows the disk
space before and after installing the package. Hercules itself, without a mainframe operating system
installed, uses approximately 11 MB of disk space.
Figure 24: Disk Space Information (MSVC Installer Package)
When you are satisfied with the installation options, click on "OK".

A confirmation dialog is presented, this is a final opportunity to change any of your selections made in the
previous screens.
Figure 25: Installation Confirmation (MSVC Installer Package)
If you do not want to change any of your choices, click on "Next >" to start the actual installation process.

The installer now begins to copy files to the destination directories.
Figure 26: Installation Progress Bar (MSVC Installer Package)
If necessary the process of copying files can be stopped by clicking on "Cancel".

After a few seconds the installation process will finish and present the final window.
Figure 27: Installation Complete (MSVC Installer Package)
Click on "Close" to terminate the installation dialog and proceed to customise your installation as de-
scribed in the following sections.
8.4 Installation Steps (MSVC Self-Extracting Archive)

The MSVC native version of the Hercules Emulator is delivered as a self-extracting archive. In this
archive the binaries and all other necessary files (e.g. html files etc.) are placed in a predefined directory
structure required to run Hercules.
The self-extracting .exe does not invoke the Windows installer therefore will not install the "Microsoft
Visual Studio 8 'C' Runtime Library" as a system file. Instead a technique is used where the 'C' runtime
DLLs are installed as a separate subdirectory of the application together with the manifest files. This is
designed to ensure that Hercules will run even if the proper 'C' runtime library is not present on the
system.
It is normal for the self-extracting archive to have a subdirectory named ‘Microsoft.VC80.CRT’ and for the
Microsoft Installer version to not have this subdirectory.
To extract the files from the archive run the executable. This will present a window where you will be
asked to specify the target directory for the installation. It is sufficient to specify only the drive letter of the
target environment as the necessary subdirectory structure is created automatically.

Figure 28: Specifying Target Directory (MSVC Self-Extracting Version)
After clicking the "Unzip" button the directories are created and files are extracted and copied to the
proper locations. Alternatively WinZip can be called to extract the files manually. When all files are copied
a confirmation window appears.
Figure 29: Confirmation Message (MSVC Self-Extracting Version)
The root directory that is created is called hercules-v.rr, where v stands for the current version and rr for
the current release. This naming convention is useful if you plan to run several Hercules versions in
parallel. If your intention is to run only one Hercules version at a time the directory can be renamed to
"hercules" without a version or release indication.
Next proceed to section 9.6 ‘Customisation Steps’ below.
8.5 Customization Steps

After the actual installation is complete there are additional customization steps required, these include:
 Creating the Hercules Configuration File
 Creating the Hercules Startup Batch File
 Creating the Hercules Run-Commands File
 Creating the Terminal Batch File
These manual customization steps are explained in detail over the following sections.

8.5.1 Creating the Hercules Configuration File
When starting the Hercules Emulator from either a DOS command line or via the Hercules Windows GUI,
you may specify the name of a configuration file as a parameter:
HERCULES [ -f filename ] …
HERCGUI [ -f filename ] …
where filename is the name of the configuration file. The default filename if none is specified during the
startup is ‘hercules.cnf’. The name of the default configuration file may be overridden via the environment
variable HERCULES_CNF.
The configuration file is an ASCII text file that is used to describe the processor definition, the device
layout and any runtime parameters. Details of the format and acceptable directives that can be made
within the file are found in Chapter 3 of the Hercules User Reference Guide.
8.5.2 Creating the Hercules Startup Batch File

Although the Hercules Emulator can be started manually from a DOS command prompt it is often easier
to establish a batch file to do this. The batch file can then be executed by double-clicking it from Windows
Explorer, called directly from a DOS command prompt window or it can be integrated as a shortcut into
the Windows start menu or desktop.
8.5.2.1 Hercules Startup Batch File

The following figure shows an example of a Hercules startup batch file using the native Hercules console.
@ECHO OFF
REM
REM **************************************************************************************
REM CHECK / SET HERCULES PATH (1)
REM **************************************************************************************
REM
IF %SETHERC%.==1. GOTO RUNIT
SET SETHERC=1
PATH D:\Hercules;%PATH%
SET HERCULES_RC=D:\MVS\CONF\HERCULES.RC
:RUNIT
REM
REM **************************************************************************************
REM START HERCULES EMULATOR (2)
REM **************************************************************************************
REM
START D:\Hercules\Hercules -f D:/MVS/CONF/MVS38J.CONF >D:\MVS\LOG\Hercules_Log.txt
EXIT
Figure 30: Hercules Startup Batch File
This example batch file contains two main sections:

(1) In the first section a check is made to determine if the path to the Hercules binaries has already
been set. If so, then the rest of the first section is skipped. If not, then the path to the Hercules

binaries is set and the environment variable %SETHERC% is set to ‘1’ to indicate that the path
has been successfully set.
(2) In the second section the Hercules Emulator is started with a configuration file located in a direc-
tory other than the emulator itself. Additionally the path and filename for the log file is set.
8.5.2.2 Hercules Windows GUI Startup Batch File

The following figure shows an example of a Hercules startup batch file using the Hercules Windows GUI.
@ECHO OFF
REM
REM **************************************************************************************
REM CHECK / SET HERCULES PATH (1)
REM **************************************************************************************
REM
IF %SETHERC%.==1. GOTO RUNIT
SET SETHERC=1
PATH D:\Hercules;%PATH%
SET HERCULES_RC=D:\MVS\CONF\HERCULES.RC
:RUNIT
REM
REM **************************************************************************************
REM START HERCULES WIN GUI AND HERCULES EMULATOR (2)
REM **************************************************************************************
REM
START D:\Hercules\HercGui -f D:/MVS/CONF/MVS38J.CONF
EXIT
Figure 31: Hercules Windows GUI Startup Batch File
This example batch file contains two main sections:

(1) In the first section a check is make to determine if the path to the Hercules binaries has been al-
ready set. If so, then the rest of the first section is skipped. If not, then the path to the Hercules
binaries is set and the environment variable %SETHERC% is set to ‘1’ to indicate that the path
has been successfully set.
(2) In the second section the Hercules Windows GUI is started which will in turn start the Hercules
Emulator, using a configuration file located in a separate directory to the emulator itself.
Differently to the first example above, the filename and path of the log file are not given as a
parameter to the Windows GUI, rather they are configured within the GUI itself.
8.5.3 Creating the Hercules Run-Command File

Hercules also provides the ability to automatically execute Hercules panel commands after startup via the
'run-commands' file. If the run-commands file exists when Hercules starts, each line contained in the file
is read and interpreted as panel command.
In the following example file the Windows telnet program is started in a shell, all currently valid Hercules
panel commands are displayed and MAXRATES is reset. Finally a couple of tn3270 sessions for con-
soles and TSO terminals are started.

sh startgui telnet localhost 3270
?
maxrates
sh startgui C:\Programs\Vista32\vista32.exe MVS_MST.ses
pause 3
sh startgui C:\Programs\Vista32\vista32.exe MVS_OPR.ses
pause 3
sh startgui C:\Programs\Vista32\vista32.exe MVS_TSO.ses
pause 3
pause 3
Figure 32: Hercules Run-Commands File
If the "sh" (shell) command is used in the run-commands file, then the "startgui" keyword should also be
used when starting external applications if one of the following is true:
a) If starting Windows GUI applications (as opposed to command-line programs),
regardless whether or not the Hercules Windows GUI is being used.
b) If starting any program, Windows GUI programs or command-line programs (either via
the Hercules panel command-line or via the run-commands file), when running Hercules
via the Hercules Windows GUI.*
* If you wish to capture the output of a shell command however (e.g. "sh dir"), then you should not use
startgui since it prevents the output from being captured / piped back to Hercules or the Hercules
Windows GUI.
Creative use of the run-commands file can completely automate Hercules startup and initiate the IPL of
the mainframe operating system. For details about the usage of the run-commands file see the "Hercules
User Reference Guide".
8.5.4 Creating the Terminal Batch File

When the Hercules Emulator is been started using one of the previously described batch files, terminals
(consoles and terminals) must then be connected. If they are not automatically started via the rc-file as
described in the section above, the easiest way to do this is also with a separate batch file, which can
start several instances of a terminal emulation program.
In the example file below several terminals are connected to the Hercules emulator using tn3270 emu-
lation software "Vista tn3270" from Tom Brennan. The initiation of terminal connections to Hercules is
particular to the 3270 emulator you chose to use – consult the documentation of your emulator software
for these details.

@ECHO OFF
REM
REM **********************************************************************
REM Start master console (0700) and wait for connection to Hercules (1)
REM **********************************************************************
REM
START "C:\PROGRAMS\VISTA32\VISTA32.EXE C:\PROGRAMS\VISTA32\MVS_MST.SES"
PAUSE 2
REM
REM **********************************************************************
REM Start operator console (0701) and wait for connection to Hercules (2)
REM **********************************************************************
REM
START "C:\PROGRAMS\VISTA32\VISTA32.EXE C:\PROGRAMS\VISTA32\MVS_OPR.SES"
PAUSE 2
REM
REM **********************************************************************
REM Start TSO terminals (0702-0704) and wait for connection to Hercules (3)
REM **********************************************************************
REM
START "C:\PROGRAMS\VISTA32\VISTA32.EXE C:\PROGRAMS\VISTA32\MVS_TSO.SES"
PAUSE 2
PAUSE 2
EXIT
Figure 33: Terminal Batch File
This example terminal batch file contains three sections:

(1) Connecting the master console
(2) Connecting the alternate (operator) console
(3) Connecting the TSO terminals
Generally these three sections are identical except for the session profile used. The number of terminals
to be started depends on your needs although it is recommended that at least three terminal sessions
(master console, alternate console and TSO terminal) be started.
The WAIT command is used to define a one second delay and helps ensure that the terminal sessions
connect in the correct sequence to the intended addresses. The length of this wait interval depends on
the speed of the host system CPU and should be changed to a value appropriate for your environment.
You may need to experiment with this setting in order to discover an appropriate value.

9. Installing the Hercules Windows GUI

The Hercules Windows GUI can be downloaded from www.softdevlabs.com. Several other programs
from the developer (David B. Trout, aka ‘Fish’) require a custom DLL, FishLib.dll, it may be appropriate to
download the FishLib package as well.
The GUI also requires some Microsoft Foundation Classes (MFC) and C runtime DLLs (MFC42.DLL,
MSVCRT.DLL, MSVCP60.DLL and DbgHelp.DLL). It is possible that these DLLs are already present in
the Windows system directory. If not though, they must be downloaded and copied to the Windows sys-
tem directory. These DDLs are all available from www.softdevlabs.com.
The source code for the Hercules Windows GUI is no longer available due to current efforts to commer-
cialise this product.
Note: Beginning with release 1.11.1.5265 of the Windows GUI additional DLLs are required. These are
Microsoft MFC and VC Runtime DLLs that you can download from the address mentioned above. The
installation takes a few seconds and does not require a reboot. There are a 32-bit and a 64-bit version of
these DLLs. Please ensure you are using the correct one according to the product you are installing (32-
bit or 64-bit version of the Windows GUI).
These DLLs are normally automatically installed as part of a standard Microsoft Installer program (.msi),
however as the Windows GUI does not have an installer program you will need to do this manually. Note
that you only need to install these C Runtime DLLs once even if new versions of HercGUI are subse-
quently installed.
9.2 Installation Steps

The installation involves simply unzipping the executables into the directory where the Hercules exe-
cutables reside. No other installation steps are required. Uninstalling is the reverse, just delete the files.
On its first startup the Hercules Windows GUI adds a new key to the Windows registry to hold some con-
figuration settings. To completely remove all trace of the GUI you must manually delete this key using a
registry editor such as the Microsoft "regedit" utility.
The Hercules Windows GUI uses the following registry key:
"HKEY_CURRENT_USER/Software/Software Development Laboratories/Hercules"

The first time the Hercules Windows GUI is started it will open the Preferences dialog. Completing this
dialog is the only customization required, it adds necessary information (e.g. directory names) required for
the GUI to operate.
The following topics describe the various dialogs in detail. Please note that this installation section de-
scribes many of the tasks involved in the use of the GUI in preference to separating this information into
the Hercules User Reference Manual.

9.4 Main Screen
The various panels of the main screen can be re-located to suit the user's preferences. The device list bar
can be docked on either side of the screen and the various status bars at either the top or bottom of the
screen. You can float them in a window by themselves or you can hide them altogether.
To do this just grab the panel using your mouse and drag it to your preferred location. The screen layout
is remembered across sessions. If you place the controls panel at the bottom of the screen, then it will be
in the same place the next time you start Hercules.
Figure 34: Hercules Windows GUI Main Panel
Since version 1.9.5 the Hercules Windows GUI allows you to specify the target directory that the 'sh'
(shell) command will use. Simply browse to and select the desired directory using the GUI.
Once this is set any shell command entered will be processed using the defined directory as its current
working directory. This provides a workaround for the fact that the Windows GUI's current directory
changes depending on the dialog in use. This also compensates for the fact that prior to version 3.03
Hercules's current directory normally never changes.

9.5 Preferences
The Preferences dialog is where directories, file extensions, logging options etc are defined. The following
subtopics describe each of the Preferences tabs in detail.
9.5.1 Directories
The Directories tab allows you to specify the preferred directories for each file type.
Figure 35: Preferences Directory Tab
The path for executable files, configuration files and log files are all required, all others are optional and
provided for convenience. If specified, they are used as default directories by the various device configu-
ration dialogs.

9.5.2 File Extensions
The File Extensions tab allows you to specify the preferred file extensions used in the "Files of type"
dropdown list in all standard 'Open' and 'Save as' dialog boxes that the Hercules Windows GUI uses.
Figure 36: Preferences Extensions Tab
This feature allows each user to have different naming conventions for their reader, punch and disk files
etc.

9.5.3 Logging
The Logging tab allows you to specify the preferred console logging options.
Figure 37: Preferences Logging Tab
The 'At Startup' option requests the filename of the console log file when the GUI is started. The 'At
Shutdown' option asks if the console log file should be saved or not when the GUI is about to be closed.
The 'Automatic' option does not ask for a filename at all and instead generates a filename automatically
based on the parameters provided. For example, if the base filename is "Hercules Logfile.txt" the gene-
rated log filename will be "Hercules Logfile.000.txt" the first time the GUI is started, then "Hercules Log-
file.001.txt" for the next start of the GUI, etc.
Starting with version 1.4.0, once log files are created by whichever method, they are written to con-
tinuously as new messages arrive. This removes the need to do a periodic "Save Messages".
As new messages are now automatically written to the log file during Hercules execution, it is recom-
mended to use the "Advanced Logging Options" dialog to specify the maximum log file size in number of
lines. This is meant to prevent the log file from filling up your hard drive. Use the ‘Advanced’ button on
the main Logging preferences tab to access these settings.

Figure 38: Advanced Logging Options Memory Tab
Figure 39: Advanced Logging Options Disk Tab

Figure 40: Advanced Logging Options Format Tab
The log file is a wrap-around file, where the oldest messages will be overwritten by newer messages
when the specified size limit has been reached. Once the specified maximum number of lines has been
written to the log file, the GUI will reset its file position pointer back to the beginning of the file and begin
writing new log file messages over the top of older ones.
The file is not recreated when full. When it wraps around and begins to overlay older messages, the mes-
sages near the end of the log file are still present until eventually overwritten.
Note too that the Advanced Logging Options dialog lets you specify the maximum number of messages to
be retained in memory. A limit is required to prevent run-away memory consumption. This memory limit is
a separate value from the disk log file limit and essentially controls how far back you can scroll the con-
sole to see older messages.
9.5.4 Console
The Console Tab allows it to specify the preferred console font, font colour and background colour for the
Hercules console message area.

Figure 41: Preferences Console Tab
Simply click on the appropriate button and select the font or color. Your selection will then be reflected in
the sample edit-box to let you see what the console would actually look like before your changes are
applied.
9.5.5 Misc
The Misc Tab allows you to specify various miscellaneous preferences, such as how the GUI should react
to your pressing the "Power Off" button.

Figure 42: Preferences Misc Tab
When shell command support was added to Hercules for the Windows environment a bug was revealed
in the manner that Cygwin processed the 'fork' command. Although a workaround was developed the
GUI was also modified to be able to issue the shell commands directly instead.
In order for the GUI to be able to issue shell commands instead of Hercules itself a new program called
'conspawn.exe' was developed. The GUI passes the shell command to conspawn for execution. The
conspawn program is included as part of the GUI package and must reside in the same directory as the
other Hercules executables.
The Ignore Parse Errors option was created to allow you to open and use a Hercules control file that the
GUI would otherwise fail to parse properly for whatever reason.
When a control file is opened the GUI parses the statements and saves the information in an internal con-
trol area. This information is used later to complete various fields in the dialogs such as the device con-
figuration dialog. If the GUI cannot properly parse a given control file statement it throws a parse error
and prevents you from opening or using what it considers to be a bad control file. This option can be used
to bypass this error, for example when using a device statement containing a new parameter that Her-
cules understands but the GUI may not yet support.
The "Ignore Parse Errors" option instructs the GUI to ignore the parse error and open and use the control
file anyway. When this option is set the GUI ignores all parse errors and will always successfully open
whatever control file you instruct it to. As the GUI can update the Hercules control file, it is highly recom-

mended that you leave this option disabled and enable it only when needed to avoid accidentally
damaging a file that may not contain valid Hercules control specifications.
If you do need to enable this option, remember to disable it when no longer needed as once enabled it
will stay that way until you purposely disable it. Like all preference options it is persistent across
executions of the GUI.
9.5.6 Misc2
The Misc2 Tab provides additional options that would not fit on the original Misc options tab.
Figure 43: Preferences Misc2 Tab
Since version 3.0 of Hercules support has been added for command-line options beyond the existing -f
(control file) option. Here you can enter any of the new command-line options you may wish to have
issued whenever the GUI starts up ("Powers On") the Hercules emulator.
Note that you must not specify the -f option here. The GUI constructs the -f option automatically based on
the configuration file previously defined in the Preferences dialog. You may enter any other command-line
options in addition to the required ones - see the important note immediately below.

You must specify here either "EXTERNALGUI" (without quotes) or – starting with Hercules Ver-
sion 3.0 – a new command line option "-d -l dyngui". This option must not be left blank. If you
accidentally leave this option blank it is possible that both Hercules and the GUI will not operate
at all and highly likely that they will not operate as expected.
This is an advanced option and should not be modified by end users. Please only change this if instructed
to by Hercules Technical Support or Hercules developers.
9.6 System Configuration

When a Hercules control file is opened by the GUI it is parsed and then a "System Configuration" dialog
is displayed showing the various configuration settings.
Since HercGUI version 1.9.5 the System Configuration dialog information is displayed in three separate
property pages: the Architecture page, the O/S Tailor settings page and the Other / Misc page.
The Identification section simply displays the full pathname of the configuration file that was opened and
provides an input field for a text description to be associated with this particular configuration file. This is
in case you have multiple system configurations where it is useful to have some indication that you are
modifying the correct one. The description you enter here is saved as a comment at the beginning of the
configuration file.
9.6.1 Architecture Settings

This page of the System Configuration dialog is where you define various hardware and architectural
settings, e.g. how many emulated CPUs, how much emulated main storage etc.
The Architecture radio buttons allow you to define the default architectural mode your emulated CPUs will
be initially started in. For emulated z/Architecture machines the actual IPL takes place in ESA/390 mode
and it is the responsibility of the IPL'ed operating system to switch the CPU(s) into z/Architecture mode
when it is ready to use this mode. It does this using the SIGP instruction.
The following figure shows the Architecture Settings tab.

Figure 44: Architecture Settings Tab
In the main System Configuration dialog, if the GUI finds a specially formatted file called "cpu-types.txt" in
your preferred configuration files directory, a small '>' button will appear next to the "CPU Model number"
edit-box. This file may contain a list of the various CPU model numbers, their names and their correspon-
ding STIDP (Store CPU ID instruction) values.
When the System Configuration dialog is initialized, if the GUI finds this file, it will parse the entries and
use them to construct a drop-down box that will be displayed when you click the '>' button. This allows
you to easily select the desired CPU Model you wish your virtual mainframe to be reported as.
Neither the GUI nor the Hercules Emulator itself makes any attempt to try and emulate all aspects or fea-
tures of a given CPU model. This CPU model number simply specifies what value to use in the STIDP
(Store CPU ID) instruction.
When your CPU Model is selected in this way the GUI automatically fills in the "CPU Model number" edit-
box field with the corresponding value it finds in the "cpu-types" file. You have the option of manually
overriding this value. A sample "cpu-types" text file is included with the distribution of the Hercules GUI.

9.6.2 O/S Tailor Settings
The O/S Tailor settings page is where you can establish certain settings related to the type of guest ope-
rating system you intend to actually run on your virtual mainframe. The purpose of the O/S Tailor radio
buttons is to limit the amount of Hercules generated message traffic by selectively suppressing certain
program check and trace type messages which are considered normal for the specified operating system.
Figure 45: O/S Tailor Settings Tab
When the "Enable licensed program product O/S" option is specified for a given control file any attempt to
power on Hercules using that control file will result in a dialog box being displayed that asks you to verify
your true intentions.

Figure 46: PGMPRDOS LICENSED Acknowledgment
As soon as this dialog is displayed a 10-minute timer is started. If you respond before the timer expires
your response is accepted as-is. If your response is "No, I do NOT honestly wish to run in unrestricted
mode" then your virtual mainframe will not be powered on. If your response is "Yes" - whether explicit or
presumed (see next paragraph) - then Hercules will be powered on.
Please note that if you fail to respond within the 10-minute time limit your response is presumed to be
"Yes, I honestly DO wish to run in unrestricted mode". If you do not wish to wait the entire 10 minutes
then you will have to respond to the dialog manually yourself. There is no way to disable or override this
feature.
This dialog is displayed each time you attempt to power on Hercules during a given Hercules GUI session
when using a configuration file with the "Enable licensed program product O/S" option checked. Although
you only have to respond to this message once during a single session if you continue to use the same
configuration file. If you switch to a different configuration file and then return later to the first one (or exit
the GUI entirely and start it again), you will be asked once again to confirm your intent.
9.6.3 Other / Misc Settings

The "Other / Misc" window allows you to define more system configuration values, mostly related the in-
ternal functioning of the Hercules emulator. Please refer to the documentation for the Hercules emulator
itself for more information regarding the various values that may be specified here.

Figure 47: Other / Misc Tab
Hercules's HTTP Server support allows you to control Hercules via any standards compliant web
browser. This dialog allows you to define the HTTP Server parameters that Hercules is to use.
Figure 48: HTTP Server Parameters
Enter the port number for Hercules's HTTP Server to listen on and if desired specify the authentication
criteria needed to connect to the server. You can also enter the root directory from which the web pages
will be served.

If you enter a userid for authentication then you must also enter a password. If no userid and password
are entered then anyone with a browser that is able to connect to your Windows host system will be able
to control your Hercules system via the HTTP Server interface. The password you enter is not encrypted
in any way and is stored in your Hercules control file, as well as passed through the network, in unencryp-
ted plain text format. You should therefore take whatever steps are required to secure Hercules control
file(s) that contain HTTP Server passwords.
Since Hercules version 2.17 the behavior Compressed CKD DASD (CCKD) functionality is controlled via
the setting of certain global parameters. CCKD functionality is no longer adjustable on an individual
device-by-device basis.
Figure 49: CCKD Parameters
9.6.4 Advanced Settings

The Advanced configuration page is where settings for features that are intended only for more advanced
users may be made. If you have a custom dynamic module (DLL) you wish Hercules to use or wish to
modify Hercules's default priority settings you would do that here.
Please see the “Hercules User Reference Guide” for more details on the options presented here.

Figure 50: Advanced Tab
9.7 Device Settings

Clicking the "Devices" button from the System Configuration dialog or selecting "Modify Devices" from the
File menu will take you to the Device Configuration dialog. From here you can add, delete or modify the
devices in the current configuration.
This particular dialog is resizable as device configuration statements can be quite long.

Figure 51: Device Configuration
The "Maximum shutdown wait time expected for this configuration" setting defines a time limit to the
Hercules GUI. This limit is the amount of time the GUI is to expect between when the 'quit' command is
issued (or the "Power Off" button is pressed) and when Hercules finally finishes exiting after completing
its shutdown sequence.
When you use compressed disks (CCKD) Hercules needs time to write-back cached copies of track ima-
ges and adjust the free space for each disk before it can safely exit. If the expected wait time is exceeded
the GUI issues a warning asking whether to continue waiting or forcibly terminate the Hercules Emulator
process. If many compressed disks are frequently updated it can take over a minute to write all cached
data to disk.
It is safe to specify a value for this setting that is high enough for all likely cases in your environment. The
Hercules GUI will terminate as soon as Hercules itself ends regardless of the wait time setting.
Right clicking on a device statement presents a context menu from which you can select 'Edit' or 'Proper-
ties'. Selecting 'Properties' presents the "Reinitialize Device" dialog, also displayed by double-clicking the
device statement.
When 'Edit' is selected from the right-click context menu you are presented with a simple device state-
ment edit dialog. From here you can directly modify raw device statements.
Figure 52: Edit Device Configuration Statement
To add a new device, click on one of the 'Add' buttons:

Figure 53: Add New Device
To delete a device select the desired device first to highlight it and then click on the 'Remove' button. To
modify an existing device double-click on the entry for the desired device:

Figure 54: Reinitialize Device
Note: If you used any of the new CCKD parameters on the main System Configuration dialog, some
controls in the above dialog will not be displayed. This occurs because the new System Configuration
CCKD parameters modify CCKD functionality on a system-wide basis and remove the ability to specify
these parameters on per-device basis.
9.8 Display / Alter Memory

The "Display / Alter Memory" item in the command menu allows you to display or modify absolute main
storage.
It is very important that you keep in mind that when you alter absolute main storage via this dialog then
neither the storage keys nor the CPU instruction and data caches are updated in the Hercules emulator
itself. Instead the memory of the Hercules emulated operating system is directly modified without the
Hercules Emulator knowing of this.
Please use this feature with caution. It is designed for examining and searching main storage for emulator
debugging purposes and not as a safe means of modifying hosted operating system storage.
The following figure shows the "Display / Alter Memory" dialog.

Figure 55: Display / Alter Memory Dialog
If you need to modify real or virtual storage it is highly recommended that you use the Hercules Emulator
'r' and 'v' panel commands. These ensure that the hardware emulator is aware of any changes.
9.9 Load Card Reader, Load Tape, Unload Tape

These menu items provide a quick and easy way to do just as their descriptions suggest. The 'Load
Reader' command is provides an interface to submit jobs to the system. It displays the "Re-Initialize
Device" dialog for the card reader. From here you can use standard Windows 'Open File' dialogs to
browse for a file that you want to submit. The selected file will be loaded into the card reader. Clicking OK
issues the appropriate Hercules devinit panel command.

Figure 56: Reinitialize Card Reader Dialog
The "input data is from socket" option is found to the right of the device type field. It allows you to tell
Hercules to obtain card reader input from a specified socket instead of a disk file as by default. This
allows you to submit card decks remotely using a simple utility that connects to the specified socket and
writes card images directly to Hercules. Recent releases of the GUI provide a DOS program "HercRdr" to
support this capability. For more information on the HercRdr utility and the 'sockdev' option refer to the
Hercules User Reference Guide.
9.10 Device List Bar

The "Device List" bar, similarly to its non-GUI console mode counterpart, lists the devices in the current
configuration and their status.

Figure 57: Device List Bar
A grey diode indicates the device is offline and not open. A green diode indicates it is online or open. The
green diode changes to yellow whenever the device is busy and changes to red when there is an interrupt
pending for the device.
As the hosted system runs and performs I/O to the devices in your configuration you will see the diodes
change between yellow, red and green. This shows that there is I/O activity taking place on the device.
Devices are displayed in a tree-list with a branch for each class of device. Right-clicking the Devices with-
in a branch presents a context sensitive menu. You can also right-click each branch.
To add a new disk drive to your configuration right-click on the "DASD Devices" branch and select 'Add
device' from the menu that appears. To delete ("detach"), rename ("define"), reinitialize ("devinit") or pre-
sent an attention interrupt ("i") for a particular device, right-click the device and select the appropriate
option from the context menu presented.

9.11 Utilities Menu
All of the Hercules utility programs can be run by completing the appropriate dialog. Both Hercules and
these utilities run as separate processes, so it is possible to run more than one utility at the same time as
Hercules images.
A progress dialog is displayed as each utility runs, all messages generated by the utility are displayed on
the GUI console just as Hercules messages are. Each message is prefixed with its process ID to differen-
tiate between utility program messages and a timestamp.
The following figures show an example of the DASDINIT utility window.
Figure 58: DASDINIT Utility Window
9.12 Registry Tweaks

Some of Hercules minimum, maximum and default values used by the GUI are stored in the windows
registry. The following table shows the valid values.
Apart from the "MinTODDrag" and "MaxTODDrag" which are string values, all of the values below are
DWORD values and are stored in the "Limits" branch of the main Hercules Windows GUI registry key:
"HKEY_CURRENT_USER/Software/Software Development Laboratories/Hercules/Limits"

Note that changing the values of these registry entries will not necessarily change the actual function of
the Hercules Emulator. If the GUI accepts the new value this does not necessarily mean that Hercules
itself will accept the value.
Name Default Description
MaxCPUs 32 Maximum allowable number of central processors
MaxVectors 4 Maximum allowable number of vector facilities
MaxMainMem 2048 Maximum allowable amount of central storage (MB)
MaxExpandedMem 1024 Maximum allowable amount of expanded storage (MB)
MinEpoch 1801 Minimum allowable clock epoch year
MaxEpoch 2099 Maximum allowable clock epoch year
MinPanRate 10 Minimum allowable panel refresh rate (milliseconds)
MaxPanRate 5000 Maximum allowable panel refresh rate (milliseconds)
MaxTapeSizeMB 2048 Maximum allowable emulated tape size (MB)
MaxEOTMarginKB 2048 Maximum allowable emulated tape 'end-of-tape warning

area' margin-size (KB)
MaxECPSVMLevel 99 Maximum allowable ECPSVM value
DefECPSVMLevel 20 Default ECPSVM value
MinTODDrag 0.0001 Minimum allowable TOD clock drag factor
MaxTODDrag 10000 Maximum allowable TOD clock drag factor
MinCCKDgcparm -8 Minimum allowable CCKD parameters garbage- collection

aggressiveness level
MaxCCKDgcparm +8 Maximum allowable CCKD parameters garbage- collection

DefCCKDgcparm 0 Default CCKD parameters garbage- collection

MaxCCKDfreepend 4 Maximum allowable CCKD freespace pending interval

value
DefCCKDfreepend -1 Default CCKD freespace pending interval value
MaxCCKDrat 16 Maximum allowable CCKD read-ahead tracks
DefCCKDrat 2 Default CCKD read-ahead tracks
MaxCCKDraq 16 Maximum allowable CCKD read-ahead queue size

Name Default Description
DefCKDraq 4 Default CCKD read-ahead queue size
MaxCCKDra 9 Maximum allowable CCKD read-ahead threads
DefCCKDra 2 Default CCKD read-ahead threads
MaxCCKDwr 9 Maximum allowable CCKD writer threads
DefCCKDwr 2 Default CCKD writer threads
MaxCCKDgcint 60 Maximum allowable CCKD garbage-collection interval

(seconds)
DefCCKDgcint 5 Default CCKD garbage-collection interval (seconds)
MaxCCKDtrace 200000 Maximum allowable CCKD trace table size (number of

entries)
DefCCKDtrace 0 Default CCKD trace table size (number of entries)
MaxCCKDcache 64 Maximum allowable CCKD cache size (MB)
MaxCCKDl2cache 2048 Maximum allowable CCKD level-2 cache size (MB)
MeterThreadRate 1000 CPU percent utilization meter update interval

(milliseconds)
NagleThreadNagleRate 75 Maximum 'continue buffering' (to prevent screen refresh)

message reception rate (milliseconds)
NagleThreadMaxNagleRate 375 Maximum allowable delay before displaying buffered

messages (milliseconds)
MinCaptureBuffsize 64 Minimum allowable TunTap32 WinPcap device driver

capture buffer size (KB)
MaxCaptureBuffsize 16384 Maximum allowable TunTap32 WinPcap device driver

capture buffer size (KB)
DefCaptureBuffsize 1024 Default TunTap32 WinPcap device driver capture buffer

size (KB)
MinPacketBuffsize 16 Minimum allowable TunTap32 DLL I/O buffer size (KB)
MaxPacketBuffsize 1024 Maximum allowable TunTap32 DLL I/O buffer size (KB)
DefPacketBuffsize 64 Default TunTap32 DLL I/O buffer size (KB)
Table 16: Hercules Windows GUI Registry Keys

10. Installation of CTCI-W32

The CTCI-W32 components can be downloaded from http://www.softdevlabs.com. Two packages are
required, CTCI-W32 and FishLib.
CTCI-W32 consists of FishPack.dll, TunTap32.dll and TT32Test.exe packaged together as one product.
The FishLib package is required with all recent versions of Fish's software. It contains common routines
used throughout the packages.
Note: Beginning with release 3.2.1.160 of CTCI-W32 additional DLLs are required. These are Microsoft
MFC and VC Runtime DLLs that you can download from the address mentioned above. The installation
takes a few seconds and does not require a reboot. There are a 32-bit and a 64-bit version of these DLLs.
Please ensure you are using the correct one according to the product you are installing (32-bit or 64-bit
version of the Windows GUI).
If you previously installed the Hercules Windows GUI as described earlier in this manual then these DLLs
are already present on your system. Note that you only need to install these C Runtime DLLs once even if
new versions of CTCI-W32 are subsequently installed.

The installation of the CTCI-W32 packages is straightforward. Unzip the executables and DLLs from the
downloaded ZIP files into the same directory as the Hercules executables and the installation is complete.

The customization of the CTCI-W32 consists of three major steps described further below:
 Configuring Windows Networking
 Configuring Hercules
 Configuring the Guest Operating Systems TCP/IP Settings
For details on how CTCI-W32 works internally see the Hercules "General Information" manual.
10.3.1 Configuring Windows Networking

Only minor configuration of Windows networking is required in order to use CTCI-W32, beginning with
WinPcap (see chapter 7). Next verify that the network adapter has an IP address assigned and default
gateway assigned. In most installations this will already be the case and no further configuration will be
required.
If you are using DHCP rather than assigning a static IP address to the network card, then it will be neces-
sary to tell Hercules the exact hardware (MAC) address of the network adapter Hercules is to use. See
section "Configuring Hercules" below for further information.

To verify the IP address of your network interface open the network card properties and double-click on
the "Internet Protocol (TCP/IP)" component. The following properties dialog will appear:
Figure 59: Windows TCP/IP Properties
Make sure you have entered a valid IP address, subnet mask and default gateway. This is all that is
necessary on the Windows system side, the remaining configuration of the CTCI-W32 functionality is
controlled via Hercules device statements.
10.3.1.1 IP Forwarding
You may or may not need to have "IP Forwarding" enabled on your Windows system. Whether this is
required or not depends on your use of a router within your network. If you are using a router to define
routes to hosts on your LAN, then you should not need "IP Forwarding" enabled on your Windows sys-
tem. If however your are not using a physical hardware router then you will likely need to enable IP For-
warding.
To allow your Hercules guest operating system to communicate with hosts on the LAN apart from the
host machine itself (where Hercules is running), TCP/IP requires routes to and from the Hercules hosted
operating system. This is necessary so that the Hercules virtual guest OS's packets can be properly
routed to their final destination. This is typically the role performed by a hardware router. If you do not use
a hardware router then Windows "IP Forwarding", together with appropriate ROUTE statements, will per-
form this role.

Without a router or "IP Forwarding" enabled you will only be able to communicate with your Hercules
guest OS from the same Windows computer that Hercules is running on and the hosted OS will only be
able to communicate with the Windows system it is running on.
To enable "IP Forwarding" on Windows 2000 / Windows XP, make the following registry change:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters]
"IPEnableRouter"="1"
Figure 60: Windows 2000 / XP "IP Forwarding" Registry Key
For Windows 98 / Windows ME, make the following registry change instead:
[HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\MSTCP]
"EnableRouting"="1"
Figure 61: Windows 98 / ME "IP Forwarding" Registry Key
If the "IPEnableRouter" (or "EnableRouting") registry value does not yet exist under the mentioned re-
gistry key then you will have to add it manually. Select 'New' from the 'Edit' menu and add a new DWORD
value with the indicated name.
10.3.2 Configuring Hercules

Two IP addresses must ultimately be assigned, one for the Hercules end of the link and another for the
driving system's (host systems) end of the link.
Note that the format of the Hercules configuration file statements for networking emulation has changed
from previous releases of Hercules. The older 'CTCI-W32' format has been deprecated. Please ensure
your CTC device statements are updated to use the newer 'CTCI' or 'LCS' format in order to remain com-
patible with current and future releases of Hercules. For example:
0E20 3088 CTCI 192.168.0.4 192.168.0.2

0E21 3088 CTCI 192.168.0.4 192.168.0.2
Figure 62: Sample CTCI definition for static IP addresses
The first IP address (192.168.0.4) is the IP address of your Hercules system, i.e. the guest operating sys-
tem running under Hercules. The second IP address (192.168.0.2) identifies the CTCI-W32 logic, i.e. the
network adapter that CTCI-W32 is to use in order to reach the Windows TCP/IP stack.

It is recommended that the IP address you choose for your virtual guest (like 192.168.0.4 in the above
example) is in the same subnet as your Windows host in order for CTCI-W32 to work properly. The
simplest way to approach things is to configure your guest as if it were a real system connected to your
network. Thus it would normally be assigned an IP address within the same subnet as all the other work-
stations on your LAN.
Note that it is possible to place the guest OS in a separate subnet to your Windows host if you are pre-
pared to define the proper routing entries. However it is usually a lot simpler and less problematic to de-
fine all hosts in the one IP subnet.
If your network adapter does not have a static IP address then instead of specifying an IP address as the
second parameter in the Hercules device statement, you must specify the MAC address of the adapter
you wish to use:
0E20 3088 CTCI -n 00-80-B3-E1-DF-69 192.168.0.4 0.0.0.0

0E21 3088 CTCI -n 00-80-B3-E1-DF-69 192.168.0.4 0.0.0.0
Figure 63: Sample CTCI definition for dynamic IP addresses

Note that the format of the CTCI definition statement is slightly different in this case. The ‘-n’ parameter
informs Hercules that this is a MAC address, however the parser still expects to see two IP addresses,
hence the second address is specified as a ‘dummy’ address, i.e. all zeroes. The first IP address is still
the address you have assigned to the OS hosted by Hercules.
10.3.3 Configuring the Guest Operating System TCP/IP Settings

The procedure for configuring TCP/IP on any guest operating system you plan to run under Hercules is
different for each OS. For example the procedure is completely different for z/VM than it is for z/OS. For
detailed instructions on how to configure TCPIP profiles for using a CTCI device please refer to the
appropriate operating system manuals.
A sample configuration is shown in below:
TCP/IP configuration using CTCI-W32

-----------------------------------
The following values belong in the TCP profile.
The first entry in the TCP profile is the DEVICE entry. This is the Para-
meter that defines the UCB address assigned to the interface within the MVS
environment. It is related to the LINK statement to build the TCPIP connec-
tion between the hardware and the TCPIP stack.
DEVICE CTC1 CTC E20
LINK CTC1L CTC 0 CTC1
The second entry is the HOME entry. This is where the IP address is
assigned to the device interface within the TCPIP stack. The HOME entry
connects the IP address to the hardware through the LINK defined with the
DEVICE.
HOME
192.168.0.4 CTC1L

The GATEWAY describes how the IP stack gets to the rest of the network. It
defines the physical first hop from the local interface out to the entire
network. In our example, we are defining a gateway to one physical IP
address, 192.168.0.2. 1492 is the data packet size.
GATEWAY
192.168.0.2 = CTC1L 1492 HOST
The DEFAULTNET statement instructs what path the IP stack should take to
look for address it doesn't know about. IP assumes the next hop will be
able to resolve the IP address the stack is trying to connect to.
DEFAULTNET 192.168.0.2 = CTC1L 1492 0
The final statement needed in the profile is the command to instruct TCPIP
to start the device.
START CTC1
Figure 64: Sample TCP/IP Configuration for CTCI-W32
If you wish to try using an LCS (LAN Channel Station) device instead then the following sample may be
useful. LCS can handle any Ethernet packet rather than just IP packets:
Sample regular / normal LCS device definitions
0E20-0E21 LCS -n 172.16.9.163 -m 00-00-5e-90-09-5d 172.16.9.93

-----------------------------------------------------------------
Sample LCS device definitions for Enterprise Extender
0E20-0E23 LCS -n 172.16.9.163 -o oatfile.txt

-----------------------------------------------------------------
oatfile.txt:
*********************************************************
* Dev Mode Port Entry specific information *
*********************************************************
0E20 IP 00 PRI 172.16.9.93
HWADD 00 00-00-5E-90-09-5D
0E22 IP 01 SEC 172.16.10.93
HWADD 01 00-00-5E-90-0A-5D
-----------------------------------------------------------------
Sample TCPIP PROFILE statements for Enterprise Extender
(Note: not all statements are shown)
IPCONFIG DATAGRAMFWD VARSUBNETTING SYSPLEXROUTING
DEVICE LCS1 LCS E20 AUTORESTART
LINK ETH1 ETHERNET 0 LCS1
DEVICE VDEV1 VIRTUAL 0

LINK VLINKA VIRTUAL 0 VDEV1
DEVICE IUTSAMEH MPCPTP
LINK EELINK MPCPTP IUTSAMEH
START LCS1
START IUTSAMEH
HOME
172.16.9.93 ETH1
172.16.10.93 VLINKA
BEGINROUTES
ROUTE 172.16.0.0 255.255.0.0 = ETH1 MTU 1492
ROUTE DEFAULT 172.16.13.1 ETH1 MTU 1492
ENDROUTES
PORT
12000 UDP VTAM
12001 UDP VTAM
12002 UDP VTAM
12003 UDP VTAM
12004 UDP VTAM
-----------------------------------------------------------------
(Not shown: VTAM definitions)
Figure 65: Sample LCS Configuration for CTCI-W32
10.3.3.1 Defining the Guest's Default Gateway

The correct definition of your guest operating systems default gateway depends on whether or not you
are using a real router. If you do not have a real router and are instead using the Windows "IP Forwar-
ding" (IP Routing) feature to perform routing, then your default gateway should be the physical adapter on
your Windows system that your virtual interface is using.
Alternatively if you do have a real router then your default gateway should be the IP address of your
actual router. In the sample LCS configuration immediately above 172.16.13.1 is a real network router
and thus knows how to route traffic to the other end of the guest's Enterprise Extender link. Note that, as
recommended, the guest's IP addresses (172.16.9.93 and 172.16.10.93) are within the same subnet
(255.255.0.0) as the Windows host that Hercules is running under (172.16.9.163).
10.3.4 Tweaking CTCI-W32

The CTCI-W32 protocol supports some additional tuning parameters in addition to the required para-
meters. You can adjust the size of the WinPcap kernel device driver's internal packet buffer, as well as
the size of TunTap32.dll's own packet I/O buffer to try and increase the performance of your network:
0E20 3088 CTCI -n 00-80-B3-E1-DF-69 -k 1024 -i 64 192.168.1.99 0.0.0.0

0E21 3088 CTCI -n 00-80-B3-E1-DF-69 -k 1024 -i 64 192.168.1.99 0.0.0.0
Figure 66: CTCI-W32 Tuning Parameters

The numbers 1024 and 64 in the above statements are the size of the WinPcap kernel device driver's
internal packet buffer (in KB), and the size of TunTap32 DLL's internal packet I/O buffer (in KB)
respectively. Please note that memory for WinPcap's kernel device driver's packet buffer is taken from
Windows "non-paged" memory pool (i.e. from your system's real physical memory). The size of this buffer
has a direct impact on Windows performance. If you choose a ridiculously large number here Windows
will have little memory left to work with and the overall performance of your Windows system will be
degraded.
The second number (64 in the above example) is the size in KB of the I/O buffer allocated inside the
TunTap32 DLL. This defines how much data TunTap32 will request from the device driver each time it
needs to do an I/O operation to the physical adapter and therefore how much data will be transferred from
the device driver's internal buffer to TunTap32's I/O buffer. The memory for this buffer is allocated in vir-
tual memory from the Hercules process's address space and should not impact Windows's performance
unless a ridiculously large number is specified. If too high a number is specified then Windows will likely
‘thrash’ attempting to page the entire Hercules address space and performance will be degraded.
The TunTap32 DLL passes packets to Hercules one at a time. When it runs out of packets in its internal
I/O buffer it requests more data from the WinPcap device driver via the FishPack DLL. The TunTap32 I/O
buffer size determines how much data and therefore how many packets it will receive from WinPcap for
each request.
The larger this buffer, the fewer actual I/O's TunTap32 will perform to WinPcap via FishPack, but at the
same time the longer the interval between those I/O's. This implies that the WinPcap device driver will
have to buffer its data for a longer period between less frequent I/O's. This requires a larger kernel buffer
in order to ensure that no packets are lost during periods of high network activity. Conversely, the larger
the actual I/O (i.e. the more bytes transferred per I/O), the longer each I/O takes. Although this is mea-
sured in microseconds, the delay holds up the entire Windows operating system during transfers of data
from kernel-space to a user-space. It is good to perform as little I/O as possible as these can be expen-
sive, but the benefit drops quickly if each I/O has significant impact on the overall system, so choose
these settings carefully.
Unless you are using a Gigabit or faster network it is usually best to leave these at their default settings.
The currently implemented minimum, maximum and default values are:
Buffer Type Minimum Default Maximum
WinPcap device driver capture buffer size 64 KB 1 MB 16 MB
TunTap32 DLL I/O buffer size 16 KB 64 KB 1 MB
Table 17: CTCI-W32 Buffer Sizes
If you decide to adjust these buffer size values to try and increase network throughput and performance,
you may find the Hercules "tt32stats" command useful.
The tt32stats command shows the actual tt32 statistics as shown below:
23:59:11.098 0000066C tt32 stats e20

23:59:11.098 0000066C TunTap32.dll Statistics:
23:59:11.118 0000066C Size of Kernel Hold Buffer: 1024K
23:59:11.118 0000066C Size of DLL I/O Buffer: 64K
23:59:11.128 0000066C Maximum DLL I/O Bytes Received: 2K
23:59:11.138 0000066C 7 Write Calls
23:59:11.148 0000066C 8 Write I/Os

23:59:11.148 0000066C 319 Read Calls
23:59:11.158 0000066C 259 Read I/Os
23:59:11.168 0000066C 282 Packets Read
23:59:11.168 0000066C 8 Packets Written
23:59:11.178 0000066C 38172 Bytes Read
23:59:11.178 0000066C 542 Bytes Written
23:59:11.188 0000066C 1 Internal Packets
23:59:11.198 0000066C 2 Ignored Packets
Figure 67: tt32 Statistics
If the reported "Maximum DLL I/O Bytes Received" value is identical to the value specified for the "Size of
DLL I/O Buffer", then each time TunTap32 requested more packets the WinPcap device driver had at
least a full buffer worth waiting to be delivered to TunTap32.
This generally indicates that the default buffer size is too small or that your network is extremely busy.
This would be the least common situation though. TunTap32 is rarely unable to deliver an entire buffer of
packets to Hercules before another buffer arrives unless Hercules is performing extremely poorly or your
network really is under heavy load.

11. Installation of Vista tn3270
Figure 68: Vista tn3270 Logo
11.1 Vista tn3270

Vista tn3270 is a Windows program designed to emulate IBM 3270 terminals connected to a host via an
IP. It is written by Tom Brennan, is currently available as a free 30 day trial and a perpetual license costs
approximately $30 US dollars. This emulator was created with mainframe programmers in mind and has
some unique features unavailable on even the most expensive commercial emulators.
Vista has features designed especially for programmers such as built-in multiple cut and paste buffers,
fully customizable keyboard, extensive select/copy/paste functions – especially the “SelectJCL” function
that is used to select dataset names, parameters, and similar items with a single mouse click.
Vista uses bitmapped raster fonts for the clearest text possible. There are 2 sets, "Thick" and "Thin", in 73
sizes each from 4x6 to 16x36. With so many sizes you can easily setup Vista to suit your monitor size
and terminal model preferences in either full-screen or windowed mode.
Parts of the following sections about the Vista tn3270 installation have been taken from the original Vista
tn3270 documentation with the kind permission of Tom Brennan.
11.2 Downloading the Installation Routine

The binaries for the Vista tn3270 Terminal Emulation can be downloaded directly from Tom Brennan's
Vista tn3270 webpage using the following link:
www.tombrennansoftware.com
The downloaded version of Vista tn3270 can be used for a free trial for 30 days following installation.
After this free trial period a license key must be entered for continued use of the software.
11.3 Install Vista tn3270

To start the installation process, just double-click on the downloaded executable file.

The installation welcome screen is presented:
Figure 69: Vista tn3270 – Welcome Screen
Click on "Next >" to continue the installation process.

The following screen prompts you for the installation directory. Select a destination directory of your
choice and click “Next” to continue.
Figure 70: Vista tn3270 – Select Destination Directory

The screen presented next allows you to choose the Windows Start Menu Group to which the emulator
icons should be added. The default group is usually acceptable. Click on “Next” again to continue.
Figure 71: Vista tn3270 – Select Program Group

Now the installation program is ready to copy the necessary files to your harddisk. A confirmation screen
appears where you can change your previous selections. If you do not want to change any of these click
on "Install" and the setup program begins the actual installation.
Figure 72: Vista tn3270 – Ready to Install Screen

Next the setup program installs Vista tn3270 according to your previous settings.
Figure 73: Vista tn3270 - Installation Progress

When the installation process is finished the “Setup Completed” screen will appear. You must confirm by
clicking “Finish”.
Figure 74: Vista tn3270 – Setup Completed
11.4 Activation of the Software

The Vista tn3270 software creator, Tom Brennan, allows you to try the product for 30 days. When this
period expires a licence key must to be entered to enable the product for use again. You can purchase
the product via the online purchasing system at the product website. After purchase a license key is sent
by email, normally within 24 hours.
11.5 Create Sessions

The detailed process of creating terminal emulation sessions and the impact of all possible options within
Vista tn3270 is beyond the scope of this manual. For details regarding these please refer to the printed
Vista tn3270 documentation or the online help within the product. A short introduction to creating Vista
sessions for connection to a Hercules hosted OS follows.
Start a Vista tn3270 window by clicking on "Vista" in the Vista program folder or wherever you chose to
install the product. This creates a new Vista instance and immediately opens the "Start a new Terminal
Session" dialog, where you can specify IP address and port number. If instead you click on “Vista Stan-
dard Session”, then Vista immediately attempts to connect to the last used IP address and port.

Figure 75: Vista tn3270 - New Terminal Session Dialog
The following options can be specified in this dialog:

Session File Select an existing session file or type a new name. A session file contains most
of the parameters for a session such as font size, screen colours and other
options. Multiple Vista windows can share the same session file but that each
window stores parameters when it is closed. This means that the parameters will
be set to those of the last window closed.
Host IP Name/Alias This name is usually a dot address like 206.85.100.23 or a DNS (Domain Name
Server) name, such as "tn3270.company.com". It can also be an Alias name that
points to either a DNS or dot address (see Assign Host to Alias below). IP names
and their associated port numbers are stored in the VISTA.INI file rather than the
session file so that they can be shared among sessions.
The special host name "localhost" or the IP address "127.0.0.1" means the local
machine.
IP Port Each Host IP Name has an associated IP Port number which you can change
using this field. Normally TN3270 is defined to port 23 but in some cases your
connection may need to use a different port number. This port number has to be
the same as that specified for the CNSLPORT system parameter in the Hercules
Configuration File.
If you need to logon to the same hostname using various port numbers create
multiple Alias names which point to the same host but use different ports.
Additionally you can define aliases for IP addresses. This can help you remem-
ber which host Vista is connecting to.
Delete Host This button can be used to delete the selected Host IP Name if you want to clean
up the list.
Terminal Model Vista can emulate 5 standard terminal models:
Mod 2 (24 lines by 80 columns)


User (variable up to 72 lines by 200 columns)
Assign Host to Alias Dot addresses and DNS IP names can be cryptic to look at. Instead you can type
a more descriptive name such as "P390" in the Host IP Name or Alias field then
press the Assign Host to Alias button to relate the alias name to a real DNS
name or dot address. Alias names can also provide the ability to logon to the
same hostname using different port or LU names.
TN3270E TN3270E is the default protocol for Vista connections.
LU Name When in TN3270E mode, you have the option of specifying a VTAM 8 character
LUNAME to be used when establishing the connection. If you need to logon to
the same hostname using various LU names, create multiple Alias names which
point to the same host but have different LU’s.
Connect Button When this button is pressed, Vista attempts to connect to the specified Host IP. If
all is correct Vista connects to Hercules and presents the Hercules welcome
screen. If however there is a problem you may see an error window such as the
following one:
Figure 76: Vista tn3270 - Connection Error

12. Installation of XMIT Manager
Figure 77: XMIT Manager Logo
12.1 XMIT Manager Basics

The XMIT Manager is a Windows based application that allows you to manipulate Xmit format files gene-
rated on an IBM mainframe. With XMIT Manager you can open Xmit files and view or extract both, binary
or text data contained within them. Xmit Manager will process both partitioned and sequential datasets
using a graphical interface.

The binaries for the XMIT manager can be downloaded from various locations. The most reliable and
therefore recommended source is the CBT website which can be accessed with the following link:
http://www.cbttape.org/njw/

Installation of the XMIT Manager is straight forward. First extract the ZIP-file you downloaded from the
CBT website to a directory on your harddisk. This creates some files after which you start the installation
by running the SETUP.EXE program.

The setup program first presents a screen showing the Software License Agreement.
Figure 78: XMIT Manager Setup – Software License Agreement
Read the "Software License Agreement" and accept it by clicking on “Yes”.

The destination location screen will be shown, from here choose the directory where you want the setup
program to install the software. The default location “C:\Program Files\Xmit Manager” is usually satisfac-
tory. If you wish to install the software somewhere else click on “Browse” and chose your preferred drive
and directory, or type a path directly in the panel.
Figure 79: XMIT Manager Setup – Destination Location
When you are satisfied with your choice of the installation directory click on "Next >" to continue.

The setup program will ask you to select a program folder, the default is normally acceptable.
Figure 80: XMIT Manager Setup – Select Program Folder
Click on "Next >" again to proceed with the installation.

The following screen gives you a chance to review your selections and to go back and correct any, if ne-
cessary.
Figure 81: XMIT Manager Setup – Review Settings
When you are satisfied with your installation choices, continue by clicking “Next”. The installer will start
copying files to your harddisk, creating icons and updating registry settings.

The final setup screen will then be displayed.
Figure 82: XMIT Manager Setup – Setup Complete
You can now either exit the setup program or optionally select to launch the application as you exit setup.
Click on "Finish" to complete.

13. AWS Browse
13.1 AWS Browse Basics

The AWS Browse Utility can be used to view the contents of emulated mainframe tapes (AWS and HET)
directly from the Windows desktop without having to start a mainframe operating system. There are cur-
rently two implementation of AWS browse.
The first and older one from Rob Storey is no longer supported. The second one is from David B. Trout
(Fish), which has more features and is the subject of the rest of this chapter.

The binaries for the AWS Browse utility can be downloaded from various locations. However the recom-
mended source is the developers to ensure you have the latest version. The following link leads you
directly to the download page:
http://www.softdevlabs.com/Hercules/hercgui-index.html
Note: Beginning with release 1.5.1.1805 of AWS Browse additional DLLs are required. These are Micro-
soft MFC and VC Runtime DLLs that you can download from the address mentioned above. The instal-
lation takes a few seconds and does not require a reboot. There are a 32-bit and a 64-bit version of these
DLLs. Please ensure you are using the correct one according to the product you are installing (32-bit or
64-bit version of the Windows GUI).
If you previously installed the Hercules Windows GUI as described earlier in this manual then these DLLs
are already present on your system. Note that you only need to install these C Runtime DLLs once even if
new versions of AWS Browse are subsequently installed.

Download the file called “AWSBrowse-version.zip” to your harddisk. ‘Version’ is the version number of the
utility in the form “v.r.m.b” (version.release.modification.build), i.e. AWSBrowse-1.2.0.1278.zip.
The archive contains several files; the actual AWSBrowse EXE files (32-bit and 64-bit versions) and some
DLLs. Please check the README file for the latest instructions.
Unzip these files and copy them to either your Hercules directory (see Chapter 8. Hercules Emulator
Installation) or a directory of your choice from where you wish to run the utility. Be sure to you place the
executable and the DLLs in the same directory. The Installation is now complete.
Clicking on the desired executable starts AWS Browse with the initial screen showed below.

Figure 83: AWS Browse - Initial Screen

14. Hercules “MSVC” Build Instructions
14.1 Introduction
This section provides instructions on how to build the MSVC version of Hercules. Once you have
successfully set up the build environment (which you only need to do once) the process of actually
building Hercules is very simple. Just open the provided ‘Hercules.sln’ solution file and click the ‘Build’ or
‘Rebuild All’ button.
14.2 Setting up the Hercules build environment

The overall setup and build process consists of the following steps:
1. Download and install Visual C++ 2008 Express

(http://www.microsoft.com/express/download/#webInstall).
2. Install the ZLIB package. (optional, details see below)
a. Download the package

(http://www.softdevlabs.com/Hercules/ZLIB1-1.2.3-bin-lib-inc-vc2008-x86-x64.zip).
b. Unzip to a directory of your choice.
c. Define a ZLIB_DIR environment variable pointing to the path from the previous step.
3. Install the BZIP2 package (optional, details see below).

(http://www.softdevlabs.com/Hercules/BZIP2-1.0.5-bin-lib-inc-vc2008-x86-x64.zip).
c. Define a BZIP2_DIR environment variable pointing to the path from the previous step.
4. Install the PCRE package (optional, details see below).

(http://www.softdevlabs.com/Hercules/PCRE-6.4.1-bin-lib-inc-vc2008-x86-x64.zip).
c. Define a PCRE_DIR environment variable pointing to the path from the previous step.
5. Start Visual C++ 2008 Express, open the Hercules provided “Hercules.sln” solution file and click
on the ‘Build’ or ‘Rebuild All’ button.

14.3 Setting up ZLIB Support
ZLIB is a compression algorithm written by Jean Loup Gailly and Mark Adler and may be used in the
Hercules project pursuant to the ZLIB license.
In source form the Hercules project does not contain any ZLIB source code at all. In binary form however
the Hercules project may include an unmodified version of the ZLIB runtime DLL in addition to its own
distribution binaries.
The ZLIB_DIR environment variable defines the location where the files required for building a version of
Hercules with ZLIB compression support are found. The makefile used by the Hercules build process
tests whether this environment variable is defined and acts accordingly to build Hercules with or without
ZLIB compression support.
If ZLIB_DIR is undefined when building Hercules then an attempt is made to locate the ZLIB library in a
predefined default directory. If it does not find it then ZLIB support will not be generated. Otherwise
ZLIB_DIR must point to a valid directory where the ZLIB package is installed.
ZLIB_DIR should contain the path of the ZLIB directory, where the following file / directory layout is
expected:
\$(ZLIB_DIR)
zlib1.dll
zlib1.pdb
\Debug
\include
zconf.h
zlib.h
\lib
zdll.lib
\x64
zlib1.dll
zlib1.pdb
\Debug
\include
zconf.h
zlib.h
\lib
zdll.lib
Figure 84: ZLIB directory layout

When building a 64-bit (x64) version of Hercules the above ‘x64’ subdirectories are automatically
searched, so as long as the above directory structure is adhered to then Hercules should build fine.

14.4 Setting up BZIP2 Support
BZIP2 is a freely available open source, BSD-style license, patent free, high-quality data compressor
written by Julian R. Seward. It typically compresses files to within 10% to 15% of the best available
techniques from the PPM family of statistical compressors, and performs approximately twice as fast at
compression and six times faster at decompression than comparable implementations.
In source form the Hercules project does not contain any BZIP2 source code at all. In binary form how-
ever the Hercules project may include an unmodified version of the BZIP2 runtime DLL in addition to its
own distribution binaries.
The BZIP2_DIR environment variable defines the location where the files required for building a version
of Hercules with BZIP2 compression support are found. The makefile used by the Hercules build process
tests whether this environment variable is defined and acts accordingly to build Hercules with or without
BZIP2 compression support.
If BZIP2_DIR is undefined when building Hercules then an attempt is made to locate the BZIP2 library in
a predefined default directory. If it does not find it then BZIP2 support will not be generated. Otherwise
BZIP2_DIR must point to a valid directory where the BZIP2 package is installed.
BZIP2_DIR should contain the path of the BZIP2 directory, where the following file / directory layout is
expected:
\$(BZIP2_DIR)
\Debug
bzlib.h
libbz2.dll
libbz2.lib
libbz2.pdb
\x64
\Debug
bzlib.h
libbz2.dll
libbz2.lib
libbz2.pdb
Figure 85: BZIP2 directory layout

14.5 Setting up PCRE Support

PCRE (Perl-Compatible Regular Expressions) is a set of functions that implement regular expression
pattern matching using the same syntax and semantics as Perl 5. PCRE has its own native API as well as
a set of wrapper functions that correspond to the POSIX regular expression API. The PCRE library is
free, including use in commercial software.
In source form the Hercules project does not contain any PCRE source code at all. In binary form
however, the Hercules project may include an unmodified version of the PCRE runtime DLLs in addition
to its own distribution libraries.

The Perl-Compatible Regular Expressions library is needed only to support the Hercules Automatic Ope-
rator (HAO) Facility. If you do not plan to use the Hercules Automatic Operator Facility then you do not
need to install PCRE support and you may skip this step.
The PCRE_DIR environment variable defines the location where the files required for building a version
of Hercules with PCRE support are found. The makefile used by the Hercules build process tests whether
this environment variable is defined and acts accordingly to build Hercules with or without PCRE support.
If PCRE_DIR is undefined when building Hercules then an attempt is made to locate the PCRE library in
a predefined default directory. If it does not find it the regular expression support will not be generated.
Otherwise PCRE_DIR must point to a valid directory where the PCRE package is installed.
PCRE_DIR should contain the path of the PCRE directory, where the following file / directory layout is
expected:
\$(PCRE_DIR)
\bin
pcre3.dll
pcre3.pdb
pcreposix3.dll
pcreposix.pdb
\include
pcre.h
pcreposix.h
\lib
pcre.lib
pcreposix.lib
\x64
\bin
pcre3.dll
pcre3.pdb
pcreposix3.dll
pcreposix.pdb
\include
pcre.h
pcreposix.h
\lib
pcre.lib
pcreposix.lib
Figure 86: PCRE directory layout


14.6 Building Hercules using the Visual Studio IDE
Default Visual Studio 9.0 (Visual C++ 2008 Express) solution and project files are included as part of the
Hercules source-code distribution.
To build Hercules just open the ‘Hercules.sln’ solution file and click the ‘Build’ or ‘Rebuild All’ button.
When you click the ‘Rebuild All’ button the makefile project simply invokes ‘makefile.bat’ which in turn
invokes the ‘nmake’ command for ‘makefile.msvc’ after calling few batch files to define the MSVC build
environment.

15. Maximizing Hercules Available Memory
15.1 Introduction
This chapter provides instructions and suggestions to help maximize the amount of available memory on
Windows systems. It is the result of research conducted by Fish (David B. Trout) into this subject from a
Hercules developer's perspective although it pertains to all general Windows application development.
Please note, that these steps are optional. They are not necessary to run Hercules.
15.2 Windows Memory Layouts

The following figures show how Windows divides each process's 4 GB address space on 32-bit Windows
systems.
a) Win 9x memory layout:
0x00000000 – 0x00000fff (4KB) MS-DOS & 16-bit Windows

(inaccessible; reserved
for NULL ptr assignments)
0x00001000 – 0x0003ffff (4MB) MS-DOS & 16-bit Windows

(read/write, but don't touch)
0x00400000 – 0x7fffffff (2GB) Private to Win32 processes

(unreserved, usable)
0x80000000 – 0xbfffffff (1GB) memory-mapped files, shared

Win32 DLLs, 16-bit apps and
memory allocations; shared by
all Win32 processes.
(read/write, usable)
0xc0000000 – 0xffffffff (1GB) VxDs, memory manager and file

system code; shared by all Win32
processes.
(read/write, but don't touch)
Figure 87: Windows 9x Memory Layout

b) Win NT memory layout:
0x00000000 – 0x0000ffff (64KB) inaccessible; reserved

for NULL ptr assignments
0x00010000 – 0x7ffeffff (2GB) Private to Win32 processes

(unreserved, usable)
0x7fff0000 – 0x7fffffff (64KB) inaccessible; reserved

for NULL ptr assignments
0x80000000 – 0xffffffff (2GB) Operating system use

(inaccessible)
Figure 88: Windows NT Memory Layout
As can be seen even though each process has 4GB of address space (addressable using 32 bits) only
slightly less than 2 GB (31 bits) is actually available to any given application. The rest is reserved for the
operating system and cannot be accessed.
To further complicate matters, just as with most operating systems, any application or binary image (i.e.
.EXE, .DLL, etc.) can define at link time its preferred base address. Also known as a load address, this is
the address at which the image in question prefers to be loaded.
The reason images (.EXEs and .DLLs, etc.) have defined preferred base or loading addresses is simply
to relieve the operating system from having to relocate the image to another part of memory. At link-edit
time - when the image gets built - all of the program's address constants etc. are pre-initialized with what-
ever preferred base address and offset was defined on the LINK statement. Using this method, if the
image can be loaded at the preferred base address, the operating system has no other work to do for the
image, specifically; all address constants etc are already set to the values they need to be for this binary
image.
If however the image cannot be loaded at the preferred base address then the operating system, after
loading it at a different address, must then adjust all of the address references in the entire image to re-
flect the new base. Applications that do a lot of image loading and may be running on slow systems can
take a few extra microseconds to do this work. With the expansion of addressable memory and the speed
of both RAM and CPU today such things are no longer really a concern, although Windows is still de-
signed to cater for this.
The end result being that a default build always creates EXE’s with a preferred base address of
0x00400000 (4MB) as this is the lowest address an image can be loaded at on Win 9x. If you try speci-
fying a lower base address the linker will issue a warning that the resulting executable may not run on
Win 9x.
Additionally the default preferred base address for DLLs is at 0x10000000 which is 256MB. Thus up to
256MB of valuable virtual address space will be wasted as it cannot be used for the "malloc heap" and
serves only as space to load additional DLLs if required.

15.3 The "VADUMP" Report
The SDK utility VADUMP ("vadump -sv -p <pid>") can report a process's memory layout. Running it on a
default MSVC build of Hercules reveals the following memory layout on a test system:
Memory Layout (before rebase)
00230000 : 0023f000 hsys.dll

00240000 : 00276000 hdasd.dll
00280000 : 00290000 hutil.dll
00290000 : 002a3000 zlib1.dll
002b0000 : 002ce000 LIBBZ2.dll
00400000 : 00406000 Hercules.exe
00bc0000 : 00bc6000 hdteq.dll
00bd0000 : 00bec000 dyncrypt.dll
00bf0000 : 00bf7000 dyngui.dll
00c00000 : 00c09000 hdt3505.dll
00c10000 : 00c16000 hdt3525.dll
00c20000 : 00c27000 hdt1403.dll
00c30000 : 00c3b000 hdt3270.dll
02800000 : 028c1000 DbgHelp.dll
10000000 : 101ba000 hengine.dll
43000000 : 43005000 GoogleDesktopNetwork1.dll
68590000 : 685a6000 rsvpsp.dll
68c40000 : 68c49000 RAPILIB.dll
74fd0000 : 74fee000 msafd.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
759b0000 : 759b6000 LZ32.dll
77820000 : 77827000 VERSION.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7C000 GDI32.dll
77f80000 : 77ffc000 ntdll.dll
78000000 : 78045000 msvcrt.dll
7c2d0000 : 7c335000 ADVAPI32.dll
7c370000 : 7c409000 MSVCR80.dll
7c570000 : 7c623000 KERNEL32.dll
Figure 89: Memory Layout before Rebase
Note 1: It is likely that the default build for the Hercules MSVC version has been changed since the time
this analysis was performed. Thus the information above may no longer be accurate and it is included for
illustrative purposes only.
Note 2: The VADUMP utility does not display its report in any meaningful sequence. All these displays
were manually sorted into ascending virtual address sequence.

15.4 Using "REBASE"
Adding the command (without the quotes of course) "rebase -b 0x400000 $(X)*.dll" immediately
following the "all: allzlib alllibbz2" build-rule in the Hercules dllmod makefile results in the following
memory layout:
Memory Layout (after rebase)
00370000 : 0038C000 dyncrypt.dll

00400000 : 00406000 Hercules.exe
00420000 : 00427000 dyngui.dll
00450000 : 00486000 hdasd.dll
004a0000 : 004a7000 hdt1403.dll
004d0000 : 004db000 hdt3270.dll
004f0000 : 004f9000 hdt3505.dll
00500000 : 00506000 hdt3525.dll
00510000 : 00516000 hdteq.dll
00530000 : 006ea000 hengine.dll
006f0000 : 006ff000 hsys.dll
00710000 : 00720000 hutil.dll
00720000 : 0073e000 LIBBZ2.dll
00740000 : 00753000 zlib1.dll
02800000 : 028c1000 DbgHelp.dll
68590000 : 685a6000 rsvpsp.dll
68c40000 : 68c49000 RAPILIB.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
759b0000 : 759b6000 LZ32.dll
77820000 : 77827000 VERSION.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7c000 GDI32.dll
78000000 : 78045000 msvcrt.dll
7c2d0000 : 7c335000 ADVAPI32.dll
7c370000 : 7c409000 MSVCR80.dll
7c570000 : 7c623000 KERNEL32.dll
Figure 90: Memory Layout after Rebase
Note how hengine.dll has moved down from its default 0x10000000 slot thus freeing up valuable con-
tiguous memory. This is exactly the outcome we desire.

Continuing these efforts further with a Windows 2000 Server virtual machine the following memory
layouts were observed:
W2KSRVR VIRTUAL MACHINE
Using old Ivan snapshot; MAINSIZE 64
00230000 : 0023f000 hsys.dll

00240000 : 00278000 hdasd.dll
00280000 : 00290000 hutil.dll
00290000 : 002a2000 zlib1.dll
00400000 : 00406000 hercules.exe
00ba0000 : 00ba6000 hdteq.dll
00bb0000 : 00bb6000 hdt1052c.dll
00bc0000 : 00bc8000 hdt3505.dll
00bd0000 : 00bd6000 hdt3525.dll
00be0000 : 00be6000 hdt1403.dll
00bf0000 : 00bfB000 hdt3270.dll
10000000 : 101dd000 hengine.dll
68590000 : 685a6000 rsvpsp.dll
68c40000 : 68c49000 RAPILIB.dll
72a00000 : 72a2d000 DbgHelp.dll
74fd0000 : 74feeE000 msafd.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7c000 GDI32.dll
78000000 : 78045000 MSVCRT.dll
7C2d0000 : 7c335000 ADVAPI32.dll
7c340000 : 7c396000 MSVCR71.dll
7c570000 : 7c623000 KERNEL32.dll
Using new rebased version; MAINSIZE 64
00400000 : 00406000 hercules.exe

00410000 : 0042C000 dyncrypt.dll
00430000 : 00436000 hdt1052c.dll
00440000 : 00447000 hdt1403.dll
00450000 : 00486000 hdasd.dll
004e0000 : 004eb000 hdt3270.dll
004f0000 : 004f9000 hdt3505.dll
00500000 : 00506000 hdt3525.dll
00510000 : 00516000 hdteq.dll
00530000 : 006ea000 hengine.dll
006f0000 : 006ff000 hsys.dll
00710000 : 00720000 hutil.dll
00720000 : 0073e000 LIBBZ2.dll
00740000 : 00753000 zlib1.dll

68590000 : 685a6000 rsvpsp.dll
68c40000 : 68c49000 RAPILIB.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7c000 GDI32.dll
78000000 : 78045000 msvcrt.dll
7c2d0000 : 7c335000 ADVAPI32.dll
7c370000 : 7c409000 MSVCR80.dll
7c570000 : 7c623000 KERNEL32.dll
un-rebased snapshot: old max MAINSIZE = 1500
00230000 : 0023f000 hsys.dll

00240000 : 00278000 hdasd.dll
00280000 : 00290000 hutil.dll
00290000 : 002a2000 zlib1.dll
00400000 : 00406000 hercules.exe
00ba0000 : 00ba6000 hdteq.dll
00bb0000 : 00bb6000 hdt1052c.dll
00bc0000 : 00bc8000 hdt3505.dll
00bd0000 : 00bd6000 hdt3525.dll
00be0000 : 00be6000 hdt1403.dll
00bf0000 : 00bfb000 hdt3270.dll
10000000 : 101dd000 hengine.dll
6e0b0000 : 6e0c6000 rsvpsp.dll
6e0d0000 : 6e0d9000 RAPILIB.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7c000 GDI32.dll
78000000 : 78045000 MSVCRT.dll
7c2d0000 : 7c335000 ADVAPI32.dll
7c340000 : 7c396000 MSVCR71.dll
7c570000 : 7c623000 KERNEL32.dll
rebased snapshot: New max MAINSIZE = 1800!
00400000 : 00406000 hercules.exe

00410000 : 0042c000 dyncrypt.dll
00430000 : 00436000 hdt1052c.dll
00440000 : 00447000 hdt1403.dll

00450000 : 00486000 hdasd.dll
004e0000 : 004eb000 hdt3270.dll
004f0000 : 004f9000 hdt3505.dll
00500000 : 00506000 hdt3525.dll
00510000 : 00516000 hdteq.dll
00530000 : 006ea000 hengine.dll
006f0000 : 006ff000 hsys.dll
00710000 : 00720000 hutil.dll
00720000 : 0073e000 LIBBZ2.dll
00740000 : 00753000 zlib1.dll
719c0000 : 719d6000 rsvpsp.dll
719e0000 : 719e9000 RAPILIB.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7c000 GDI32.dll
78000000 : 78045000 msvcrt.dll
7c2d0000 : 7c335000 ADVAPI32.dll
7c370000 : 7c409000 MSVCR80.dll
7c570000 : 7c623000 KERNEL32.dll
Figure 91: Windows 2000 Server Virtual Machine Memory Layouts
The above displays illustrate how a simple rebasing of DLLs helps to free up valuable virtual memory,
over 300MB in this particular case, as well as the apparent reshuffling of already loaded DLLs caused by
specifying a large MAINSIZE. It is an educated guess based on the observed evidence that Windows
does this in order to try and make room for a heap of the specified size.
Continuing the same effort but on a production development system provided the following results:
PRODUCTION SYSTEM
With only Hercules rebased, max MAINSIZE = 1000
00370000 : 0038C000 dyncrypt.dll

00400000 : 00406000 Hercules.exe
00420000 : 00427000 dyngui.dll
00450000 : 00486000 hdasd.dll
004a0000 : 004a7000 hdt1403.dll
004d0000 : 004db000 hdt3270.dll
004f0000 : 004f9000 hdt3505.dll
00500000 : 00506000 hdt3525.dll

00510000 : 00516000 hdteq.dll

00530000 : 006ea000 hengine.dll
006f0000 : 006ff000 hsys.dll
00710000 : 00720000 hutil.dll
00720000 : 0073e000 LIBBZ2.dll
00740000 : 00753000 zlib1.dll
02800000 : 028c1000 DbgHelp.dll
68590000 : 685a6000 rsvpsp.dll
68c40000 : 68c49000 RAPILIB.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
759b0000 : 759b6000 LZ32.dll
77820000 : 77827000 VERSION.dll
77d30000 : 77da8000 RPCRT4.dll
77e10000 : 77e6f000 USER32.dll
77f40000 : 77f7c000 GDI32.dll
77f80000 : 77ffC000 ntdll.dll
78000000 : 78045000 msvcrt.dll
7C2d0000 : 7c335000 ADVAPI32.dll
7c370000 : 7c409000 MSVCR80.dll
7c570000 : 7c623000 KERNEL32.dll
Rebasing DbgHelp.dll and GoogleDesktopNetwork1.dll, max MAINSIZE = 1800!
00370000 : 0038C000 dyncrypt.dll

00400000 : 00406000 Hercules.exe
00420000 : 00427000 dyngui.dll
00450000 : 00486000 hdasd.dll
004a0000 : 004a7000 hdt1403.dll
004d0000 : 004db000 hdt3270.dll
004f0000 : 004f9000 hdt3505.dll
00500000 : 00506000 hdt3525.dll
00510000 : 00516000 hdteq.dll
00530000 : 006ea000 hengine.dll
006f0000 : 006ff000 hsys.dll
00710000 : 00720000 hutil.dll
00720000 : 0073e000 LIBBZ2.dll
00740000 : 00753000 zlib1.dll
00bb0000 : 00c71000 DbgHelp.dll
00e80000 : 00e85000 GoogleDesktopNetwork1.dll
722e0000 : 722f6000 rsvpsp.dll
72300000 : 72309000 RAPILIB.dll
75010000 : 75017000 wshtcpip.dll
75020000 : 75028000 WS2HELP.dll
75030000 : 75044000 WS2_32.dll
759b0000 : 759b6000 LZ32.dll
77820000 : 77827000 VERSION.dll
77d30000 : 77da8000 RPCRT4.dll

77e10000 : 77e6f000 USER32.dll

77f40000 : 77f7c000 GDI32.dll
78000000 : 78045000 msvcrt.dll
7c2d0000 : 7c335000 ADVAPI32.dll
7c370000 : 7c409000 MSVCR80.dll
7c570000 : 7c623000 KERNEL32.dll
Figure 92: Production System Memory Layout
As can be seen from the above displays the result of rebasing both Hercules's DLLs - and perhaps more
importantly the Google desktop DLL - resulted in the recovery of over 800 MB of usable virtual address
space.
15.5 Rebasing DLLs which are in use

If you encounter the error "REBASE: *** RelocateImage failed (foobar.dll). Image may be corrupted"
when trying to rebase a particular DLL this means that the DLL is either marked read-only or is already
loaded and in use by a currently executing process and thus cannot be rebased.
If you still wish to rebase such a module you will need to identify which process or processes are using
the module and shut these down or in the case of a service, stop that service. Note that stopping a key
system service when other system services depend on it may have negative ramifications for your system
overall. Make changes such as this at your own risk carefully testing each individual change and be pre-
pared to recover the entire system from backups if necessary.
As a practical example, in the test case, rebasing "DbgHelp.dll" was easy, as it was not in use. Rebasing
"GoogleDesktopNetwork1.dll" is a more difficult process. The RpcSs ("Remote Procedure Call, RPC")
service was using it and shutting down this particular critical system service requires several steps. You
need to go into "REGEDIT" and set the services 'Start' value from 2 (Automatic) to 4 (Disabled) then re-
boot into Safe Mode. During this reboot the Windows Explorer may take much up to several minutes to
start. Also, once disabled, you will not be able to re-enable it via the Services snap-in. You will need to
use "REGEDIT" again to change its 'Start' value back from 4 to 2 and then reboot.
Once you have disabled the RpcSs service and have rebooted into Safe Mode go into the directory
"Program Files\Google\Google Desktop" and rebase Google's network DLL as needed. This should work
now that RpcSs is no longer running, use the following command:
rebase -b 0x400000 GoogleDesktopNetwork1.dll
Once you have rebased it go back into "REGEDIT", change RpcSs back to automatic as described above
and reboot normally.
There is no known Microsoft Windows utility that will tell you what process is using a given DLL. The
Company "Sysinternals" provides a free "Process Explorer" similar to the Windows' Task Manager with
more functionality and features.
You may also want to make some registry tweaks to Hercules Windows GUI so it will accept MAINSIZE
values larger than 1024. See the Registry Tweaks section of the Hercules GUI help pages for more in-
formation.
Finally the size of the Windows swap file limits the amount of memory a program can acquire. If the Win-
dows swap file is too small then no matter what Hercules does it will never obtain the memory it requests.
If possible, set "Maximum paging size" value to the maximum supported.

15.6 Bottom Line
Like the previous examples have shown, by rebasing different DLLs it is possible to recover a lot of
available virtual memory. However it should be noted that this is a significant intervention in the Windows
operating system. It is strongly recommended that you create an image copy backup of your operating
system before experimenting with rebasing DLLs.

Part III: Linux Installation

16. Linux Installation
The "Linux Installation" is not yet documented.

Part IV: Mac OS X Installation

17. Mac OS X Installation
The "Mac OS X Installation" is not yet documented.

Appendix A. Links
 The Hercules System/370, ESA/390, and z/Architecture Emulator
http://www.hercules-390.org
 Hercules Developer Snapshots (Ivan Warren)
http://www.ivansoftware.com/snapshots/snapshots
 Hercules PDF Documentation (Peter Glanzmann)
http://hercdoc.glanzmann.org
 The MVS Tur(n)key System, Version 3 (Volker Bandke)
http://www.bsp-gmbh.com/turnkey/index.html
http://www.mvs-turnkey.de
 Hercules WinGUI (“Fish”, David B. Trout)
 CTCI-W32 (“Fish”, David B. Trout)
http://www.softdevlabs.com/Hercules/ctci-w32-index.html
 Hercules Studio (Jacob Dekel)
http://www.mvsdasd.org/hercstudio
 WinPcap, Politecnico di Torino
http://www.winpcap.org

 Vista tn3270, Tom Brennan Software
http://www.tombrennansoftware.com
 X3270, Paul Mattes
http://x3270.bgp.nu
 AWSBROWSE (“Fish”, David B. Trout)
 XMIT Manager
www.cbttape.org
 CBT MVS Utilities Tape (CBTTAPE)
www.cbttape.org
 Microsoft Visual C++ 2008 Express
http://www.microsoft.com/express/download/
 ZLIB
http://www.zlib.net
http://www.softdevlabs.com/Hercules/ZLIB1-1.2.3-bin-lib-inc-vc2008-x86-x64.zip
 BZIP2
http://www.bzip.org
http://www.softdevlabs.com/Hercules/BZIP2-1.0.5-bin-lib-inc-vc2008-x86-x64.zip

 PCRE
http://www.pcre.org
http://www.softdevlabs.com/Hercules/PCRE-6.4.1-bin-lib-inc-vc2008-x86-x64.zip

Hercules Emulator - Installation Guide
Hercules System/370, ESA/390,
z/Architecture Emulator
Installation Guide
HEIG030700-00
Version 3 Release 07
Hercules Emulator
Page 138

Hercules - Installation Guide: Hercules System/370, ESA/390, Z/architecture Emulator

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Hercules - Installation Guide: Hercules System/370, ESA/390, Z/architecture Emulator

Caricato da

Copyright:

Formati disponibili

Hercules System/370, ESA/390, z/Architecture Emulator

Hercules - Installation Guide

Hercules Emulator - Installation Guide Page 2

Hercules Emulator - Installation Guide Page 3

Hercules Emulator - Installation Guide Page 4

Hercules Emulator - Installation Guide Page 5

Hercules Emulator - Installation Guide Page 6

Hercules Emulator - Installation Guide Page 7

1.1 Edition information

1.2 What this book is about

1.3 Who should read this book

1.4 What you need to know to understand this book

1.5 How to use this book

1.6 Revision Notice

Hercules Emulator - Installation Guide Page 8

Send your comments by email to the Hercules-390 discussion group:

1.8 Legal Advice

Hercules Emulator - Installation Guide Page 9

Hercules Emulator - Installation Guide Page 10

2.1 Hercules Emulator – General Information

2.2 Hercules Emulator – Installation Guide

2.3 Hercules Emulator – User Reference Guide

2.4 Hercules Emulator – Messages and Codes

2.5 Hercules Emulator – Reference Summary

Hercules Emulator - Installation Guide Page 11

Hercules Emulator - Installation Guide Page 12

Hercules Emulator - Installation Guide Page 13

3.1.3 Disk Storage

Hercules Emulator - Installation Guide Page 14

3380-J 885 47’476 712’140 630 MB

3380-E 1’770 47’476 712’140 1.26GB

3380-K 2’665 47’476 712’140 1.89 GB

3390-1 1’113 56’664 849’960 946 MB

3390-2 2’226 56’664 849’960 1.89GB

3390-3 3’339 56’664 849’960 2.83 GB

3390-9 10’017 56’664 849’960 8.51 GB

3390-27 32’760 56’664 849’960 27.84 GB

3390-54 65'520 56'664 849'960 55.68 GB

9345-1 1’440 46’456 849’960 1.0 GB

9345-2 2’156 46’456 849’960 1.5 GB

Table 1: DASD Device Capacity

Hercules Emulator - Installation Guide Page 15

Hercules Emulator - Installation Guide Page 16

4.3 Hercules Performance Measurements

4.3.1 Hercules Emulator Performance

Hercules Emulator - Installation Guide Page 17

4.3.2 Emulated CKD / CCKD DASD Performance

Hercules Emulator - Installation Guide Page 18

Figure 2: DASD Emulation Type Performance

4.3.3 Host CPU Performance

Hercules Emulator - Installation Guide Page 19

Figure 3: Hercules CPU-based Performance

4.3.4 Host Disk Performance

Hercules Emulator - Installation Guide Page 20

Western Western Hitachi Hitachi

Nvidia Nvidia Adaptec Adaptec

Table 2: Disk Configurations

Figure 4: Disk Transfer Rates

Hercules Emulator - Installation Guide Page 21

Figure 5: Host Disk Performance (IPL in seconds)

4.3.5 Emulated Instruction Performance

Hercules Emulator - Installation Guide Page 22

Test Scenarios Scenario 1 Scenario 2 Scenario 3