Several people have asked me how I managed to get a mainframe running on my laptop. This post explains how I did that. Enjoy!
### Setting Up The Host Machine
You can run the entire setup from your native workstation, if you want. But that's not what I did. for the sake of portability, compatibility, and stability, I constructed a virtualbox using Debian 12, on which to host the Turnkey package:
* ISO: Debian 12 (64bit)
* CPU(s): 2 (explained in a moment)
* Acceleration: Paging, VT-x/AMD-V, PAE/NX, KVM
* RAM: 1024MB
* Display: Default
* Storage: VDI 60GB
* Network: **Bridged**
The reason for 2 CPUs is because when we set up the TK5 system, it will include two of its own mainframe cpus, and we want to be able to take advantage of that on the host.
The reason for the BRIDGED adapter, is because we want to make the mainframe accessible from other devices on the local subnet. If everything you do is local to the host machine, then a normal NAT connection will also work.
Go through the normal debian installation process. Don't include a desktop environment, because it won't be needed. Make sure to include the ssh server as part of the installation, and make sure you're able to ssh into the the VM from your host:
<preclass="decterm">
gmgauthier@boethius $ ssh sysa
Linux tk5-sysa 6.1.0-23-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.99-1 (2024-07-15) x86_64
The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Jan 14 21:45:05 2025 from 192.168.68.103
</pre>
### Installing Turnkey
Next, you'll want to install the base turnkey package to the root account. You'll be working entirely from root now. Use wget to download the zip file from [Eric Prince's Turnkey Page](https://www.prince-webdesign.nl/images/downloads/mvs-tk5.zip), to the root account. Once there, unzip it in place. your director should now have an `mvs-tk5.zip` file, and an `mvs-tk5` directory:
-rw-r--r-- 1 root root 928 May 30 2023 tk5_updates.cnf
-rwxrwxrwx 1 root root 29360 Dec 7 1998 ZZSACARD.BIN
-rw-r--r-- 1 root root 1026 Aug 4 09:53 zzsa.cnf
-rwxrwxrwx 1 root root 26400 Dec 7 1998 ZZSADIMG.BIN
-rwxrwxrwx 1 root root 26400 Dec 7 1998 ZZSATIMG.BIN
</pre>
Now, edit the `tk5.cnf` file, which is the default configuration (despite the fact that there's already a file by that name). You should see this as the first few lines before the device configs:
Set `CPUMODEL` to `3083`. Then, set `NUMCPU` and `MAXCPU` to `2`. Finally, set `TZOFFSET` to either `+` or `-` the value in hours, relative to GMT. I personally just leave it as-is, because I don't care about the precise time. Once that's all done, the system will be set up to take advantage of both cpus on the virtual host.
Below the basic configuration values, you'll find the "DASD" virtual volume configuration. "DASD" is the IBM acronym for "Direct Access Storage Device", which basically just means magnetic disk. Or, in our case, virtual files that emulate IBM magnetic disk devices.
<preclass="decterm">
#
# TK5 DASD
#
0390 3390 dasd/tk5res.390
0391 3390 dasd/tk5cat.391
0392 3390 dasd/tk5dlb.392
0380 3380 dasd/int001.380
0190 3390 dasd/tso001.190
0191 3390 dasd/tso002.191
0192 3390 dasd/tso003.192
0248 3350 dasd/page00.248
0249 3350 dasd/spool0.249
0290 3390 dasd/work01.290
0291 3390 dasd/work02.291
0292 3390 dasd/work03.292
0293 3390 dasd/work04.293
0298 3390 dasd/tk5001.298
0299 3390 dasd/tk5002.299
</pre>
ALL of these volumes are absolutely necessary for a full system. But the most important volumes are the ones suffixed `RES`, `CAT`, and the `PAGE` and `SPOOL` volumes.
The `RES` Volume stands for "System Resident", and just means all the datasets that need to be loaded directly into memory for system execution. This of this as the conceptual equivalent of a bootstrap directory of a PC.
The `CAT` Volume stands for "System Catalog", and contains an indexed list of all the datasets available on your MVS system. Without this, you would have no way to access data on the system. Think of it as the conceptual equivalent of a VTOC on a PC disk drive.
The `PAGE` volumes are conceptually similar to Swap partitions on a linux machine, and the `SPOOL` volume is actually kind of unique to MVS. It's a place where all program output is queued for distribution to an output device like a printer.
The remaining disk volumes are data disk volumes for storing source code, binary executables, and other forms of data necessary for application programs.
The next batch of lines in the configuration file, are for peripheral devices attached to the mainframe:
The first column sets a device id the system will use to identify the peripheral. The second column is the model of the device, which effectively identifies the *kind* of device. A `1403` is a printer. A `3505` is a card reader. A `3525` is a card punch. Device 0480 is a `3420` tape drive. This will be important to know, when we attempt to apply the supplement tape update to this instance.
By default, all output devices are defined to dump to text files on the host system path for that device ("prt/", "pch/", "log/"). But you will notice that a few have been defined with TCPIP ports instead. The reader device on 000C, for example, is set to port 3505. This will come into play in a further post, on how to submit remote JCL cards to your mainframe, which will make it easy to write and submit JCL from someplace like VSCode!
Note also, tha there are two 1403 Printers defined to localhost:1403 and localhost:1404. These printers will send all of their plain-text output to those ports. A separate post here will explain how to set up linux printer daemons that will produce greenbar PDF files from that output, and ship it to an output directory on your local machine.
Lastly the configuration file sets up our 3270 devices and terminals. These are the way we will "log in" to the system as a human user, and interact with it; writing programs, running programs, looking at output, and other things.
<preclass="decterm">
#
# local 3270 devices (VTAM)
#
00C0 3270
00C1 3270
00C2 3270
00C3 3270
00C4 3270
00C5 3270
00C6 3270
00C7 3287
#
# local 3270 terminals (TCAM)
#
03C0 3270 TCAM
03C1 3270 TCAM
03C2 3270 TCAM
03C3 3270 TCAM
03C4 3270 TCAM
03C5 3270 TCAM
03C6 3270 TCAM
03C7 3270 TCAM
</pre>
For now, that's all we really need to cover in the configuration file. So, let's close out of the file, and `cd` back into the base directory
At this point, there is technically only one other thing that is necessary to get the system going. You will want to do this so that you can interact with the machine directly from the console. `cd` into the "unattended" directory:
Hercules console mode activated for unattended operations mvs
Press any key to continue...
</pre>
Once that's done, return to the base directory. From there, we can launch the system with the `mvs` command, which will load the master console directly:
<preclass="decterm">
root@tk5-sysa:~/mvs-tk5/unattended# cd ..
root@tk5-sysa:~/mvs-tk5# ./mvs
HHC01536W HDL: WARNING: '/usr/local/lib/hercules' is not a valid directory
HHC00007I Previous message from function 'hdl_checkpath' at hdl.c(769)
HHC01413I Hercules version 4.7.0.0-SDL
HHC01414I (C) Copyright 1999-2024 by Roger Bowler, Jan Jaeger, and others
HHC01417I ** The SDL 4.x Hyperion version of Hercules **
You are now at the **Master Console** of an IBM S/370 running MVS 3.8j. A system that, back in 1980, would have cost you approximately $4.7m ($17.9m in current dollars).
HHC00013I '/' input entered for console 0:0009: "d r,l"
d r,l
/23.13.27 IEE111I NO OUTSTANDING REQUESTS
HHC00013I '/' input entered for console 0:0009: "d a,l"
d a,l
/23.13.31 IEE102I 23.13.31 25.018 ACTIVITY 453
/ 00009 JOBS 00006 INITIATORS
/ CMD1 CMD1 CMD1 V=V
/ BSPPILOT BSPPILOT C3PO V=V S
/ JES2 JES2 IEFPROC V=V
/ NET NET IEFPROC V=V
/ TP TP TCAM V=V
/ MF1 MF1 IEFPROC V=V S
/ TSO TSO STEP1 V=V S
/ SNASOL SNASOL SOLICIT V=V
/ JRP JRP JRP V=V
/ 00000 TIME SHARING USERS
/ 00000 ACTIVE 00040 MAX VTAM TSO USERS
herc =====>
</pre>
At this point, most of you will be wondering: "Okay. What now?". Well, now you operate your system. That's what. There is a distinction that needs to be made here. It's not like how we "use" microcomputers today. Back in the day, there was an "operator", and there was a "user". The user was the administrator, the programmer, or the accountant, who just used various programs available to him on his terminal device.
The Operator, however, sat all day long at this console, monitoring system resources, responding to system prompts, mounting tapes, running utility jobs, printing output, and occasionally "IPLing" the system (what we now call 'rebooting').
To know how to operate the system, you need to know a little something about the system. For starters, how do you enter commands, and what are they showing you? For example, how can you see all the things running on the system? For linux users, there's the `ps` command, or `htop` if you prefer something a little more aesthetically pleasing. It's kind of not like that on MVS.
