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
- TK4 Update 8
The following changes were applied to the default TK4- Update 8 configuration as available on https://wotho.ethz.ch/tk4-/
- 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 tk4:latest .
When running the container, hercules, the mainframe System/370 emulator, will be started, configured to run MVS 3.8j, and an IPL of TK4- 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.
It is recommended to create separate DASDs (Direct Access Storage Device) to store data on MVS that is not part of the standard TK4- configuration. While by default all DASD are stored in the directory /opt/tk4/dasd, user created DASD should be placed in /opt/tk4/dasd.usr which is configured as docker volume to allow for persistent storage.
Details on how to create additional DASD and configure MVS to use them can be found in the section Customizing TK4-
To run TK4- in a container requires that the container is started with the correct options:
--name tk4 assigns the name tk4 to the container. If omitted, docker will be assign a random name. For the purpose of this documentation, the container is referred to as tk4
--it runs the container interactive and assigns a terminal (tty). This allows to access the hercules console not only through the web interface but directly in a terminal session. If this option is omitted, TK4- will be started an the hercules console can be accessed through the web interface on http://localhost:8038
--mount src=tk4-dasd,target=/opt/tk4/dasd.usr creates or connects an existing volume named tk4-dasd and mounts it as /opt/tk4/dasd.usr inside the container.
-p 3270:3270[^1] exports port 3270 of the container on the host using the same port number
-p 8038:8038 exports port 8038 of the container on the host using the same port number
Note:
By reassigning ports 3270, respectively 8038 to different ports on the host it would be possible to run multiple instances of TK4- in parallel, each of which can be accessed using a different port number. Should another container already be using any of these port numbers it cannot be launched using the default port numbers.
- Default TK4 configuration
docker run --name tk4 -it --mount src=tk4-dasd,target=/opt/tk4/dasd.usr -p 3270:3270 -p 8038:8038 praths/tk4 - Rob Prins' enhanced TK4 edition
docker run --name tk4.rob -it --mount src=tk4-dasd,target=/opt/tk4/dasd.usr -p 3270:3270 -p 8038:8038 praths/tk4:rob
Loading of TK4- is completed when the following is shown on the Hercules console:
To change the timezone modify SYS1.PARMLIB(PARMTZ)
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. However, TK4- does not support DASD models later than than 3350. In this example a DASD of type 3350 is created which provides a capacity of approximately 300MB.
MVS communicates to DASD through addresses. TK4- has assigned the following address ranges for DASD devices:
In TK4- 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/tk4-.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 tk4 /bin/bashand use the following command to create the DASD.dasdinit -z -a /opt/tk4/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/tk4/dasd.usr/usr000.34a: creating 3350 volume USR000: 560 cyls, 30 trks/cyl, 19456 bytes/track
HHC00460I 0:0000 CKD file /opt/tk4/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/tk4/dasd.usr to automatically attach the newly created dasd at address 34a. This file is referenced as include in the TK4- base configuration file (/opt/tk4/conf/tk4-.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 tk4 nano /opt/tk4/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/tk4/dasd.usr directory, respectively run docker usingdocker run --name tk4 -it --mount src=tk4-dasd,target=/opt/tk4/dasd.usr -p 3270:3270 -p 8038:8038 tk4:latestwith a docker volume that already contains the DASD files -
Attach the DASD file mount the volume
- Attach DASD & mount it Attach the DASE 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/tk4/dasd.usr/usr_dasd.cnf to automatically attach the newly created dasd at address 34a. This file is referenced as include in the TK4- base configuration file (/opt/tk4/conf/tk4-.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)) //