zPET - IBM Z and z/OS Platform Evaluation and Test - Group home

Exploring z/OS Through Zowe, ZOAU, and IDE Tools

  

Introduction

Today, it seems that there is no shortage of modern methods of interacting with z/OS. I see this as both a blessing and a curse, and it’s something that has been in the back of my mind for quite some time now. It seems like every day (OK maybe that’s a stretch, let’s just say “relatively frequently”) there is a new tool from a new area that offers a modern interface or method to interact with z/OS. What’s worse, is that when folks explain or demonstrate these tools to their peers, it seems that they often get feedback that “this is nothing new” or “such and such a tool does (or used to do) the same thing.” Again, I find this both troubling and amazing at the same time. In a time where more early-tenured software engineers and computer scientists are working on the mainframe than at any recent point, this is certainly a good problem to have. The myriad of tools we young folks have available is great in that it allows us to choose, and in some cases even build a solution to, how we interact with the mainframe. In my opinion though, it can sometimes be difficult trying to decide which tool is the best choice to use. In this blog post, I hope to offer some insight on which tools will best meet your goals. Since covering every available tool would take considerable time not only for me to research but for you to read about, I would like to offer a comparison of two of my favorite, and still relatively new tools: Zowe and Z Open Automation Utilities or ZOAU.

Problem Statement

Before delving into the pros, cons, and differences between Zowe and ZOAU, I’d like to first offer a use case for which we can refer to for this blog. Imagine you are an application developer or a system programmer. You have a workload with one piece replicated to three z/OS jobs, each running in a unique region spread across three z/OS LPARs. Each of these regions displays a transaction counter in its logs unique to itself, but you want to get a global view of the transactions, meaning you want to see how each region is doing individually compared to the others as well as what the current global transaction count is. How would you do it? Initially, you might simply use SDSF, search for the jobnames of the three regions, and jump into the output of each one in sequence searching for the information you want.

Below are some screenshots of what this currently looks like in SDSF. As an example I’m using an application I have called Issuing Bank or ISSBANK as it’s named on the system. ISSBANK1 denotes that it’s running on system 1, ISSBANK2 is running on system 2, and so on. So in order to look at the jobs’ output, in the first panel I issued pre ISSBANK* to get a list of all the jobs.


I then issued a ? on the active ISSBANK1 to get a listing of its output files.


Finally, I issued S on the STDOUT file to view the portion of the output I was concerned with.


While simple and time-tested, this method of jumping around from panel to panel and sifting through output can be somewhat cumbersome especially for early tenured employees. As with most things the more you work with it the better you get with it, but even so if I wanted to compare the output of ISSBANK1, ISSBANK2, and ISSBANK3, I’d be doing a lot of jumping around. To avoid this, let’s take a look at some alternatives to this approach that will make our lives easier.

Eclipse vs VS Code

One approach you might take is to utilize an integrated development environment (IDE) like Eclipse or VS Code to view the output of the three jobs all at once. At this point you might be saying “Whoa hey now wait a minute, this blog was supposed to be about Zowe and ZAOU! Not Eclipse!” That’s true, however, I think it’s important to mention these tools as well since they both have their merits in this space.

Both Eclipse and VS Code offer extensions that solve our problem of having disparate jobs whose output we would like to view at the same time. Eclipse has Remote System Explorer (RSE) and VS Code has the Zowe Explorer plugin. Both of these plugins offer a drop-down menu driven method of viewing job output. Below, I’ve added two screenshots to show what it’s like to look at the output of the ISSBANK jobs in Eclipse and VS Code. As a general note, please excuse some instances in the screenshots below and throughout the rest of this blog where I’ve redacted some sensitive information.


As we can see above Eclipse lets us look at multiple files at once, one of the main things we want to be able to do. However, Eclipse has its own set of known problems that has driven many developers away from it when given the choice. Personally, I tend to find myself using Eclipse out of sheer habit but agree that it’s not the best tool for some situations.


As we can see by the familiar layout, VS Code’s offering is not that dissimilar from Eclipse’s. VS Code is not without its own set of frustrating nuances though. It takes a while to get used to working with VS Code’s interface for filtering job names, as well as keeping files open that you want open (by default it seems to change from file to file unless you double click on the file name on the top navbar). Regardless of its shortcomings, VS Code seems to be wildly popular with young software professionals, making the frustrations with Zowe Explorer a small price to pay for a “one stop shop” IDE that you can use for multiple aspects of your job.

Overall, this is a good step in the right direction. From both of these IDEs we can see how many jobs are running, return codes of completed jobs, and peruse the output at different levels in one place. Additionally, these IDEs both offer functionality to submit jobs to be run, as well as cancelling running jobs and purging completed ones.

To add another to the list of possibilities, we can consider Zowe Desktop (I’ve also seen it referred to as ZLUX) as a third option. Zowe Desktop is a web-driven rendering of what resembles a simple PC desktop. It has several tools that allow you to interact with z/OS including a USS file explorer, JES explorer, and even a TN3270 emulator. In terms of JES interaction, Zowe Desktop offers a similar interface to what we saw in Eclipse and VS Code, that is, a drop-down menu driven window that lets you view, cancel, and purge job output.


As we can see, there are plenty of methods available for interacting with z/OS jobs without having the need to jump through green screens. With all of that being said, all of these methods have their pre-requisites, which might be seen as detriments depending on who you ask. Eclipse RSE requires that a daemon be run on your z/OS system to enable the remote connection, and both VS Code’s Zowe Explorer plugin and Zowe Desktop are dependent on your system supporting Zowe. While these are all important considerations when deciding which tool is right for you, the point of this blog is to discuss the available options, so let’s move on to the next topic.

Zowe vs ZOAU - CLI

Let’s say we want to use Zowe (not Zowe Desktop) and/or ZOAU to view the output of our three jobs we mentioned earlier, how can we do this? As you may have guessed by now, there are several options available to us. Zowe has both a command line interface (CLI) as well as a REST interface. ZOAU offers both Python and Java APIs as well as some Shell commands. For this discussion, we’ll focus on the Python APIs and touch on the Shell commands, but we’ll leave Java out of the discussion for brevity’s sake.

First, let’s talk about the CLI option. For Zowe, once you have the CLI installed and your profile setup, it’s really simple to view the output of jobs. Generally speaking, you’d want to install Zowe CLI on your local machine (this will require Node.js as a pre-requisite, as well as z/OSMF being installed on your z/OS system). Please refer to the documentation here for a quick guide that will help you install the Zowe CLI and run your first commands.

Let’s say we want to view the STDOUT spool file for our job ISSBANK1. We will first issue zowe zos-jobs list jobs --owner * --prefix issbank*. These arguments function just like they would on z/OS directly, and both of these options honor the wildcard character “*”. Next, we use the output from the previous command to use as input in our next command zowe zos-jobs list spool-files-by-jobid S0075699 where the jobid S0075699 was in the initial list of returned jobs. With the output from that command, we can choose the spoolfileid of the spool file we want to view and run the following zowe zos-jobs view spool-file-by-id S0075699 101 to specifically look at STDOUT. The screenshot below shows an example of running the commands back-to-back in real time, again using the job ISSBANK1 that we’ve been looking at for this use case.


As you can see, the different commands build upon each other, each one giving you a bit more information that you can use to run another command. This seems to be quite common when working with both Zowe or ZOAU and while it might seem tedious at times, there are certainly ways to script or abstract this as we will see later. Unfortunately, one downfall here is that there currently does not appear to be a way to view all of the output together at once through just the Zowe CLI commands.

Ok, on to ZOAU. As I stated earlier ZOAU offers both Python APIs as well as some Shell commands. This is where the comparison gets a bit tricky. Currently the documentation here shows over thirty different commands allowing you to interact with jobs, datasets, and operator commands. Unfortunately these commands don’t fit our use case of looking at specific job output. We can use the jlscommand to list jobs running under a certain user/prefix, and then issue jcan to cancel or purge the job.


Currently, there doesn’t seem to be a way to investigate the jobs further through just the Shell, so let’s move on to using Python.

We can utilize the ZOAU Python package via an interactive Python shell or by writing a Python script which can then be run like any other program. The former method resembles the way we used the Zowe CLI, so please check out the screenshot below to see the commands in action.


For this use case we ran: Jobs.list(owner='*', job_name='ISSBANK*')> Jobs.list_dds('S0032106') > Jobs.read_output('S0032106', 'JES2', 'STDOUT'). As you can see, the ZOAU commands operate in a similar fashion to the Zowe commands. While the syntax may be different, the concept of getting a list of jobs and then drilling down to the specific output file you want is the same. Now this is all well and good, but I think we want to go further no? What if we wanted to just grab the last line in the log file? After all, we might not care about the transaction count or rate from 10 minutes ago and just want to see the most recent message. Or what if we wanted to build our own web-based view of the jobs? For these tasks, we will need to add a bit more code around these commands to help us out.

Zowe vs ZOAU - Web

Rather than reinventing the wheel here, I’d like to refer you to a very well written article with a simple yet powerful example of using Flask and ZOAU to create a job management system. If you haven’t read https://medium.com/@kalebporter/z-os-job-management-with-python-6f740144636 before, I can’t recommend it enough. Now, having read that article, you can see how Kaleb uses the Jobs.list() and Jobs.cancel() functions to build a neat interface for viewing and cancelling jobs running on z/OS. What’s better is that with a few additional function calls, you could add as much or as little to this project as you wanted.

For example, if you wanted to display the full output of each job, you could add an additional Flask route that would call Jobs.read_output() in a loop for each spool file for a given job. The results could then be consolidated and easily displayed with the help of Jinja templating (as we already saw in the medium.com article). For brevity’s sake, I won’t get into implementation details, but I hope that the previous explanation of the Zowe and ZOAU functions have sparked some ideas and gotten the gears turning in your head.

