praths/mvs-tk5 repository overview

⁠MVS 3.8j - TK5 Update 4

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.

This repository contains the TK5 Update 2⁠ implementation provided by Rob Prins for ARM64 platforms using SDL-Hercules-390

⁠Changes to TK5 Update 4

• Replace embedded Hercules with current version of SDL-Hercules-390⁠
• Added support for user defined DASD (Direct Access Storage Device i.e., external disks) using docker volume

⁠Running TK5 as container

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.

⁠Downloading and running TK4 for the first time

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 praths/mvs-tk5

Loading of MVS-TK5 is completed when the following is shown on the Hercules console:

⁠Login to MVS-TK5

• 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
  

⁠Customizing TK5

⁠Changing the Timezone

• 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)

  

⁠Enabling the CBT Catalogue

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

⁠Adding User DASD

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:

⁠Create and configure a user DASD

1. 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/bash and use the following command to create the DASD.

   dasdinit -z -a /opt/tk5/dasd.usr/usr000.34a 3350 USR000
   

   Copy

   This 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
   

2. 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
   

   Copy
   

3. 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)                                           
   //                                                                    
   

   Copy

   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.

   

4. 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`
   

   Copy
   

   After the volume is set online it must be mounted.

   /m 34a,vol=(sl,usr000),use=private
   

   Copy
   

   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.

5. 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 
     

     Copy
     

   • 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.34a
     

     Copy

     To 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
     

     Copy

6. 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) )             
   //                                                             
   

   Copy

⁠Connecting an existing volume to a system

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

1. Copy DASD file
   Copy the DASD file to /opt/tk5/dasd.usr directory, respectively run docker using docker run --name mvs-tk5 -it --mount src=mvs-tk5_dasd.usr,target=/opt/tk5/dasd.usr -p 3270:3270 -p 8038:8038 mvs-tk5:latest with a docker volume that already contains the DASD files

2. 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.34a
   

   Copy

   Once the DASD is attach, set it online using /v 34a,online and mount it /m 34a,vol=(sl,usr000),use=private

3. 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 
     

     Copy
     

   • 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
     

     Copy

4. 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))                         
   //
   

   Copy

⁠Running TK5 as a docker service using Docker Compose

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.

#
# 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'