Installing MVS 3.8
Performing a System Generation - Building MVS 3.8j
The System Generation Process
System generation is the process that creates an OS/VS2 MVS system control program tailored to both the data processing requirements and machine configuration of an installation.
For a complete system generation, the job stream produced during Stage I is processed during Stage II to create an entirely new MVS system control program.
The two summary statements above are taken from the OS/VS System Generation Reference [GC26-3792].
The system control program referenced in these statements is not a single program, but rather a complete set of datasets, allocated (planned, then defined on one or more DASD volumes, and initialized to receive content), catalogued in a Master Catalog (a VSAM object defined on the primary DASD volume of the system), and then populated with object modules, load modules, tables of parameters, and JCL (Job Control Language) statements. The majority of the material used to populate the datasets will come from the Distribution Libraries built from the IBM product tape, however some of the material is derived from settings chosen during the system design. In a production system in a real world environment, many settings are the result of months or years of fine tuning and modification.
To recap prior steps, in order to perform a System Generation, you should already have downloaded/installed on your computer -
Although not mandatory, this is the structure into which I have MVS related files and these instructions will show commands, output, etc. using this relative structure as a reference point:
The installmvs archive (item #3 in the prerequisites list above) contains fourteen files that are required for this step (I only include one each of the create.dasd, condcode, and stage2 scripts in this count):
The clock time required to complete the steps below should be approximately 35 minutes; the actual elapsed time for the jobs to execute was extracted from the jobs' SYSOUT logs, so I have added 15 minutes to this estimate for 'user' time. All times given here should be taken as estimates. The actual time reported for each job depend greatly upon the hardware and host Operating System (Linux/MAC/Windows) upon which Hercules is executing. The time necessary for you to complete the steps may be longer if you have not already gathered all required files and have them restored to the appropriate locations before beginning.
Create additional DASD Volumes
The end result of building the distribution libraries in the prior step was three 3350 DASD volumes, which are located in the dasd directory, along with the two 3330 DASD volumes which contain the starter system.
Now we will use the the create.dasd.bat (the same script we used before) to create four additional DASD volumes required for this step. In this step you will:
On a Windows system, open a Command Prompt window and type the command:
and press Enter. The script will execute, creating the four DASD images: The console output of the script on my system is shown below:
The DASD volumes that are created are simply raw emulated volumes; they have not been initialized for use by MVS and contain no VTOC or control structures. They will be initialized in the next step.
On Linux systems: I have also provided a bash version of this script (create.dasd.sh); on Linux systems, execute this script with the single argument 'sysgen' to create the three DASD images.
Alternately you may also issue the commands from a console prompt after changing to the dasd directory:
Checking MVS Completion Codes
Every batch job or started task that executes under MVS returns a completion code (also known as a condition code or return code) at the conclusion of each step (program executed). The value of the completion code is printed in the Job Log section of the SYSOUT listing, following the Allocation messages for each step. It is essential that you examine the output of each job to ensure that the codes you received for each step match those expected. If you receive an unexpected code, it probably means an error has occurred during execution of the job that must be corrected, and the job rerun, before you proceed. The SYSOUT listings can be found in the host Operating System file assigned to the printer device address as specified in the Hercules' configuration file. If you use the configuration files included in the installmvs archive, the file will be located in the mvs directory and will be named prt00e.txt. You can view this file with a text viewer or editor while Hercules is still running. The current version of Hercules protects the files assigned to its emulated devices by making them read-only access. The completion code is listed in a message with the prefix IEF142I, so you can find the completion code by searching for this string. As an alternative, I have included a Perl program in the installmvs archive - condcode.pl - and a REXX program - condcode.rexx - either of which you may use to display the step completion codes for any job; their function is identical, I simply needed the REXX version for a computer on which I did not have PERL installed. Of course you will need Perl or REXX installed on your system to use one of these. The command line syntax for the program is:
If you are following the directory structure I have suggested, the program should be executed from the mvs directory. The output can also be redirected to a file, a printer, or filtered to another program, such as more. Any step with a completion code other than 0000 will be indicated by the inclusion of "<--" to the right of the completion code. Remember that a non-zero completion code may be acceptable for a particular step; all acceptable and expected codes will be listed in these instructions.
IPL the Starter System
Again you will be using a slightly different configuration from before. The hardware environment defined in the Hercules' configuration file - sysgen.cnf - is:
Notice that this graphic doesn't quite match the Hercules configuration file, as distributed, because the four DASD volumes at the bottom are not present in the configuration file. The reason for this is that those are the volumes that we just created and will need to be initialized by a utility executed on the starter system; that utility requires that the volumes be 'offline' and so cannot be present when the starter system is IPLed. Also, you may notice that the five DASD volumes from the previous steps are now located at slightly different unit addresses. The reason for this is that the MVS Starter System does not have 3350 DASD devices generated at seven consecutive unit addresses, so the seven 3350 DASD volumes are split between addresses on channel 1 and channel 2.
The purpose for each of the new volumes is:
Open a console window (Linux) or a Command Prompt window (Windows) and start hercules by typing the command hercules -f conf/sysgen.cnf and pressing Enter.
Hercules will read the configuration file and wait for the console to connect at address x'01f'.
Start your telnet client and connect to 'localhost', port number 3270; if your client does not store options, remember that you need 'local echo' set on.
On the command line in the console window where Hercules was started, type the command ipl 150 and press Enter.
Since we rebuilt some load modules at the end of the prior step, it would be a good idea to rebuild the Link Pack Area, so for the first prompt - IEA101A SPECIFY SYSTEM PARAMETERS FOR RELEASE 03.70.VS2 - type r 0,clpa and press Enter in the telnet client window.
We do not need to format the JES2 queue this time, so in response to the message - *00 $HASP426 SPECIFY OPTIONS - HASP-II, VERSION JES2 4.0 - type r 0,noreq in the telnet client window and press Enter.
There are three initiators started. In will make things simpler for you to manage if there is only one job executing at a time, so we will stop two of the initiators. On the MVS Starter System console (in the telnet client window), type the command $pi2-3 and press Enter. Initiators 2 and 3 will end.
At this point the system is ready to process jobs and service operator commands. However, the four DASD volumes we created above are not defined in the Hercules configuration file (sysgen.cnf in the conf directory). As with the previous steps where we built the distribution libraries, I have provided a Hercules script to add the drives to the 'active' configuration. On the command line in the console window where Hercules was started, type script conf/sysgen.script and press Enter. Your Hercules command window should look like:
Initialize Target DASD Volumes and Prepare for System Generation SYSGEN00
The first task is to initialize the four DASD volumes that we just created on which the new MVS 3.8j system will be built. The jobstream to complete that task - SYSGEN00 - is contained in the file sysgen00.jcl located in the jcl directory.
On the command line in the window where Hercules was started, type the command devinit 12 jcl/sysgen00.jcl eof and press Enter. The job will begin execution and on the Starter System console (telnet client window) you will see:
The ICK003D message is informing you that an offline volume at address 149 is to be initialized or labeled and the operator is requested to verify that the desired volume is currently mounted at the address. This is expected and acceptable, so you will reply U to proceed. In the telnet client window type the command r 1,U and press Enter. Remember that the response number shown in the screen captures here may differ from the response numbers presented on your system.
You will receive the same message - ICK003D - four times in succession, once for each of the DASD mounted at addresses x'149', x'14a', x'14b' and x'14c' in sequence; you should reply U to each of these messages:
As soon as the four DASD volumes are initialized, SYSGEN00 submits a second jobstream through the internal reader. This job will have the same name - SYSGEN00 - although it is a completely separate job. The first task of this new job is to issue MVS commands to place the new volumes online and set their volume attribute. The MVS Starter System will not execute commands submitted through a job without confirmation, so on the Starter System console you will see message IEF166D asking you to confirm the execution of the first command, which will Vary the four new DASD volumes online:
In the telnet client window type r 5,Y and press Enter to accept (execute) the command. You will receive four additional IEF166D commands in response to the mount commands for the four volumes. Reply Y to each of the messages. The purpose of the mount command is to place each of the new volumes online with a volume attribute of PRIVATE; this ensures that there will be no datasets allocated on the volumes that are not specifically directed to the volume by the jobs we submit.
SYSGEN00 takes 0.44 minutes to complete. Remember there were two jobs named SYSGEN00, so I am including the execution time for both in this total and the expected condition codes for all steps of the two SYSGEN00 jobs are:
The IEHPROGM step of SYSGEN00 attempts to delete some datasets we will be creating in the following steps (in case of a need to restart from this point); the datasets are not there, so the return code 0008 is expected. If they had been present and successfully deleted, then the expected return code is 0000.
The remaining steps are setting the environment to build the new system and must receive return codes of 0000. If you are interested in the details of what each step is doing, I have placed numerous comments in the jobstream explaining the reason for each step.
You may remember from building the distribution libraries, you can also check on the completion of the mount commands:
Stage 1 SYSGEN01
The Stage 1 jobstream - SYSGEN01 (contained in file sysgen01.jcl in the jcl directory) - contains all of the specifications for the hardware configuration of the new MVS 3.8j system to be built.
If you have utilized previous versions of my instructions to build MVS 3.8j, you should note that I have made some changes to the hardware configuration. After all, it has been several years since I made any modifications, so I thought it a wise time to do so. I have incorporated some changes as a result of looking over some additional configurations that have come by my desk, but some of the changes are the result of discussions on the Hercules' community newsgroups. I have added some devices that I am anticipating I might want to use later, even though I might not be ready to use them right away.
If you know of some changes you would like to make, you should feel free to edit the configuration, but be aware that you may create errors that you will need to resolve before you proceed past this step.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/sysgen01.jcl eof and press Enter.
SYSGEN01 takes 0.46 minutes to complete. Like the previous job, if there are no serious errors, SYSGEN01 submits a second jobstream through the internal reader. This job will have the same name - SYSGEN01 - although it is a completely separate job whose purpose is to punch the output from processing the Stage 1 into card images. Expected condition codes are:
The CLEANUP step attempts to delete the dataset which will hold the output from the job; it is not there when we start, so the return code 0008 is expected. If you need to rerun the job, you should expect a return code of 0000 for this step. You may rerun this job as many times as you desire, or are needed to remove all errors discovered during the assembly. If you are using the jobstream as I have distributed it, there are no errors to be resolved.
If you look at the printed output from this step, in the diagnostics listing from the assembler, you should see a single MNOTE issued at statement 2045. The severity of this error is 0, so it is only an informational message, specifically stating that all tables will be included for the 3800 printing subsystem. This is expected and normal; no corrective action needs to be taken to resolve this.
If you do make changes to the configuration and serious errors occur during the assembly which must be corrected, the assembly will be terminated prematurely and a Stage 2 deck will not be created. If there are serious errors, the secondary job will not be submitted, so you will not even see the steps listed for the IEBGENER and PUNCH steps. The punch step transfers the card images produced when the Stage 1 deck is assembled to the file attached to the emulated card punch at address x'013'; they may be found in the file pch013.txt in the mvs directory.
However, there are some changes that need to be made to the jobstreams before they are submitted.
I am aware that other folks who have done this process have taken the approach to modify the System Generation macros, which results in these changes already being made when the card images are produced. My approach is to leave the macros as they are distributed and make the changes at this point, when the card images have been transferred to a text file on the host operating system (LINUX, Windows, etc.).
You may make the changes manually with your favorite text editor - joe, vi, notepad, etc. - but I have also provided a couple of scripts that will make the changes for you. To make the changes manually, copy pch013.txt to stage2.jcl; then edit the stage2.jcl file to make the changes. If you utilize my scripts (which are described in the highlighted section below), execution of the script will copy the contents of pch013.txt as it makes the changes.
The first two card images in the punched deck, and the last card image in the deck, are job separator cards and should be deleted. The remainder of the file contains the six jobstreams which generate the MVS 3.8 system, each preceded by a JOB card generated during the Stage 1 processing. The following changes need to be made to the jobs before the may be submitted for processing:
The reasons for these changes are:
Since there has been some confusion
about these instructions to those unfamiliar with Job Control Language, I have
added a "before" and "after" comparison viewable at: pch013.txt - stage2.jcl.pdf. If you
are unfamiliar with Job Control Language, I strongly recommend that you locate a
good reference/textbook, since a thorough understanding of JCL is required to
successfully utilize MVS. My recommendation would be System/370 Job
Control Language by Gary DeWard Brown, preferably an edition prior to the
fourth, which concentrates far too much on modern facilities and drops
discussion of some of the features which are required on MVS 3.8j. You can
find this and other JCL books at larger university libraries. You local
library may be able to acquire books for you through WorldCat/Interlibrary
Loan. You might
also check for used copies reasonably priced at ABE
Submit the Stage 2 jobstreams to the reader. On the command line in the console window where Hercules was started, type the command devinit 12 stage2.jcl eof and press Enter.
The jobs will be read in by the Starter System and placed on hold:
To release the first job for processing, on the MVS Starter System console (in the telnet client window) type the JES2 command: $a'sysgen1' and press Enter.
After each job is completed, you must check the output to ensure that there are no significant errors and the completion codes received are those expected. Then release the next job in sequence - sysgen2, sysgen3, sysgen4, sysgen5, and sysgen6 - using the $a command shown above. Since the output from one or more steps in each job is usually required as input in the succeeding job, it is imperative that only one job be processed at a time, that all steps of each job are run, and that there are no unexpected completion codes.
SYSGEN1 takes 0.56 minute to run. The expected completion codes are:
SYSGEN2 takes 0.25 minute to run. The expected completion codes are:
SYSGEN3 takes 0.01 minute to run. The expected completion codes are:
SYSGEN4 takes 0.13 minute to run. The expected completion codes are:
SYSGEN5 takes 0.45 minute to run. The expected completion codes are:
SYSGEN6 takes 0.01 minute to run. The expected completion codes are:
With the exception of STEPZ1 in SYSGEN6, all of the 0004 completion codes indicate warning messages. These are expected warnings, which if you investigate the jobstreams (and printed output) you will see are noted in comments in the Linkage Editor control statements for each of the jobs receiving a 0004 return code. STEPZ1 is attempting to delete a member from a dataset that doesn't exist and therefore receives the 0008 completion code.
When the second step of SYSGEN5 executes you will see a message on the console similar to:
which is issued when SYS1.LOGREC is initialized. This does not indicate an error has occurred.
JES2 Generation SYSGEN02
During SMP, the elements of JES2 are loaded into libraries, but it is necessary to use the link editor to build the JES2 load modules. Also, the parameters required for JES2 operation need to be set up in SYS1.PARMLIB and a procedure to execute JES2 must be created in SYS1.PROCLIB.
The jobstream to link JES2 is included in the Base Program Directory document.
Volker Bandke posted a combined jobstream to the Hercules MVS group that includes the two link steps for JES2 from this document, and also sets up both the parmlib and proclib members. Over time I have incorporated changes suggested on the Hercules MVS discussion group into the options included in the SYS1.PARMLIB member; the result is SYSGEN04 (contained in file sysgen02.jcl in the jcl directory).
Tommy Sprinkle has made available the JES2 parameters (and other SYS1.PARMLIB members) he used in a production system. For more information and to download a copy of his parameters, see http://www.tommysprinkle.com/mvs/parmlib.html. If you decide to change some of the parameters for your system his information will be extremely helpful. You might also acquire a copy of the manual SC23-0046, System Programming Library: JES2 Installation, Initialization, and Tuning from a source such as http://bitsavers.trailing-edge.com/.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/sysgen02.jcl eof and press Enter.
SYSGEN02 takes less than a minute to run. The expected completion codes are:
Completing the Target System
Although technically the process of System Generation is complete at this point, the generated system is not really ready to run until a few more basic enhancements are applied.
The jobstream SYSGEN03 (contained in file sysgen03.jcl in the jcl directory) performs the following tasks:
In several cases, the members to be created already exist; in these cases a backup is made of the original member, preserving the existing contents.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/sysgen03.jcl eof and press Enter.
One change is made by this job to the Starter System - the SMPASM/SMPASML/SMPAPP/SMPREC procedures that are placed in the target system are also copied into the Starter System. That is because they are used several times as we continue to set up the target system. As SYS1.PROCLIB on the Starter System is protected by an expiration date, you will receive message IEC507D when this update is attempted:
Type r 11,U to allow the update.
Like the previous jobs, SYSGEN03 submits a continuation job with the same name. This is because some of the latter tasks that need to be done have as prerequisites some of the earlier tasks listed above and the job would receive JCL errors and fail to execute if the job were submitted as a single jobstream..
SYSGEN03 takes 2.13 minutes to run, which is the sum of the times for both the primary job and the continuation job which has the same name. The expected completion codes are:
The jobstream SYSGEN04 (contained in file sysgen04.jcl in the jcl directory) performs the following tasks:
Almost all of the material in this jobstream was used as supplied by Jim Morrison with his 3375/3380/3390 modifications published in April, 2002.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/sysgen04.jcl eof and press Enter.
SYSGEN04 takes 0.17 minutes to run. The expected completion codes are:
Every MVS system I have ever worked on employed an SMF exit to report resource utilization statistics at the end of each job step. Although the information is similar from installation to installation, most installations had some custom modifications applied to their report. The load module called by this exit is IEFACTRT, and I have another page on this site where I have collected several versions of this exit. The first task of SYSGEN05 is to install the version that I use on my own system. Perhaps the most useful feature of this exit is that it displays the step completion codes on the MVS console, allowing you to know if there is a problem with a job without opening and searching through the printed output. If you code the NOTIFY= parameter on your JOB card, it will also send the information to your TSO User ID.
SMF (System Management Facility) collects information constantly (job start, step start, dataset open, dataset close, step end, job end, etc.) as MVS manages your hardware and executes user programs. The amount of information collected will vary depending upon options set up in SYS1.PARMLIB(SMFPRM00). The parameters may be overridden by the operator during IPL or changes may be permanently made by editing this member. The information collected is stored in two datasets created during System Generation - SYS1.MANX and SYS1.MANY. One of the datasets is the active dataset, into which new records are written. When this dataset becomes filled, SMF will automatically switch to the other dataset and issue a message to the MVS console to indicate action needs to be taken to preserve the data in the filled dataset. At the very least, you must clear the records from the filled dataset so that when SMF fills the alternate dataset, it will be able to switch back to the original dataset to continue recording.
As the information collected can sometimes provide interesting insight into MVS operation, I set up a system to retain the latest five sets of SMF data collected. I keep the records in a Generation Data Group on the SMP000 volume. To facilitate the transfer of the records, as well as clearing the SMF datasets after the transfer is complete, I wrote a procedure that is placed in SYS1.PROCLIB. Also, there is a user exit available from the CBT tape that can automate the entire process. For complete information about my Generation Data Group setup, my procedure, and the user exit, you can read IEFU29 here on my site. But for convenience, I collected the required jobstreams and that is the second part of SYSGEN05.
The jobstream SYSGEN05 (contained in file sysgen05.jcl in the jcl directory) installs both of these exits/procedures.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/sysgen05.jcl eof and press Enter.
SYSGEN05 takes 0.14 minutes to run. The expected completion codes are:
During the fourteen years I have been involved with Hercules, and running MVS 3.8j under Hercules, there have been a number of user modifications proposed, submitted, and discussed in the Hercules discussion groups. There are twenty-five user modifications that I regard as pretty mandatory to the orderly and 'user friendly' operation of MVS 3.8j. I have gathered those modifications into a single jobstream - SYSGEN06 (contained in file sysgen06.jcl in the jcl directory).
The twenty-five user modifications included are:
The name Kevin Leonard appears several times above, so obviously I hold his modifications in high regard. He provides many useful modifications at his site: http://www.j76.org/hercules/ for MVS 3.8, MVT 21.8f, HASP V4, and ASP V3.2 and makes frequent contributions to the Hercules discussion groups.
Greg Price is also a frequent contributor to the Hercules/MVS 3.8j community. His website is also a wonderful place to have bookmarked: http://www.prycroft6.com.au/.
When all twenty-five of these usermods were combined into a single jobstream, they were a bit much for the small JES2 spool of the Starter System. Not to worry, I have divided them into five separate jobs, all contained in the same file. When they are submitted, they will execute serially and everything works out just fine.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/sysgen06.jcl eof and press Enter.
SYSGEN06 (all five jobs totalled) takes 3.17 minutes to run. The expected completion codes are:
The three steps which receive a return code of 0004 all have link-editor subordinate tasks which have unresolved external links. This is expected and acceptable for these three cases.
The final jobstream we will execute to complete the creation of the target MVS 3.8j system is FDZ1D02 (contained in file fdz1d02.jcl in the jcl directory).
The reason for the strange job name is that this is in fact a product element which we did not accept with all the other elements on the product tape. Why not, you may ask. The reason is that FDZ1D02 is Release 13.0 of the Device Support Facilities, or as it is more commonly known, ICKDSF, the DASD initialization program. The version we did install, way back when we built the Distribution Libraries is version 6.
Actually I can think of a couple of questions you may have at this point - Why install version 6 when we have version 13? Why do we need version 13 now? Let's take the last first.
Why do we need version 13 now? If you want to utilize 3375/3380/3390 DASD, you need version 13 to initialize them. Version 6 of ICKDSF knows nothing about device types later than 3350. Of course, you could still utilize the DASDLOAD utility that is supplied with Hercules to create perfectly usable 3375/3380/3390 DASD volumes outside of the MVS environment. But I like to find solutions that allow me to utilize MVS to do everything I need to do related to the operation of the system as it was intended.
Why install version 6 when we have version 13? Well, version 13 has a problem initializing 3350 DASD. So we need both versions of the utility to be able to accomplish everything we might want to accomplish.
I put together FDZ1D02 using the distribution libraries. In fact, the jobstream restores the TLIBs from the product tape, extracts the JCL to link-edit the utility, builds a secondary jobstream and submits it through the Internal Reader to complete the installation. The load module for the utility is placed into SYS1.LINKLIB with the name ICKDSF13, so that it does not replace the original load module which has the name ICKDSF.
This places the responsibility upon you to utilize the correct load module when you are initializing 3375/3380/3390 DASD or any of the earlier models. But I will elaborate on that later on, when we are creating some additional empty DASD volumes to use.
On the command line in the console window where Hercules was started, type the command devinit 12 jcl/fdz1d02.jcl eof and press Enter.
This job will require the product tape, so you will see a IEF238D message on the console (telnet client window):
On the command line in the window where Hercules was started, type the command devinit 170 tape/product.het and press Enter.
On the Starter System console (telnet client window), type r 12,170 and press Enter. Remember, your response number may not be the same as the one seen here in the screen capture from my system.
FDZ1D02 takes 0.59 minutes to run. The expected completion codes are:
Again, there are two jobs that execute with the name FDZ1D02: the first builds the jobstream for the second and submits it, so there are two completely distinct jobs, each with the same name. The first three steps are from the first job and the last two steps are from the second job. All should receive a completion code of 0000, as shown.
Shut Down the Starter System
We have now completed the System Generation and tailoring of the system to the point that it will IPL, so it is time to shut down the Starter System.
It would be a great time to take another snapshot backup. There are now nine DASD volumes in the dasd directory. After you have shut down MVS and Hercules, simply make a copy of them with your favorite archive program - WinZip, PKZIP, tar - or copy them onto a CD-rom blank. Then if you encounter a catastrophic error later, it is simple to come back to this point by restoring your backup copy.
In the telnet client window, type the command $p jes2 and press ENTER. This command instructs JES2 to shut down normally. The following messages will be displayed:
which are issued by JES2 and MVS as JES2 terminates. In the telnet client window, type the command z eod and press ENTER.
This command instructs the MVS operating system to shut down normally. The following message will be displayed:
which indicates the MVS system has reached a point where power down is possible. Note that MVS is still running and additional operator commands might be entered and jobs submitted. But, the object of the "z eod" command is to close all the system files and prepare for an orderly shutdown. In the telnet client window type the command quiesce and press ENTER.
This command instructs the MVS operating system to write any buffers to the DASD devices. This ensures that when you shut down Hercules any information held in memory by MVS is written to the DASD images.
On the command line in the console window where Hercules was started, type the command quit and press ENTER.
Hercules will close all the files for the emulated mainframe devices and terminate. You may close your telnet client.
The next step is to IPL the newly built MVS system for the first time and do some tailoring that may only be done on the system as it is executing. So, when you are ready, proceed to the next step - Customizing Your New MVS 3.8 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:
This page was last updated on November 09, 2015 .