# Hercules Version 2: Frequently-Asked Questions

#### What is Hercules?

Hercules is a software implementation of the System/370, ESA/390 and z/Architecture hardware which runs under Linux on several hardware platforms including the Intel Pentium PC, and under Windows NT and Windows 2000.

#### So what exactly does that mean?

It means that your PC can emulate an IBM mainframe processor. The mainframe can range from a 360 to a z900 - running in "System/370" mode, "ESA/390" mode, or "z/Architecture" mode. Hercules executes S/370, ESA/390, and z/Architecture instructions and channel programs. It emulates mainframe I/O devices by using PC devices. For example, 3390 DASD devices are emulated by large files on your hard disk, and local 3270 screens are emulated by tn3270 sessions. (Note: Not all 370 and 390 features have been implemented in Hercules. See the list of particulars later in this document. Also, certain non-standard models, 360/20s, and the 360/67 virtual memory mode are not emulated.)

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 operating system or standalone program yourself, unless you can manage to obtain 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.

#### Is it functional enough to run production work?

No. At the moment it's a system programmer's toy, though it's rapidly becoming good enough to run a wide range of software without problems.

#### Can it run z/OS, z/VM, VSE/ESA, Linux/390 and Linux for zSeries?

Yes. Hercules is a software implementation of the architecture, and so it is capable of running Linux, z/OS, VSE/ESA, and z/VM, as well as older versions of these OS's.

#### What IBM operating systems can I run legally?

Linux/390 and Linux for zSeries can be run as there are no licensing issues involved.

OS/360 (PCP, MFT and MVT), as far as I know. OS/360 is in the public domain. The status of OSes for which IBM did not charge a license fee is somewhat murky; these include MVS 3.8, VM/370 release 6, and DOS/VS release 34. OS/390 and other ESA versions of OS's are definitely licensed to a particular machine. Therefore, in practice you cannot run any ESA operating system on your PC unless you can obtain a license from IBM allowing you to do so. It is believed that there are, however, three legal ways you could run z/OS, z/VM, or VSE/ESA under Hercules:

1. Running under Linux on the Pentium processor of a P/390 which is licensed to run the OS.
2. Running under Linux/390 on a mainframe which is licensed to run the OS.
3. Running under the terms of a disaster recovery provision of the OS license (but I really don't recommend depending on Hercules to be your disaster recovery solution!).

#### What other programs will run under Hercules?

Any program which uses the S/370, ESA/390, or z/Architecture instruction set, as implemented in Hercules. Some special utilities in the form of standalone programs are known to run well. I can particularly recommend Jan Jaeger's excellent standalone editor (ZZSA) which is included in the Hercules distribution, or it can be downloaded from http://www.cbttape.org/~jjaeger; I use it regularly to look at DASD while debugging an OS installation, which is just what it's designed to do. Note: ZZSA runs in ESA/390 mode. See Jan Jaeger's website for more information and special logon procedures.

#### Where can I obtain OS/360?

1. Rick Fochtman's OS/360 archive CD is now obtainable by download from these locations:

- http://www.cyberdynesys.com/os360.tgz
- ftp://ftp.ox.ac.uk/pub/linux/hercos360/os360.tar.gz

2. If you are interested in obtaining a copy of the CD itself, contact Rick Fochtman at rfochtman @ ync.net.

You can use the `dasdload` and `dasdisup` programs (see the Creating Hercules DASD document) to build an OS/360 IPL volume from the unloaded files on the archive CD.

3. Alternatively, you can download the mftr33.tar.gz package which contains a minimal MFT system on a 3330 image, with some minimal documentation. The configuration is that of a 370/145 with 2 megabytes of main storage, running OS/MFT Release 21.0, with several volumes of pre-loaded DASD. 2 program partitions (P0 and P1) have been genned. There is no working TOD clock, and no SMF. Volume DLIB01 which is specified does not exist in the zipped file, but can be created using a plf file with the CDROM of OS/360. DLIB01 can be commented-out from the config (cnf) file if desired. The mftr33 package also includes the IPL text and program for the standalone IBCDASD program as file "ibcdasdi.rdr" which can be used if desired.

#### Where can I find documentation?

I've produced a document describing how to build an OS/360 system on Hercules, called "OS/360 on Hercules". It can be found at http://www.conmicro.cx/hercos360.

The Creating Hercules DASD document describes various methods of creating and loading virtual DASD volumes.

Malcolm Beattie has also produced two useful documents on 3270s and TSO:
"Guide to Using 3270 Consoles and Terminals for Hercules" at http://users.ox.ac.uk/~mbeattie/hercules/3270.html

"Guide to Installing TSO Under MVT on Hercules" at http://users.ox.ac.uk/~mbeattie/hercules/tso.html

For adding multiple 3270 terminals to TCAM, see the document by Mike Ross at http://www.corestore.org/hercules.html

#### What are the licensing restrictions for Hercules?

Hercules is a copyright work which has been made generally available, subject to the terms of the Q Public License. In essence this allows free use and distribution of the program for personal and commercial use. You may not distribute modified copies of the program, but you may distribute your own patches along with the program, provided that you also grant the maintainer permission to include those patches in future versions of the program. You may not copy any portion of the source code for use in any other program.

Hercules is not, repeat, not GPL software! The GNU General Public License is a Unix/Linux software licensing agreement, which we, the authors, will not participate in. We believe that the QPL, which has been certified as compliant with the Open Source Definition, provides the benefits and protections of open source for both users and developers, without the political baggage that has come to be associated with the GPL.

#### What PC hardware do I need to run Hercules?

It depends how fast you want it to run. A Pentium 200 with 32Mb RAM is probably the minimum practical requirement; 500+ MHz with 128Mb RAM would be much better. Hercules doesn't use any fancy graphics, but it does need a fast processor to achieve a reasonable MIPS rate.

If you can afford a multiprocessor system, so much the better. Hercules makes extensive use of multithreading to overlap I/O with CPU activity, so you should find that a dual or quad Pentium 200 system will outperform a uniprocessor Pentium 450. My development system is a Compaq ProLiant 6000 with four Pentium Pro 200s, and response time is quite satisfactory.

Hercules does not depend on the Pentium architecture. I've built and run it successfully on a 500 MHz Alpha 21164, and others have run it on SPARC and S/390 (!) Linux systems. (One guy has even run OS/360 under Hercules under Linux/390 under Hercules under Linux/390 under VM/ESA!) The only weirdness about building the package on an Alpha is that you'll get compiler warnings about "unsigned long value, unsigned long long format". You can ignore these.

You will need enough Linux swap space to accommodate your S/390 real storage (main storage plus expanded storage). For maximum throughput, you should set your main and expanded storage sizes high enough to eliminate S/390 paging. S/390 storage is allocated out of Linux virtual storage, so if you can provide enough RAM to eliminate Linux paging as well, then so much the better.

You also need enough hard disk space to accommodate the emulated DASD. A virtual "3330 model 1" disk drive will need about 100 megabytes of space for emulation (a 3330-11 will need about 200 megabytes). A 3380 "single density" model will need about 650MB, and a 3390 model 2 needs about 2GB. If you use the compressed CKD DASD feature, these sizes will shrink dramatically, usually to about 20 to 30 percent of the original size.

#### What PC software do I need to run Hercules?

1. You need a Linux system with POSIX threads (pthread) support. I will only provide support for Linux 2.2.x or later kernels with glibc2 (libc6) as supplied in popular distributions such as Red Hat 6.0 or later and SuSE Linux 6.1 or later. My development system runs Red Hat 6.1. You can also run under Windows NT or Windows 2000, though Hercules isn't quite as polished on that platform.

2. A recent version of the GNU C compiler (GCC), normally distributed with Linux. See the notes below on this compiler. If you wish to rebuild the Windows version, you will need the Cygwin tools from Red Hat.

3. You will also need tn3270 client software for the virtual 3270 console. The tn3270 client can run on the same machine as Hercules, or on any Unix or Windows box with a TCP/IP connection to the Hercules machine.

The supported and recommended tn3270 clients for Hercules are:

x3270 for Unix
  x3270 is included with most Linux distributions, or you can download it from www.geocities.com/SiliconValley/Peaks/7814
Vista tn3270 for Windows
  Vista tn3270 can be obtained from www.tombrennansoftware.com. The very modest license fee charged for this excellent 3270 emulator helps to support an independent software developer.

Other tn3270 clients, such as QWS3270, IBM Personal Communications, Attachmate Extra, or Dynacomm Elite should also work in most cases, but be aware that some tn3270 clients have bugs which make them unusable as OS/360 or MVS consoles.

#### What sort of MIPS rate can I expect?

Thanks to the performance enhancements which began around release 1.60, as a result of work by Mike Noel, Juergen Dobrinski, Valery Pogonchenko, and Jan Jaeger, you should now see an execution speed of around 0.8 to 1 MIPS, even on a Pentium 200. That's enough to run OS/360 (MFT or MVT) with a response time similar to that of a 3033 from the 1970's. It's also fast enough to run VSE/ESA with an acceptable response time. If you want to run OS/390 instead of OS/360 (assuming you can do so legally), you'd better get a gigahertz or so Pentium III. On a fast dual Pentium III it's now not unusual to see 10 MIPS or better.

Typical I/O rates of around 50 EXCP/second are reported on average hardware, with rates over 500/second achievable with hardware RAID.

#### Which C compiler should I use to build Hercules?

You must use GCC 2.9x, previously known as EGCS. I am using the version that came with Red Hat 6.1 and it seems to work OK. The version number reported by the Linux command `cc -v` is: egcs-2.91.66 19990314/Linux (egcs-1.1.2 release). If your compiler is version 2.9 or higher, it's EGCS-based, and should work fine, as EGCS version 1 is just another name for gcc version 2.9.

Older versions of gcc are known to produce incorrect code for some 64-bit (unsigned long) integer operations. I have had reports that earlier versions of egcs produce strange results too.

If you have both an old gcc and egcs compilers installed, use the CC parameter on the "make" command to force it to choose the correct compiler:
`make CC=egcs` ...

Red Hat 7.0 ships with two versions of gcc. If you don't do anything special, you get gcc 2.96, which will not compile the Linux kernel, so they included 2.91 as well as `kgcc`. If you encounter problems when building Hercules with the 2.96 compiler, try `make CC=kgcc` instead. I would appreciate reports as to how well the 2.96 compiler works, as it is a development snapshot, and lots of folks, including the GCC development team and Linus Torvalds, were very unhappy that Red Hat included it in their distribution.

#### Why do I get an unexpected fixed-point divide exception (program check 0009 or abend 0C9) on a CVB instruction?

You are using an old gcc compiler. You must use the newer egcs-based compiler instead. See previous question for the required compiler level.

#### Do you plan to port Hercules to other platforms?

No. I do not have the resources to support more than one operating system.

If you want to make Hercules run on Solaris, Linux 2.0.x, or whatever, then by all means go ahead. I welcome reports of any bugs or problems you find, but I probably won't fix problems if it means introducing platform-specific code, and I will not be able to test new releases against other platforms. Folks who have gotten it compiled on the BSDs report that the hardest part is removing the Linux-specific tape support. Hercules is part of the FreeBSD packages collection.

There is ongoing work to make Hercules run under Windows 98, NT, and 2000. The source code has support for these platforms included, and there is a Win32 makefile as makefile.w32.

The Hercules code is not intended to be specific to Intel hardware, so if you find any issues or faults related to running on other hardware (SPARC, Alpha, PPC, ...) under Linux 2.2, then I'm likely to be receptive to fixing that sort of problem. Issues related to Unix variants are less likely to be fixed.

#### How can I create a virtual DASD volume?

The Creating Hercules DASD document describes various methods of creating and loading virtual DASD volumes.

#### Can I read a tape which was created on a mainframe?

Yes, indirectly. The mainframe tape must be converted to AWSTAPE format and then downloaded to your PC. The tapeconv.jcl file in the Hercules directory contains a sample program which you can run under OS/390 on your mainframe system. It reads a file from tape and converts it to AWSTAPE format. Download the AWSTAPE file to your PC (making sure to choose binary format for the download), and then add the downloaded filename to the Hercules configuration file as a virtual tape device. You will then be able to read the tape file from the virtual tape drive located on your PC.

Note: the "tapeconv" program will not correctly process input tapes whose block size exceeds 32760!

One symptom of this may be the message "`ADRY011E I/O ERROR - DEVICE NOT ATTACHED.0000,NA,00...00,0000"` when attempting to restore from tape originally created using the default DF/DSS block size. The solution is to recreate the dump tape with DCB=BLKSIZE=32760.

#### Can I attach a PC tape drive to Hercules?

Yes. Hercules can read and write tapes on SCSI drives on Linux systems. I have tested this with 4mm DAT, QIC-1000, and 9-track drives. The Cygwin libraries that support Hercules on Windows do not provide support for SCSI tapes.

#### Can I process mainframe tapes with Hercules?

Yes. It is possible to obtain 9-track open reel drives and 3480-type cartridge drives which attach to the SCSI bus. Hercules makes these appear to the operating system as channel-attached 3420 or 3480 devices, making it possible to read and write real mainframe tapes.

#### Can I create Assembler programs without a mainframe?

Yes. If you want to write Assembler (BAL) programs to run on Hercules, but you don't have access to a mainframe, then there are two interesting products which you can run on your PC to assemble programs:

The "Tachyon 390 Cross Assembler" ( http://www.tachyonsoft.com/tachyon)
  With this assembler you can produce S/390-compatible object decks using your Linux or Windows PC. A high degree of HLASM compatibility, coupled with the ability to perform complex assemblies at lightning speed, make this a product which is well worth looking at. I have tried this assembler and it is truly amazing.
The "Dignus Systems/C Compiler" ( http://www.dignus.com)
  This is a C compiler which runs under Windows or Linux and generates mainframe assembler code which you can then assemble using the Tachyon assembler.

Sam Golob wrote a fascinating review of these two products in the September 1999 issue of NaSPA Technical Support magazine.

#### What architectural features are implemented?

The following standard features have been implemented:

- Address-Limit Checking
- Commercial Instruction Set
- Decimal Instructions
- Hexadecimal Floating-Point Instructions
- 24-bit and 31-bit addressing
- Key-Controlled Protection
- Page Protection
- Low-Address Protection
- Dynamic Address Translation
- 370-XA Channel Subsystem
- Channel Indirect Data Addressing
- Program Controlled Interruption (PCI)
- Channel Program Suspend/Resume
- Dual Address Space (ESA/390 only, for now)
- Access Register Mode
- Home Space Mode
- Branch and Save
- Conditional Swapping
- TOD Clock, Clock Comparator, and CPU Timer
- MVCS/MVCP/MVCK/MVCSK/MVCDK instructions
- TB/TPROT instructions
- LURA/STURA instructions
- BAKR/PC/PR/PT instructions
- Linkage Stack
- Compare and Form Codeword and Update Tree instructions

The following optional features have been implemented:

- Access-List-Controlled Protection
- Branch and Set Authority
- Broadcasted Purging
- Checksum instruction
- Compare and Move Extended instructions
- Dynamic Reconfiguration
- Expanded Storage
- Halfword-Immediate instructions
- Branch-Relative instructions
- Incorrect-Length-Indication Suppression
- Interpretive Execution (SIE)
- Move Inverse
- Move Page (Facility 2)
- MVS assists
- Operational Extensions: Console Integration
- Private Space
- Set Address Space Control Fast
- Service-call-logical-processor (SCLP) facility
- Square Root
- Storage-Protection Override
- Storage Key assist
- String instructions
- Subspace Group
- Compare Until Substring Equal
- Concurrent Sense
- Suppression on Protection with Virtual-Address enhancement
- Extended TOD clock
- Compression
- Perform Locked Operation
- Vector Facility
- Multiple Controlled Data Space (VM dataspaces)
- Extended Translation
- Extended Translation Facility 2
- Store System Information
- 64-bit operations
- Cancel I/O Facility
- Program Event Recording
- Guest PER enhancement

The following standard feature has not yet been implemented:

- Clear I/O (full functionality for S/370)

The following standard feature has been partially implemented:

- Binary Floating-Point instructions

The following optional features have been partially implemented:

- Channel-Subsystem Call

The following features are not yet implemented, either due to lack of documentation, limited host system capability, or lack of supporting hardware:

- Asynchronous Data Mover Facility
- Asynchronous Pageout Facility
- Coupling Links
- ESCON
- EMIF (ESCON Multiple Image Facility)
- Extended Sorting
- External Time Reference
- ICRF (Cryptography)
- Operational Extensions: Automatic Reconfiguration, Storage Reconfiguration, SCP-initiated Reset, Processor Availability
- PR/SM
- Sysplex Timer (ETR)
- VM/370 assists

Hercules is compliant with IBM's ALS-1, ALS-2 and ALS-3 architectural level sets to the degree necessary to run all OS/390 versions through 2.10 and known versions of z/OS in both ARCHLVL 1 and ARCHLVL 2 mode, and Linux and z/VM in both ESA/390 and z/Architecture mode.

#### What z/Architecture features are implemented?

z/Architecture includes as standard all of the features of ESA/390, except vector operations, which is not part of the z/Architecture. It also includes new standard features such as 5-level DAT, 64-bit addressing, IDAW format-2, and many new instructions.

#### Who are the Herculeans?

The following people are among those who have contributed to this project, either as coders or as testers or both:

- Roger Bowler (original author)
- Jay Maynard (current maintainer)
- Jan Jaeger
- Volker Bandke
- David Barth
- Malcolm Beattie
- Mario Bezzi
- Vic Cross
- Juergen Dobrinski
- Fritz Elfert
- Steve Gay
- Roland Goetschi
- Glen Herrmannsfeldt
- Brandon Hill
- Dan Horak
- Soren Jorvang
- Willem Konynenberg
- John Kozak
- Nobumichi Kozawa
- Peter Kuschnerus
- Paul Leisy
- Albert Louw
- Peter Macdonald
- Rick McKelvy
- Dave Morton
- Mike Noel
- Andy Norrie
- Dutch Owen
- Reed H. Petty
- Valery Pogonchenko
- Emerson Santos
- Axel Schwarzer
- Paul Scott
- Daniel Seagraves
- Greg Smith
- Adam Thornton
- David "Fish" Trout
- Ronen Tzur
- Bernard van der Helm
- Kris Van Hees
- Matt Zimmerman

  And thanks for support and encouragement from:

- Tim Alpaerts
- Bertus Bekker
- Giorgio de Nunzio
- Rick Fochtman
- Alex Friis
- Sam Golob
- Cory Hamasaki
- Tony Harminc
- Richard Higson
- Sam Knutson
- Mike Ross
- Daniel Rudin
- Rich Smrcina
- Henk Stegeman
- Mark S. Waterbury

  If anyone feels they have been unfairly omitted from either of these lists, please let me (Jay Maynard) know.

  If you have any comments and questions, join the Hercules discussion group at http://groups.yahoo.com/group/hercules-390

  Last updated 1 February 2003