Zowe CLI and TSO commands
{Core}The Open Mainframe Project’s Zowe command line interface (CLI) provides a way to access z/OS services by issuing commands from your PC. This blog will show how to configure and use the TSO command feature of Zowe so you can perform tasks such as zowe tso issue command "TIME" (to get the clock value of your mainframe) as well as more complex scenarios.
CLI Introduction
I recall showing Zowe CLI at a conference when an audience member seemed upset that in a presentation on mainframe modernization they weren’t seeing something more high tech. While Zowe does have great graphical user interfaces (the VS Code Zowe Explorer, the Zowe Web Desktop), the CLI shouldn’t be overlooked at hugely important in opening up the platform. As analogy, think of working with git or docker where even though GUIs exist, many IT folks gravitate to their CLIs to become productive. The Zowe CLI fills the same space, allowing ad-hoc issuing of commands by a user from their PC terminal or command shell, as well as CLI inclusion in scripts allowing the fusion of off-platform tools being able to drive on-platform mainframe tasks.
Getting Zowe working with z/OSMF
If you haven’t already got Zowe CLI working on your PC, then you can find instructions to download it at https://docs.zowe.org/stable/user-guide/cli-installcli.html. Once you’ve installed the CLI the next step is to create a profile which captures details about the mainframe you’re wanting to connect to. This profile not only contains the z/OSMF REST API host and port (the endpoints) but it contains details on how to authenticate your requests to the mainframe (typically your user ID and password, although the CLI can be configured to work with multi-factor-authentication products, see Dan Kelosky’s blog Zowe CLI:Token Authentication, MFA, and SSO).
When you have a profile you can issue commands to work with jobs, data sets (and members), and unix directories (and files). For example the command zowe jobs list jobs will show a list of all jobs for your user ID, or zowe jobs list jobs owner IBMUSER will list all jobs for user ID IBMUSER and so forth. The command zowe --hw opens a web page locally showing command syntax documentation which includes any CLI plugins you’ve installed.
What is TSO ?
Time Sharing Option (or TSO) allows a user to create an interactive session with a single-user logon capability and in some ways is the CLI of z/OS itself. When you enter logon myuserid at a telnet session what you’re doing is creating a z/OS process assigned to your userid through which you can interact with the mainframe’s services. At a traditional TSO/E Logon screen shown below notice the field Acct Nmbr that for my system has the value of ACCT# . For yours it might be different. Make a note of its value as we’ll be using this later on. Note also the Command and Reconnect field values.
Reconnect:
When you log onto TSO it creates an address space for your user ID with a prefix of TSU. You can see this with the Zowe CLI itself by issuing the command zowe jobs list jobs | grep ACTIVE to get all jobs for the current user ID and filtering for active ones.
If before you log onto TSO there is an already active TSO address space for your userid then you won’t be able to start another session from your terminal and will get the message IKJ564251 Logon rejected as shown below.
If this occurs and you can’t log onto TSO from your terminal (which can occur if your emulator ended abnormally and you haven’t had your old address space terminated either by timeout, or a system programmer clean up task), then the Reconnect field at the logon prompt allows you to reconnect to the existing address space.
(Note, for some z/OS systems out there you may have a different way of logging on where you don’t have a TSO logon screen with the Acct Nmbr field visible. If that’s the case then look for the MVS acct. field on the ISPF primary menu (as shown below)
Command
Many mainframers typically logon at their TSO prompt and then open ISPF to begin working with jobs, files, RACF, and other z/OS services through panel based interfaces. Going straight to ISPF is so common that this is often made the default application, as shown screen shot above where the Command field shows ISPF filled in to automatically start ISPF after logon. If you leave the Command field blank (or press F3 when you’re in ISPF to exit one level back) you’ll find yourself at a raw TSO command prompt. This is where TSO commands like time can be issued, as shown below.
How can Zowe work with TSO commands ?
The endpoint for Zowe CLI TSO commands is the z/OSMF server. However unlike the other z/OSMF commands (jobs, files, workflows) for TSO you need to create a second profile. This TSO profile doesn’t contain any endpoint or authentication information, instead it contains details about the TSO connection you’re going to be using. A TSO session must include the account number, and the easiest way to determine this is to use the one from the TSO logon screen itself, in our case ACCT# as shown above (that I hope you wrote down from your TSO logon screen as you were asked to ealier !). To create a TSO profile called ukzowe4 using the account ACCT# use the command
zowe profiles create tso ukzowe4 -a ACCT#.
The command also allows you to specify attributes such as the character set, code page, region size, as well as number of rows and columns per screen.
Having created the TSO profile we can now use it to issue commands. Because the TSO profile doesn’t contain the endpoint by default it will use the default z/OSMF profile, although if you have more than one z/OSMF profile and need to point to a particular one you can append — zosmf-profile <name>. A TSO command can be thought of as a z/OSMF REST API call with a payload of TSO Account Name included. The TSO CLI command syntax is zowe tso issue command <CMD_NAME> and a nice simple command TIME will return the current z/OS clock time.
The power of having TSO commands at your fingertips in the Zowe CLI opens up a whole new world of what’s possible, and can be very useful if you find what you want to do on z/OS isn’t available as a core Zowe feature. In that case you can most likely drop to to execute raw TSO commands. For example, the zowe files copy CLI allows you to copy data sets but it doesn’t currently let you copy data sets to USS and vice-versa. However because data set copy functionality is available in TSO using the oget command, you can copy the file /u/directory/file.txt to a PDS member USER.PDSNAME(MEMBER) issuing the command zowe tso issue command "oget '/u/directory/file/txt' 'USER.PDSNAME(MEMBER)' . The commandzowe tso issue command LU lists your user attributes showing what groups you’re part of, and"LU <userID" lets you list attributes for the named userID. Recently for a jenkins test pipeline script I was working on I used the command zowe tso issue command "RACDCERT LISTRING(IZUKeyring.IZUDFLT) ID(IZUSVR)” to retrieve details for the z/OSMF key ring as I needed to get the name of the z/OSMF certificate. It was a life saver because without this I’d have had to submit some JCL and download the result, analyze error messages, and it’d have been messy. Zowe TSO command made it much easier. Because Zowe’s TSO commands authenticate to z/OSMF with the credentials defined to the profile you can only perform TSO commands that your user ID has privileges for.
What about the TSO session ?
Recall the TSO session where we logged on a terminal and created an address space through which we could issue commands. If TSO was created to allow a user to log onto z/OS and issue commands through a long running session, how does this work with Zowe CLI ?. The zowe tso issue command behind the covers does create a session, execute the command, wait and collect the response, and then disconnect the session. However, it is possible to use the Zowe CLI to do each steps separately and keep the session open for as long as is needed.
The commandzowe tso start address-space will create a TSO address space (your session). This will return a key to identify the address space that is used subsequently to direct the Zowe CLI tso commands to the address space withzowe tso send address-space <key> --data <data> . You can keep sending commands (as long as the address space remains active), and to log off (and cancel the address space) issue zowe tso stop address-space <key> .
Issuing three commands for start send and stop might seem like overkill when a single issue command does the same, but there are advantages to creating the session, keeping it alive to execute consecutive commands, and then closing it.
- Speed. Each TSO session costs z/OS resources to create and tear down, so if you are writing a script that issues back to back TSO commands you’ll see faster performance on both the client running the Zowe CLI and on z/OS itself if the session is persisted.
- Chaining. Some TSO commands modify the current session and will then rely on that modification (such as DD allocations). For those types of commands the session will need to be persisted and re-used during the sequence of individual commands.
Example of where TSO chaining matters
For an example of chaining commands earlier we used zowe tso issue command "oget '/u/directory/file.txt' 'USER.PDSNAME(MEMBER)' to copy a unix file from /u/directory/file.txt to the PDS member USER.PDSNAME(MEMBER) . What if we were copying JCL for a PROCLIB where the PDS was already allocated to the PROCLIB concatention ? Because the PDS is already allocated the ocopy will fail ? To make the command work we need to allocate the target data set with a shared lock before issuing the ocopy command. The ALLOC needs to persist across the commands so separate zowe tso issue command won’t work and the commands must be chained within a single TSO session.
If the commands were issued in a z/OS TSO command prompt they would be
In the Zowe CLI to achieve this result we can create an address space that returns the key, use this for subsequent TSO sends, and then stop the address space as shown below.
The full list of TSO commands is documented in the IBM Knowledge Centre together with examples. There are also great tutorials on-line as well as youtube videos from experienced system programmers showing the power of TSO. Married with the Zowe CLI that allows TSO commands to be issued in a client-server fashion from somewhere like a jenkins pipeline, an automation server, or anywhere else the CLI is running provides almost limitless capabilities and opens up a powerful doorway to z/OS.
If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.
