May, 2024
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, which was 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:
the lack of a starter system under which to do the installation/system generation,
some required components were missing from the libraries,
there were unknown modifications to some of the components in the libraries, and
there appeared to be some licensed material included on the volume which could potentially lead to legal conflicts with IBM.
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 eighth revision of my MVS 3.8j installation instructions, hence the designation in the link of 'V8'. It is going live in May, 2024. 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 early versions also relied upon a couple of key components that had been extracted from the Bekker distribution libraries. The current version, as with the last several versions, relies exclusively upon the IBM distribution libraries.
When I completed the last major revision of this guide, back in 2020, I did not believe I would have reason to be making another major revision. However, in the last quarter of 2023, Rob Prins released a new version of the Turnkey MVS system. The original Turnkey system was the product of Volker Bandke, and he maintained and updated it for a number of years. The last release Volker made was Turnkey 3. The Turnkey system was subsequently maintained by Juergin Winkelmann, along with a team of other individuals; updated versions were released as Turnkey 4 and Turnkey 4-. When Rob Prins released Turnkey 5 in 2023, he sent to me updated version of the Jim Morrison 3375/3380/3390 DASD modifications, as well as some other updated modifications. With these updates, it is possible to generate an MVS 3.8j system where most, but perhaps not all, system datasets may reside on 3375/3380/3390 DASD volumes. In fact, the Turnkey 5 system resides mostly on 3390 DASD. So I was interested in updating my instructions to generate a system that could more fully utilize the later DASD models. Note: Because the Starter System, under which MVS 3.8j is generated, is unable to write to these later DASD types, the system generated using these instructions must still reside on DASD devices no later than 3350. However, using the system generated by this guide, it is possible to generate a second generation system that may then reside on the larger 3380/3390 DASD.
Since Rob Prins also sent me other updated user modifications as well, I have taken this opportunity to add a number of additional user modifications to the target MVS 3.8j system; quite a few beyond previous versions of this guide. I have found over the years that whenever I was using this procedure to generate a new MVS 3.8j system, I was subsequently adding on several additional user modifications. So it just makes sense to include them in these instructions.
I continue to use version 3.13 of Hercules (25 September 2017), even though there have been no updates to that version of the Hercules emulator in a number of years. For MVS 3.8j, this version of Hercules still functions well for me. If you are starting out new with Hercules, I recommend that you download and install the version of Hercules emulator maintained by Fish at Software Development Labs. The SDL version of Hercules is actively maintained and frequently receives new features. Bill Lewis' Hercules helper package will download the SDL Hercules source and prerequisites and build the emulator for you automatically on a variety of hardware platforms. You can find the Hercules helper at https://github.com/wrljet/hercules-helper.
If you are using a version of Hercules other than 3.13, some of the screen captures in this guide may appear different from what you encounter on a different version of Hercules emulator.
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 Volker Bandke, Ken Hall, Jay Maynard, Jim Morrison, Dutch Owens, Phil Roberts, Wolfgang Schaefer, and Peter Stockdill, as well as other names that I have not included here. 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.
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 (well, recently when this paragraph was written in 2020) 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.
I began building this site in early 2000, and it includes lots of material on many topics. It has not been possible for me to keep all areas of the site completely synchronized. For example, there are pages for the individual language compilers, which predated the creation of the single compilers and tools volume - SYSCPK. The CBT software pages all predate both the creation of SYSCPK and most of the material contained in this guide to building a target MVS 3.8j system. Everything you need to build a working MVS 3.8j system is contained here in this guide. It is not necessary to gather additional pieces from other areas of my site.
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 Rob Prins' Turnkey 5 system. 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, Linux, or macOS system, plus a huge set of utilities and bonus MVS programs that Rob, and the other maintainers of the Turnkey system, have gathered and installed. The website from which it may be obtained is https://www.prince-webdesign.nl/tk5.
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, 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. Your best chance of a response is to send your question(s) to me directly via email. 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 * * *
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 macOS.
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 scripts 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 NT, and subsequently to its successors, up 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) should function identically, regardless of which system you extract them on. Text files which contain scripts and 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 may 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 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.
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.
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 business 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.
The steps involved in installing MVS can be divided into five main phases -
The final step I have added below is the normal startup (and shutdown) of 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:
This page was last updated on April 30, 2024.