Plug-in Documentation

CICS TS

Overview

Overview

CICS Transaction Server for z/OS provides scalable, general-purpose, transaction processing solutions for high-volume updates to shared data. Businesses have used CICS to differentiate themselves by creating, extending, and evolving their critical applications.

You can use steps from the CICS TS plug-in for UrbanCode Deploy, in combination with other plug-ins,to automate the deployment and undeployment of CICS applications.

In a wider context, the CICS TS plug-in can be used in conjunction with other CICS tooling to automate the build and deployment of CICS artifacts as part of a continuous delivery environment.

Need help? View Questions or Ask a Question.

Features

The plug-in includes steps to:

  • Install CSD resources, groups, and lists
  • Install BAS resources, resourcedescriptions, and groups
  • Discard resources
  • Enable and disable resources
  • Open and close resources
  • New copy and phase in resources
  • Make resources available and unavailable
  • Check the available, enable,and openstatus of resources
  • Scan pipelines
  • Deploy and undeploy a bundle
  • Deploy and undeploy an application
  • Check the status of an application
  • Enableand disable an application
  • Make an application available and unavailable

Component Templates

Overview

You can use component templates to reuse component processes and properties across similar deployment scenarios. The CICS TS plug-in provides the CICS TScomponent template.

Using a component template

To use acomponent template, you should first create a newcomponent from the component template:

  1. Fromthe Componentstab, click Create Component.
  2. In the dialogue box that opens, select the relevant templatefrom theTemplatelist. For example,CICS TS.
  3. Fill in the other required fields, and click Save.

Updating a CICS supplied component template

The component template will be updated when the CICS TS plug-in is updated.

You can bind your component to a specific version of the template to avoid automatically using newer versions. If you wish to modify the template processes, you should copy the process and make changes to the copy.

More information

For more information aboutcreating, using, and editingcomponent templates, see the Component Templates section of the UrbanCode Deploy documentation or watchthe introductoryvideo, Component Templates in IBM UrbanCode Deploy v6.0.

CICS TS template

The CICS TS template contains the following processes:

Install new programs and transactions (BAS)

Copy program load modules, define program and transaction resources in BAS, then install the resources.

Install new programs and transactions (CSD)

Copy program load modules, define program and transaction resources in CSD, then install the resources.

New copy installed programs

Copy program load modules, then new copy installed programs.

Discard files

Disable, close, then discard files.

Rollback programs

Rollback program load modules, then new copy installed programs.


Image showing the 'Install new programs and transactions (BAS)' process.

Image showing the Install new programs and transactions (BAS) process.

Steps

Process steps in the CICS TS plug-in

Check available status of resources

Check if installed resources are available or unavailable. Requires CICS TS V5.2 or later.

Input properties for the Check available status of resources step
Name Type Description Required
Expected Status Enumeration:AVAILABLE, UNAVAILABLE The expected status. Yes
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:BUNDLE The type of resource to check. Yes
Timeout (s) String The number of seconds to make retry attempts before a timeout occurs. The valid range is 0-1800, where 0 means no retry attempts are made. The default is 15 seconds No

Check enable status of resources

Check if installed resources are enabled or disabled.

Input properties for the Check enable status of resources step
Name Type Description Required
Expected Status Enumeration:DISABLED, ENABLED The expected status. Yes
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:ATOMSERV, BUNDLE, CMDT, DB2ENTRY, EPADAPT, EPADSET, EVNTBIND, EXTRATDQ, INTRATDQ, JVMSERV, LIBRARY, LOCFILE, LOCTRAN, PIPELINE, PROCTYP, PROGRAM, URIMAP The type of resource to check. Yes
Timeout (s) String The number of seconds to make retry attempts before a timeout occurs. The valid range is 0-1800, where 0 means no retry attempts are made. The default is 15 seconds No

Check open status of resources

Check if installed resources are open or closed.

Input properties for the Check open status of resources step
Name Type Description Required
Expected Status Enumeration:CLOSED, OPEN The expected status. Yes
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:CMDT, EXTRATDQ, LOCFILE, TCPIPS The type of resource to check. Yes
Timeout (s) String The number of seconds to make retry attempts before a timeout occurs. The valid range is 0-1800, where 0 means no retry attempts are made. The default is 15 seconds No

Check status of an application

Check if an installed cloud enabled CICS application is available, unavailable, enabled, or disabled. Requires CICS TS V5.1 or later.

