Installing MVS 3.8

Gathering Prerequisite Materials

April, 2021


Required Materials

Hercules emulator
Select one version; they provide similar functionality, although there are some differences.

http://www.hercules-390.eu/
or
http://www.softdevlabs.com/hyperion.html
or
https://github.com/hercules-390/hyperion


MVS 3.7 starter system tapes

../downloads/archives/vs2StarterTapes.tar.gz
MD5: 7c12c99c387193c8650f8ef78b4771c3


MVS 3.8j distribution tapes

..downloads/archives/vs2DistributionTapes.tar.gz
MD5: ec9f1c8672bd406a4ff7bc00f139f5bc


My installation objects (scripts, jobstreams, tapes, configuration files).  You only need one of these, choose the one that is correct for your Operating System (Linux/Mac or Windows).

../archives/mvsInstallationResources.tar.gz
MD5: a2790e1cc5ed186a0b3f67be77892bf4
or
../archives/mvsInstallationResources.zip
MD5: 76b4e1da5af618661c78ff21b2211fe1


The links to these required materials are provided here for convenience, but you need to read the section immediately following which will provide necessary details about the materials.

Before you begin, you need to acquire the following:

1.  the latest version of the Hercules emulator:

This is available from the Hercules' home site - http://www.hercules-390.eu/ - you can download both the source and precompiled versions from there.  You must use a version of Hercules at level 1.71 or above, although it is unlikely that anyone will be installing a version that old.  There was a track overflow problem in versions prior to 1.71 which will prevent successful generation and use of MVS 3.8.  This revision of my instructions is being written using release 3.13 built 25 September 2017.  You will not be able to build the MVS starter system with Hercules version 3.07.  There is no reason you should not be using the latest version of Hercules that is available.

Note: The website at http://www.hercules-390.org, which was the very first site for Hercules, is no longer maintained and the material available at that site is very obsolete.  It will not allow you to complete the installation process for MVS 3.8j on your system. 

Hercules release 3.13 possibly has a bug in sockdev.c, the module which allows socket devices to be defined for card readers, card punches, and printers.  It has been reported for some versions of Linux host Operating Systems that this bug prevents the use of socket devices to submit jobs to Hercules from the host Operating System or to use socket devices to process output from emulated punches and printers.  This bug has been fixed in the Software Development Labs version of Hercules (Hyperion), which is described in the following paragraph.  If you are going to be running Hercules on a Linux platform, you may be able to fix this problem in the sockdev.c source and then build the Hercules executables as you normally would and the bug is fixed.  I describe what I have attempted in detail at:  Why has job submission through a card reader defined as a socket device stopped working?  I do not know if this bug exists in Windows versions of the Hercules' executables.  I also have inserted the word possibly in the first sentence of this paragraph, because I cannot reliably reproduce this error on my Linux system at this time.

Although I have been aware that Fish (David Trout) has for some time been maintaining another version of Hercules - which he himself describes as 'bleeding edge' - I had not followed up that knowledge by trying his version.  Recently I had a question from someone that prompted me to download and build his version, which is available from http://www.softdevlabs.com/hyperion.html.  The version I installed (on my Linux desktop, which is 64 bit LinuxMint 18.3) was 4.3.999.0-SDL.  The installation was painless and quick.  I did not go through an entire build of MVS 3.8 under the SDL version of Hercules, but the person who asked the original question did and reports that it worked flawlessly.  My own experience, so far, has been to confirm that the SDL version installs quickly and will execute an MVS 3.8j system built using my instructions.

There is also third version of Hercules, maintained by Stephen Orso and other developers available at https://github.com/hercules-390/hyperion.  The instructions for installing this version were a bit more complex, but I have successfully installed in on my computer.  I did confirm that in will IPL and run MVS 3.8j, but I did not use it to work through an entire installation/generation of MVS 3.8j on my computer.

If you are running on a version of the Windows operating system, you no longer need the Cygwin package.  The current Windows' versions of Hercules runs natively under the Windows Operating System.  You can still run under Cygwin if you choose, but you will have to build Hercules yourself from the sources.

Instructions for installing precompiled binaries for whatever host platform you are running on or downloading the source and building your own executable binaries for your platform can be found at the Hercules' home site - http://www.hercules-390.eu/, or at the links for the other two versions of Hercules mentioned above.  I do not attempt to provide any information here regarding the installation of Hercules itself.

If you build the Hercules' executables from source, you must include compression capability (bzip and zlib) in order to be able to process Hercules Emulated Tape images and compressed DASD images.  The first indication that you are missing the compression capability in your Hercules' executables is that Hercules will not IPL the stand alone utilities for building the starter system.

One final point about the various versions of the Hercules emulator:  The messages produced by the various versions are not always identical, therefore the appearance of messages on the your screen may not match those in the screen captures I provide here for reference unless you are using version 3.13.

 

2.  the MVS starter system and MVS 3.8j distribution tapes:

The MVS starter system is simply an MVS 3.7 system that is contained on two 3330 DASD volumes.  The starter system is provided by IBM on two unlabeled tapes, each of which contains three files:  1) a stand-alone program to initialize a DASD volume, 2) a stand-alone program to restore a tape dump to a DASD volume, and 3) a tape dump of the DASD volume.  I believe that all the sites that were providing these tape images for download have removed them because of their size.  They are still available to order on CD-ROM from the CBT Tape site.  I am also making them available for download from my site @ ../downloads/archives/vs2StarterTapes.tar.gz  (6.7 MB)  [MD5: 7c12c99c387193c8650f8ef78b4771c3].  The archive was created on a Linux system, but there should be no difficulty unpacking the archive on Linux, Windows, or Mac systems.  Further information about the contents of this archive, as well as detailed instructions about unpacking and placing the files for use by Hercules is contained the next section below - Environment.

The MVS 3.8j distribution tapes provided by IBM is a set of six tapes. Of these six tapes, you will only need three tapes. The first tape you will use contains the System Modification Program (SMP) load modules and procedures. There is already a version of SMP on the starter system, but it is at a version level that is too early to correctly build the MVS 3.8j system, so you will need the version on this tape. You will also need the procedures from the tape to build the distribution libraries from which MVS 3.8j will be built. The second tape you will use contains the product libraries for MVS 3.8j. The third tape you will use contains a more recent version of the Device Support Facilities than the one that will be installed with the other components from the second tape. It is nice to have both versions of these programs, as the later version is required for managing the DASD types that were introduced after MVS 3.8j.  As we will be installing user modifications to allow our target MVS 3.8j system to use those devices, we will need the services of the more updated utilities.

I believe that all the sites that were providing these tape images for download have removed them because of their size. They are still available to order on CD-ROM from the CBT Tape site. I am also making them available for download from my site @ ..downloads/archives/vs2DistributionTapes.tar.gz (17 MB ) [MD5: ec9f1c8672bd406a4ff7bc00f139f5bc]. The archive was created on a Linux system, but there should be no difficulty unpacking the archive on Linux, Windows, or Mac systems. Further information about the contents of this archive, as well as detailed instructions about unpacking and placing the files for use by Hercules is contained the next section below - Environment.

3.  my installation objects archive, which contains Hercules' configuration files, jobstreams, some additional AWS tape images, and scripts:

The nature of each file contained in the archive, as well as where to extract each file is discussed in the next section below - Environment.

I provide two versions of this archive, one is for Linux users and the other is for Windows users.  Although my own environment is Linux, which is where all of this material is created, for some of the scripts I provide I wrote Windows versions.  The Linux versions are written as a bash script and the Windows versions are written as batch command file.  Also, all text files in the archive - Hercules' configuration files, Job Control Language (jobstream) files, stand-alone job input statements, etc. - are in the correct format for the target host Operating System; which means the individual lines in the Linux files are terminated with x'0a' and in the Windows files are terminated with x'0d'x'0a.  In other areas of my website I do not provide separate versions of text files, so it will be up to the user of files downloaded from other areas of my website to ensure the line termination in text files is suitable for your system.

Do not download both of the files below.  It is only necessary to download the file below that is correct for your Operating System.

