A screenshot showing the IBM z/OS Provisioning Toolkit logo.

The z/OS Provisioning Toolkit (z/OS PT) provides a modern solution for the creation and deletion of CICS regions and other subsystems on IBM Z.  In late April 2018, we released version 1.1.1 of the toolkit, which enables CICS systems programmers to easily evaluate the toolkit and rapidly provision their first CICS region. This post provides a step by step guide to provisioning a CICS region using z/OS PT.

August 2018 update – z/OS PT version 1.1.2 is now available and makes the getting started experience even easier, by providing alternatives to the need to create logstreams for the CICS region, which some CICS systems programmers did not have authority to do. This guide is updated to reflect those changes.

You can follow this step by step tutorial, to install, configure and run the toolkit.  All the steps are performed through a 3270 terminal, using OMVS and OEDIT to run the toolkit and edit files. I chose to run my 3270 terminal emulator with a screen size of 62 lines by 160 columns, as this minimizes line wrap for some of the messages emitted during the provisioning process.

The pre-requisites needed to run the Getting started with CICS by using z/OSMF workflows scenario in z/OS PT 1.1.2, have been kept to a minimum to make it as simple as possible to provision your first CICS region.  You will need:

  • Access to a z/OSMF server.  z/OSMF includes a workflow engine. The toolkit provides workflows that run in z/OSMF to automate the steps needed to provision CICS.
  • The z/OS Provisioning Toolkit 1.1.2 downloaded from https://developer.ibm.com/mainframe/products/zospt/.
  • A user ID with authority to perform all the steps needed to create the CICS region:
    • Allocate datasets.
    • Optionally create and delete logstreams.
    • Add a procedure into a PROCLIB.
    • Issue console commands.
  • An APPLID you can use for the provisioned CICS region. The CICS region will be run as a started task and a SAF profile needs to be in place to ensure the CICS region runs under an appropriate user ID.

Further information on the supported software levels for Java and z/OSMF are available in the z/OS Provisioning Toolkit Software Compatibility Report

The steps shown here, take you through a golden path to the point of provisioning your first CICS region with z/OS PT.  However, as we all know, sometimes things go wrong, so if you hit a problem on your system, here are some tips:

  1. Every step in the provisioning process submits a JES job and all the steps will run under your user ID. You can look at the source JCL and the JES job output to help diagnose problems.
  2. Users of the toolkit post questions at dW Answers and the development team monitor these.  You may find the answer to your problem here already, but if not, please ask us and tag your question with zospt.

Installing the zospt command line tool

When you download z/OS PT, you will get a zip that needs to be unzipped on your workstation.  Within the extracted zip is a pax file containing the zospt command line tool.  The pax file must be transferred to a zFS directory in binary mode.  I used ftp to transfer the file to my home directory /u/millwoo and the steps below assume you will transfer the file to your home directory.

Unpaxing zospt

These steps unpax zospt into a directory on zFS. In the steps that follow I use the tilde character ~ as an alternative to typing my home directory.

  1. From a TSO READY prompt, type omvs and press enter.
  2. You are now in a Unix System Services shell and are likely to be in your home directory. If not, change directory to your home directory.
  3. Enter mkdir zospt112 to create a directory for zospt to be unpacked into
  4. Type cd zospt112 to change into the directory.
  5. Enter the command pax -rf ~/zospt_v1.1.2.pax to unpax zospt into the directory you are in.
  6. Type the command ls to list the contents of the directory. You should see a new directory called zospt.

Its worth noting at this point, that when a provision is run, the user ID under which the z/OSMF server is running needs permission to be able to access the contents of the zospt directory and its sub-directories, so that it can load and run the automation workflows. You will need to ensure that this access is granted. It is worth checking the permissions on your home directory, the zospt112 directory and the unpaxed zospt directory.

Adding zospt to your path and setting the location of JAVA_HOME

These steps will enable the zospt command line tool to be run from any directory on zFS, by adding the location of zospt to your path, and defining where zospt can find a Java runtime. By adding statements to a file in your home directory called .profile, the settings will take effect each time you use omvs.

Note: It is important that the host code page settings are correct in the 3270 emulator, to ensure that the dollar symbol resolves successfully. To validate this before making the change, you could issue the command echo $PATH. If this returns $PATH rather than resolving the PATH variable to its current value, then it is likely the dollar symbol is not being correctly translated.

  1. Enter the command oedit ~/.profile
  2. Add the following lines to the end of the file, where <java install dir> is the install location of java on your system.

  3. export PATH=~/zospt112/zospt/bin:$PATH
    export JAVA_HOME=<java install dir>

  4. Save the file.
  5. Enter the command . ~/.profile to activate the changes to your profile. Note that the initial period character is part of the command.
  6. Enter the command zospt
  7. You should see the output:

A screenshot showing the output of running the zospt command with no arguments.

Configuring zospt to connect to z/OSMF

In these steps, zospt is configured with the hostname and port of the z/OSMF server.

Note: In this example, zospt and z/OSMF are on the same LPAR. If they are on different LPARs, the zFS directory structure containing zospt must be shared across the LPARs for zospt to function correctly.

  1. Enter the command oedit zospt/config/zosmf.properties

  2. A screenshot of the zosmf.properties file opened in OEDIT.

  3. Modify the port number to the port the z/OSMF server is listening on.
  4. If necessary, modify the hostname that z/OSMF is listening on.
  5. By default, CICS will be provisioned onto the LPAR on which z/OSMF is running. If this is not appropriate, specify a different LPAR by changing the property systemNickname.
  6. Save the file.
  7. Enter the command zospt ps –a to test the connection. You will be prompted for your password which is sent to z/OSMF to verify you are allowed to access the z/OSMF server. You should see some information about the z/OSMF server reported back from the command.

A screenshot showing the output of the zospt ps -a command.

Customizing the provisioning process

In these steps, we customize the provisioning process to use appropriate naming conventions and to describe the configuration of the CICS region we intend to provision.

  1. Enter the command oedit zospt/templates/cics_getting_started/cics.properties
  2. Enter the command F DFH_ 1 4 to highlight the properties that can be set. There are approximately 20 properties in the cics.properties file, each of which should be reviewed and modified if necessary.

  3. A screenshot of the cics.properties file being edited using OEDIT

  4. For each property, review the default value. If the default value is wrapped in angle brackets, it must be replaced with an appropriate alternative. These are described in the table below.
    Replace With
    <APPLID> The APPLID to be used for the provisioned CICS region.
    <CICS_INSTALL_HLQ> The high level qualifier for the CICS install datasets e.g. <CICS_INSTALL_HLQ>.SDFHLOAD should be a valid dataset name.
    <CICS_REGION_DATASETS_HLQ> The high level qualifier under which the CICS regions datasets can be created.
    <STARTED_TASKS_USERID> The user ID under which the CICS region will run. This ID is used when determining the logstream names for the CICS region.
    <VTAMNODE> The name of a VTAM node to be activated to activate the applid of the CICS region.
    <CICS_LICENSE_DATASET> The dataset containing the CICS license.
  5. Save the file

Customizing the JOB statement for submitted JES jobs

Each step in the provisioning process will be submitted as a JES job. z/OSMF inserts a JOB statement into each JES job submitted. An example of the default job statement is shown below.

//             MSGLEVEL=(1,1),REGION=0M,NOTIFY=USER01

You will need to ensure that the job statement is appropriate before running the provisioning process. Completed JES jobs should not be automatically purged, as z/OSMF needs to read the job output to be able to determine whether each job has completed successfully or not.

If you need to change the default job statement used by z/OSMF, you will need to log onto the z/OSMF UI (https://<hostname>:<port>/zosmf/), then click on Workflows in the left hand navigation bar. From the Workflows view, select Actions -> Customize JOB statement.
A screenshot of the z/OSMF UI, showing how to customize the job statement used for the workflows
This only needs to be done once and then the customized JOB statement will be used each time a job is submitted under your user ID.

Provisioning the CICS region

In this step, we use the zospt command line utility to initiate the provisioning of the CICS region.

  1. Enter the command zospt images to list the images that are provided with zospt. Images encapsulate further configuration that may be required for a provisioned region.

    Note that there is an image called cics_getting_started_workflow. This image is provided to enable the CICS getting started scenario to be run.

  2. A screenshot of the output from a zospt images command.

  3. Enter the command zospt run cics_getting_started_workflow to initiate the provisioning process. You will be prompted again for your password. If the provision is successful you will see output similar to that below.
    1. A screenshot of a successful provision of a CICS region. By following this guide to provisioning CICS you should be able to provision a CICS region similar to the one shown in the screenshot.

      Next steps

      I hope you have found this guide to provisioning CICS to be useful. Your feedback is appreciated should you wish to leave a comment below.

      Now that you have successfully provisioned a region, why not try to customize it further, to see if it can be configured to meet your requirements. The first step in this process is to deprovision the region you have just created, so you can then provision it again with different configuration options. The command to do this is zospt rm -f <applid> where <applid> is the APPLID of the CICS region you provisioned.

      An example of how to further customize the provisioned CICS region is provided in my blog article Customizing your z/OS PT provisioned regions.

Join The Discussion

Your email address will not be published. Required fields are marked *