Master the Mainframe '20 | Level 3.1: Zowe CLI and VSAM

Hiya! 👋 Welcome to my blog.

In this post, I'll interact with the z/OS mainframe via Zowe CLI through a series of transactions. I'll issue a request to view the jobs, another to view data sets, another to issue a command. Behind the scenes, the open source framework, Zowe, is working to link the mainframe’s capabilities with easy-to-use APIs, commands, and libraries. Simply put, you can tap into a Z system from just about anywhere, using a wide variety of tools and platforms.

💡:This post is related to Master the Mainframe 2020 | Level 3.1: Zowe CLI and VSAM.

For MTM2020, we've been using the Zowe explore plugin for VS Code but it can do so much more. For this challenge we installed Zowe CLI on our computers as an interface with Zowe and z/OSMF which runs on the mainframe. Tell Me More About Zowe. Is it an IBM Thing Or....?

Zowe CLI is a command line interface (CLI) that provides a simple and streamlined way to interact with IBM z/OS. Zowe is an open source project for z/OS, aimed at making the platform more accessible to users who aren't starting out with years and years of mainframe experience. The Zowe project contains contributions from individuals as well as companies in the mainframe community. These include the VS Code plugin, a number of APIs, and the Zowe CLI which you're about to explore. Zowe is a project of Open Mainframe Project, which is a project managed by the Linux Foundation. It is not an IBM product, though IBM is a contributor and supporter, and continues to advocate for Zowe as a strategic model for bringing new capabilities and users to the mainframe platform.

In order to use it we had to use node packages and load them into an .npm-global directory which could be accessed by regular users.The following steps will tell npm (Node Package Manager) to use, and include that in the normal list of places it looks for programs to run. For users of MacOS Catalina, these should do the trick.

Zowe CLI Install for Mac

1. mkdir~/.npm-global
 2. npmconfig set prefix '~/.npm-global'
 3. echo "export PATH=~/.npm-global/bin/:$PATH" >> .zprofile
 4. source .zprofile5: npmi-g @zowe/cl

NPM Install for Windows

On Windows, you're first going to switch to cmdfrom PowerShell, then install zowezliusing npm, the Node Package Manager.

type cmd
npm i -g @zowe/cli
zowe

The installation for me was quite difficult as I was running into errors/permission issues. One of the main problems was with my .zprofile. For some reason, it had way more content than intended.

I’ve updated the z.profile file to only have “export PATH=~/.npm-global/bin/:$PATH” inside of it. I then ran source on .zprofile and npm i -g @zowe/cli and still got an issue:

I’m not sure why it was happening but I ran clean up via brew. Uninstalled node & npm. Reinstalled them. Redid the Zowe CLI installation. Issue was permissions with .npm-global:

Error: EROFS: read-only file system, mkdir '/.npm-global'

