Installing MVS 3.8j

September, 2020


When I joined the Hercules community in February, 2000, the only operating system that had been successfully implemented under Hercules was OS/360 MVT version 21.8f.  Efforts were already underway to make an early version of MVS available.  Throughout the remainder of that year, a lot of effort was directed toward achieving this goal.  The people contributing to this effort were located literally around the globe.  

A copy of a set of distribution libraries from a functional MVS 3.8 system was uploaded to an FTP site by Bertus Bekker.  This archived 3350 volume, often referred to in Hercules' discussions as the Bekker distribution, provided many individuals the opportunity to work on getting a functional MVS system running under Hercules.  The drawbacks of the Bekker distribution included:

Since MVS 3.8 appeared to be in the status of Public Domain software and was available for order directly from IBM as a "no charge" product, several members of the Hercules' community obtained the software directly from IBM.  The distribution tapes were converted to AWS format and made available for download from several locations. 

This is the seventh revision of the MVS 3.8j installation instructions that I have written and is going live on April 30, 2020.  The first version was based upon utilizing the combination of the Bekker distribution libraries and the starter system from the IBM distribution tapes.  Because of the possible contamination of the Bekker distribution with licensed material, the Bekker distribution was removed from the FTP site where it had been available.  Since the Bekker distribution was no longer available, I replaced that set of instructions with one based solely upon the IBM distribution tapes.  However, those instructions also relied upon a couple of key components that had been extracted from the Bekker distribution libraries.  The current version relies exclusively upon the IBM distribution libraries.  Further, this revision updates the references, screen snapshots, and output logs to reflect version 3.13 of Hercules (25 September 2017).  

Note - 6 September 2020:  Another update of this section of my website at this time may be surprising, given the complete revision that was completed in April.  However, I omitted several user modifications from that revision, as I was having difficulty resolving errors and just felt like I needed to finish what had turned into a huge project.  I have also had some additional feedback and suggestions and wanted to incorporate some of those into the process.  So I am updating some portions of the process and adding some new material, all of which I think makes for a better experience using the target MVS 3.8j.  I will summarize the updates in a separate document here:  September 2020 (Mini) Revision, as I will be incorporating the changes into this tutorial so that following it to build MVS 3.8j will be a seamless process.

From the beginning this has been a community effort, and I have relied upon and incorporated suggestions and corrections to my instructions from many other individuals in the Hercules' community.  The initial set of instructions would never have come into existence without the contributions (both directly to me and through the Hercules group discussions) by Jay Maynard, Volker Bandke, Ken Hall, Jim Morrison, Dutch Owens, Phil Roberts, and Wolfgang Schaefer.  The shared successes (and failures) in those joint endeavors were more than a little reflected in the later revisions of these instructions.  Between the major revisions, I frequently make updates to incorporate new information, either garnered from the Hercules' community discussion groups or from direct feedback received from those who have either seen errors or problems in my instructions or knew of different or better ways to accomplish the installation tasks.  I have tried to always give credit to the source of the information sent to me by others that has been incorporated into this tutorial and I shall continue to do so.

And this seems to be a good time to say "thank you," to Jeff Snyder and Michael Sullivan, who have gone through my instructions as I was doing this update, sent me many emails and lists of errata, as well as suggestions for improvements.  Without their help there likely would have been many places where bugs were left in the instructions that are now, thankfully, long gone.

Whenever possible, I provide links to the origin of the material that I present in these instructions as required to complete the generation of a working MVS 3.8j target system.  I have done that from the very first incarnation of this tutorial.  As time has passed, in many cases the locations of the original material have disappeared.  The reasons for this seem to be:  1) they were hosted on the originators' personal systems or websites and those individuals disappeared; 2) the material was hosted by organizations as a courtesy and the size of the file(s) was very large and/or interest waned; or 3) the files were hosted by an organization that, for any number of reasons, simply ceased being involved in the business that made the platform available.  The last is what has happened most recently at Yahoo Groups, where the Hercules' community lost more than 2 decades of threaded conversations about the history of Hercules, numerous contributed files, and links to other locations/sources of relevant material.  Because of this continuing disappearance of material related to Hercules and MVS 3.8j, I am now simply providing the required material directly from this site.  Whenever possible, I will also provide a link to where the material originated.  Of course I will continue to credit the originator of the material, whenever it is possible to do so.

A note of advice - as someone who started out in the early 1970s doing DOS Release 26 System Generations and has always enjoyed poking my nose "behind the scenes", I regard this type of exercise as fun and relaxing.  If you don't have some experience with IBM mainframes or do not enjoy deciphering cryptic messages and solving perplexing problems, I would advise you to acquire Volker Bandke's Turnkey MVS system.  By answering a few questions, in a matter of several minutes you will have a ready to run MVS 3.8j installed and ready to begin using on your Windows or Linux system, plus a huge set of utilities and bonus MVS programs that Volker, and the subsequent maintainers of the Turnkey system, have gathered and installed.  The Turnkey system is currently maintained by Juergen Winkelmann.  The website for it is

However, if you want to gain insight into and experience with MVS, installing and configuring your own copy of MVS is a great learning experience.  After you have successfully followed these instructions, not only will you have a functional MVS system, you will have a fair working knowledge of the MVS console, Job Control Language, and problem resolution under MVS.  You will also have a good background to know how/where to make changes if you wish to customize your system so that it will work exactly the way you want it to.


* * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * 
Due to occasional torrents of messages posted to the Turnkey-MVS forum that do not relate to the Turnkey-MVS originated by Volker Bandke, I feel it necessary to add this notice.  

The system that results from following the directions on this page, and the pages following, is NOT the Turnkey-MVS.  It does share some similarities and, of course, has a common origin in that both are built from IBM's distribution tapes for MVS 3.8j.  You should not expect the kind folks on that forum to be able to help you resolve problems with a system that you generated using these instructions.

I must repeat that building MVS from the distribution libraries is not a trivial exercise.  Although I have documented a process that is repeatable and can be completed relatively quickly by anyone experienced with IBM's MVT or MVS Operating Systems nomenclature and Job Control Language, it may be preferable to download a copy of the Turnkey-MVS CD and install the ready-built MVS system from there.  The links for doing so are given in the second paragraph above this notice.

If you have difficulties following these instructions, please first attempt to resolve the problem by carefully reviewing the information on this website.  You can often find further information by using Google or other Internet search engines using key phrases related to the problem you are having.  Problems related to MVS and their solutions are often discussed on the H390-MVS forum and the IBM-Main discussion list, and will frequently be found by a search.  If you continue to use MVS, you will probably need ready access to manuals published by IBM for MVS and the software components related to it.  At a minimum you should have copies of the OS/VS Message Library [GC26-3920], OS/VS MVS JCL (Job Control Language) [GC28-0692], and OS/VS2 MVS Utilities [GC26-3902].  If you find yourself at a complete block and cannot proceed, you may contact me for help in resolving your problem using the email address that may be found at the bottom of each page of this website.  I cannot promise instant answers, nor that I can resolve every problem, but I will attempt to provide help to all who ask.  If you do not receive a response from me, or the response you receive does not result in the resolution of your problem, posting a request for assistance on the H390-MVS forum is a likely next step.

* * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * Notice * * * 


Host Platform

These instructions can be followed to install MVS 3.8 under Hercules on either Windows or Linux platforms.  I am aware that Hercules has now been ported to BSD, Mac, and Alpha platforms, and there should be no reason that these instructions could not be used as a guide to install MVS 3.8 under Hercules on those systems, as well.  In fact, I have received feedback indicating that the instructions have been used to successfully install MVS 3.8j under Hercules running on a Mac. 

A note to Mac Users

In several places in these instructions I have placed notations regarding executing bash (shell) scripts on Macs that requires prefacing the script name with an additional parameter.  Additional feedback I have received is that the problems with executing the scrips on a Mac are related to the execute bits, which apparently are set based upon umask when the files are extracted from my archive.  As long as the read and execute bits are set properly for the user executing the scripts, they should work.  But I do not have access to a Mac to try these suggestions, so I am simply passing them along as advice to Mac users.

Although I began running Hercules on a Linux host (in 1999 and 2000), other personal requirements caused me to migrate almost exclusively to Windows 7 Professional.  In 2016 I decided that I needed to return to Linux, so that is the system under which I am now running Hercules/MVS. Because the pages on my website related to Hercules are quite extensive and have been developed over decades, you will find archives of material for download that were created under both the Windows environment and the Linux environment.   Binary files (tape and disk images) will be identical regardless of which system you extract them on.  Text files which contain jobstreams (JCL or Job Control Language files that are intended to be submitted to MVS for execution) will have lines terminated without a carriage-return character, as that is the Linux convention.  Some Windows text editors will automatically insert the carriage-return characters for you; otherwise, you will need to download a utility (tofrodos) to insert the carriage-return characters into the lines before you can utilize them on a Windows system.