For Linux host Operating Systems, download ../archives/mvsInstallationResources.tar.gz (16.8  MB) [MD5: 358667da81bb21555a2b7c835851d294].

For Windows host Operating Systems, download ../archives/mvsInstallationResources.zip (17.5 MB) [MD5: 66d3715dda1cba0373c08da1c81683da].

 

Additional Notes for Windows Users

Based upon feedback I have received from Windows 10 users, I will also add these additional recommendations, some of which may apply to older versions of Windows which I am aware are still in use.

MD5 (or other hash sum checking mechanisms) was not something that I encountered back when I was on Windows machines, so it is something that I have come to embrace in the last decade or so (after I had been using Hercules for a decade).  In fact, a criticism I received about not providing MD5 checksums for material I was providing for download was the push that got me on board, and I quickly saw that it was a good thing.  So you should have a Windows based MD5 verification program installed on your Windows 10 (or earlier versions also) computer before you begin.  There are several available, so I will not include a link, simply search for Windows MD5 and you will have several to choose from.

Apparently a telnet client is another application that Microsoft has decided to hide in Windows 10.  I am amazed to learn that Microsoft has chosen to ship Windows 10 with the telnet client disabled by default.  They have always provided an operable telnet client in prior versions, even if the telnet client in one release was so buggy as to require an alternative.  The telnet client is present in Windows 10, but must be enabled, either through the control panel or with a command issued at the command prompt: dism /online /Enable-Feature /FeatureName:TelnetClient.  I do not have a Windows 10 machine at my disposal, so this suggestion is passed along verbatim as I received it.  Regardless of the version of Windows you are running on, you will need to use the set localecho and open localhost 3270 commands once you have started the telnet client.

One last thing suggested is that you must manually add the folder where Hercules is installed to the PATH variable.  This seems to me like a shortcoming of the Hercules' installer; regardless I don't know the sequence to edit the PATH variable on Windows 10, so I am simply passing along the information I received.

I will also add here that I provide several scripts, one written awk and the others in REXX, so you will need to download and install a REXX interpreter to use the REXX scripts and an awk interpreter for the awk script.  The single awk script is made redundant because I provide a REXX script that provides the same function; the awk version was created earlier than the REXX version and has been left in simply because it exists.

 

Environment

The goal of these instructions is to guide you through the installation of MVS 3.8j and, as such, I will not detail the installation of the Hercules emulator here.  If you have not already installed Hercules, you can find instructions on the steps to follow at the Hercules' home site - http://www.hercules-390.eu/hercinst.html, or at the sites mentioned above for the other versions.

For all the files relevant to MVS 3.8j (DASD and TAPE images, jobstreams, source code, etc), I would suggest the following directory structure, since it is the one that I use and it will be easier for my references to be understood if we are working in a common reference frame.

directory structure

The top level directory, hercules, may have other directories beneath it besides those I show here.  When the Hercules emulator was first being distributed, the executable binaries (as well as documentation and some other files distributed with Hercules) could be placed in the main hercules directory; that was true on both Linux and Windows host systems, at least that was my experience.  Currently the Hercules installation package will install the binaries, documentation and other files included in the installation package into the appropriate location depending upon the host operating system.

If you have other mainframe operating systems installed (or plan to do so in the future) - MVT, VM, DOS/VS, Linux/390, OS/VS1 - they can each have their own directory at the same level as the mvs directory, and their operating files (jobstreams, print, punch, configuration, tape and dasd files) will not interfere with each other.  On my system, for example, I actually have several different MVS configurations, each located in their own mvs? directory under hercules.  

Some Hercules' users choose to place their print and punch output in a separate directory beneath the main OS directory.  For simplicity as I proceed through these instructions, the print and punch output will be placed in the main OS directory; mvs in this case.

 

MVS Starter System Archive (vs2StarterTapes.tar.gz)

Contents

This archive contains three files:  vs2spool.het (3.1 MB), vs2start.het (4.8 MB), and vs2starter.md5sums.  The text file vs2starter.md5sums contains the MD5 sums for the two compressed tape images.  You may wonder why I am giving you so many MD5 check sums for these files and the reason is that they absolutely must be correct.  Any corruption during download will render any work created from them as wasted time.  So I advise that you download the archive, check the checksum for the entire archive, extract the files from the archive, and check the checksums for the individual files that were extracted from the archive.

The origin of the starter system tapes was a CD-ROM ordered from the CBT web site:  CBT MVS Utilitys Tape CD-ROM 5 dated 2000-12-6.  The tape images on the CD-ROM were aws format (with an extension of .aws), which is an uncompressed format.  Although I do not remember the version, at some point in the history of Hercules, compressed tape images was introduced, which is known as het format (with an extension of .het).  As I understand it, the code for processing aws images was merged into the code for processing het images, so there is actually only a single set of code that processes both tape image formats.  But I have found that there are times when Hercules will refuse to process an aws image, but it will process a het image.  Strangely enough, I have found that you can simply rename a file with the .aws extension to have a .het extension and Hercules will process it just fine.  That said, I used the Hercules' utility hetupd to compress the vs2spool and vs2start tape images using the .aws files as input to produce the .het files included in the archive.  It makes the files smaller and ensures that the Hercules' code for processing .het files will be used to process these tape images.

Extracting the files

The archive may be unpacked with the archive processing program of your choice on your Operating System: tar, file roller, 7zip, winzip, unzip, etc.

When I created the archive, it was created in the mvs directory and the files the archive contains were pulled from the tape beneath the mvs directory level.  So, the files contain relative path information that will place them back into the tape directory if the archive is extracted from the mvs directory.

Think of the tape directory as your tape library.  It will contain several tapes before we are finished, and you may continue to store tape images there as you use the MVS 3.8j system you are building.

Don't forget to check the md5sums for the two tape images against the extracted tape image files.

 

MVS 3.8j Distribution Tapes Archive (vs2DistributionTapes.tar.gz)

Contents

The archive contains four files: smb4b.het (278 kB), zdlib1.het (15.7 MB), dz1d02.het (684 kB), and vs2DistributionTapes.md5sums.  The text file vs2DistributionTapes.md5sums contains the MD5 sums for the three compressed tape images.  Again I advise you to download the archive, check the checksum for the entire archive, extract the files from the archive, and check the checksums for the individual files that were extracted from the archive.

The files on these three tape images will be used by jobs you will run on the MVS Starter System.  The components in the files will build the target MVS 3.8j system.  If there is any error caused by corruption during the download of the archive, you might not see any problem until you are trying to use the MVS 3.8j system you have built.  As with the MVS Starter System, the origin of these tapes was a CD-ROM ordered from the CBT web site: CBT MVS Utilitys Tape CD-ROM 5 dated 2000-12-6. I used the Hercules' utility hetupd to compress the two aws tape images which then produced the het images.

Although not required, the base program directory for MVS 3.8j is an interesting read, and it is available at: ../downloads/pdf/mvs38bas.pdf.  This is the documentation that accompanies the product tapes distributed from IBM and contains detailed information about what is contained on the tapes.  The source of this document was Peter Stockdill; he uploaded it to the Yahoo Hercules MVS forum on January 25, 2002.  I will provide more detailed information about the contents of the distribution tapes when it is time to use them.

Extracting the files

The archive may be unpacked with the archive processing program of your choice on your Operating System: tar, file roller, 7zip, winzip, unzip, etc.

When I created the archive, it was created in the mvs directory and the files the archive contains were pulled from the tape beneath the mvs directory level.  So, the files contain relative path information that will place them back into the tape directory if the archive is extracted from the mvs directory.

Think of the tape directory as your tape library.  It will contain several tapes before we are finished, and you may continue to store tape images there as you use the MVS 3.8j system you are building.

Don't forget to check the md5sums for the three tape images against the extracted tape image files.

 

My installation objects archive (mvsInstallationResources.tar.gz /or/ mvsInstallationResources.zip)

You will only need one of these; which one you download to your computer is determined by whether you are installing on a Linux or Windows system.

The archive may be unpacked with the archive processing program of your choice on your Operating System: tar, file roller, 7zip, winzip, unzip, etc. 

When I created the archive, it was created in the mvs directory and the files the archive contains were pulled from the subordinate directories beneath the mvs directory level.  So, the files from the subordinate directories contain relative path information that will place them back into those directories if the archive is extracted from the mvs directory.  There will be some files in the archive that will, and should, extract to the main OS directory, mvs.

When I start Hercules, I always ensure that my working directory is the mvs subdirectory of the hercules main directory (as shown in the structure above).  This way, all of the relative path references in the configuration files will be correct and commands I cite will be correct.

 

Contents of the archive and location where they should be extracted

For Linux host Operating Systems, mvsInstallationResources.tar.gz:

Directory

File Name

mvs check.queue.rexx condcode.rexx create.dasd.sh stage2.awk stage2.rexx
  submit.sh        
conf dlibs.script ibcdmprs.cnf mvs.cnf mvs.script smp1.cnf
  smp2.cnf sysgen.cnf sysgen.script    
jcl date.jcl fdz1d02.jcl mvs00.jcl mvs01.jcl mvs02.jcl
  null.jcl queue38j.jcl REV370LOAD.XMI REVCLIST.XMI REVHELP.XMI
  review1.jcl review2.jcl review3.jcl rpf184.jcl smp4p44.jcl
  smpjob00.jcl smpjob01.jcl smpjob02.jcl smpjob03.jcl smpjob04.jcl
  smpjob05.jcl smpjob06.jcl smpjob07.jcl smpmount.jcl sysgen00.jcl
  sysgen01.jcl sysgen02.jcl sysgen03.jcl sysgen04.jcl sysgen05.jcl
  sysgen06.jcl usermods1.jcl usermods2.jcl usermods3.jcl usermods4.jcl
  usermods5.jcl usermods6.jcl      
sajobs inspool0.sajob instart1.sajob rsspool0.sajob rsstart1.sajob  
tape apvtmacs.het j90010.het ptfs.het rpf184.het stage1.het

After unpacking the archive, make the scripts executable: chmod +x check.queue.rexx condcode.rexx create.dasd.sh stage2.awk stage2.rexx submit.sh

 

For Windows host Operating Systems, mvsInstallationResources.zip:

Directory

File Name

mvs check.queue.rexx condcode.rexx create.dasd.bat ncat.exe stage2.awk
  stage2.rexx submit.bat      
conf dlibs.script ibcdmprs.cnf mvs.cnf mvs.script smp1.cnf
  smp2.cnf sysgen.cnf sysgen.script    
jcl date.jcl fdz1d02.jcl mvs00.jcl mvs01.jcl mvs02.jcl
  null.jcl queue38j.jcl REV370LOAD.XMI REVCLIST.XMI REVHELP.XMI
  review1.jcl review2.jcl review3.jcl rpf184.jcl smp4p44.jcl
  smpjob00.jcl smpjob01.jcl smpjob02.jcl smpjob03.jcl smpjob04.jcl
  smpjob05.jcl smpjob06.jcl smpjob07.jcl smpmount.jcl sysgen00.jcl
  sysgen01.jcl sysgen02.jcl sysgen03.jcl sysgen04.jcl sysgen05.jcl
  sysgen06.jcl usermods1.jcl usermods2.jcl usermods3.jcl usermods4.jcl
  usermods5.jcl usermods6.jcl      
sajobs inspool0.sajob instart1.sajob rsspool0.sajob rsstart1.sajob  
tape apvtmacs.het j90010.het ptfs.het rpf184.het stage1.het

Warning:  Anti-virus programs on Windows will probably complain about downloading mvsInstallationResources.zip and quarantine the file, if they even allow the download.  Even if they do not complain about the download, they may complain when unloading the archive.  The item in the archive that the anti-virus programs are complaining about is ncat.exe, which is on the list of problems because the program has been used in the past to hack into systems.  This is a legitimate program and alerts by anti-virus programs may be considered a false positive.  

The next step is the relatively short process of building the starter system.  So, when you are ready, proceed to the next step - Building the Starter System.


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:


Return to Site Home Page Frequently Asked Questions Next: Build Starter System


This page was last updated on February 09, 2024.