Input properties for the Check status of an application step
Name Type Description Required
Application Definition String The name of the CICS application definition. The default value is ${p:cics.application.definition.name}. Yes
Application Version String The application version in major.minor.micro format (for example, 1.2.345). The default value is ${p:cics.application.version}. Yes
Expected Status Enumeration:AVAILABLE, DISABLED, ENABLED, UNAVAILABLE The expected status. Yes
Timeout (s) String The number of seconds to make retry attempts before a timeout occurs. The valid range is 0-1800. Leave this field blank to not retry. No

Close resources

Close installed resources.

Input properties for the Close resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:CMDT, EXTRATDQ, LOCFILE, TCPIPS The type of resource to close. Yes

Deploy application

Deploy a cloud enabled CICS application. Requires CICS TS V5.1 or V5.2 with APAR PI56706, or V5.3 or later.

Input properties for the Deploy application step
Name Type Description Required
Application Binding Directory String The location of the CICS application binding project on zFS. The default value is
${p:cics.platform.home}/bindings/${p:cics.application.binding.directory}.
Yes
Application Definition String The name of the CICS application definition. The default value is ${p:cics.application.definition.name}. Yes
Application Directory String The location of the CICS application project on zFS. The default value is ${p:cics.platform.home}/applications/${p:component.name}_${p:cics.application.version}. Yes
Description String A description of the application definition. The default value is ${p:component.name}. No
State Enumeration:AVAILABLE, DISABLED, ENABLED The target state of the application. Yes
Timeout (s) String The number of seconds to make retry attempts before a timeout occurs. The valid range is 1-1800. The default value is 300. No

Deploy bundle

Deploy a CICS bundle. Requires CICS TS V5.1 or V5.2 with APAR PI56706, or V5.3 or later.

Input properties for the Deploy bundle step
Name Type Description Required
Bundle Directory String The location of the CICS bundle on zFS. Yes
Bundle Name String The name of the CICS bundle. Yes
Description String A description of the resource definition. No
Group Name String The name of the resource definition group. No
Resource Definition Enumeration:BAS, CSD, NONE The location in which to create the resource definition. You can also choose not to define the resource. Yes
State Enumeration:AVAILABLE, DISABLED, ENABLED The target state of the bundle. Yes
Timeout (s) String The number of seconds to wait for the bundle to deploy before a timeout occurs. Further processing of the bundle by CICS might occur after the timeout. The valid range is 1-1800. The default value is 300. No

Disable application

Disable an installed cloud enabled CICS application. Requires CICS TS V5.1 or later.

Input properties for the Disable application step
Name Type Description Required
Application Definition String The name of the CICS application definition. The default value is ${p:cics.application.definition.name}. Yes
Application Version String The application version in major.minor.micro format (for example, 1.2.345). The default value is ${p:cics.application.version}. Yes

Disable resources

Disable installed resources.

Input properties for the Disable resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:ATOMSERV, BUNDLE, CMDT, DB2ENTRY, EPADAPT, EPADSET, EVNTBIND, EXTRATDQ, INTRATDQ, JVMSERV, LIBRARY, LOCFILE, LOCTRAN, PIPELINE, PROCTYP, PROGRAM, URIMAP The type of resource to disable. Yes

Discard resources

Discard installed resources.

Input properties for the Discard resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:ATOMSERV, BUNDLE, CMDT, CONNECT, DB2CONN, DB2ENTRY, DB2TRN, DOCTEMP, EXTRATDQ, INDTDQ, INTRATDQ, IPCONN, JRNLMODL, JRNLNAME, JVMSERV, LIBRARY, LOCFILE, LOCTRAN, MQCON, PIPELINE, PROCTYP, PROGRAM, REMFILE, REMTDQ, TCPIPS, TERMNL, TRANCLAS, TSMODEL, URIMAP, WEBSERV The type of resource to discard. Yes

Enable application

Enable an installed cloud enabled CICS application. Requires CICS TS V5.1 or later.

Input properties for the Enable application step
Name Type Description Required
Application Definition String The name of the CICS application definition. The default value is ${p:cics.application.definition.name}. Yes
Application Version String The application version in major.minor.micro format (for example, 1.2.345). The default value is ${p:cics.application.version}. Yes

Enable resources

Enable installed resources.