In this version of my instructions for the installation of MVS 3.8j I am going to provide separate archives of my installation objects archive for Windows' users and for Linux' users.  The text files in each of those archives (jobstreams/JCL, Hercules' configuration files, scripts, etc.) will be created in such a way that they will be what is expected in the intended host Operating System.  The archives themselves were created using the tar utility under Linux.  I am aware that both Windows and Linux operating systems now will recognize and extract material from these archives, regardless of which system they were created under.

A note about Windows versus Linux command syntax

Although I have provided Windows batch script versions of the Linux bash scripts, in the tutorial/instructions I have tried to consistently use the Linux bash syntax.  There may be some places where I have slipped up and put in a command example in Windows command prompt syntax using the backward slash as directory (folder) terminator.  I did all of the work developing this on a couple of my Linux machines and then ran through the entire set of instructions (at least once in its entirety and parts of it several times) on a Windows 7 machine.  I do not have access to a Windows 10 machine (or a Mac, for that matter).  Although I had slipped up a couple of times and gone back to correct an error and typed/pasted in the Windows command, I believe I have gotten all of those corrected at this time.

A special note to users outside of the United States

Or, more specifically, to those in Great Britain.  It has been pointed out to me that in all places where the currency symbol which we in the United States refer to as a dollar sign ($) appear in the MVS world, in Great Britain, the currency symbol used is the pound sterling (£).  I was already aware that this was the case where JES2 commands entered on the MVS console were preceeded by this character to differentiate them from regular MVS commands.  But I was not aware that the name of the file transfer program IND$FILE in Great Britain would appear as IND£FILE.  So along with being cautious that commands have the correct slash character (/ for Linux/Mac versus \ for Windows), if you are in a country where the currency symbol is £, you may need to perform a mental edit of my instructions where I have used the United States locale symbol for currency.

All screen captures used throughout the instructions were made under Linux.


Preserving an Existing System

If you already have an MVS 3.8j system installed, you will need to plan ahead for what you will migrate from your existing system over to the new system you build.  This process was always the most difficult part in the migrations I have been involved with in the 'real world'.  If you have added programs to system libraries, it will be necessary to add those programs into the libraries of the new system; or, a better solution, put them in a library isolated from the system components.  If you have followed a plan to isolate your additions to non-system libraries, such as libraries with the high level qualifier of SYS2, you will still need to back up these datasets in order to migrate them to your new system.  If you have not already chosen a plan to backup your MVS data, you might find the page Backup and Restore to contain information that will help you in your migration.


Installation Steps

The steps involved in installing MVS can be divided into five main phases - 

  1. Gathering Prerequisite Materials
  2. Building the Starter System  [This step can be completed in approximately 10 minutes]
  3. Using SMP4 to Build the Distribution Libraries  [This step can be completed in approximately 20 minutes]
  4. Performing a System Generation  [This step can be completed in approximately 36 minutes]
  5. Customizing Your New MVS 3.8 System [This step can be completed in approximately 45 minutes]

The final step I have added below is the normal startup (and shutdown) of MVS 3.8.

  1. Normal Startup of Customized MVS 3.8

These are serial steps, since the output of each is required before the next may begin.  With a fast processor, you can complete these steps in a few hours.  Because I am familiar with the steps, I can usually complete the entire process in less than an hour.  If you are going through this process for the first time, you should expect it to take longer.  I used to suggest that you print out these instructions and gather the required files on your computer before beginning.  I recently printed the entire set of instructions out and it was almost an inch stack of paper, so I will relent and suggest that you keep your browser open in an adjacent window to follow along with the steps.

At the bottom of each page of instructions, there is a link provided to take you to the next step.

So, when you are ready, proceed to the next step - Gathering Prerequisite Materials.

I hope that you have found my instructions useful.  If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me:

dino mail address image

Return to Site Home Page Frequently Asked Questions Next: Gathering Materials

This page was last updated on September 11, 2020.