Getting started with CICS by using z/OSMF workflows

This scenario takes a CICS® system programmer through the steps to provision a simple single CICS container, by using z/OS® PT to run the z/OSMF workflows.

Use these instructions to provision a container rapidly before you try z/OS PT with IBM® Cloud Provisioning and Management for z/OS. You can become familiar with the artifacts you need to provision a container, the z/OS PT command line, and the provisioning lifecycle.

Before you begin

Before you, a CICS system programmer, provision a container by using z/OSMF workflows, complete the following checks.

Ensure that z/OSMF is installed and configured. See Configuration in the z/OSMF Configuration Guide.
z/OSMF performs a system management role, and is accessed through a web interface. z/OSMF is a single point of control that allows you to:
- View, define, and update policies that affect system behavior.
- Monitor the performance of the systems in your enterprise.
- Manage your z/OS software.
- Perform data management tasks.
- Consolidate your z/OS management tools.
- Run workflows to help you perform a common activity on z/OS.
Ensure that your user ID has the appropriate authority to run workflows, by granting it the following access:
- READ access to the ZMFAPLA class SAF-prefixZOSMF.WORKFLOW.WORKFLOWS.
- READ access to EJBROLE SAF-prefixIzuManagementFacilityWorkflow.izuUsers
For more information, see Help with security setup in IBM Z solutions product documentation.
Install z/OS PT by following the instructions here: Installing z/OS Provisioning Toolkit.

Before you can provision a CICS container, ensure that your user ID has the following authority:

Authority to start a CICS region as a started task.
Sufficient authority in a test environment for the following tasks:
- Allocating data sets.
- Creating and deleting log streams.
- Adding a procedure into a PROCLIB.
- Issuing console commands.

About this task

This task walks you through provisioning a simple single CICS container by using the z/OSMF workflows. Every step in this task runs under your user ID. A Job Entry System (JES) job is submitted for every step, and you can see the output from the JES jobs, and the source JCL. You can view the source and the output to help you to become familiar with how the workflow provisioning process works.

The following diagram shows how you can configure and run a supplied image to provision a CICS container by using the z/OSMF workflows.

This image shows how to provision a CICS container by using z/OSMF workflows, as described in the surrounding text. — Figure 1. Provisioning a CICS container by using z/OSMF workflows

Procedure

Connect z/OS PT to z/OSMF.
1. Edit the z/OS PT zosmf.properties UTF-8 file in the /zospt/config directory. Update the following properties to use the z/OSMF workflows:
  
  port
  
  The HTTPS port that z/OSMF listens on. Ask your z/OSMF administrator for this information.
  
  hostname
  
  If you are running z/OS PT on the same LPAR that the z/OSMF server is running on, set hostname=localhost. To use a host name of localhost, configure z/OSMF to listen for requests on localhost by specifying HOSTNAME(*) in the IZUPRMxx parmlib member that contains configuration values for your z/OSMF server. If you do not know which LPAR the z/OSMF server is running on, ask your z/OS administrator. Otherwise, specify the host name.
  
  systemNickname
  
  Specify this property to set the nickname of the system on which the provisioning workflows are to run. If no value is specified, z/OS PT attempts to determine a default system nickname, which runs the workflows on the LPAR on which the z/OSMF server is running. If this default cannot be determined, or is not appropriate, ask your z/OSMF system programmer for the nickname of the LPAR on which you want to provision CICS regions. Alternatively, if your user ID has authority to see them, the zospt ps -a command reports available system nicknames. You must specify the host name and port of the z/OSMF server before you run the zospt ps -a command.
2. Check that z/OS PT connects to z/OSMF by issuing the following command:
```
zospt ps -a
```
  z/OS PT reports back basic information about the z/OSMF server.
```
2018-04-21 17:03:01  IBM z/OS Provisioning Toolkit V1.1.1
2018-04-21 17:03:05  Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.
2018-04-21 17:03:06  z/OS level is V2R3.
2018-04-21 17:03:06  z/OS Management Facility level is V2R3.
2018-04-21 17:03:06  z/OSMF system nicknames are MV01, MV02, MV03, MV04, MV05, MV06, MV07, MV08, MV09.
2018-04-21 17:03:06  Getting started workflows will run on the system with nickname MV01.
NAME    IMAGE   OWNER   CREATED                 STATE   TEMPLATE        SYSTEM  CONTAINER TYPE
```
Edit the cics.properties file in the zospt/templates/cics_getting_started directory to configure the CICS region for the release you require (V5.1 or later) and to meet your naming standards. You must edit any property values that are surrounded by <> characters.