Input properties for the Enable resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:ATOMSERV, BUNDLE, CMDT, DB2ENTRY, EPADAPT, EPADSET, EVNTBIND, EXTRATDQ, INTRATDQ, JVMSERV, LIBRARY, LOCFILE, LOCTRAN, PIPELINE, PROCTYP, PROGRAM, URIMAP The type of resource to enable. Yes

Install BAS resource descriptions

Install resource descriptions from the CICSPlex SM data repository using BAS.

Input properties for the Install BAS resource descriptions step
Name Type Description Required
Resource Description List String A comma-separated list of resource description names. Yes

Install BAS resource groups

Install resource groups from the CICSPlex SM data repository using BAS.

Input properties for the Install BAS resource groups step
Name Type Description Required
Resource Group List String A comma-separated list of resource group names. Yes

Install BAS resources

Install resource definitions from the CICSPlex SM data repository using BAS.

Input properties for the Install BAS resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:ATOMDEF, BUNDDEF, DB2CDEF, DB2EDEF, DB2TDEF, DOCDEF, EJCODEF, EJDJDEF, ENQMDEF, FILEDEF, IPCONDEF, JRNMDEF, JVMSVDEF, LIBDEF, LSRDEF, MAPDEF, MQCONDEF, PARTDEF, PIPEDEF, PROCDEF, PROFDEF, PROGDEF, PRTNDEF, RQMDEF, TCPDEF, TDQDEF, TERMDEF, TRANDEF, TRNCLDEF, TSMDEF, TYPTMDEF, URIMPDEF, WEBSVDEF The type of resource to install. Yes
Version String The version of the resource to install. The default value is 1. Yes

Install CSD groups or lists

Install resources contained in groups or lists from the CSD.

Input properties for the Install CSD groups or lists step
Name Type Description Required
Group or List Enumeration:CSDGROUP, CSDLIST Specify whether to install from a CSD group or list. Yes
Group or List Name String A comma-separated list of CSD groups or lists. Yes

Install CSD resources

Install resources from the CSD.

Input properties for the Install CSD resources step
Name Type Description Required
Group Name String The name of the group that the resource or resources belong to. Yes
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:ATOMDEF, BUNDDEF, DB2CDEF, DB2EDEF, DB2TDEF, DOCDEF, EJCODEF, EJDJDEF, ENQMDEF, FILEDEF, IPCONDEF, JRNMDEF, JVMSVDEF, LIBDEF, LSRDEF, MAPDEF, MQCONDEF, PARTDEF, PIPEDEF, PROCDEF, PROFDEF, PROGDEF, PRTNDEF, RQMDEF, TCPDEF, TDQDEF, TERMDEF, TRANDEF, TRNCLDEF, TSMDEF, TYPTMDEF, URIMPDEF, WEBSVDEF The type of resource to install. Yes

Make application available

Make an installed cloud enabled CICS application available. Requires CICS TS V5.2 or later.

Input properties for the Make application available step
Name Type Description Required
Application Definition String The name of the CICS application definition. The default value is ${p:cics.application.definition.name}. Yes
Application Version String The application version in major.minor.micro format (for example, 1.2.345). The default
value is ${p:cics.application.version}.
Yes

Make application unavailable

Make an installed cloud enabled CICS application unavailable. Requires CICS TS V5.2 or later.

Input properties for the Make application unavailable step
Name Type Description Required
Application Definition String The name of the CICS application definition. The default value is ${p:cics.application.definition.name}. Yes
Application Version String The application version in major.minor.micro format (for example, 1.2.345). The default value is ${p:cics.application.version}. Yes

Make resources available

Make installed bundle resources available. Requires CICS TS V5.2 or later.

Input properties for the Make resources available step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:BUNDLE The type of resource to make available. Yes

Make resources unavailable

Make installed bundle resources unavailable. Requires CICS TS V5.2 or later.

Input properties for the Make resources unavailable step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:BUNDLE The type of resource to make unavailable. Yes

New copy resources

New copy installed program or doctemplate resources.

Input properties for the New copy resources step
Name Type Description Required
Max Retry Times String The maximum number of times to retry a new copy of the resource. A retry occurs when the new copy fails. No
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:DOCTEMP, PROGRAM The type of resource to new copy. Yes
Retry Interval (s) String The number of seconds to wait before retrying a new copy of the resource. No

Open resources

Open installed resources.

Input properties for the Open resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:CMDT, EXTRATDQ, LOCFILE, TCPIPS The type of resource to open. Yes

Phase in resources

Phase in installed program or bundle resources. Phase in for a bundle resource type requires CICS TS V5.3 or later.

