MVS TK5 is an implementation of OS/VS2 MVS Release 3.8J. The successors to MVS 3.8, MVS/XA, MVS/ESA, OS/390 and z/OS all demonstrate their OS/VS MVS 3.8 heritage.
Building the container is controlled through the Dockerfile found in the root directory of this repository. T
- Dockerized version of SDL-Hercules-390 Version 4.5 (https://github.com/patrickraths/docker-SDL-Hercules-390) used as base image
- TK5 Update 2
The following changes were applied to the default TK5 Update 2 configuration
- Remove embedded Hercules
- Remove all Windows related startup files
- Remove support to run Hercules in unattended (daemon) mode
- Modifed startup files
- Added support for user defined DASD using docker volume
- Building the Docker image
docker build -t mvs-tk5:latest .
When running the container, hercules, the mainframe System/370 emulator, will be started, configured to run MVS 3.8j, and an IPL of TK5 is performed. Once MVS has started, it can be accessed using a TN3270 emulator using port 3270. The Hercules console can be access by connecting to http://localhost:8038 using any web browser.
docker run --name mvs-tk5 -it -p 3270:3270 -p 8038:8038 --cap-add=sys_nice --mount src=mvs-tk5-dasd.usr,target=/opt/tk5/dasd.usr mvs-tk5
| Parameters | Description |
|---|---|
| --name <name> | Name of the container to be created, e.g. mvs-tk5 |
| -it | Attach interactive terminal to view log output |
| -p <host port>:<container port> | Maps ports between host and container Port 3270: Telnet 3270 to access MVS Port 8038 to access the Hecules console |
| --cap-add=sys_nice | Grants the container the CAP_SYS_NICE capability, which allows the container to raise process nice values, set real-time scheduling policies, set CPU affinity, and other operations. |
| --mount src=<volume>,target=/opt/tk5/dasd.usr | Uses the volume specified by <volume> and maps it to the containers file system as specified by target= Creates a volume, e.g. mvs-tk5_dasd.usr and maps it to the containers internal file system as /opt/tk5/dasd.usr to mount additional DASD[^1] that are not part of the system configuration in a persistent storage. By default all DASD are stored in the directory /opt/tk5/dasd, user created DASD should be placed in /opt/tk5/dasd.usr Details on how to create additional DASD and configure MVS to use them can be found in the section Customizing MVS=TK5 |
Loading of MVS-TK5 is completed when the following is shown on the Hercules console:
- Connect to port 3270 on your local host using an 3270 Emulator
- Logon using HERC02 as user and CUL8TR as password
- Accept the welcome messages until you see the ISPF Primary Menu
-
Select 2 (Edit) from the ISPF primary option menu
-
Select SYS1.PARMLIB(PARMTZ)
-
Change the Time Zone setting
Syntax:
D,HH[.MM[.SS]]
Parameters:
"E" or "W" to specify a time zone east or west or Greenwich Mean Time (GMT) HH specifies the number of hours deviation from GMT (00-12) MM specifies the number of minutes. Optional parameter. (00-59) SS specifies the number of seconds. Optional parameter (00-59)
To make the CBT Volumes accessibles submit job **SYS1.SETUP.CNTL(MVS0170) [issue sub on the Command line when viewing/editing the dataset]. This connects the SYS1.UCAT.CBT user catalog to the master catalog and defines the CBT, CBTCOV, CBT072, CBT129, CBT249, CBT429 HLQ as aliases.
Recommendation:
Change MSGCLASS from 'A' to 'H' so that the result of the job can be viewed
There are different DASD types that vary in capacity; typical models as 3330, 3340, 3350, 3380, 3390, etc.
MVS communicates to DASD through addresses. MVS-TK5 has assigned the following address ranges for DASD devices:
In MVS-TK5 the following addresses for DASD Model 3350 are in use:
| Address | Volume |
|---|---|
| 0140 | WORK00 |
| 0148 | MVSRES |
| 0149-014A | SMP001, SMP002 |
| 014B-014C | SMP003, SMP004 |
| 0240-0241 | PUB000, PUB010 |
| 0248 | MVSDLB |
| 0340-0342 | CBT000, CBT001, CBT002 |
| 0343 | CBTCAT |
| For the actual use of addresses refer to the conf/tk5-.cnf file |
-
Create the DASD
For our purpose we want to create the following volume to store user data:Address Model Volume 034A 3350 USR000 To create the DASD image hercules provides a utility called dasdinit. The terminal console of the container can be accessed either by using the Docker Dashboard or by launching a terminal session using
docker exec -it mvs-tk5 /bin/bashand use the following command to create the DASD.dasdinit -z -a /opt/tk5/dasd.usr/usr000.34a 3350 USR000This creates a new DASD of Type 3350 with the Volume name USR000
HHC02499I Hercules utility dasdinit - DASD image file creation program - version 4.5.0.10830-SDL-g58578601-modified
HHC01414I (C) Copyright 1999-2022 by Roger Bowler, Jan Jaeger, and others
HHC01417I ** The SoftDevLabs version of Hercules **
HHC01415I Build date: Mar 28 2023 at 10:51:26
HHC00462I 0:0000 CKD file /opt/tk5/dasd.usr/usr000.34a: creating 3350 volume USR000: 560 cyls, 30 trks/cyl, 19456 bytes/track
HHC00460I 0:0000 CKD file /opt/tk5/dasd.usr/usr000.34a: 560 cylinders successfully written
HHC02423I DASD operation completed -
Attach DASD
In order for MVS to communicate with the DASD it must be attached. To attach the DASD at address 34A in the running configuration use the following command in the Hercules console:attach 034a 3350 dasd.usr/usr000.34a
-
Initalize the DASD Image for use by MVS Although the dasdinit program creates the raw DASD image, MVS requires additional information that is not written by dasdinit. The following JCL initalizes newly created DASD as Volume USR000 using address 34A, and assigns 1 Cylinder (30 Tracks) for the VTOC.
//INITDASD JOB (INITDASD), // 'Initialize DASD', // CLASS=A, // MSGCLASS=H, // MSGLEVEL=(1,1) //******************************************************************** //* //* Name: (DEFCAT) //* //* Desc: Initializes a DASD for use with MVS //* //******************************************************************** //STEP1 EXEC PGM=ICKDSF,REGION=4096K //SYSPRINT DD SYSOUT=* //SYSIN DD * INIT UNITADDRESS(34A) NOVERIFY VOLID(USR000) OWNER(HERCULES) - VTOC(0,1,30) //You will be asked to confirm that you actually want to initialize the volume at the address specified:
*00 ICK003D REPLY U TO ALTER VOLUME 34A CONTENTS, ELSE T
The reply of U allows the initialization to proceed. There will be a number of informational messages printed in the SYSPRINT output during the executing of ICKDSF. The most important thing to verify is that the return code for the job is 0000.
-
Set the volume online and mount it with the appropriate storage use class
After the volume is initialized, it must be placed online before MVS will be able to allocate the volume to allow jobs to create datasets on it. On the MVS console issue the command/v <address>,online`
After the volume is set online it must be mounted.
/m 34a,vol=(sl,usr000),use=private
By using use=private new datasets will be created on this volume only if the user (via JCL or the TSO ALLOCATE command) specifies the volume serial of this disk volume.
-
Add the new volume to the MVS & Hercules configuration so it will be mounted automatically
-
Edit MVS Configuration
By modifying SYS1.PARMLIB(VATLST00) MVS will be instructed to automatically mount the volume, if accessible, and assign storage class 2 (Private)USR000,0,2,3350 ,N User Volume 1
-
Edit Hercules Configuration
Modify the file usr_dasd.cnf in the folder /opt/tk5/dasd.usr to automatically attach the newly created dasd at address 34a. This file is referenced as include in the MVS-TK5 base configuration file (/opt/tk5/conf/tk5-.cnf)# # User Added DASD # 034a 3350 dasd.usr/usr000.34aTo modify the file use the Docker Dashboard or use the following command to edit it
docker exec -it mvs-tk5 nano /opt/tk5/dasd.usr/usr_dasd.cnf
-
-
Set Up User Catalogs
Generally, when adding new storage space to the system, it is also a good time to think about how that storage space will integrate with the catalog structure in place for the system.During System Generation, a VSAM Master Catalog was created. It resides on MVSRES and the dataset name of the catalog itself is SYS1.VSAM.MASTER.CATALOG. Although any new datasets you created can be catalogued in the Master Catalog, it is not considered a good practice and would undoubtedly not be allowed in any real world shop.
To create a User catalog called UCUSR000 that resides on the new volume USR000 that will be connected to the master catalog, submit the following JCL:
//DEFCAT JOB (DEFCAT), // 'Define User Catalog', // CLASS=A, // MSGCLASS=H, // MSGLEVEL=(1,1) //******************************************************************** //* //* Name: (DEFCAT) //* //* Desc: Defines a User for the volume(s) specified by //VOL1 //* and create a user catalog on the voluem specifice in the //* VOLUME (xxxxxx) parameter in DEFINE USERCATALOG. //* //* After creating the User catalog, define an alias for all //* DNS with the High level Qualifer specified in NAME(xxxxx) //* and relate it to the User catalog //* //******************************************************************** //STEP1 EXEC PGM=IDCAMS,REGION=4096K //SYSPRINT DD SYSOUT=A //VOL1 DD VOL=SER=USR000,UNIT=3350,DISP=OLD //SYSIN DD * DEFINE USERCATALOG - (NAME (UCUSR000) - VOLUME (USR000) - CYLINDERS (20) - FOR (9999) - BUFFERSPACE (8192) ) /* Define Alias for all dataset start with PRATHS */ DEFINE ALIAS(NAME(PRATHS) RELATE (UCUSR000) ) //
When a volume is brought into the system from a prior functioning system that has its own User Catalog on the volume, the volume must be attached, added to the MVS configuration, and the catalog connected to the master catalog
-
Copy DASD file
Copy the DASD file to /opt/tk5/dasd.usr directory, respectively run docker usingdocker run --name mvs-tk5 -it --mount src=mvs-tk5_dasd.usr,target=/opt/tk5/dasd.usr -p 3270:3270 -p 8038:8038 mvs-tk5:latestwith a docker volume that already contains the DASD files -
Attach the DASD file mount the volume
- Attach DASD & mount it Attach the DASD using the following command in the MVS console:
attach 034a 3350 dasd.usr/usr000.34aOnce the DASD is attach, set it online using
/v 34a,onlineand mount it/m 34a,vol=(sl,usr000),use=private -
Modify the MVS configuration to automatically mount the DASD
-
Edit MVS Configuration
By modifying SYS1.PARMLIB(VATLST00) MVS will be instructed to automatically mount the volume, if accessible, and assign storage class 2 (Private)USR000,0,2,3350 ,N User Volume 1
-
Edit Hercules Configuration
Modify the file /opt/tk5/dasd.usr/usr_dasd.cnf to automatically attach the newly created dasd at address 34a. This file is referenced as include in the TK5- base configuration file (/opt/tk5/conf/tk5-.cnf)# # User Added DASD # 034a 3350 dasd.usr/usr000.34a
-
-
Import existing Catalog
As the existing volume already contains a User Catalog it must be imported and connected to the master catalog using://IMPCAT JOB (IMPCAT), // 'Import User Catalog', // CLASS=A, // MSGCLASS=H, // MSGLEVEL=(1,1) //******************************************************************** //* //* Name: (IMPCAT) //* //* Desc: Imports an existing User catalog and creates alias(es) //* //******************************************************************** //STEP1 EXEC PGM=IDCAMS,REGION=4096K //SYSPRINT DD SYSOUT=A //VOL1 DD UNIT=3350,DISP=OLD,VOL=SER=USR000 //SYSIN DD * IMPORT CONNECT OBJECTS((UCUSR000 VOLUME(USR000) DEVT(3350))) DEFINE ALIAS(NAME(PRATHS) RELATE(UCUSR000)) //
The following is an example of the compose.yaml file to run mvs-tk5. In addition to the volume for user defined DASD additional volumes are being used for the following devices for easier access and to to minimise run-time changes to the container.
| Device | Description | Location in TK5 file system |
|---|---|---|
| User DASD | User defined DASD as described above | /opt/tk5/dasd.usr |
| Logs | TK5 Log files | /opt/tk5/log |
| Tape | Tapes | /opt/tk5/tape |
| Printer | Printer spool files | /opt/tk5/prt |
| Punch | Card Reader | /opt/tk5/pch |
#
# Define services
#
services:
tk5:
image: praths/mvs-tk5:latest
container_name: mvs-tk5
stdin_open: true # docker run -i
tty: true # docker run -t
cap_add:
- SYS_NICE
network_mode: bridge
ports:
- 3270:3270
- 8038:8038
volumes:
- dasd.usr:/opt/tk5/dasd.usr
- log:/opt/tk5/log
- tape:/opt/tk5/tape
- prt:/opt/tk5/prt
- pch:/opt/tk5/pch
restart: no
volumes:
#
# System DASD
#
dasd.sys:
#
# User DASD
#
dasd.usr:
driver: local
driver_opts:
type: 'none'
o: 'bind'
device: '/home/user/tk5/dasd.usr'
#
# System Logs
#
log:
driver: local
driver_opts:
type: 'none'
o: 'bind'
device: '/home/user/tk5/log'
#
# Tape Devices
#
tape:
driver: local
driver_opts:
type: 'none'
o: 'bind'
device: '/home/user/tk5/tape'
#
# Printers
#
prt:
driver: local
driver_opts:
type: 'none'
o: 'bind'
device: '/home/user/tk5/prt'
#
# Card Readers
#
pch:
driver: local
driver_opts:
type: 'none'
o: 'bind'
device: '/Users/praths/Documents/tk5/pch'