jobs.py

This year Master the Mainframe competition introduces a lot of new things, from Ansible to Zowe. Along with it come the Grand Challenge, the final challenge for the competition.

For the Grand Challenge, I decided to make a Python script that calls the z/OSMF REST API. To be precise, the z/OS jobs REST interface. The Python script allows users to check the status of their jobs. Additionally, it is also possible to cancel or re-submit any jobs still inside the spool.

The submission workflow also requires us to make a flyer, a description and directions to use the creation. All of which are posted below with no non-cosmetic edits.

My Submission

Title

jobs.py

Notes

A Python script to be executed from your PC which allows you to list jobs (while allowing you to specify the prefix and job owner), restart jobs and cancel them! It is powered by z/OSMF REST APIs and require Python 3 to run. As a beta feature, the script can also accept client certificates as replacement for user/password authentication, allowing those of you with stricter security to run it too!

Flyer

Flyer for jobs.py

Directions

Scan the QR code from the flyer or go to https://gist.github.com/tanto259/d24fa0fcafff8964c8332c63383c3dcb and download the script! If you are using MTM, you are good to go, otherwise you might want to edit your hostname near the top of the script :) So, assuming you have Python 3 installed, you can execute the various features with python3 jobs.py .

There are 3 available functions: list, restart and cancel. List requires you to specify a user parameter, while prefix (default = *) and owner (default = same as user) are optional. While for restart and cancel: user, jobid and jobname are all required.

Examples includes python3 jobs.py list --user IBMUSER --owner Z00686, python3 jobs.py restart --user z00686 --jobid JOB05368 --jobname ADD1JCL and python3 jobs.py cancel --user z00686 --jobid JOB05368 --jobname ADD1JCL.

More details available if you execute python3 jobs.py.

For the sysprogs among us, z/OSMF must be enabled and running for this to run. To enable additional features such as validation for server certificates and client side certificate authentication, check the lines near the top of the script :)

Technical Reflection

When I first learned of Zowe, I was amazed. It has many features that enable users to work with the mainframe while remaining attractive for the younger generations to try their hands on this system. Looking through the architecture, I learned that Zowe Core CLI, and hence the Zowe Explorer extension, use z/OSMF REST APIs for workflows, TSO commands, files, USS and even JES. So I decided to explore more on z/OSMF.

One of the things I learned is that z/OSMF is shipped and started by default starting from z/OS 2.3. Thus, usage will be high. Additionally, the system programmer doesn’t need to install any other stuff!

At first, I explored making a website to call the REST APIs and perform the functions via a browser. But it turns out that due to many browser’s security settings, cross-origin resource sharing must first be configured in the RACF installation. So, I decided to go for a Python script instead. In any case, cross-site requests must be enabled by sending over an HTTP header named X-CSRF-ZOSMF-HEADER with every request.

Looking at the documentation, I decided to implement jobs status checking and cancellation, since those have dedicated endpoints on the documentation page. While cancelling a job is a much direct task, checking the status of the jobs is not. First, all jobs belonging to the owner must be retrieved and then for every job, the status is checked.

Then I think about adding other things. One of the things that often came up when I was doing COBOL is a need to re-submit JCL jobs that compile COBOL programs after fixing the bug contained within. So, I decided to explore the possibility of re-submitting existing jobs. Apparently, after digging around the documentation, it is possible to retrieve the JCL submitted for a specified job. With that, it is an easy task to submit a new job with the retrieved JCL.

The next issue is authentication. The easiest method which would work is sending the username and password through basic authentication. This is certainly not the safest option since the username-password combination is base64-encoded and put directly into the HTTP request header. But this option is the most direct and can be used by everyone doing Master the Mainframe.

After exploring the documentation, I found out that z/OSMF also supports certificate authentication. This would be safer but it requires the RACF administrator to generate a client certificate tied to your user ID. Thus it’s not something I can test, but the requests package on Python supports it. Therefore, I decided to put it in as a beta feature.

Since the script is intended for Master the Mainframe users, it accepts self-signed connections by default. However, this can be overridden easily on the first few lines of the code. Other variables such as hostname and the client certificate path are also defined there. Therefore, should the application be used for production work, the system programmer can modify the variable easily.

I’m aware that you can use Zowe to replicate the same effect, but in this case, I wanted to explore the underlying functionality that enabled Zowe to work. Additionally, the Z Open Automation Utilities Python library only works on the mainframe system, but in this case, I wanted to be able to execute the code directly from my local workstation. Hence, I resorted to z/OSMF.

Master the Mainframe 2020 has been a wonderful learning experience. I certainly learned and explored much new stuff while also revisiting those learned previously. I can’t wait for the 2021 edition! Hope I’ll see you around next year.

If you’re interested to learn more about mainframe, check out my post on the IBM Z Global Student Hub to check other learning materials available for everyone.