These tutorials are intended to introduce new hobbyists to the Hercules environment. These tutorials use VM/ESA 2.4.0 available on the Internet Archives as an example but the same patterns may be useful for any other installation.
* NOTE * This environment is highly “opinionated” and prescribes a set up that may not work for your needs. The setup that is prescribed is intended to provide consistency in the documentation and tutorial stages.
Install Hercules as described on the SoftDev Labs (SDL) site.
This software is under active development from the GITHUB repository and the documentation, while marked “obsolete” is still quite excellent.
This configuration assumes that the filesystem is set up as follows:
{Root} ... Command and Configuration Files
├───batch ... Stand-Alone Utilities
├───conf ... Configuration File(s)
│ ├───includes ... Optional/Included Configurations
│ └───_docs ... Local Documentation
├───disks
│ ├───dosvs ...Guest OS Main Disks
│ │ └───shadows ...Guest OS Shadow Disks
│ ├───dosvse
│ │ └───shadows
│ ├───mts
│ │ └───shadows
│ ├───musicsp
│ │ └───shadows
│ ├───mvs
│ │ └───shadows
│ ├───vm370ce
│ │ └───shadows
│ ├───vmesa
│ │ └───shadows
│ └───vseesa
│ └───shadows
├───io ... General I/O Output
│ ├───pun000d ... Punch Device (By CCUU)
│ ├───pun010d
│ ├───rdr000c ... Reader Input (By CCUU)
│ └───rdr010c
├───tapes ... Utility Tapes
├───_direct ... Guest Machine Directory Files
├───_dist ... Distribution Files (Originals)
│ ├───DOSVS
│ ├───DOSVSE
│ ├───hercules
│ ├───vmesa
│ │ └───vmesa.originals
│ │ ├───Compressed.CKD
│ │ └───Uncompressed.CKD
│ └───vseesa
└───_docs ... Supporting Documentation / Reference
├───<GuestOS1>
├───<GuestOS2>
└───<GuestOSn>
The distribution images are assumed to be on CD-ROM (ISO) images.
Listing archive: VMESA_240_ADCD_CD1.iso
System: VM/ESA
Volume: VMESA24DAD1
VolumeSet: VM 2.4.0 A/D 3390 System
Publisher: IBM P/390 Development
Preparer: Jim Ii; John A. Hupcey
Application: P/390 VM/ESA Application Development CD-ROM version 2.4.0
Copyright: README.CKD
Abstract: VMESA24D.AD1
Bib: VM3390.PAC
Created = 1999-09-30 08:00:00
Modified = 1999-09-29 17:00:00
Date Time Attr Size Compressed Name
------------------- ----- ------------ ------------ ------------------------
1999-09-28 06:44:00 D.... AIX
1999-09-27 08:00:00 ..... 10816 10816 AIX\DEVMAP.1VM
1999-09-27 08:00:00 ..... 17830 17830 AIX\DEVMAP.NME
1999-09-27 07:58:00 ..... 5165 5165 AIX\README.AIX
1999-08-25 10:20:00 ..... 40341 40341 INSTALL.CMD
1994-10-11 01:18:00 ..... 23452 23452 PKUNZIP2.EXE
1999-09-30 02:00:00 ..... 13753 13753 README.CKD
1994-08-31 16:01:00 ..... 92723 92723 UNZIP.EXE
1999-09-30 06:15:00 ..... 3207 3207 VM3390.PAC
1999-09-28 06:46:00 D.... VMESA
1999-09-27 04:15:00 ..... 289260272 289260272 VMESA\240RES_1.ZIP
1999-09-27 04:16:00 ..... 49507843 49507843 VMESA\240RES_2.ZIP
1999-09-27 04:35:00 ..... 193760873 193760873 VMESA\240W02_1.ZIP
1999-09-27 04:36:00 ..... 55961342 55961342 VMESA\240W02_2.ZIP
1999-09-27 04:00:00 ..... 4480 4480 VMESA\DEVMAP.1VM
1999-09-29 08:19:00 ..... 5510 5510 VMESA\DEVMAP.N99
1999-09-27 04:00:00 ..... 5467 5467 VMESA\DEVMAP.NME
1999-09-29 08:20:00 ..... 4672 4672 VMESA\DEVMAP.P99
1999-09-27 04:39:00 ..... 38376 38376 VMESA\DISK.MAP
1999-09-27 04:39:00 ..... 9829730 9829730 VMESA\P390NSS.ZIP
1999-09-30 02:00:00 ..... 13753 13753 VMESA\README.CKD
1999-09-09 08:15:00 ..... 491609 491609 VMESA\SDISKADD.580
1999-09-27 04:39:00 ..... 11376 11376 VMESA\SYSTEM.CFG
1999-09-27 04:39:00 ..... 152087 152087 VMESA\USER.DIR
1999-09-30 06:15:00 ..... 3207 3207 VMESA\VM3390.PAC
1999-09-29 08:43:00 ..... 6906 6906 VMESA\VMESA240.IOP
1999-09-27 04:40:00 ..... 14637239 14637239 VMESA\VMPPNSS.ZIP
1999-09-27 03:47:00 ..... 188 188 VMESA24D.AD1
------------------- ----- ------------ ------------ ------------------------
1999-09-30 06:15:00 613902217 613902217 26 files, 2 folders
Listing archive: VMESA_240_ADCD_CD2.iso
System: VM/ESA Volume: VMESA24DAD2 VolumeSet: VM 2.4.0 A/D 3390 System Publisher: IBM P/390 Development Preparer: Jim Ii; John A. Hupcey Application: P/390 VM/ESA Application Development CD-ROM version 2.4.0 Copyright: VMESA24D.AD2 Abstract: VMESA24D.AD2 Bib: VMESA24D.AD2 Created = 1999-09-28 10:30:00 Modified = 1999-09-27 17:00:00 Date Time Attr Size Compressed Name ------------------- ----- ------------ ------------ ------------------------ 1994-10-11 01:18:00 ..... 23452 23452 PKUNZIP2.EXE 1994-08-31 16:01:00 ..... 92723 92723 UNZIP.EXE 1999-09-28 09:13:00 D.... VMESA 1999-09-27 04:16:00 ..... 13900052 13900052 VMESA\240SPL.ZIP 1999-09-27 04:30:00 ..... 330171978 330171978 VMESA\240W01_1.ZIP 1999-09-27 04:31:00 ..... 10277370 10277370 VMESA\240W01_2.ZIP 1999-09-27 04:39:00 ..... 95335986 95335986 VMESA\240W03_1.ZIP 1999-09-27 04:39:00 ..... 10277370 10277370 VMESA\240W03_2.ZIP 1993-12-02 05:59:00 ..... 131584 131584 VMESA\DDR370.IPL 1999-04-24 04:36:00 ..... 110344 110344 VMESA\DDRXA.IPL 1999-08-05 09:12:00 ..... 1067524 1067524 VMESA\ICKDSF.IPL 1999-09-27 03:47:00 ..... 188 188 VMESA24D.AD2 ------------------- ----- ------------ ------------ ------------------------ 1999-09-28 09:13:00 461388571 461388571 11 files, 1 folders
Unzip the contents of BOTH distribution ISOs and position the contents of the following UnZipped files into the _dist folder structure as shown above:
| Name | Container File | Last Write Time | Length |
|---|---|---|---|
| 240RES_1.123 | VMESA\240RES_1.ZIP | 9/24/1999 12:02 PM | 2147397632 |
| 240RES_2.123 | VMESA\240RES_2.ZIP | 9/24/1999 12:02 PM | 699034112 |
| 240SPL.128 | VMESA\240SPL.ZIP | 9/24/1999 12:02 PM | 948810752 |
| 240W01_1.124 | VMESA\240W01_1.ZIP | 9/24/1999 10:24 AM | 2147397632 |
| 240W01_2.124 | VMESA\240W01_2.ZIP | 9/24/1999 10:24 AM | 699034112 |
| 240W02_1.125 | VMESA\240W02_1.ZIP | 8/25/1999 1:53 AM | 2147397632 |
| 240W02_2.125 | VMESA\240W02_2.ZIP | 8/25/1999 1:53 AM | 699034112 |
| 240W03_1.126 | VMESA\240W03_1.ZIP | 8/25/1999 1:53 AM | 2147397632 |
| 240W03_2.126 | VMESA\240W03_2.ZIP | 8/25/1999 1:53 AM | 699034112 |
The uncompressed images are very large and bulky to manipulate, additionally they are unnecessary in their distributed form. To make these more manageable, the images can be compressed at the Operating System level (in the case of Windows) or at the file/container level. Hercules supports a “Compressed Count-Key-Data” virtual device format which we will use for this purpose.
Original DASD Size: 12.3 GB OS Compressed Size: 2.75 GB (Windows 10) Hercules CCKD Size: 0.772 GB
If you already have an existing system and want to include existing shadow files in the new CCKD images:
Assuming this structure:
<your_disk_directory>
| (contains)
+- shadows
|
+- <your shadow files>
You may use the following CMD snippet to convert the base images in <your_disk_directory> combined with the contents of the shadow files into the new CCKD format files.
Hint: Remove @echo once you have the command structure the way you want it.
@for %h in (<your_disk_directory>\*_1.12*) do @echo dasdcopy -z "%h" SF="%~dphshadows\%~nh.shadow" "%~dpnxh.cckd"
If you only wish to compress the distributed files:
@for %h in (<your_disk_directory>\*_1.12*) do @echo dasdcopy -z "%h" "%~dpnxh.cckd"
Example:
Assuming that you are positioned in the directory E:\Uncompressed, executing the
above command string would result in the following enumeration of dasdcopy:
<zterm><nowiki> E:\Uncompressed E>@for %h in (*_1.12*) do @echo dasdcopy -z "%h" "%~dpnxh.cckd" dasdcopy -z "E:\Uncompressed\240RES_1.123" "E:\Uncompressed\240RES_1.123.cckd" dasdcopy -z "E:\Uncompressed\240W01_1.124" "E:\Uncompressed\240W01_1.124.cckd" dasdcopy -z "E:\Uncompressed\240W02_1.125" "E:\Uncompressed\240W02_1.125.cckd" dasdcopy -z "E:\Uncompressed\240W03_1.126" "E:\Uncompressed\240W03_1.126.cckd" </nowiki></zterm>
Note that the inconsistently named file will need to be copied:
dasdcopy -z "E:\Uncompressed\240SPL.128" "E:\Uncompressed\240SPL_1.128.cckd"
Move the COMPRESSED images into the proper DASD file location as previously indicated.
The final resulting folder structure should look like this:
\VMESA\DISKS\VMESA │ 240RES_1.123.cckd │ 240SPL_1.128.cckd │ 240W01_1.124.cckd │ 240W02_1.125.cckd │ 240W03_1.126.cckd │ └───shadows (This directory will be needed in subsequent steps)
continue to Configure Hercules