Input properties for the Phase in resources step
Name Type Description Required
Resource Name List String A comma-separated list of resource names. Yes
Resource Type Enumeration:BUNDLE, PROGRAM The type of resource to phase in. Yes

Scan pipelines

Scan installed pipeline resources.

Input properties for the Scan pipelines step
Name Type Description Required
Pipeline List String A comma-separated list of pipelines. Yes

Undeploy application

Undeploy a cloud enabled CICS application. Requires CICS TS V5.1 or V5.2 with APAR PI56706, or V5.3 or later.

Input properties for the Undeploy application step
Name Type Description Required
Application Definition String The name of the CICS application definition. The default value is {p:cics.application.definition.name}. Yes
Application Version String The application version in major.minor.micro format (for example, 1.2.345). The default value is ${p:cics.application.version}. Yes
State Enumeration:DISABLED, DISCARDED, UNAVAILABLE The target state of the application. Yes
Timeout (s) String The number of seconds to make retry attempts before a timeout occurs. The valid range is 1-1800. The default value is 300. No

Undeploy bundles

Undeploy CICS bundles. Requires CICS TS V5.1 or V5.2 with APAR PI56706, or V5.3 or later.

Input properties for the Undeploy bundles step
Name Type Description Required
Bundle Name List String A comma-separated list of bundle names. Yes
Group Name String When the target state is Discarded, enter the name of the resource definition group in which the bundle is defined. No
Resource Definition Enumeration:BAS, CSD, NOT When target state is Discarded, choose the location of the resource definition to delete. You can also choose to NOT delete the resource definition. The default action
is to delete the resource in CSD.
Yes
State Enumeration:DISABLED, DISCARDED, UNAVAILABLE The target state of the bundle. Yes
Timeout (s) String The number of seconds to wait for each bundle to undeploy before a timeout occurs. Further processing of a bundle by CICS might occur after the timeout. The valid range is 1-1800. The default value is 300. No

Output properties

Overview of output properties

A step in UrbanCode Deploy is able to return output properties. These can be used in the step post-processing script and to pass information between steps. For an example workflow using output properties, see Properties in the UrbanCode Deploy documentation.


The cics.response.errors output property

If the CICS TS plug-in step fails (because CICS returns an error, for example) the step returns the cics.response.errors output property.

Thispropertys value consists ofa JSON document of error codes, one set for each resource in the resource list.The following elements are returned in the JSON document:

Element name Description
action The action performed by the step.
resourceName The name of the CICS resource.
resourceType The type of CICS resource.
responseName The plain text translation of the response code.
reasonName The plain text translation of the reason code.
attribute The name of the attribute that is in error.
errorCode The CICSPlex SM error code associated with the resource.
resp1Name The plain text equivalent of the resp value.
resp2 The CICS RESP2 code or the CICSPlex SM API EYUDA reason code as a numeric value.

How to view output properties

You can view a steps output properties in the Log tab of the Process Request window.Next to the desired step name, click on the Input/Output properties icon. In the popup that follows, click View Output Properties.

Image showing the location output properties in the Process Request window.

Image showing the location output properties in the Process Request window.

The following is a sample of the cics.response.errors output when NEWCOPY fails with a NODATA error:

[{"action":"NEWCOPY","attribute":"","errorCode":"","reasonName":"","resourceName":"NOTEXIST","resourceType":"PROGRAM","resp1Name":"","resp2":"","responseName":"NODATA"}]

Use cics.response.errors in a post-processing script

You can configure a post-processing script to run after a step finishes. Post-processing scripts can be used to ensure that the expected results occurred, and to pass properties between steps. Formore information on using and storing reusable post-processing scripts, see the Post-processing scripts section of the Urban Code Deploy documentation.

The following is a usageexample of a post-processing script for the New copy resources step in the CICS TS plug-in:

The New copy resources step will instruct CICS to reload the resource the next time it is requested. The step will fail in CICS with a NODATA response if the resource was not already loaded, however in most cases this failure can be ignored as CICS will automatically load the resource when it is next used.

The following script will analyse the cics.response.errors output property and providing the only errors are NODATA, will change the step to be successful:

var exit = properties.get('exitCode');
commandOut.println("Running the post-processing script.");
if (exit == 0) {
 commandOut.println("The main step passed.");
properties.put('Status', 'Success');
} 
else {
commandOut.println("The main step failed. Analysing its errors...");
var responseErrors = JSON.parse(properties.get("cics.response.errors"));
if (responseErrors) {
if (responseErrors.length > 0) {
for(var i = 0; i < responseErrors.length; i++){
commandOut.println("Analysing result with response name '" + responseErrors[i].responseName + "'.");
if (responseErrors[i].responseName != "NODATA") {
commandOut.println("Breaking early.");
break;
}
}
if (responseErrors.length > 0 && i == responseErrors.length) {
commandOut.println("All errors were NODATA. The step will succeed.");
properties.put("Status", "Success");
} 
else {
commandOut.println("Not all errors were NODATA. The step will be failed.");
properties.put("Status", "Failure");
}
} 
else {
commandOut.println("No error records found. The step will be failed.");
properties.put("Status", "Failure");
}
} 
else {
commandOut.println("No CICS response errors found!")
}
}

Defining and deleting resource definitions

Usingthe Submit Job stepfromthe z/OS Utility plug-in, you canperformthe followingactions in CICS:

  • Run DFHCSDUP to define or delete resource definitions in the CSD.
  • Run EYU9XDBT to define or delete resource definitions in the CPSM data repository.

In the following example, DFHCSDUP is run withreplace tokens @CICSHLQ@,@CSD@, and @CSDUPDATE@.

Image showing the 'Submit Job' step configured to define some CICS resources.

Image showing the Submit Job step configured to define some CICS resources.

Replace tokens allow you to customizevalues in your JCL templates, in order to use the same JCL in different deployment scenarios.

For example, a token such as @CSD@ can be linked to a matching UrbanCode Deploy property, cics.jcl.csd. This property is then assigned a value, such as CICSTS53.CICS.DFHCSD, which canbe set attheenvironment level, or wherever is most suitable.

For more details on the Submit Job and Wait For Job steps, see the Steps pageof the z/OS Utility plug-in documentation.

Default input properties

The following properties are present on all CICS TS plug-in steps. You can view them on any step configuration page by selecting the Show Hidden Properties check box.

These properties are typically environment or component-specific. To reduce manual configuration, you can define propertiesat an Application, Environment, or Resource level.

For an example of how to setup a CICS installation as an UrbanCode DeployResource, see Setting up resources for simple management of properties. More information on usage of properties is available on the Properties Overview pageof the UrbanCode Deploy documentation.

Name Default value Description
Host ${p:cics.host} The host name of the CICS region to connect to.
Port ${p:cics.cmciport} The CMCI port to connect to.
CICSplex ${p?:cics.cicsplex} The name of the the CICSplex (defined set of CICS Systems) to connect to.
Scope ${p?:cics.scope} The name of the Scope to connect to. The scope can be a CICSplex, a CICS system, a CICS system group, or any set of CICS resources that are defined as a logical scope.
Username ${p?:cics.username} The username for connecting to CICS.
Password ${p?:cics.password} The password for connecting to CICS.
Enable SSL ${p?:cics.ssl} Whether to enable SSL connection to CICS. When set to true, this enables SSL connection to CICS. By default, SSL is disabled.
Keystore Location ${p?:cics.kslocation} The location of the keystore that is used to provide credentials for client-certificate authentication, if SSL is enabled.

-For files in zFS, use a hierarchical file path such as

/u/myuser/keystore.jks

or

file:///u/myuser/keystore.jks

-For keys contained in RACF keyrings that are stored in software, use a URL in the format

safkeyring:///<keyring name>

-For keys contained in RACF keyrings that are stored in hardware with ICSF, use

safkeyringhw:///<keyring name>

Keystore Type ${p?:cics.kstype} The type of the keystore that provides credentials for client-certificate authentication, if SSL is enabled. If unspecified, the agents default Java keystore type is used. For keys contained in RACF keyrings, use JCERACFKS when the keys are stored in software, or JCECCARACFKS when the keys are stored in hardware with ICSF.
Keystore Password ${p?:cics.kspassword} The password of the keystore that provides credentials for client-certificate authentication, if SSL is enabled. For keys contained in RACF keyrings, leave this value empty.
Truststore Location ${p?:cics.tslocation} The location of the truststore that verifies credentials, if SSL is enabled.

-For files in zFS, use a hierarchical file path such as

/u/myuser/truststore.jks

or

file:///u/myuser/truststore.jks

-For certificates contained in RACF keyrings that are stored in software, use a URL in the format

safkeyring:///<keyring name>

-For certificates contained in RACF keyrings that are stored in hardware with ICSF, use

