Zowe Development Updates

How to Add a UserID to z/OS Using a Zowe Script!

By | Blog, Zowe, Zowe Development Updates

Written by Daniel Jast, member of OMP’s Zowe community and zSystems Technical Specialist at IBM Worldwide Client Experience Centers

Here in Poughkeepsie at the Client Experience Center, our Z team is constantly looking for opportunities to modernize, by using new tools and technologies coming available on the platform. I am always looking for ways to leverage the Zowe platform to better manage the Z Infrastructure I supports. I provide many technical demos for Zowe, where we show off plenty of “Out of the box” functionality, as well as some extensions and scripts used in the  Zowe environment. I previously worked with my internal team and others on creating a common process to plug Jupyter Notebook web applications into the Zowe Desktop.

My team and I have now moved onto some scripting use cases, to better manage and automate tasks across their systems. One task that a Systems Programmer is required to do on a regular basis, is create UserIDs on a system, so a user can log on and get access to z/OS. Not only is this a repetitive task, but one has to know all the different system specific information, depending on which system the UserID is being added to. With help from my colleague Alex Lieberman, we created a base script for Systems Programmers to start adding z/OS UserIDs to systems. You can download and customize this script to fit your environment and can find the Github repository where this code is stored here.


Prerequisites: What you need set up

There are some things we are going to need to have set up on our z/OS System and on our local workstation before this script will run successfully. This section describes what to do prior to running the script. This script is written in bash, so you will need to have bash installed on your workstation.

Creating Zowe CLI Profiles

There are 3 Zowe CLI profiles needed for each system you are accessing. These 3 profiles are a z/OSMF profile, a SSH profile, and a TSO profile. To create the 3 profiles, you can use the following command syntax:

z/OSMF Profile:
zowe profiles create zosmf SYSNAME –host IPAddress –user ibmuser –pass myp4ss –reject-unauthorized false –overwrite

  • The z/OSMF Profile is used for the dataset and job API commands. These commands allow us to upload our JCL to the z/OS System, and then submit those datasets as jobs.

SSH Profile:

zowe profiles create ssh SYSNAME –host sshhost –user ibmuser –password myp4ss

  • The SSH Profile is used to issue Unix commands. We issue commands against the UserID’s home unix directory to change ownership and permissions.

TSO Profile:
zowe profiles create tso SYSNAME –account ACCOUNTnumber

  • The TSO Profile is used to issue TSO commands. We issue LISTUSER commands to verify our script is creating what we want.

Wherever you see SYSNAME in the profile creation commands, you should replace that with the name of the system(LPAR) that you are creating that profile to connect to. It is a good practice to name your profiles after the system you are connecting them too, so it is easy to differentiate between profiles.

Allocate a PDS to Store the Jobs

When looking at the script, you will notice that there are 6 different jobs that are uploaded to our z/OS and then ran. When our JCL is uploaded to z/OS, we need to put it somewhere before we run it. Therefore, allocate a JCL library where these jobs can be stored. You then need to change this value in 2 different places throughout the script.

First change the target JCL Library where you want these jobs to be stored when they are uploaded to z/OS:

zowe zos-files upload stdin-to-data-set “DANJAST.JCL(ZWEUSERX)”

Second, where the job is being stored when submitting the job:

jobid1=`zowe jobs submit data-set “DANJAST.JCL(ZWEUSER1)” –rff jobid –rft string`

Add REXX to Your System

If your organization uses SMS to manage where a UserID’s datasets should be directed, you will need a program to go into your ACS.SOURCE(STORCLAS) member to add the new UserID. Alex Lieberman has written a basic REXX script which goes into the STORCLAS member and adds a new line for the new user being added. The REXX to do so has been uploaded to the Github repo here. This REXX needs to be added to your z/OS System prior to script execution. You also need to point JOB 1 at the dataset you created for the REXX.

Change the following line of JCL in JOB 1 to point to your REXX location:

EX ‘SYSL.REXX(INACSSRC)’ ‘${username},${description}’

NOTE: You may need to edit the REXX script to fit your organization’s STORCLAS member.

Script Part 1: Set Variables
Scripting with the Zowe CLI commands is easy. Dan is a programmer with few years of experience and recognizes an opportunity for automation, which is why he writes simple bash scripts to automate z/OS tasks. The first thing we are going to want to do in any script we write leveraging Zowe CLI commands, is to set our variables. In this use case, we need to get the UserID the Systems Programmer wants to add to the z/OS System using the following code:

echo ‘What is the UserID you would like to add to z/OS? This must be less than 8 characters long.’

read username

echo The username you are creating is: $username

This takes in the user’s input for what the username will be, and loads that into the $username variable. Now throughout the rest of our script, $username will be replaced with what the user specified. This can be within Zowe commands, as well as within JCL in the script. Some of the other variables we are going to want users to specify at the beginning of the script include:
$system = What z/OS system we are adding this new UserID too