The cics.properties file contains the minimum set of CICS properties that is needed for you to get started, and information about each property that needs to be set. This list of properties is a subset of the full list of CICS properties.

Run the cics_getting_started_workflow image by issuing the following command:

zospt run cics_getting_started_workflow

If the provisioning is successful, output similar to the following example is displayed:


2018-04-23 16:02:35  IBM z/OS Provisioning Toolkit V1.1.1
2018-04-23 16:02:35  Running image cics_getting_started_workflow.
2018-04-23 16:02:35  Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.
2018-04-23 16:02:37  Creating container USERTEST with id nzmay83vng8o4k9vkklaaxk8z4onwpdy on system MV01.
2018-04-23 16:02:43  Validating allowed properties for CICS getting started workflows - Complete
...
2018-04-23 16:03:57  Starting the CICS region - Complete.
2018-04-23 16:03:58  DFH_REGION_APPLID : USERTEST
2018-04-23 16:03:58  DFH_CICS_TYPE : Unmanaged
2018-04-23 16:03:58  Created container USERTEST with id nzmay83vng8o4k9vkklaaxk8z4onwpdy on system MV01.
2018-04-23 16:03:58  Container USERTEST has been started.

You can also run the following command to view your provisioned container, and to see that it has a container type of Workflow:

zospt ps


2018-04-26 11:41:21  IBM z/OS Provisioning Toolkit V1.1.1
2018-04-26 11:41:24  Connecting to z/OSMF on host localhost port 32000.
NAME      IMAGE                           OWNER     CREATED               STATE         TEMPLATE   SYSTEM   CONTAINER TYPE
USERTEST  cics_getting_started_workflow   user01    2018-04-26T11:34:56   provisioned   N/A        MV01     Workflow

If the provision fails, the output contains the following diagnosis information; most importantly, the job information:


...
2018-04-23 16:38:56  ERROR: The request failed to complete.
2018-04-23 16:38:56  IZUWF0150E: The job that was submitted in step "Validating access to CICS data sets" failed during automation processing. Return code: "CC 0004" .
2018-04-23 16:38:56  Workflow Name              : provision_USERTEST_1523543918825
2018-04-23 16:38:56  Job Information            : JOBNAME: IZUWFJB, JOBID: JOB25101, CC 0004
2018-04-23 16:38:56  Current Step Title         : Validating access to CICS data sets
...

The workflow steps submit JES jobs under your user ID. If the run fails, you can use the information that is returned in the failure to examine the job output and find the problem.

View the JES job to diagnose the error.
Find the job and view the output for the failing job step. You can also view the source JCL for any of the jobs, because the jobs all run under your user ID. Use this information to diagnose and fix the error.

Deprovision the failed container by using the following command:

zospt rm -f containerName

In this example, containerName is USERTEST. The output shows a successful deprovision.


2018-04-23 17:00:22  IBM z/OS Provisioning Toolkit V1.1.1
2018-04-23 17:00:22  Performing deprovision on container USERTEST.
2018-04-23 17:00:28  Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.
2018-04-23 17:00:35  Container USERTEST has been deleted.
2018-04-23 17:00:35  Deletion of environment completed successfully.
2018-04-23 17:00:35  Removal of all containers completed successfully.

The deprovision process removes everything that was created during the provisioning process, so no manual deletion is needed.

Rerun the zospt run command. Issue the following z/OS PT command:
```
zospt run cics_getting_started_workflow
```

Results

You successfully connected z/OS PT to z/OSMF, customized the CICS region, and used the z/OS PT command line interface to provision and deprovision a CICS container.

What to do next

Before you move on to trying a scenario that uses Cloud Provisioning, you can try exploring further, for example, by adding further customization to the cics.properties file. To do so, follow these steps:

Try out the other zospt commands. See The zospt command syntax.
Deprovision your CICS container by using the following command, where containerName is USERTEST in this example:
```
zospt rm -f containerName
```
Change some properties in the cics.properties file to configure your CICS region, for example, setting SIT parameters or DFHRPL concatenation. For more information, see Optional CICS properties.
Reissue the zospt run command.

When you are ready, you can move on to Getting started with CICS by using IBM Cloud Provisioning and Management for z/OS, which uses the same workflows and configuration, but introduces Cloud Provisioning. Before you start this scenario, you must deprovision your CICS container by using the following command, where containerName is USERTEST in this example:

zospt rm -f containerName