Mainframe Advanced Deployment using IBM UrbanCode Deploy (UCD) to perform a CICS NewCopy and a Db2 Bind.

Date: January 25, 2023

Overview of an Advanced zOS Deployment 

One of the areas in software delivery that drives the most value for your dollar is automating release deployments.   This is especially true in mainframe environments where deploying software is tedious at best and can often be nerve-racking.   Using IBM UrbanCode Deploy (UCD), deploy time of an application can be reduced from a few hours to 3 minutes.

In this blog, I want to share an example of what an ‘advanced’ deployment looks like using IBM UrbanCode Deploy.    For the mainframe, as you deploy data sets for a COBOL program, the update you apply may require a CICS NewCopy operation to be performed.   Further, your code update could require a Db2 Bind operation be run.  This can also be referred to as a DBRM.   This is an ‘advanced’ deployment in the mainframe world and we will look at these examples.

Using IBM UrbanCode Deploy, deploy time of an application can be reduced from hours to minutes using a repeatable process which provides consistent results.  Let’s get started!

The Starting Point

A component process that is typical for a mainframe deployment will look like this:

In this example, we are deploying data sets to a PDS member.   With this in mind, we are going to build upon this to support situations where a CICS NewCopy or a Db2 Bind is required to support the datasets that are deployed.

Adding Steps to Support the Advanced Use Case

Before we begin, please sure you have the ‘zOS Multi Generate Artifact Information’ plugin installed as shown below:

If you do not have this automation plugin installed, you can download the plugin from this URL:

https://urbancode.github.io/IBM-UCx-PLUGIN-DOCS/UCD/#zos-multi-generate-artifact-information

For this blog, we are working with a component named zOS_TM089.   Here are the steps:

1. To begin our update to the component process, we are going to add a step named ‘Generate Multiple Artifact Information’ to our process as shown below:

        We named the step ‘Artifact_Info’.   A simple name is a best practice without spaces.   Click on the pencil icon to view the properties in the step:

        We will need to configure the “Deploy Type Filter JSON” field.   In this example, we placed the following in that field as a starting point:

      We then need to scroll down and edit the “Template JSON” field as shown below:

      The following JSON is a sample that we used to get started:

     NOTE: the bind card format above should be checked with the client’s bind card format and adjusted.  This is an initial pass to get started. 

      In the BIND JCL above, we have information about the DB2 member name and bind.   As we start processing our list of DBRMS to do BINDS, it will basically input these bind cards into our JCL.   That is why sometimes people call it BIND CARDS or some people call it DBRMS LIST.

2. Save your changes and close this step.

3. From the step palette on the left, drag and drop the ‘Switch’ step to your process design.

4. Edit this step and rename it ‘Check for CICS Loads’ as shown below:

For the “Check for CICS Loads” switch step, add this property to the ‘Property Name’ field:

${p:Artifact_Info/cics-loads-count}

5. Click OK to close this step.

6. From the Step Palette on the left, drag and drop another Switch step on to your process.

7. Name this switch step “Check for DBRMS” or “Check for Bindcards”.

8. In the Property Name field, add this property:

${p:Artifact_Info/bindcards-count}

9. Click OK

10. From the ‘Artifact_Info’ step, connect two lines to each switch statement as shown below:

11. Drag and drop two Submit Job steps from the step palette on the left to the process design.

12. Connect your steps with lines as shown below including the lines down to the Finish step:

13. From each switch statement, add another line that connects to the Finish step. Untoggle the ‘default’ to Finish and put in a value of 0 as shown below:

14. Edit each “Submit Job” step to change their names to ‘Submit Bind Job’ and ‘Submit NewCopy Job’ as shown below:

15. Click Save to save our process so we don’t lose any of our updates.

You are now starting to understand what an advanced process looks like for a mainframe deployment.   There are other scenarios that can be considered, however, we are focusing on a CICS NewCopy or a DB/2 Bind which are very common additions to a mainframe deployment process.

In the next section, we will get into the details around each of these types of operations.

The Submit Job – CICS NewCopy 

To get started, edit the ‘Submit NewCopy Job’ step as shown below:

This is a pre-made step provided by the zOS Utility plugin.   Using this plugin step, there are two ways to achieve what we are trying to accomplish:

1. State a JCL member that is currently on the system to run. You do this by putting the JCL data set and member in the JCL Dataset field.

or

