What is Hercules?


IBM S/370 and ESA/390



Hercules is a software implementation of International Business Machines System/370 and Extended System Architecture/390 mainframe hardware which runs under Linux on a personal computer.

Hercules was created by Roger Bowler, an enthusiastic S/370 fan who envisioned himself, and other computing enthusiasts, exploring and learning mainframe computing techniques at home without spending fortunes for equipment.  There are thousands of Hercules' supporters located around the world using, enhancing, and expanding Hercules' capabilities.  Their numbers are constantly increasing as more people learn about the existence of Hercules.

Hercules by itself only provides the implementation of the hardware instruction set of IBM mainframe architectures, S/370, ESA/390, and z/390.  In order to utilize Hercules, it is necessary to acquire either an operating system or a stand-alone program that has been designed to run on IBM mainframe hardware.  Like the hardware itself, the operating system software that runs mainframe computers is prohibitively expensive.  However, there are older versions of several of IBM's popular operating systems that are now classified as Public Domain, meaning that they may be obtained and utilized freely.

Hercules Console

[Click for larger image/information]

MVS 3.8 Console

The Hercules community runs a variety of vintage IBM mainframe operating systems which have been determined to be in the public domain, including MVT release 21.8, MVS release 3.8, DOS/VS release 34, and VM370 R6 (all from the 1970's time period).  Linux/390 by its very nature is publicly available.  Under the disaster recovery provisions of their licenses, some have successfully run more recent operating systems on their Hercules enabled systems.  

Since January, 2001 I have personally devoted my time to MVS 3.8, as it is the environment that I have spent the majority of my career working in and with which I am the most familiar.  However, there is still information on this site to benefit those who are running MVT 21.8f.

[Click for larger image/information]

My purpose in creating this web site is to share tips, code, job streams, and links to other Hercules web sites with the growing community of Hercules enthusiasts.

What will you find here?

I have collected and organized a diverse amount of information on this site to help those who are just starting out with Hercules and/or one of the operating systems that run under Hercules' emulation.  Some of the material is hosted elsewhere and I simply provide a link to the host site.  Some material I provide a copy of that is directly downloadable from the server that hosts my web pages, in some cases in a slightly different format from that the original material.  However, the most important content of this site is the documentation and tutorials that I have written to help people get up to speed using Hercules and MVS 3.8j on their own systems.

The information in this site is organized into specific topic categories.  The links below may be used to navigate to the beginning page of a particular topic area.  Some topics include quite a bit of information and have additional levels of pages accessible from the main page.  A brief summary of some of the topics follows.

Getting Started If you have just discovered Hercules, follow this link to view suggestions and links to get you started with installing Hercules and operating system software on your own computer.
Installing MVS 3.8 These pages have evolved over time, and although the very first version focused mainly on the MVT operating system, my own professional experience began with MVS 3.8.  Therefore, the main focus of my site has now shifted to focus on the installation and use of MVS 3.8j.  At this link you will find a step-by-step guide to installing MVS 3.8j using the distribution tapes obtained from IBM.
Installing BREXX370 If you would like to be able to write REXX scripts on your MVS 3.8j system, follow this step-by-step guide to install BREXX370.
Installing KICKS Guided installation of Mike Noel's KICKS (CICS-link transaction processing) for MVS 3.8j
MVS 3.8 Optional Materials The contents of the optional materials tapes for MVS 3.8, restored to a 3380-K DASD.
Adding DASD Volumes If you need to add new DASD volumes for your MVS 3.8j system, this narrative explains the steps necessary.
Assembling/Compiling If you need help assembling, compiling, and link-editing your own programs under MVS or MVT, at this link you will find instructions, job streams, and examples of how to prepare source programs in a variety of various programming languages for execution.  
Backup & Restore Datasets When you have created some datasets under MVS 3.8j, you need to be able to periodically back up the data and, when the need arises, you will need to be able to restore from the backup sets, whether it is a single dataset from the backup set, or the entire set.  I document the steps, and provide examples, for VSAM objects, partitioned datasets, and sequential datasets.  These methods are also useful for transferring datasets between installations or between instances of MVS 3.8j running under Hercules.
Compilers for MVS Since MVS 3.8 only includes the Assembler, you will need to install compilers if you are interested in ALGOL, COBOL, FORTRAN, PL/1, etc.  This  navigation link will take you to a guide to installing these compilers under MVS.  You will also find the MVT Sort/Merge program at this link.
SYSCPK Compilers/Tools Single 3350 DASD image containing many language compilers and tools for MVS.
User Modifications User modifications for MVS 3.8j.
RPG Tutorial In the feedback I received from people who had visited early versions of this site, I was made aware of the fact that there was interest in learning some beginning information about RPG programming.  Conceding that there is indeed little information available for the casual inquiring mind (ie, without spending $50 or more on a book that will mostly contain information about RPG II, RPG III or RPG IV), I set out to produce an introductory tutorial to RPG I.  This is definitely an introductory tutorial and is limited strictly to the version of RPG that we have available to run under MVT/MVS, but it will get you started if you want to try writing some RPG programs.
CBT Software There is a wealth of software available for MVT, MVS, and OS/390 on the CBT tape.  However, it is frequently necessary to modify some of the programs in order to run properly on the vintage version MVS we have available.  Whenever I find something on the CBT tape that is useful to me under MVS 3.8j, I simplify the installation, to a single jobstream if possible, and add it to this page with a brief introduction.  At times I will also add some additional material, such as execution jobstreams and TSO Help text.  As a learning experience, you might get the original material from the CBT tape site (I always document exactly which file(s) the material came from) and follow my changes to see what it takes to retrograde some of this software to MVS 3.8j level.
ABEND Codes File #134 of the CBT tape contains a TSO HELP member which documents frequently encountered System (and even a few commonly seen User) Abend Codes.  All I have done is to remove the TSO HELP control information yielding plain text, but it could be useful to print out a copy and keep near your system.
MVS Utilities Originally created in 2000/2001, the OS (MVT/MVS) Utilities page has been one of the most visited pages on my site.  However, except for corrections, which were made in the early years, there had been no updates to this page in a long while.  In January, 2022 I completely rewrote this page, increasing the number of utilities covered from ten to above forty.  In the case of the IBM originated utilities, I went back to the original manuals for the source of the information.  For the non-IBM sourced utility programs, I had to range farther to find source material, in some cases the only source found was from comments in the program code.  I added programs that are frequently used in the Hercules/MVS 3.8 environment, and, in general, where the original focus was MVT utilities, the focus has now shifted to an MVS environment.  As before, there is a PDF version of the page available for download and use as a local reference.
ISAM/VSAM Interface Utility Another byproduct of my efforts to write the RPG tutorial was this section on the ISAM interface, which allows programs written to access ISAM files to instead process datasets defined in VSAM Key-Sequenced clusters.  Even though I maintained programs using the ISAM interface in a production system for several years, it took several hours of dump reading followed by several more hours of research to reacquaint myself with the finer points of this feature.  You can read the summary of what I extracted from the available IBM documentation at this link.  If you want to access VSAM datasets from COBOL or PL/1 programs (compiled with the MVT compilers), you might want to look at the routines I wrote to let you do just that.  Instructions for using them and the downloads are at the VSAM for COBOL and VSAM for PL/I navigation links.
Make/View AWS Tape Utility I have a lot of source code (COBOL and ALC mostly) on CD-ROM and ZIP cartridge archives that I created on my personal computer.  I finally got tired of manipulating these ASCII files to create individual job streams using IEBUPDTE to load them over to source libraries under MVS.   So, I wrote a small program that can build AWSTAPE files on MS/PC-DOS, Windows/??, or even OS/2 (the OS I was running when I wrote it).  I have also made a version that will run on Linux.  I know that some people have even customized the utility (using the supplied source code) to load datasets that have records that are not card image, which was my original goal.
IEFACTRT Exits I have begun adding some IEFACTRT (SMF step/job accounting) exits that I have collected at this link.  I keep hoping I will get back to this project, but so far other things have taken priority.
FORTRAN Mini-Reference This link contains a mini-reference manual for the FORTRAN IV language.  Although not as extensive as my RPG tutorial, it will help beginners get started using the FORTRAN compiler from the MVT system.  I will try to add more to it in the future.
VSAM for COBOL I had been frustrated for more than a year because the MVT COBOL compiler wouldn't handle VSAM files.  I valiantly tried to make the ISAM Interface Program suffice, but it just didn't cut it for some of the things I wanted to do.  So, I wrote an assembler routine that could be called from COBOL that implements almost all of the VSAM file handling available in the later COBOL compilers we don't have access to.  Documentation on how to download, install and use the program can be found at this navigation link.
VSAM for PL/I And as I finally began looking at learning some PL/I, I decided it would be nice to have access to native VSAM from PL/I programs, so I wrote a wrapper routine to call the routine I wrote for COBOL (above) from PL/I programs.  The installation and sample PL/I programs can be found at this navigation link.
VSAM Tutorial I put together a general VSAM overview and what I hope is a thorough coverage of the IDCAMS utility at this link.  There are lots of sample job streams that can get you started building a library of jobs to handle lots of common tasks.
Miscellaneous Programs These are a handful of programs that I have had around for some time.  Some are subroutines I wrote that have been migrated from operating system to operating system with me, such as the date routines and field formatting routines.  Some of code in the date routines originated back in the late 1970s when I was working on a Burroughs medium system (anyone remember MCPV?).
MVS PTFs When the bugs were being worked out in order to get MVS 3.8j running under Hercules, an effort was made to collect as many PTFs that might apply to MVS 3.8j as possible.  I put this page together to collect all of them that were mentioned on the discussion groups.
Frequently Asked Questions This is exactly what it says it is.  The questions are divided into categories - General MVS, General Hercules, Console Operations, JES2, System Generation, Application/User Tasks.  When I receive questions or see questions posted on the discussions that are asked more than once, I put the question and at least one solution here.
IEFU29 Exit This user exit may be installed under MVS 3.8j to automatically dump and clear SMF datasets when they become filled.  Even if you don't want to install the automatic exit, this page includes instructions for setting up a Generation Data Group to hold archived SMF datasets plus the JCL to copy the SMF data from the collection datasets into the Generation datasets and clear the collection datasets when they get full.
IMASPZAP Utility Instructions and job streams for using the ZAP utility to dump and/or patch load modules.
TSO Tutorial This is an extensive tutorial on using basic TSO - it includes an overview of the TSO environment and command syntax for most of the commands.  At least half of this page is devoted to writing TSO Command Lists.  We may not have REXX available for MVS 3.8j (yet!), but there is an tremendous amount you can do with a CLIST.

These pages are devoted to helping install a couple of useful additions to MVT.  

VSCopy is a version if IEBCOPY that may be used to restore datasets under MVT that were unloaded using the version of IEBCOPY from MVS - the versions of IEBCOPY included with MVT is very limited and is not compatible with the version included with MVS.  

IFOX00 is the assembler that is included with MVS and is much more capable than the assembler included with MVT.  However, there is nothing that prevents the IFOX assembler from executing under MVT and this page will help you install it - an archive included on the page has everything you need.  In addition, this page includes a set if revised assembler procedures that allow you to easily use both versions of assembler on a single system.  There is also a detailed comparison of the options effective for each assembler.

Recommended Book List A short list of books I recommend for the serious MVS user.
Additions/Updates Even I was having trouble keeping up with what changed on these pages and when, so I added this page to annotate the date and what changed whenever I make a change here.

Hercules is a Free and Open Source product.  Hercules is not owned by anyone, although a number of people have contributed to its development over the years (decades) and have exercised their right to declare their copyright to the code and/or design elements they contributed.  Anyone is freely licensed to use, copy, study, and change the software in any way, and the source code is openly shared so that people are encouraged to voluntarily improve the design of the software.  There does not exist for Hercules any type of Technical Support department to call upon if your efforts to install and use Hercules (or the Operating Systems that run underneath Hercules) do not result in the outcome you expect.

There is a group of dedicated individuals who, in their spare time and for no compensation, are willing to help others find solutions to problems they have with Hercules (and/or the Operating Systems that run underneath Hercules).  If you have exhausted your own efforts to solve a particular problem with your own efforts reading the material provided with Hercules and/or available on the Internet, you may be able to find assistance in resolving your problem(s) by joining one of the Hercules related support forums.  In these forums, there is a wealth of information available in archived messages extending back over a period of years, file sections, and links to other resources.  If your question is still not answered, you may post a message for describing your problem(s) and ask others if they are able to offer any assistance.  Please make an effort to post your question to the forum most relevant to the question.  Posting Operating System questions on the main Hercules forum is not as likely to result in the assistance you are seeking.

In January, 2020, Yahoo, where the Hercules' discussion forums had been hosted for decades, terminated hosting of this type of forum.  As a result, the Hercules related groups migrated to the groups.io platform.  Below is the information for the various Hercules groups at groups.io.

Hercules 390 - Main Hercules forum

Group Web Page:  https://hercules-390.groups.io/g/group

Group Files and archives:  https://hercules-390.groups.io/g/group/files

Group Email Addresses:

            Post:  group@hercules-390.groups.io
            Subscribe:  group+subscribe@hercules-390.groups.io
            Unsubscribe:  group+unsubscribe@hercules-390.groups.io
            Group owner:  group+owner@hercules-390.groups.io
            Help:  group+help@hercules-390.groups.io

DOS/VS - Running DOS/VS, DOS/VSE or z/VSE under Hercules

        Group Web Page:  https://groups.io/g/H390-DOSVS

        Group Files and archives:  https://groups.io/g/H390-DOSVS/files

        Group Email Addresses:  

            Post:  H390-DOSVS@groups.io
            Subscribe:  H390-DOSVS+subscribe@groups.io
            Unsubscribe:  H390-DOSVS+unsubscribe@groups.io
            Group owner:  H390-DOSVS+owner@groups.io
            Help:  H390-DOSVS+help@groups.io

H390-MVS - Running MVS or z/OS under Hercules

        Group Web Page:  https://groups.io/g/H390-MVS

        Group Files and archives:  https://groups.io/g/H390-MVS/files

        Group Email Addresses:

            Post:  H390-MVS@groups.io
            Subscribe:  H390-MVS+subscribe@groups.io
            Unsubscribe:  H390-MVS+unsubscribe@groups.io
            Group owner:  H390-MVS+owner@groups.io
            Help:  H390-MVS+help@groups.io

PL/I(F) and MVS 3.8j - PL/I(F) and MVS 3.8j

        Group Web Page:  https://groups.io/g/pl1f-and-mvs38j/

        Group Email Addresses:

            Post:  pl1f-and-mvs38j@groups.io
            Subscribe:  pl1f-and-mvs38j+subscribe@groups.io
            Unsubscribe:  pl1f-and-mvs38j+unsubscribe@groups.io
            Group owner:  pl1f-and-mvs38j+owner@groups.io
            Help:  pl1f-and-mvs38j+help@groups.io

H390-OSVS - Running OS/VS1 and OS/VS2 Rel. 1 (SVS) under Hercules

        Group Web Page:  https://groups.io/g/H390-OSVS

        Group Files and archives:  https://groups.io/g/H390-OSVS/files

        Group Email Addresses:

            Post:  H390-OSVS@groups.io
            Subscribe:  H390-OSVS+subscribe@groups.io
            Unsubscribe:  H390-OSVS+unsubscribe@groups.io
            Group owner:  H390-OSVS+owner@groups.io
            Help:  H390-OSVS+help@groups.io

Turnkey-MVS - Running the Tur(n)key MVS38j operating system under Hercules

        Group Web Page:  https://groups.io/g/Turnkey-MVS

        Group Files and archives:  https://groups.io/g/Turnkey-MVS/files

        Group Email Addresses:

            Post:  Turnkey-MVS@groups.io
            Subscribe:  Turnkey-MVS+subscribe@groups.io
            Unsubscribe:  Turnkey-MVS+unsubscribe@groups.io
            Group owner:  Turnkey-MVS+owner@groups.io
            Help:  Turnkey-MVS+help@groups.io

H390-vm - Running VM/370, VM/SP, VM/ESA or z/VM under Hercules

        Group Web Page:  https://groups.io/g/h390-vm

        Group Files and archives:  https://groups.io/g/h390-vm/files

        Group Email Addresses:

            Post:  h390-vm@groups.io
            Subscribe:  h390-vm+subscribe@groups.io
            Unsubscribe:  h390-vm+unsubscribe@groups.io
            Group owner:  h390-vm+owner@groups.io
            Help:  h390-vm+help@groups.io

H390-MTS - Running the MTS operating system under Hercules

        Group Web Page:  https://groups.io/g/H390-MTS

        Group Files and archives:  https://groups.io/g/H390-MTS/files

        Group Email Addresses:

            Post:  H390-MTS@groups.io
            Subscribe:  H390-MTS+subscribe@groups.io
            Unsubscribe:  H390-MTS+unsubscribe@groups.io
            Group owner:  H390-MTS+owner@groups.io
            Help:  H390-MTS+help@groups.io

H390-MUSIC - Running the Music/SP operating system under Hercules

        Group Web Page:  https://groups.io/g/H390-MUSIC

        Group Files and archives:  https://groups.io/g/H390-MUSIC/files

        Group Email Addresses:

            Post:  H390-MUSIC@groups.io
            Subscribe:  H390-MUSIC+subscribe@groups.io
            Unsubscribe:  H390-MUSIC+unsubscribe@groups.io
            Group owner:  H390-MUSIC+owner@groups.io
            Help:  H390-MUSIC+help@groups.io

Hercules-OS380 - Running the OS380 operating system under Hercules

        Group Web Page:  https://groups.io/g/Hercules-OS380

        Group Files and archives:  https://groups.io/g/Hercules-OS380/files

        Group Email Addresses:

            Post:  Hercules-OS380@groups.io
            Subscribe:  Hercules-OS380+subscribe@groups.io
            Unsubscribe:  Hercules-OS380+unsubscribe@groups.io
            Group owner:  Hercules-OS380+owner@groups.io
            Help:  Hercules-OS380+help@groups.io

MVS38j-Wylbur - Running the Wylbur operating system under Hercules

        Group Web Page:  https://groups.io/g/MVS38j-Wylbur

        Group Files and archives:  https://groups.io/g/MVS38j-Wylbur/files

        Group Email Addresses:

            Post:  MVS38j-Wylbur@groups.io
            Subscribe:  MVS38j-Wylbur+subscribe@groups.io
            Unsubscribe:  MVS38j-Wylbur+unsubscribe@groups.io
            Group owner:  MVS38j-Wylbur+owner@groups.io
            Help:  MVS38j-Wylbur+help@groups.io

KICKSforTSO - Running KICKS for TSO under MVS38j under Hercules

        Group Web Page:  https://groups.io/g/KICKSforTSO

        Group Files and archives:  https://groups.io/g/KICKSforTSO/files

        Group Email Addresses:

            Post:  KICKSforTSO@groups.io
            Subscribe:  KICKSforTSO+subscribe@groups.io
            Unsubscribe:  KICKSforTSO+unsubscribe@groups.io
            Group owner:  KICKSforTSO+owner@groups.io
            Help:  KICKSforTSO+help@groups.i

hercules-s370asm - Programming in S/370 assembler with the Hercules emulator

        Group Web Page:  https://groups.io/g/hercules-s370asm

        Group Files and archives:  https://groups.io/g/hercules-s370asm/files

        Group Email Addresses:

            Post:  hercules-s370asm@groups.io
            Subscribe:  hercules-s370asm+subscribe@groups.io
            Unsubscribe:  hercules-s370asm+unsubscribe@groups.io
            Group owner:  hercules-s370asm+owner@groups.io
            Help:  hercules-s370asm+help@groups.io

 SATK - SATK and Bare-Metal programming on mainframes

        Group Web Page:  https://groups.io/g/satk

        Group Files and archives:  https://groups.io/g/satk/files

        Group Email Addresses:

            Post:  satk@groups.io
            Subscribe:  satk+subscribe@groups.io
            Unsubscribe:  satk+unsubscribe@groups.io
            Group owner:  satk+owner@groups.io
            Help:  satk+help@groups.io

 cbt-tape - CBT MVS Utilities and Overflow Tapes

        Group Web Page:  https://groups.io/g/cbt-tape

        Group Files and archives:  https://groups.io/g/cbt-tape/files

        Group Email Addresses:

            Post:  cbt-tape@groups.io
            Subscribe:  cbt-tape+subscribe@groups.io
            Unsubscribe:  cbt-tape+unsubscribe@groups.io
            Group owner:  cbt-tape+owner@groups.io
            Help:  cbt-tape+help@groups.io

H390-Legacy-Hardware - A group for those interested in interfacing real legacy hardware to the Hercules IBM Mainframe Emulator

        Group Web Page:  https://groups.io/g/H390-Legacy-Hardware

        Group Files and archives:  https://groups.io/g/H390-Legacy-Hardware/files

        Group Email Addresses:

            Post:  H390-Legacy-Hardware@groups.io
            Subscribe:  H390-Legacy-Hardware+subscribe@groups.io 
            Unsubscribe:  H390-Legacy-Hardware+unsubscribe@groups.io 
            Group owner:  H390-Legacy-Hardware+owner@groups.io 
            Help:  H390-Legacy-Hardware+help@groups.io

Credit to SoftDevLabs for these links.

Visitors since June, 2020

My personal site

This page was last updated on February 04, 2022.