CA JCLCheck and Zowe ensure that JCL runs successfully at your site
{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.
Traditional JCLCheck capabilities
With the traditional JCLCheck application, a user supplies JCL to a batch job. The batch job produces a report that identifies issues within the JCL such as syntax errors, missing data sets, and insufficient access permissions. The user can then correct the JCL before submitting a job that will fail when it is run. You may be thinking that simply running the JCL will display such errors. While that is true, the limitations to this approach are three-fold.
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
Broadcom delivers a JCLCheck REST API which, behind the scenes, calls the JCLCheck assembler API to perform JCLCheck operations. Since calling a REST API is done by making an HTTP request, this REST service enables consumers to programmatically access JCLCheck functionality from numerous programming languages on numerous platforms.
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 NOSIGNThe 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
APIs are great. They provide flexibility to incorporate the functionality of an external product into an in-house application in a very customized fashion. But not every consumer wants to write a client program to call a REST API. To accommodate consumers who are interested in a higher-level of abstraction, Broadcom delivers a JCLCheck plugin for the Zowe CLI.
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.
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.
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.
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.
Summary
We used Zowe technology to expand the powerful capabilities of the JCLCheck mainframe application. This enables JCL validation to be used in continuous integration pipelines and to be used in an ad-hoc fashion on remote systems.
Locations of components mentioned in this article
- JCLCheck Workload Automation 12.0
- Instructions for installing the z/OS JCLCheck application are documented at: Installing JCLCheck™ Workload Automation 12.0
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
- Name: @broadcom/jclcheck-for-zowe-cli
- Version: 1.1.2 accessed by @latest or @zowe-v1-lts
- NPM Registry: https://registry.npmjs.org/ or
- Broadcom-managed Zowe Free Distribution or
- Broadcom Brightside Customer Support site
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.
