CA JCLCheck and Zowe ensure that JCL runs successfully at your site

Gene Johnston
Feb 8 · 9 min read
Image for post
Image for post
When your JCL works first time

{Ecosystem} JCL is a fundamental component of programs running on a mainframe. People who are new to the z/OS platform will benefit from automated assistance in creating correct JCL. Experienced engineers may also benefit if they do not write JCL frequently enough to get it perfect the first time. Further, customer sites may have specific standards that even an expert in writing JCL may not always remember.

In this article, I discuss how new Zowe tooling surrounding Broadcom’s z/OS application “CA JCLCheck™ Workload Automation” enables both novice and experienced mainframe engineers to produce correct JCL with confidence that the JCL will run successfully in a production environment.

The following diagram shows the available components related to JCLCheck.

Image for post
Image for post
JCLCheck components working together

Traditional JCLCheck capabilities

First, you will be faced with an emergency fix if the JCL fails when it is run on a production system for a time-critical application.

Second, since some jobs can take hours to run, you may have an extensive delay before finding an error. For example, it would be frustrating and unproductive to wait for 2 1/2 hours out of a 3 hour job before a JCL error stops the job.

Third, a company may choose to enforce certain site-specific standards. Some JCL may be technically correct, but it may be unacceptable for use at that company. JCLCheck provides a means for companies to extend the set of checks performed by JCLCheck to enforce their site standards.

JCLCheck contains a z/OS assembler API that enables programmatic access to JCLCheck capabilities from an arbitrary batch job or started task. Such access is, of course, limited to assembler programming on the same operating system. However, the assembler API is a critical component for producing the expanded access to JCLCheck that we discuss next.

REST API

As you may know, most modern (and many not-so-modern) programming languages easily perform an HTTP request. HTTP requests travel over your network to a designated server. Therefore, you can write a client program on any platform. In a call to the JCLCheck REST API, your client program can specify the name of a z/OS data set as the source of your JCL. Thus, you do not have to move your JCL to run your client program on another platform.

First release of the REST API enabled experimentation

The first supported release of the JCLCheck REST API was sufficiently hardened and tested so that customers could confidently bring the application into a site which does not permit the use of beta-release applications. However, to get that early validation, the functionality of the REST API was limited. Specifically, the JCLCheck options which require APF authorization were not available to avoid any potential security vulnerability. Customers were able to learn and experiment with this version of the REST API.

New GA release of the REST API includes APF authorized options

The second release of the REST API supports APF-authorized options. This change greatly expands the options that can be used. This release also establishes security boundaries to ensure that unauthorized users cannot gain access to JCLCheck operations.

The new capabilities of the REST API enable you to:

  • Perform more extensive validation of file existence, security access, and utility control cards.
  • Use JCLCheck’s library override options for procedure, control card, and load libraries.
  • Use AUTOPROC to pull the system PROCLIBs from JES.

One difference between using the REST API and running JCLCheck as a batch job is that options requiring a DD name as a parameter cannot be used in the REST API. However, in most cases there are versions of these options which specify a library data set name instead, such as LOADOVER(library name), CNTLOVER(library name), and OPROCLIB(library name). By using the option that specifies a library name, that option can be used with the REST API. An example may help clarify this requirement.

JCLCheck options are passed to the REST API as a query string.

https://...?options=NOAS HCD NOJCL NORES SEC NOSIGN

The DD name variant of an option is meant for batch job submittal.

//OVERLLIB DD   DISP=SHR,DSN=QA.LOADLIB
...
//JCLOPTS DD *
LOADOVDD(OVERLLIB)

There are no DD statements in a REST API, but you can achieve the same result by using the library dataset variant of that same JCLCheck option, for example:

https://...?options=LOADOVER(QA.LOADLIB)

A site’s custom JCL checks are accomplished with language-specific options. The COBEXIT option specifies that site-specific checks are implemented as a user exit written in the COBOL programming language. COBOL exits are fully supported in the REST API in this release.

Similarly, the STDREXX option enables you to use the REXX programming language to enforce site-specific JCL standards. The STDREXX option is currently the only option that does not have a library option. The current format of the STDREXX option is:

STDREXX(rexx_pgm[,ddname])

This option format specifies a DD name, but it does not allow a library to be specified. The lack of a library name prevents STDREXX from being used in the REST API. An APAR is currently available from the JCLCheck Support Team which adds a library name to the STDREXX option. The new format is:

STDREXX(rexx_pgm[,ddname][,dsn])

With the new dsn argument, users can specify a REXX library data set name. By specifying a library name, the REST API will be able to run site-specific JCL checks which are written in REXX.

Zowe CLI plugin

With the JCLCheck plugin, you enter a command in which you specify the location of your JCL and the set of options to trigger specific JCL checks. You can type such a command interactively in a native terminal window on your laptop. The results from JCLCheck are displayed on your terminal. This works well for an ad-hoc confirmation of some JCL that you are developing.

Perhaps the most significant advantage to using the CLI interface is the ability to script your JCLCheck commands into a Continuous Integration / Continuous Delivery pipeline. This is frequently a more powerful use case for a customer site. Various components of an enterprise-wide application are often pulled together in preparation for promotion of the application into a production environment. The components may include a web site user interface, a Linux middle-ware component, and a mainframe back-end. It is common for the front-end and middle-ware components to be built and tested in a CI/CD pipeline. Mainframe components’ participation in such CI/CD pipelines have lagged behind the other platforms.

The Zowe ecosystem has been a driving force for the inclusion of mainframe components into CI/CD pipelines. JCL is a common element of mainframe components, and since this is an article about JCL, let’s just focus on JCL validation in a CI/CD pipeline.

Because the JCLCheck plugin is a Zowe command, it is capable of running on Windows, Linux, and Mac systems. Most CI/CD pipelines run on one of these platforms. Pipeline operations are typically performed by running numerous command line programs. JCLCheck plugin commands can be run in a pipeline on one of these distributed systems and perform the site-required checks of JCL which resides on one of your mainframe systems. If the JCL checks are not successful, you can cause the pipeline to fail, and prevent the application from being promoted to production.

Further, if the JCL checks succeed (along with all of your other automated tests) additional Zowe CLI commands can be used to promote your mainframe components to production. In the case of JCL, Zowe CLI commands could copy the JCL to a production data set on your mainframe, or the Zowe CLI commands could trigger the promotion of JCL elements stored in an Endevor source management system.

Default output of the JCLCheck plugin

Here is an example of the default output format of the JCLCheck plugin. Assume that profile information was previously set which identifies the desired mainframe host. The following command checks the JCL in a data set on the mainframe.

Image for post
Image for post
Default output of the JCLCheck plugin

The JCL in the example above contains a lower case letter in the name of a data set specified within the JCL. The command displays a return code, which can be used as a pass/fail indicator. It also displays the line numbers containing errors and the reasons for the errors. In this case, the lower case letter ‘ell’ in the data set name beginning with “ lOWCASE” is invalid syntax within JCL. The second error demonstrates how JCLCheck goes beyond syntax checking to confirm whether the JCL can run in the environment of your mainframe system. By identifying that the specified data set does not exist, JCLCheck has informed you that this JCL cannot run successfully on this LPAR.

Detailed output of the JCLCheck plugin

Many more details about the validation of the JCL are available from the plugin, such as a complete JCL listing, numerous reports produced by JCLCheck, and directly accessible properties about those reports. These details can be retrieved by specifying the option “response-format-json”. Here is the same command from the previous example with that option specified.

Image for post
Image for post
Detailed output of the JCLCheck plugin

Only a brief snippet of the output is shown above. About 860 lines of output was actually displayed. Who would read that much output? Nobody. But another program could read it. A custom program could do detailed interrogation of the JCLCheck output and perform various actions, based on site-specific criteria. Such a program could stop a pipeline, trigger some other automation, notify a responsible person, or extract the information into a custom report.

In our own lab, we wrote a program to extract detailed information from the output of the JCLCheck plugin and generate an HTML web page to display just the set of information in which we were interested. The following HTML page was generated from the same JCL as the previous example, with slightly different JCLCheck options specified.

Image for post
Image for post
Custom web page from output of JCLCheck plugin

The validation of JCL can be taken to an even higher level of abstraction. In the following companion article, I discuss how (with no programming or scripting) you can perform JCL validation while you edit your JCL.

Use Zowe to validate JCL with the touch of a button

Summary

Locations of components mentioned in this article

2. STDREXX library parameter capability

  • Contact your JCLCheck Support Team for the APARs for this feature
  • At the publication time of this article, these were the required APARs
  • ST15107
  • ST15108

3. JCLCheck plugin

4. JCLCheck apps were verified with the following component versions

  • z/OS version 02.04.00
  • z/OSMF version 27.0
  • Visual Studio Code version 1.52.1
  • Any Zowe CLI 6.x version. The NPM @zowe-v1-lts tag will obtain a compatible version. At the time of the publication of this article, the @latest tag will also obtain a compatible version.

Zowe

Zowe is the modern open source interface for the mainframe…

Thanks to Michael DuBois

Gene Johnston

Written by

I am a principal software engineer at Broadcom and a contributor to the Command Line Interface component of the Zowe project.

Zowe

Zowe

Zowe is the modern open source interface for the mainframe and z/OS. The Zowe blog has how-to’s, tips & tricks and other helpful insights for mainframe devops. Zowe is a project within the Linux Foundation’s Open Mainframe Project (OMP). Download @ Zowe.org.

Gene Johnston

Written by

I am a principal software engineer at Broadcom and a contributor to the Command Line Interface component of the Zowe project.

Zowe

Zowe

Zowe is the modern open source interface for the mainframe and z/OS. The Zowe blog has how-to’s, tips & tricks and other helpful insights for mainframe devops. Zowe is a project within the Linux Foundation’s Open Mainframe Project (OMP). Download @ Zowe.org.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store