2. You select a ‘JCL File’ on the USS side. It will move it over to MVS side and run it.   However, we recommend that you put the JCL directly into the step in the ‘JCL’ field.  This allows you to replace properties in the JCL for variability.    The properties use the ‘Replace Tokens’ feature.

We will follow the recommended best practice by providing some example JCL that submits a NEW COPY to place in the ‘JCL’ field.   Here is the example:

The end user can customize this sample JCL to fit their environment.   Here is a real-world example:

 This JCL includes the job card name plus the rest of the JCL syntax.   Some of our clients make the job card name a property in UCD.

Notice that the JCL refers to an output property set in the “Artifact_Info” step for the “cics-loads”.    It also will substitute the @CICSREG@ token shown above as well.    To do this, we use the “Replace Tokens” field.   You place this in the token replace field:

    @CICSREG@ -> ${p:environment/cics.region}

In our UrbanCode Deploy (UCD) application, we will set the ‘cics.region’ property for each of our target environments.   Here is an example for my Dev_New environment:

Let’s return to our component step which is ‘Submit NewCopy Job’ as shown below:

I would like to point out that there is a default job statement field (highlighted above) that uses a property you could use if you didn’t fill in the JCL field.   Notice that this field refers to ${p?:deploy.env.jobstatement}.   The ‘${p?:’ prefix means to only use this field if the property is set.  For the purpose of this blog, we will not set this property and we will use the JCL field.

NOTE: If you set this property, it would use this property value as the default job statement and will ignore the JCL field above it.

Before we move to the next topic, I did want to share with you that for a CICS NEWCOPY, there is an alternative way of performing these steps without running JCL.    As an alternative, you can use the CICS Plugin, which uses the CMCI administration interface provided by CICS.   This could be the preferred way to update resources in CICS, especially if the CICS system is not accepting commands from the MVS console (which can be the default behavior).   Many thanks to @Mathieu Dalbin of the DevOps Acceleration Team (DAT) for sharing this with me.   You can download the CICS Transaction Server (CICS TS) plugin from this link:
https://urbancode.github.io/IBM-UCx-PLUGIN-DOCS/UCD/CICS/

Monitoring the Submitted Job

We are almost done.   You might ask, how would UrbanCode Deploy know that the JCL submission completed?   To answer this, scroll down to the bottom this step dialog and check the box for ‘Show Hidden Properties’ as shown below:

We need to set these four JES properties to our environment to allow us to monitor the batch job submission.

JES is short for Job Entry Subsystem which is a component of IBM’s MVS mainframe operating system that is responsible for managing batch workloads.   When we submit the job, UCD will go through a command that talks directly to MVS to monitor the job using these properties.

Since our UCD Agent is running on the same mainframe as our JES system is on.   We often just use localhost here.   The JES monitor port is what JES is listening on.  The default port is 6715.   I think IDz uses this same port.  The JES.user is a mainframe user id that has access to submit jobs on the system.   It is typically the same id used with the UCD agent.   The password field has a ? on the property meaning it is not a required property.   If the id has permissions to submit jobs using “Passtickets”, it does not need a password.   By default, the “Use Passticket” is set (true) as shown on the step above.

We typically set these properties for each target environment.   Here is an example for my ‘Dev_New’ environment:

You are all set!   The concepts for monitoring are all the same for the Db2 Bind job.   We will review that in the next section.

The Submit Job – Db2 Bind 

The step that will handle the DBRMS or DB/2 Bind will be very similar to what you completed for the CICS NewCopy.   To begin, edit the step by clicking the pencil icon.  In the JCL field, here is an example JCL you can leverage to perform the bind:

Here is an example screen shot of the step:

This step leverages a property for the DB/2 subsystem name (SSN).   In my case, I set this property at the environment level to the value shown below:

You are good to go!

Conclusion

One of the areas in software delivery that drives the most value for your dollar is automating release deployments.   This is especially true in mainframe environments where deploying software is tedious at best and can often be nerve-racking.   Using IBM UrbanCode Deploy (UCD), deploy time of a mainframe application can be reduced from a few hours to 3 minutes.

IBM has worked closely with teams who write mainframe software and who deploy routinely to the mainframe.   This includes the more advanced deployment use cases that we covered in this blog that might include a CICS NewCopy or a Db2 Bind.  Capabilities have been built-in to the product to support these use cases with our plugins out-of-the-box.