Kategorie: COBOL on Host Beitraege

...Installing a "Transaction Monitor"

When I first heard of someone talking about COBOL online programs they always used the term "transaction monitor" and CICS. Me, as a java developer, was wondering why monitoring a database transaction is so important for the development of the 3270-Screens. As I learned now, I couldn't be more wrong!

In "Jurassic Park" a "Monitor" is neither a Device to show some UI on a screen nor a program that helps you to analyze the control flow of a program. A Monitor is more of some kind of system. (As far as I understood. But let me know if I'm wrong). And CICS is one of the very first implementations of such a system to handle user Input in a transactional way. All the old systems, that makes the world turn in the 60s to today are developed with this transaction monitor CICS.

So CICS is in the conceptional view very similar to Jakarta EE or a REST Controller. It is the way you handle user input and processes it in an "All or Nothing" transactional way.

Since CICS is a commercial product and is not free to the public there is now (legal) way to get it run on a Hercules emulator. But there is a free alternative that is somehow compatible with CICS. At least on the API Level. This alternative is KICKS!

The installation process of KICKS is quite complicated. The youtuber moshix made a nice video, that you can follow up and you will have a running KICKS-System on your Hercules-driven MVS/TK4 Mainframe.
When you done with the video, you should be able to start the KICKS-Transaction-Monitor under the user HERC01

But I want to use it under my own user ID and that needs a little extra work. As the KICKS-Documentation says you have to allow access to the VSAM-Files to everybody. So logon as HERC01, open the data set "SYS2.SECURE.CNTL(PROFILES) and add the following lines to the end. (Unbelievable. I understand what I'm writing here!)

DATASET HERC01.KICKS.MURACH.CUSTMAS                         UPDATE
DATASET HERC01.KICKS.MURACH.INVCTL                          UPDATE
DATASET HERC01.KICKS.MURACH.INVOICE                         UPDATE
DATASET HERC01.KICKS.MURACH.INVOICE.PATH                    UPDATE
DATASET HERC01.KICKS.MURACH.PRODUCT                         UPDATE
DATASET HERC01.KICKS.TACDATA                                UPDATE
DATASET HERC01.KICKS.V1R5M0.SDB                             UPDATE
DATASET HERC01.KICKSSYS.V1R5M0.KIKINTRA                     UPDATE
DATASET HERC01.KICKSSYS.V1R5M0.KIKTEMP                      UPDATE

The editor screen should look something like this:

Saving the file and restart rakf (or the whole Hercules to be save)

Next, you should copy the member KICKS and KFIX to the SYS2.PROCLIB data set. The tool MOVE/COPY (option 3.3) is very handy for this task and i managed it without reading any manuals.

When you finished these copies, you can logoff and logon as a regular user. CASI in my case.

Now it should be able to launch KICKS from the TSO command prompt. I tried and.... failed. After a little research and asking the experts at discord it turned out, that i forgott the ' !! So the correct command to start KICKS is:

EXEC 'SYS2.CMDPROC(KICKS)'

With this command (AND DO NOT MISS THE APOSTROPHE!) the system will start. Press CLEAR Button and enter BTC0 and you will see the TAC-Transaction used in Nevada Department of Labor in the 70s.

There are some other transactions also installed. Especially all the examples of the Murach's bible of "CICS for the COBOL Programmer". I think I'm now done with the installation of Hercules, TK4, ROBs enhancements and KICKS. So the next step could be implenting a first online transaction in COBOL.

... when two worlds come together

Hercules is actively developed under the project Hercules Hyperion and the current release 4.5 is available on github. I tried to compile it on my macOS but got some trouble with the software not being available and so I decide to give docker a chance and carry this cute little Dinosaur. And it was actually quite easy. (Attention: This approach is only tested on x86 architectures. I tried a build on a Raspberry Pi 4 with 64Bit and it failed due to missing external libraries. I'm working on it)

First, I cloned the github repository on a local directory.

git clone https://github.com/SDL-Hercules-390/hyperion.git

Then you will have the whole project on your local drive. The installation instructions in the project documentation are straightforward and so I followed them up in a Dockerfile. (Copy this Dockerfile into the project directory.)

#
# Start building hercules-hyperion docker image from a debian base
# since it does not need many stuff the slim image should be sufficient
#
# The extra software is installed with apt.
#
FROM debian:stable-slim AS env

RUN mkdir /opt/build &&\
    apt-get update &&\
    apt-get -y install git wget time &&\
    apt-get -y install build-essential cmake flex gawk m4 autoconf automake libtool-bin libltdl-dev &&\
    apt-get -y install libbz2-dev zlib1g-dev &&\
    apt-get -y install libcap2-bin

# No the environment is set and the build can Start
# copy all the project files into the build directory and Start
# building it.
#
FROM env AS build

WORKDIR /opt/build

COPY . /opt/build

RUN ./configure &&\
    mkdir /opt/hercules &&\
    make &&\
    make install &&\
    /sbin/ldconfig -v

#
# With the hercules hyperion build it is no easy to Start
# hercules.
#
# The docker image expects a working area mounted to /opt/hercules
# and in that directory there must be the configuratio under conf/herculues.cnf
# The start script inside the hercules console has to be under scripts/ipl.rc
#
#  <DirecotryMountedUnder/opt/hercules>
#   .
#   +--conf/hercules.cnf
#   +--scripts/ipl.rc
#
FROM build AS hercules-hyperion
WORKDIR /opt/build
VOlUME /opt/hercules

CMD ["/bin/bash", "/opt/build/container-start"]

The Dockerfile has three stages. The first stage starts from the Debian-slim image and follows the installation instructions of the project documentation. It leaves a stage env to use in the next stage.

The stage build copies the whole project into the working directory of the image and follows the make instructions of the project documentation. This leads to a new stage build that has a compiled and installed Hercules inside. The only thing I need to add was the /sbin/ldconfig -v command to make the Hercules libraries accessible in the image.

The third stage is the final stage which builds the final image and makes Hercules run in a docker container. It uses a little bash script:

#!/bin/bash

(
cd /opt/hercules
export HERCULES_RC=scripts/ipl.rc
hercules -f conf/hercules.cnf -d >3033.log
)

The script changes to a directory /opt/hercules, sets the environment variable HERCULES_RC to scripts/ipl.rc, and starts the Hercules emulator. As you may see this script implies some setups from the user. You have to mount a directory with your own hercules environment under /opt/hercules and in that environment you have to store the configuration under conf/hercules.cnf and the startup script under scripts/ipl.rc

Starting Hercules is one thing. But installing the software and bringing it all together is a much more difficult task. At least for me as a java developer. There are some readily defined distributions with all devices, dasds, configs, and start scripts needed available and you surely want to use them. Like the TK-4 distribution mentioned in the other articles. This distribution has the configuration under conf/tk4-.cnf. Copy it to conf/hercules.cnf and you are fine. The start script is under scripts/ipl.rc as required by the container script.

docker build -t hercules-hyperion .

When you start the docker build like:

docker will create the image. To start the image use this command:

docker run -v /<YOUR HERCULES ENVIRONMENT DIRECTORY>:/opt/hercules \
    -p 3270:3270 \
    -p 3278:3278 \
    -p 8038:8038 \
    --name hercules \
    hercules-hyperion

Now you have a running hercules 4.5 hyperion instance in docker. The ports are exposed to 3270 (3270-Terminal emulation), 3278 (Telnet port) and 8038 (Web-Server)

The easy part...

installing and starting HERCULES today (2023) really is no problem at all. It can run on any commonly used OS like Windows, MacOS, and Linux. I choose my old Raspberry PI 3B as my mainframe platform. And it does the job quite well for one user. So how is it going:

My first try was running raspberry pi OS 64-bit and downloading the tk4-current.zip distribution. You can download the current up-to-date distribution from here (tk4-current.zip). The documentation says you have to unzip the zip archive in a folder of your choice and start the ./mvs script.

The first start stops with an error message. After a while, I figured out, that your raspberry pi OS has to be a 32-bit version. So I installed the 32-bit version of the OS and tried it again... And voila! here it is:

So what next? You can press the ESC-Button to see the "other" page of this master console.

It looks like it is running. Next is to start a 3270-Terminal emulation (like c3270) to connect to the mainframe. I'm using c3270 which is part of the brew ecosystem. brew install c3270 will install a terminal emulation.

After that a

$ > c3270 hercules-pi:3270

starts a 3270-Session to the mainframe and you can logon: User herc01, password cul8tr

After successfull logon with herc01 you will see a screen like this:

If your screen looks a little different it my because I already installed the update on mvs turnkey 4. At the moment of writing, i didn't have a clue what this update is doing, but it sounds good and so I did it.

To Install you have to shut down the Hercules by entering "quit" in the master console (the window where you started the mvs script). Download the ROB'S update zip and unpack it in your Hercules installation directory. Directly in the root of Hercules. You have to add 2 entries into the tk4-.cnf-File. Look at the documentation of Rob's package. Then start Hercules again and you are done...

That was the easy part. But now it is getting hard for a Java programmer, that wants to start his first COBOL program. This will be part of the next session...

...Welcome to Jurassic Parc. The world of the Dinosaurs.

I'm a Java programmer since my very first days as a professional software engineer. Before that, I started programming with BASIC and Assembler on a Commodore +4. During my studies is programmed C on an ATARI-ST or on Solaris Workstations. My first job was in the military domain where I helped to create the firmware of a RADAR system. So I really never touched this mystic world of IBM Mainframes.

In my later jobs, I went into the banking and insurance domain and there were colleagues talking about very strange things. They used words I never heard before. Talking about "COPYSTRECKEN", Partitioned Data Sets, Members and Jobs. And they were using the programming language COBOL which must be very cool. At least they were very enthusiastic about it. I was impressed by them sitting at their desks, using a text-driven terminal the whole day, and didn't miss a mouse or a graphical UI. And the applications they implement were very mission-critical. But the problems they had seemed to me so unbelievable. Why is it difficult to make a Field some bytes longer? What the heck is a "COPYSTRECKE"... ISPF, MVS, TSO, JES2 all these things were all absolutely strange to me. And since there were no open source systems available to this world it kept strange to me.

That changes with the upcoming HERCULES emulator. This little tiny program can start a whole IBM Mainframe on your personal computer. And with the TK4 setup available on the internet you have a complete 1980s Mainframe running MVS and some software that can bring you into this strange world. Especially if you add the prince update.

So here are my first steps in this world of these IT dinosaurs.