At this point I’d like to circle back to Zowe and discuss how Zowe could be used in place of ZOAU in the above scenario to achieve the same result. However, it’s important to pause and refer back to a previous note I had made about Zowe including a RESTful interface, as this is a key difference between the two technologies. Zowe can be setup to allow RESTful API endpoints; this means you can (with the appropriate permissions and access authority) make calls to Zowe from anywhere. This is particularly useful if you would like to use Zowe in conjunction with technologies that aren’t available on your z/OS systems. For example, maybe you don’t have Flask installed in your z/OS environment, or you might simply want to deploy the application you built to a z/OS Container Extensions instance instead. In these cases as well as others, you can make use of the APIs in much the same way we’ve seen the other methods used. To follow the same thread of getting 1 specific output file for a given job, we could call the following APIs in order: /api/v2/jobs > /api/v2/jobs/{jobname}/{jobId}/files > /api/v2/jobs/{jobname}/{jobId}/files/{fileId}/content. This is of course following the same logic as before: we first get a list of jobs, pick a particular jobId to investigate further and get a list of files, then get specific file content based on a fileId. Additionally, Zowe offers an API endpoint /api/v2/jobs/{jobName}/{jobId}/files/content which allows you to get the contents of all job output files at once, saving you a step. It’s worth noting here that one should be careful when grabbing the contents of all job output files, as long-running jobs or jobs that have abended and included a SYSDUMP can return huge files. Moving on, Zowe also has facilities for cancelling and purging jobs as we saw with ZOAU earlier (PUT and DELETE requests to /api/v2/jobs respectively). While the nature of setting up and performing API calls as well as parsing the returned payloads will add some complexity to your codebase, you can still use them to create a similar application to what we saw in the medium.com article.

Conclusion

Up until now we’ve discussed how to use Zowe and ZOAU, but what we haven’t really touched on is the differences between the two in a true side-by-side comparison.

Zowe

  • Pros
    • REST enabled
    • Allows interaction with z/OS from off-platform
    • Myriad of tools under the /zosmf APIs*
    • Zowe enablement offers several choices for interaction (CLI, APIs, zLUX, Zowe Explorer)
  • Cons
    • Requires z/OSMF
    • Requires Node.js (for CLI)
    • REST calls can add code complexity
    • CLI is cumbersome in comparison

*While the /z/OSMF APIs technically aren’t part of the Zowe codebase, Zowe operates on top of these APIs and they can be found in the API reference of your local install

ZOAU

  • Pros
    • Python package is simple to pick up and use
    • Simple "1 line" function calls to linklist & parmlib
    • Returned values are easy to parse/work with
  • Cons
    • Does nont have any USS functions (at the time of writing)
    • Limited to available APIs only
    • Extra steps/tooling needed to run off-platform

Key Differences

  • Returned fields and verbosity of output can differ on a function-by-function basis
  • Some functions for one tool are more robust than the other's
    • Ex. Where Zowe's /api/v2/jobs API allows you to provide a status parameter (to say only return ACTIVE jobs) ZOAU's opposing function does not
  • Where the Zowe CLI can connect to your z/OS system remotely, ZOAU cannot. However, using a technology like Ansible, it is possible to write some code or playbooks that SSH into your system in order to call ZOAU functions

While the above pros and cons list does not cover every aspect of these two tools, it does bring some context to the discussion of which tool to utilize. Realistically, you can’t go wrong with either one of them. ZOAU is certainly attractive in that its lightweight and if you have the necessary package installed on your system, you should be able to get a script up and running in about an hour. However, it’s limited by its requirement of being run on-platform. On the flip side, Zowe allows you to interact with z/OS from off-platform, but the pre-requisites of z/OSMF and Node.js can be daunting and unattractive for simple use cases.

The answer to the question of which tool to use really comes down to a simple question, which tool do you want to use? There is no right or wrong answer here, it’s truly up to the end user to decide which one best suits the problem at hand, based on what is available to them and what functionality they need. To add some personal perspective to this, I myself began a project using Zowe due to ZOAU having what I perceived to be limited functionality at the time, only to later realize that ZOAU had been built up to include everything I needed. I feel like many developers might get hung up on this point, unsure of which tool to explore for fear of one of them one day being made obsolete by the other. In my opinion it’s best not to dwell on such a decision. I think the Z community will naturally gravitate to one tool or another, so it’s best to be familiar with both in case your chosen horse loses that race. On the other hand, both tools might be relevant for quite some time, in which case either one will be able to help you do your job more effectively. Overall, these two technologies are a huge testament to how far z/OS has come in recent years. The fact that a developer can quickly and easily program REST calls or Python functions to view and manage jobs running on z/OS is a tremendous victory. I for one, will continue to explore and work with both of these fascinating tools (as well as the other options like Eclipse and VS Code) and am extremely excited to see how they will continue to grow and develop.

References & Helpful Links

Zowe CLI quick start
Using the Zowe Desktop
ZOA Utilities command and API reference
z/OS Job management with Python