$description = Why are you adding this userid to your system? (Documentation/management purposes)

In setting the $system variable, we need to add some logic to allow for the user to specify which system is their intended target system to add the UserID too. Customize this this script to fit the environments you would like to exploit.

Script Part 2: Edit Script JCL

Throughout the script, there are 6 different jobs we are going to submit. These jobs, in their current state, have JCL that is in the syntax which the Poughkeepsie Client Experience Center uses for their JCL. Your organization may customize your JCL differently, therefore you will need to review all JCL in the script. As good practice, you can manually load these jobs into datasets and add a user. This way, you can ensure the jobs function the way you intend, and then any changes you make to the JCL you can put in your script. The purpose for the 6 different jobs submitted are as follows:

  1. JOB1: Submit a REXX program that edits the ACS.SOURCE(STORCLAS) member to add SMS logic for UserIDs
  2. JOB2: Create RACF Permissions / Work for new userid
  3. JOB3: Create the ALIAS for the UserID on the system. This is a CATALOG entry to allow dataset creation for the HLQ of the UserID
  4. JOB4: The ISPPROF dataset is needed by ISPF for each userid when using ISPF. When they logon, the logon proc will need this dataset to be active before they can successfully access ISPF.
  5. JOB5: To access OMVS (USS), the userid on PEL systems will attempt an auto-mount of a ZFS file in naming convention: ZFS.USER.<userid>.  So, when the user enters TSO ISH or TSO OMVS, auto-mount will attempt a mount with the following specifications:   mount point /u/<userid>  mounted to file OMVS.ZFS.USER.<userid>. The ZFS file is needed.  Create the ZFS file with the following batch job.  Be careful to ensure that words “aggregate” and “compat” are lower-case.
  6. JOB6: Add OMVS segment for userid. Remember the UID we got from TSO ISH?….. It was 209.  This is where that comes in to play.  We need to add an OMVS segment to the userid.  OMVS segment requires the UID.  Be careful to check the GID (group ID) with TSO ISH.  Be careful that the syntax is case-sensitive!

To access the script, please visit the following repo:

Good luck scripting with the Zowe CLI! If you create complex scripts on your own to automate z/OS tasks, consider contributing those scripts back to the open source community so others can use them!

We’d love to hear about what you’re doing. Join the Zowe channels on the Open Mainframe Project Slack today!

Zowe is now available on IBM Z Trial!

By | Blog, Zowe, Zowe Development Updates

by Pluto Zhang, Zowe community member and IBM developer

This blog post originally ran on the IBM Developer blog earlier today.   

Zowe™, a project of the Open Mainframe Project™, is now available on IBM Z Trial. You can get your hands on a Zowe trial on demand at no charge. This trial environment is a fully configured z/OS environment with Zowe preinstalled and set up along with a set of integrated hands-on tutorials. You can start your Zowe trial experience within hours of completing a simple registration to be assigned with a trial system for 3 days.

Figure 1. zTrial wizard for Zowe

Figure 1. zTrial wizard for Zowe

Register and try it out

Explore the project first

In this Zowe trial, you can experience cloud-like modern interfaces that Zowe provides for interacting and working with z/OS. You will also learn how to create and extend Zowe using sample plug-ins and extensions. This trial environment includes a sample Node.js API, a sample web application plug-in, as well as a sample Zowe Command Line Interface (CLI) extension along with all required resources and files.

The trial offers a set of basic scenarios with easy-to-follow instructions that explain how to complete the following tasks. Each scenario takes about 15-20 minutes.

  • Get started with Zowe, including Zowe Desktop and Zowe CLI
  • Extend Zowe with new APIs
  • Extend Zowe Desktop with new web application
  • Extend Zowe CLI with new CLI commands

New to Zowe? No problem! You can get to know the modern Zowe interfaces through several simple tasks in the “Getting started with Zowe” scenario.

Figure 2. Getting started with Zowe scenario

Figure 2. Getting started with Zowe scenario

Already familiar with Zowe? You can learn how to extend Zowe by creating your own APIs and applications by following the step-by-step instructions provided.

Figure 3. Extending Zowe API scenario

Figure 3. Extending Zowe API scenario

Figure 4. Extending Zowe Application Framework scenario

Figure 4. Extending Zowe Application Framework scenario

Figure 5. Extending Zowe CLI scenario

Figure 5. Extending Zowe CLI scenario

We hope you find this trial program informative in getting started with Zowe as you kick-start your journey toward becoming a developer, extender, and/or contributor to this new open source project on z/OS.

Register and try it now!

To learn more about the Open Mainframe Project, click here. To learn more about Zowe, click here.

Zowe™, the Zowe™ logo, and the Open Mainframe Project™ are trademarks of The Linux® Foundation. Linux is a registered trademark of Linus Torvalds.