Installing MVS 3.8
Gathering Materials and Creating DASD Volumes
Required 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.org/ - and you can download precompiled versions for Windows from Ivan Warren's site - http://www.ivansoftware.com/. Ivan's site provides almost daily snapshots so you can choose to remain safe with a stable release or right on the bleeding edge with the developers. 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 earlier versions which will prevent successful generation and use of MVS 3.8. This revision of my instructions is being written using release 3.05 built 23 June 2007.
If you are running on a version of the Windows operating system, you no longer need the Cygwin package. The current Windows' version 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.
2. the MVS starter system and MVS 3.8j distribution tapes,
The starter system is contained on three 3330 DASD volumes. The MVS 3.8j distribution is contained on six AWS tape images. On one site, the starter system is in an archive labeled mvsstarter.tar and the distribution tapes are in an archive labeled mvsdlibs.tar.
These are significant sized files to download (between 13 and 20 megabytes each, depending upon the compression method), so you may want to consider ordering a CD-ROM from Sam Knutson, who is the maintainer for the CBT Tape web site (http://www.cbttape.org/cdrom.htm).
In order to install MVS 3.8j, it is only necessary to have two of the six tape images. As the number of sites where these tape images were available for download continued to decline, during a previous revision of these instructions I opted to make the two required tape images available for download from my site. The archives are http://www.jaymoseley.com/hercules/download/zips/mvsstarter.tgz (6.23 MB) [MD5: AA0B033DF00F903CF9A557F9BFC03EED] and http://www.jaymoseley.com/hercules/download/zips/mvsdist.tgz (15.5 MB) [MD5: C8D06A30CF6E8FE3BE1847AFAA5646C5].
3. my installation jobstreams, AWS images, and scripts archive.
This archive contains scripts, configuration files, MVS jobstreams, and AWS tape images. 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. Because of the difference in record termination convention in text type files between Windows and Linux, I provide this archive in two versions. The Windows version - http://www.jaymoseley.com/hercules/download/zips/installmvs.zip (435 KB) [MD5: 381D4968CFA58EEF35675D30ABF68498] - and the Linux version - http://www.jaymoseley.com/hercules/download/zips/installmvs.tgz (429 KB) [MD5: 93DE12BB7DD5697F8470F18BE3223552]. Note: the content of these archives is essentially identical -- you only need to download the one that is correct for your host Operating System.
Although not required, the base program directory for MVS 3.8j is an interesting read, and it is available from the Hercules' group files section at: http://groups.yahoo.com/group/hercules-390/files/mvs38bas.zip This is the documentation that accompanies the product tapes distributed from IBM and contains detailed information about what is contained on the tapes.
Environment
My instructions are intended 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 excellent instructions, written by Jay Maynard, at the Hercules' home site - http://www.hercules-390.org/.
On my Windows/2000 system I installed the Hercules' distribution in its own directory, appropriately named /hercules. The installer created several subdirectories for the various types of files included in the distribution under the main directory. All of the executables necessary to run Hercules and its utilities are contained in the /hercules/bin directory. Under Linux, the Hercules' executables are installed in /usr/bin; the dynamic libraries in /usr/lib and /usr/lib/hercules; sample configuration files in /etc/hercules; and the IPLable card deck for the ZZSA standalone utility will be placed in /var/share/hercules.
On my computer I start Hercules under Windows/2000 from a desktop shortcut that invokes a command file (.BAT extension) that first modifies the path to include the /hercules/bin directory. The command file contains the following statement:
path=e:\hercules\bin;%path%;
Note that although I installed on drive e on my system, you may install on any drive with the required space available on your system.
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.
If you have other mainframe operating systems installed (or plan to do so in the future) - MVT, VM, DOS/VS, Linux/390 - 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.
When I created my installation archive (installmvs), the files it contains were pulled from this directory structure. So, the files from the /jcl and /tape directories contain relative path information that will place them back into those directories, if the archive is extracted to the /mvs directory. The script and configuration files will extract into the /mvs directory.
When I start Hercules, I always ensure that my working directory is the /mvs subdirectory of the hercules main directory (as shown above). This way, all of the relative path references in the configuration files will be correct.
I have received feedback stating that this archive (installmvs) is confusing. So to alleviate possible confusion, the complete contents of this archive, along with relative directories to which the files should be extracted, is:
files which should be restored to the /mvs directory: condcode.pl ibcdasdi.cnf mvsdasd.bat sysgen.cnf ibcdasdi.00c mvs.cnf smp.cnf files which should be restored to the /jcl directory: az58122.jcl smpjob01.jcl smpjob06.jcl sysgen04.jcl writeipl.jcl ickdsfg.jcl smpjob02.jcl sysgen00.jcl sysgen05.jcl sgnreset.jcl smpjob03.jcl sysgen01.jcl sysgen06.jcl smp4p44.jcl smpjob04.jcl sysgen02.jcl sysgen07.jcl smpjob00.jcl smpjob05.jcl sysgen03.jcl sysgen08.jcl files which should be restored to the /tape directory: ibcdasdi.het mvs38jptfs.het
Checking MVS Completion Codes
Every batch job or started task that executes under MVS returns a completion 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. However you must never modify the file while Hercules is running. 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 (condcode with no extension in the Linux version) - which you may use to display the step completion codes for any job. Of course you will need Perl installed on your system to use it. The command line syntax for the program is:
condcode.pl <print file name> <MVS job name>
If you are following the directory structure I have suggested, the program should be executed from the mvs/ directory and the output from the program will be displayed on the console. 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.
Creating DASD Volumes
During the SMP and System Generation process, you will be creating MVS datasets on five 3350 DASD (Direct Access Storage Device) volumes. A utility is included with Hercules - dasdinit - which builds mainframe DASD volume images. I have included a script - mvsdasd.bat in the installmvs.zip archive or mvsdasd in the installmvs.tgz archive - that will use the Hercules' dasdinit utility to create the five 3350 DASD volumes.
Execute the script from the /mvs directory. The console output of the script, on my Windows 2000 system, is shown below:
The Windows and Linux versions of the script are not identical, simply because of the different scripting capabilities of the two Operating Systems. However, the DASD images created for Hercules are identical. The output from the Linux version of the script, executed on my Debian system is shown below:
My thoughts on compressed DASD - Quite a few releases back, Hercules gained
the ability to utilize compressed MVS DASD images. This allows even the
very large 3390 type DASD to occupy a reasonably small space in the host
operating system file. Data is automatically uncompressed during MVS read
operations and compressed during MVS write operations. The compression
system also has the ability to make the base file read only with any
updates to the data stored in shadow files. A number of people
regularly use compressed DASD with absolutely no problems, and there is
continual improvement in the compression algorithms and features available for
use with compressed DASD. I have chosen to utilize non-compressed DASD,
both because I have the hard drive space available and because there is a
tradeoff in performance to achieve the reduced host file system space.
"... If you use compressed dasd, particularly using bzip2, then the cpu overhead of all the compression/decompression is noticeable. Interestingly, in some circumstances it has been noted that the cpu overhead offsets the hard drive latency in a single processor machine. That is, by transferring less data to/from the hard drive but spending cycles doing compression/decompression results in a faster elapsed time ..." posted by Greg Smith, 5 July 2003
If you wish to utilize compressed DASD, it is only necessary to add one option (-z) to the dasdinit utility lines above. Once the DASD images have been compressed Hercules will automatically maintain the compression. For more information, execute the dasdinit utility with no parameters. Also be aware that you can convert the DASD images from/to compressed format at any time utilizing the Hercules' dasdcopy utility.
Initializing the DASD Volumes for MVS
Although the dasdinit utility creates the DASD images, it does not create all the control information on the DASD image that MVS will require. Specifically, it does not create a Volume Table of Contents (VTOC) which is the structure in which MVS records information about datasets created on the volume.
There is a stand-alone DASD initialization program - IBCDASDI - included in the distribution materials from IBM. You will use this program to initialize and write the VTOCs on all five of the 3350 DASD volumes. The files included in the installmvs archive required for this step are:
File
Directory
Contains
ibcdasdi.cnf /mvs Hercules' configuration information file ibcdasdi.00c /mvs job control statements ibcdasdi.het /mvs/tape stand-alone program on unlabeled tape image
The hardware environment defined in the Hercules' configuration file - ibcdasdi.cnf - is:
Open a console window (Linux) or an MS-DOS Command Prompt window (Windows) and start hercules from the /mvs directory:
Remember that location of the Hercules' binaries must be included in the PATH prior to attempting to execute Hercules.
In another window, start a telnet client and connect to localhost at port 3270. This session will be used by the stand-alone disk initialization program as the console at device address 009. Note: You must use a telnet client, not an x3270 client, to connect to the console port for the stand-alone disk initialization utility.
* * * * * * * Windows/2000 * * * * * * *
There have been several discussions on the Hercules' list about the inability of the Windows/2000 telnet client to successfully connect with Hercules. Three solutions that I am aware of:If you have access (legally and physically) to a Windows/NT 4.0 system, the telnet client included may be copied onto Windows/2000 and will work fine.
Hyperterminal, included with Windows/2000 will work. It may expose your computer to a security risk, so if you use it, you should visit Microsoft's web site to learn more and possibly download the patch to fix Hyperterminal.
Download Tera Term - ttermp23.zip [MD5: CDE2C5A58662002C5CA79B7BC5C198B7] - a free telnet client that will work fine with Hercules. On the Connection settings window, change Host to localhost and port# to 3270; on the Settings->Terminal window, change Transmit to CR+LF and check the local echo box.
At this point, your telnet client window should display information very similar to:
IPL from device 280 (the tape containing the stand-alone disk initialization program - tape/ibcdasdi.het). In the Hercules command window, type the command:
ipl 0280
and press ENTER. When the program load is complete, Hercules will enter a wait state and the right most halfword of the PSW will contain FFFF:
In the telnet window, press ENTER. The program will display:
Respond to this prompt by typing:
input=1442,00c
and press ENTER. This is instructing the disk initialization program to read control statements from device type 1442 (the card reader) at device address 00c. The configuration file is already set up to point the card reader to the file containing the control statements, so the program will read the statements and process them. There are five volumes to initialize, and the control statements for all five volumes are stacked back-to-back in the file. The program will read all the statements and process them without further intervention. A log of the entire session on the console should appear almost identical to this:
When the program has completed processing the five jobs, Hercules will enter a wait state and the right most halfword of the PSW will contain EEEE. In the Hercules command window, type the command:
quit
and press ENTER to terminate Hercules.
Unpacking the Starter System
The MVS starter system is a very compact (limited) version of MVS 3.7. The archive that contains the MVS starter system contains quite a few files, including the distribution tape images from IBM which can be used to build the starter system DASD images. Jay Maynard, who was the creator of this archive, has already built the DASD images. All you need to extract from the archive in order to use my instructions here are the three 3330 DASD images:
- start1.150
- spool0.151
- work01.152
In all the copies of the mvsstarter.tar archive I have encountered, these
three files are contained in internal gzipped tar files. If you utilize
the archive contained on my site, these are the only three files contained in
the archive. Extract them into the /dasd directory.
Unpacking the Distribution Tapes
If you have obtained an archive containing all of the distribution library materials from IBM, it should include six tape image files. You only need two of those -
- smp4[.aws or .het extension, depending upon the author of the archive] which contains the SMP load modules and procedures
- zdlib1[.aws or .het extension] which contains the MVS 3.8j distribution
If you utilize the archive contained on my site, these are the only two files contained in the archive. Extract these two files into the /tape directory. Depending upon where you download these files, the extension will be either .aws or .het; both designate AWS tape image files; the .het extension designates that the file is compressed. For a thorough understanding of emulated tapes under Hercules, see the excellent document prepared by James Campbell at http://groups.yahoo.com/group/hercules-390/files/herctape-0-1a.html.
Rob Storey has written a very handy AWS tape browser which is available for download at http://groups.yahoo.com/group/hercules-390/files/Awsbrows.zip. Unfortunately, it will only function on Windows platforms, so if you are running under Linux, BSD, etc, this tool will not be available to you. However the Hercules utilites hetmap and tapemap, both included in the Hercules' distribution, can be used to investigate the contents of any AWS tape image file.
Installing SMP4 on the Starter System
The program used to reload the MVS 3.8j product tape onto DASD is SMP4 (System Modification Program Release 4). The AWS tape labeled smp4 contains version 4.22 of this program. Unfortunately, version 4.24 is required to successfully reload MVS 3.8j. So it is necessary to extract the components of SMP4 from the product distribution tape (labeled zdlib1). There are procedure library members on the smp4 tape that must be restored to the procedure library, so you will still need the smp4 tape image.
The files included in the installmvs archive required for this step are:
File
Directory
Contains
smp.cnf /mvs Hercules' configuration information file smp4p44.jcl /mvs/jcl job control statements
You will start Hercules with the configuration file required for the SMP phase of the installation, then retrieve and install the SMP4 program into the load library of the MVS starter system. The hardware environment defined in the Hercules' configuration file - smp.cnf - is:
It is time to IPL the starter system. Open a console window (Linux) or an MS-DOS Command Prompt window (Windows) and start hercules from the /mvs directory:
In another window, start a telnet client and connect to localhost at port 3270. This session will be used by the starter system as the console at device address 01f. Remember: You must use a telnet client, not an x3270 client, to connect to the console port for the MVS starter system.
IPL from device 150 (the 3330 DASD containing the MVS starter system - dasd/start1.150). In the Hercules command window, type the command:
ipl 0150
and press ENTER. In the telnet window, you should see:
Since this is the first time the MVS starter system has been loaded, you need to type (in the telnet client window):
r 0,clpa
and press ENTER. Note that there is a space between the r and the numeral zero in this response. This reply tells MVS that it needs to rebuild a set of load modules that it retains in the paging files from the system load library (the Link Pack Area). It will take a few seconds and then you should see:
This message is from JES2 (Job Entry System 2). The asterisk (*) preceding the message indicates that the system requires a reply and the 00 following the asterisk is the number that needs to be entered to allow the system to associate your reply with the outstanding message. [The reply number that is displayed is incremented by the system each time a response is required, so the number displayed on your console may not always match the number I show in these instructions!] The leading zero of the reply number may be omitted when you type your responses. You should type:
r 0,format,noreq
and press ENTER. Note that there is a space between the r and the numeral zero in this response. This reply tells JES2 to format the spool area (since this is the first time JES2 has been started on this system, it has never been formatted), and that JES2 is to start operation without waiting for startup commands. You should then see:
This message is also the result of this being the first time JES2 has been started with these Spool files. You should type:
r 1,y
and press ENTER. Note that there is a space between the r and the numeral one in this response. JES2 will complete initialization and you will see:
at which point the system is ready to process jobs and service operator commands. Before submitting jobs, there is one command that should be issued to reserve the volume SMP001. During the IPL procedure, MVS utilizes a parameter list to assign all mounted DASD volumes to storage classes. Any volumes not specifically included in this list are assigned to the default class of PUBLIC. You have added a couple of volumes that won't be included in this list - SMP001 and WORK02. WORK02 is intended to be used as a public "work" volume, but SMP001 was created to contain the distribution libraries. So, you need to tell MVS to reserve it for that exclusive purpose. On the telnet client window, type the command:
m 148,vol=(sl,smp001),use=private
and press ENTER. Note that there is a space between the m and the numeral one in this response. There will be some informational messages displayed as the MOUNT task is started, but none of the messages should require a response. If you wish to verify that the mount completed successfully, open the file to which Hercules' is writing the output from MVS/JES2 PRINTER1 (the 1403 printer attached to address 00e in the Hercules' configuration file) with a text editor or text viewing program. If you are following my directory structure, the file will be found in the /mvs directory and will be named prt00e.txt. Be careful that you do not alter the contents of the file if you open it with an editor. You may also use the PERL program I supplied in installmvs archive - condcode.pl - to view the completion code; use the job name mount. The completion code from the mount task should be 0000 and will appear in the prt00e.txt file as a line identical to:
IEF142I MOUNT 148 - STEP WAS EXECUTED - COND CODE 0000
or, if you use condcode.pl:
Now you are ready to submit the first job.
Peter Stockdill posted a job to the Hercules' group files area that will create the necessary SMP load modules and procedures from the two distribution tapes - zdlib1 and smp4b. The JCL for that job is contained in the file - smp4p44.jcl. To submit the job to MVS, on the Hercules' command window, type the command:
devinit 012 jcl/smp4p44.jcl eof
and press ENTER. This command causes Hercules to initialize device 012 (the 3505 card reader) to point to the file containing the jobstream - smp4p44.jcl in the jcl directory. The eof parameter instructs Hercules to set the end of file indicator when the contents of the file have been completely read in. A series of messages will be displayed as the job is read in and begins processing:
The asterisk in front of message IEF238D indicates operator decision and action is required by MVS. The particular message encountered here changed as of release 3.01 of Hercules; in prior releases the tape drive at address 170 was detected during IPL as being online and the message issued was a tape mount request. This message is asking for a tape device to be made available (varied online) to the operating system; step S1 of the job is attempting to open an existing file on a tape with the volume serial number MVS38J. I know from the Base Program Directory that this is the product tape - zdlib1. So, in the Hercules command window, type the command:
devinit 170 tape/zdlib1.het
and press ENTER. This command causes Hercules to initialize device 170 (the 3420 tape drive) to point to the file containing the required AWS tape volume - zdlib1.het in the tape directory. Note: If you have a non-compressed tape, the extension will be .aws rather than .het. The tape is now ready to be read by the starter system, so in the telnet window (on the MVS starter system console), type the command:
r 2,170
and press ENTER to instruct MVS to utilize the tape drive at address 170. Note that there is a space between the r and the numeral two in this response. The program will process the tape, the tape will be unloaded, and you will see another series of messages:
The IEC502E message is informing you that the program has finished with the tape on 170; it has been dismounted and is to be kept. The IEC501A message is informing you that a new tape is required by the job - specifically, it is requesting that on the drive at address 170 the job requires an existing tape with the volume serial number T74172 to be mounted. This time, the tape required is the one contained in the AWS (or HET) image file smp4. In the Hercules command window, type the command:
devinit 170 tape/smp4.het
and press ENTER. This command causes Hercules to initialize device 170 (the 3420 tape drive) to point to the file containing the required AWS tape volume - smp4.het in the tape directory. Note: If you have a non-compressed tape, the extension will be .aws rather than .het. The program will process the tape, the tape will be unloaded, and you will see another series of messages:
The $HASP395 message indicates that the processing for the job has been completed. The $HASP150 message indicates that the printed output of the job is being written to the host operating system file assigned to PRINTER1 (the 1403 printer attached to address 00e). For jobs with large output, this can take several seconds. The $HASP250 message indicates that all output processing for the job has been completed.
After the print output from a job has been written to the host operating system file attached to the printer - prt00e.txt - you should view this file to ensure that all steps of the job completed successfully, either with no error messages or with acceptable and expected messages. In the case of this job, each step should complete with a completion code of zero. The three lines in the output which indicate this are:
IEF142I SMP4P44 S1 - STEP WAS EXECUTED - COND CODE 0000 IEF142I SMP4P44 S2 - STEP WAS EXECUTED - COND CODE 0000 IEF142I SMP4P44 LK S3 - STEP WAS EXECUTED - COND CODE 0000
or, if you use condcode.pl:
If you receive a completion code other than expected, on this or any MVS job, you will need to determine the cause of the error(s), correct the condition causing the error, possibly back out partial modifications made by the failing job, and resubmit the job. These steps must be repeated until acceptable completion codes indicate successful completion of a job. If you proceed with subsequent jobs after a job which encountered errors, you are probably wasting your time. The resulting system may be unstable or completely unusable.
Among the first set of messages printed for job SMP4P44, there was an informational message printed on the console from commands embedded in the JCL:
$HASP104 SMP4P44 ****************************************************** $HASP104 SMP4P44 * An IPL is required after this job has completed!!! * $HASP104 SMP4P44 ******************************************************
In order to execute the load module for SMP4 which has been added to the system load library of the MVS starter system, it is necessary to shut down and re-IPL the starter system. 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:
IEE334I HALT EOD SUCCESSFUL
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. Type the command:
quiesce
in the telnet client window 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. In the Hercules command window, type the command:
quit
and press ENTER. Hercules will close all the files for the emulated mainframe devices and terminate.
The next step is the relatively long process of building the distribution libraries from the product tape. So, when you are ready, proceed to the next step - Using SMP4 to Build the Distribution Libraries.
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 23, 2008 .