safkeyringhw:///<keyring name>

Truststore Type ${p?:cics.tstype} The type of the truststore that verifies credentials, if SSL is enabled. If unspecified, uses the agents default Java keystore type. For certificates contained in RACF keyrings, use JCERACFKS when the certificates are stored in software, or JCECCARACFKS when the certificates are stored in hardware with ICSF.
Truststore Password ${p?:cics.tspassword} The password of the truststore that verifies credentials, if SSL is enabled. For certificates contained in RACF keyrings, leave this value empty.

Usage

Usage sections:


Setting up resources for simple managementof properties

Before you begin

  • Ensure your UCD agent is installed. For more information on installing UCD agents, see Installing agents from the command line.
  • Ensure that the CICS region or CICSplex you want to connect to is available through the CICS Management Client Interface (CMCI).

About this task

You can use Resources in UrbanCode Deploy to reduce the manual configuration needed in each of your deployment processes.Resources contain properties which you can use within the steps of your processes. The properties defined within a given resource are inherited by their descendants.

The following diagram represents a suggested CICS resource tree, which shows a sysplex with two agents running on different logical partitions. One of these logical partitions contains two CICSplexes managed by a single WUI Server. One of the CICSplexes contains a number of CICS regions and system groups.The Core Banking Systemcomponent is assigned to the AORs system group, and the CatalogBack-End component is assigned to the TORs system group. Propertieswhich are defined for a higher-level resource (for example, a sysplex) are inherited by the contained components and resources (for example, several CICSplexes).

Diagram showing a possible CICS resource tree.

Diagram showing a possible CICS resource tree.

When you add a new CICS step to a process, the step contains a number of default values that refer to properties. You can view all available default input properties for the CICS TS plugin on the default input properties page.

For CICS steps, it may be useful to set up a resource tree as previously described, defining propertiesat the following resource levels:

Property Resource with tag
cics.host
Agent
cics.cmciport
WUI
cics.cicsplex
CICSplex
cics.scope
CICSplex, System Group, or Region
cics.username
Sysplex
cics.password
Sysplex

For more general information on property inheritance, see Referring to properties.


Deploying new load modules and performing a NEWCOPY on the related programs

Before you begin

  • Ensure your UCD agent is running. (You can check this by clicking on the Resources tab, then clicking on the Agents tab. The status of the agent should be Online.)
  • Ensure that the CICS region or CICSplex you want to connect to is available through the CICS Management Client Interface (CMCI).

Process

  1. The Copy Artifacts step loads the artifacts that make up the z/OS component version. Use the FTP Artifacts step if build and deployment are on two different z/OS systems.
  2. The Deploy Data Sets step deploys the component version to z/OS by copying datasets and members to their required location.
  3. The NEWCOPY Resources step then performs a NEWCOPY of a specified program or list of programs.
Diagram showing a process with 'Copy Artifacts','Deploy Data Sets', and 'New copy resources' steps.

Diagram showing a process with Copy Artifacts,Deploy Data Sets, and New copy resources steps.

Deploying and undeploying CICS applications

Component and Component Version for a CICS application

Components represent deployable items and the processes, properties, and other configuration that operate on them.

Create a Component to store your CICS application ready for deployment. The component name should match the CICS application name. For example: com.ibm.cics.minibank.application

A version of the Component is created by your build script. The script typically extracts the Eclipse projects that consist of the source of the CICS application (including the binding, application, and bundles) from your source code management (SCM) system. The script then calls the CICS TS build toolkit to build the application. The build output directories and files are stored in UCD as a new Component Version.

Component process to deploy a CICS application

A CICS application is deployed using the Deploy application step.

Define your component process to take the following actions:

  1. Download the artifacts to a temporary location.
  2. Call the CICS build toolkit to resolve variables in the application.
  3. Copy the resolved application to the CICS platform home directory.
  4. Use the Deploy application step to define, install, and make the application available in CICS.
Image showing the default values for the Deploy application step.

Image showing the default values for the Deploy application step.

Component process to undeploy a CICS application

You can undeploy a CICS application by using the Undeploy application step.

Optionally, you can use the component process to remove the application and application binding directories. You should not remove the CICS bundle directories, as it is likely they are shared by several applications, or several versions of the same application.

Image showing the default values for the Undeploy application step.

Image showing the default values for the Undeploy application step.

Required properties

The following properties are required by the Deploy application and Undeploy application steps:

Property Recommended property context Example value
component.name Component com.ibm.cics.minibank
cics.application.definition.name Component minibank
cics.application.binding.directory Component ${p:component.name}.${p:cics.platform.definition.name}.binding_${p:cics.application.binding.version}
cics.application.version Component version 1.0.0
cics.application.binding.version Component version 1.0.0
cics.platform.definition.name Environment prod
cics.platform.home Environment /var/cics/CICSPLX1/prod

Connecting securely with SSL

Overview

You can use SSL to provide additional securitywhenconnecting between the UrbanCode Deploy agent on z/OS and CICS. Connecting with SSL is available using client certificates or HTTP basic authentication. Connecting with client certificates stored on z/OS in a security manager such as RACF or zFS has the benefit of avoiding the storage and maintenance of userids and passwords on the UCD server.

For SSLwith HTTP basic authentication, skip to Configuring SSLin CICS.

For SSL with certificates, start with Configuring a keystore and truststore.


Configuringa keystore and truststore

Firstly, in your security manager, configure a key ring and certificate for the CICS regions userid.

  1. If no CA certificate exists, define a self-signed CA certificate.
  2. Define your userids certificate, signed with a CA certificate.
  3. Define your userids key ring.
  4. Add both the CA and userids certificates to the useridskey ring.

Secondly, using the same steps, configure a key ring and certificate for the agents userid. (Alternatively, you can use JKS or PKCS12 format keystores for the agent. For example usage, see ConfiguringSSL in the CICS TS plug-in.)

Finally, in order to complete the handshake,connect the CA certificate of the CICS region to the agent userskey ring, and the CA certificate of the agent user to the CICS regions key ring. This can be done using the RACDCERT CONNECT command, with USAGE(CERTAUTH).

For details on using RACF commands, see RACF command syntax in the z/OS product documentation.


Configuring SSL in CICS

1. If you are using a CICSplex, you must enable CPSM security. To do this, updateyour CMAS CICSplex EYUPARM file with SEC(YES).

2. Configure your CMCI TCPIPSERVICE resource with SSL support.

  • Update your WUI SIT parameters with SEC=YES, adding KEYRING=my-keyring if you are using SSL with certificates.
  • For SSL with server and client certificates, update your WUI initialization parameters with the following example configuration:
CMCIAUTH(CERTIFICATE)
CMCISSL(CLIENTAUTH)

  • For SSL with HTTP basic authentication, update your WUI initialization parameters with the following example configuration:
CMCIAUTH(BASIC)
CMCISSL(SSL)

For details of available configurations, seeConfiguring CICS to use SSLin the CICS product documentation.


ConfiguringSSL in the CICS TS plug-in

Each CICS step has default,hiddenproperties. In order to use SSL, update the relevant propertieswiththe following values.

SSL Set to true.
Keystore Location The location of the keystore that is used to provide credentials for client-certificate authentication. For files in zFS, use a hierarchical file path such as

/u/myuser/keystore.jks

or

file:///u/myuser/keystore.jks

-For keys contained in a key ring managed by a security manager that are stored in software, use a URL in the format

safkeyring:///<keyring name>

-For keys contained in a key ring managed by a security manager that are stored in hardware with ICSF, use

safkeyringhw:///<keyring name>

Keystore Type The type of the keystore that provides credentials for client-certificate authentication. If unspecified, the agents default Java keystore type is used. For keys contained in a key ring managed by a security manager, use JCERACFKS when the keys are stored in software, or JCECCARACFKS when the keys are stored in hardware with ICSF.
Keystore Password The password of the keystore that provides credentials for client-certificate authentication. For keys contained in a key ring managed by a security manager, leave this value empty.
Truststore Location The location of the truststore that verifies credentials. For files in zFS, use a hierarchical file path such as

/u/myuser/truststore.jks

or

file:///u/myuser/truststore.jks

-For certificates contained in a key ring managed by a security manager that are stored in software, use a URL in the format

safkeyring:///<keyring name>

-For certificates contained in a key ring managed by a security manager that are stored in hardware with ICSF, use

safkeyringhw:///<keyring name>

Truststore Type The type of the truststore that verifies credentials. If unspecified, uses the agents default Java keystore type. For certificates contained in a key ring managed by a security manager, use JCERACFKS when the certificates are stored in software, or JCECCARACFKS when the certificates are stored in hardware with ICSF. For more information, see the Hardware Cryptography IBMJCECCA Overview.
Truststore Password The password of the truststore that verifies credentials. For certificates contained in a key ring managed by a security manager, leave this value empty.

Troubleshooting

Tip: For more questions and answers, see the UrbanCode forum on IBM developerWorks.

Troubleshooting sections

FAQ

If a step fails, is there a rollback mechanism provided?

The CICS TS plug-in does not provide a specific rollback mechanism for a failed process or step. When a step fails, the context of the failure is important. First, check the step logs for more details on how the step failed. Then you can either manually rollback the relevant steps, orpreferably, you can build and run a process that will take your environment back to the state it was in prior to the process having run.


Using the step logs

Most failures can be detected by inspecting the step output logs in IBM UrbanCode Deploy. If an error occurs within the UCD set up, the step output log typically contains an error message similar to authentication failed, which often indicates an incorrect user name and password.

If the problem is more CICS specific, the step output log will contain a message such as the following:

2015/03/10 10:28:35.703 GMT BUZCP0030E PROGRAM "DFHSJJI" was not found.

BUZCP is the prefix for all CICS TSplug-in messages.
0030 is the message number.
E|W|I is the message level: error, warning, or informational.

An Error level message indicates the step failed with an error. A Warning level message indicates the step continued, but some properties may not be set correctly. An Information level message indicates progression of the step.

Where available, the log contains CICS RESP and RESP2 codes for more detailed troubleshooting:

2015/03/10 16:42:13.219 GMT BUZCP0006I Connected to "your.cicsplex.com:29000".
2015/03/10 16:42:13.638 GMT BUZCP0037I Perform DISCARD Operation.
2015/03/10 16:42:13.733 GMT BUZCP0026E DISCARD PROGRAM "DFHSJJI" failed.
2015/03/10 16:42:13.736 GMT BUZCP0031E EXEC CICS command (DISCARD PROGRAM) RESP(NOTAUTH) RESP2(100).
2015/03/10 16:42:13.750 GMT BUZCP0029I Summary: 0 DISCARD request(s) succeeded, 1 DISCARD request(s) failed.

In this example, the Discard resources step fails for program DFHSJJI. The output of message BUZCP0031Elists theattempted EXEC CICS command, DISCARD PROGRAM, followed by the RESP and RESP 2 codes NOTAUTH and 100 respectively. You can find information on the command and response codes in theDISCARD PROGRAM topic of the CICS TS online production documentation.

Detailsfor any EXEC CICS command and respective RESP and RESP2 codes are available in the System Programming reference section of the CICS TS online product documentation, sorted by command name.

Note: If the target scope of a step is more than one region, the step will fail when one or more regions fail to complete a request. Use the step log to determine the scope, then use the CICS logs to determine the specific regions in which the failures occurred, and confirm the cause.


Resources which operate asynchronously

When a CICS TS plug-in step completes, it is generally true that the action also completes in CICS TS, as the operation is synchronous. However, there are a number of CICS resources where steps run asynchronously.

For an asynchronous operation, the step log shows only whether the plug-in successfully connects to CICS TS and makes the request, not if the operation completes successfully. You should check the status of the resource in CICS TS to confirm the success of an asynchronous operation.

Here is a list of steps, with respective resources that complete asynchronously:

Disable resources Bundle, File, DB2 Entry, Data Table.

Enable resources Bundle, JVM Server.

Install BAS resource groups / Install CSD groups or lists / Install BAS resource descriptions Bundle, Web Service, Pipeline, JVM Server.

Install BAS resources/Install CSD resources Bundle, Web Service, Pipeline, JVM Server.

Close resources Data Table, File, TCP/IP Service.


Checking the status of a resource that was installed in the previous step

After a resource is installed in CICS, it might take a few seconds for the existence of the resource to be returned by CICSPlex SM. To help ensure that the steps which check the status of a resource return an accurate status, the default timeout value is 15 seconds. If you decrease this timeout value, the step might not return the correct status of the resource, and you might receive the following error:

BUZCP0046E Resource "MYRESO01" does not exist in the target scope


Collecting data for plug-in problems

If you need to open a service request(SR)or problem management record (PMR), please collect the process logs associated with the failure and the logs for the UCD agent.


Resolving Unsupported CICS release message

If you have recently updated CICS, you might receive the following error when you usethe plug-in:

BUZCP0043E Exception detailed message: Unsupported CICS release.

To resolve this issue, upgrade to the latest version of the CICS TS plug-in.