To resolve this, I ran sudo chown -R $(whoami) $(brew --prefix)/* to own node & npm. I did this because I wasn’t the owner of node_modules. This was creating the issue, I thought. However, after clearing house with brew, found that npm wasn’t linked to node. I linked it, removed .npm-global & .zprofile and ran the installation again.

The problem then became that the command npm i -g @zowe/cli. For some reason, lib wasn’t created or present. Simply, I manually create ‘lib’ and reran cmd npm i -g @zowe/cli (no luck). Then it occurred to me to simply run npm install -g @zowe/cli and zowe installed. I ran npm i -g @zowe/cli just to be sure and this time it ran. After a successful installation, I realized that my bash profile was overriding my path and that I'd need to run source .zprofile before using Zowe CLI.

Build It, Load It, Print It VSAM Style

For this level I had to build a VSAM data set, load it with data and print out records using JCL.

VSAM, what is that? VSAM is not used for things like storing JCL or “Welcome to the Mainframe” messages. Its time to shine is when an application needs to access records as quickly and efficiently as possible. In fact, without special software to interpret VSAM files, you can’t open them up in a normal editor, but applications happily eat those files right up.

VSAM is complicated, and this little grey box is not going to give you years of experience working with VSAM data sets, but it will tell you that if you want that mainframe job, do all the reading and practicing with VSAM data sets that you can. They are a core component of any big mainframe company.For now, know that there are four main types of VSAM data sets, KSDS (key sequenced), ESDS (entry-sequenced), RRDS (relative record), and Linear (LDS). KSDS and ESDS are the most common, and the difference comes down to how each record gets stored and accessed. KSDS means that you reference a key (like looking up an account number) and getting the information for that account as the record. ESDS stores data in a sequential order, for data that is likely to be read one after the other in a particular order. That’s enough for now, but if you’re still hungry, here’s some more to consider .

To do all of this, I referred to Zowe online help .

I made a VSAM data set called ZXXXX.VSAMDS on a specific volume. After creating this data set I wanted to see its attributes.

You'll see something pretty interesting; it looks like there are THREE data sets here.

Next, we’re going to load it up with records. I'll use the data in MTM2020.PUBLIC.RECORDS. Doing this though I'll need to consider a few notes: The first column must be in order Omit any blank records/rows You’ll want leading zeroes for keys, otherwise it may not see them as being in order when you go to import. Next, I grabbed the text file provided with this challenge, and download it to my workstation, placing it in the folder or directory I'm currently working from. I'll have to adjust the output data set to point to my VSAM data set. Then, use zowejobs submit lf"repro.txt" to submit that JCL directly from my machine, through the ZoweCLI. I got a nice little animation, and a job number. Next, I checked that job number and make sure it ran.

MTM2020.PUBLIC.RECORDS

This document has up to 1k lines of data. I did have to fix the formatting to ensure a successful job.

Original repro.txt file Let’s talk about what I just did. The JCL runs IDCAMS, which is primarily used to manage VSAM data sets. Within IDCAMS, we’re using the REPROcommand to load a sequential data set into a VSAM-formatted data set. There’s a LOT of complexity happening here that we don’t see, but just like before, there’s plenty of opportunity to dial in exactly how you want that copy to happen, including cryptographic parameters. The data is the same, but it is now structured fundamentally different, indexed by key, and able to be referenced much more efficiently by programs (including ones written in REXX)In reality, thisdata is not indexed very well, since each line is its own key, but if we dive into the particulars of building a VSAM cluster, you can see how the keys and record size can be specified.

I have taken the data from MTM2020.PUBLIC.RECORDS, reformatted it and placed it in the VSAM data set.

Next, I am going to use one more IDCAMS command to look at our output, the aptly-named PRINT command. I want to print out that VSAM data set in character format. So I need to pay attention to the CHARACTER parameter. To complete this challenge, I needed to create a sequential data set, print the first 20 lines of output from to copy/paste into another sequential dataset called ZXXXX.OUTPUT.VSAMPRNT.

Here's how I did it. I rewrote the repro.txt file with the following:

Modified repro.txt file

Let's dissect these changes:

VSDSET2 DD identifies the entry-sequenced VSAM cluster, Z08467.OUTPUT.VSAMPRNT, that the records are copied into.
The REPRO command copies the first 20 records from the source data set, Z08467.VSAMDS, into the target entry-sequenced cluster, Z08467.OUTPUT.VSAMPRNT. Its parameters are:
- INDATASET identifies the source data set, Z08467.VSAMDS.
- OUTFILE points to the VSDSET2 DD statement. The VSDSET2 DD statement identifies the output data set, Z08467.OUTPUT.VSAMPRNT.
- COUNT specifies that 20 records are to be copied. Because the SKIP parameter was not specified, access method services assumes the first 20 records are to be copied. The records are always added after the last record in the output data set.
The IF ... THEN command sequence verifies that the REPRO command completed successfully before the first PRINT command runs.
The IF ... THEN command sequence ends with the HEX parameter because no continuation character follows this parameter. If you want two or more access method services commands to run only when the IF statement is satisfied, enclose the commands in a DO...END command sequence.
The first PRINT command prints the records in the entry-sequenced cluster, Z08467.OUTPUT.VSAMPRNT. Its parameters are:
- INFILE points to the VSDSET2 DD statement. The VSDSET2 DD statement identifies the cluster, Z08467.OUTPUT.VSAMPRNT.
- HEX specifies that each record is to be printed as a group of hexadecimal characters.
The second PRINT command, which runs even if the REPRO command was unsuccessful, prints the first 20 records of the non-VSAM data set, Z08467.VSAMDS. Its parameters are:
- INDATASET identifies the non-VSAM data set, Z08467.VSAMDS.
- COUNT specifies that 20 records are to be printed. Because SKIP was not specified, access method services prints the first 20 records.
- CHARACTER specifies that each record is to be printed as a group of alphanumeric characters.

Resources: