Troubleshooting the DFHDPLOY utility

If errors occur when the DFHDPLOY utility runs, these troubleshooting methods might help you. The location of the DFHDPLOY log is specified by the JCL SYSTSPRT data definition.

Timeout

When a DFHDPLOY command times out, message DFHRL2039W will be issued at the point in the script where the timeout occurred. Message DFHRL2040E may also be issued for applications that time out, and message DFHRL2041E for bundles that time out. DFHDPLOY will then display the current state of the application or bundle being processed, and where applicable the state of the application management or bundle parts to enable more detailed error diagnosis.

A timeout will result in a return code of 4 if the timeout occurs during the last step in processing a command, but DFHDPLOY has not had time to query whether all bundles or applications have reached the intended target state.

If you receive a return code of 4 due to a timeout on a DEPLOY command, issue a SET command with the same state.
If you receive a return code of 4 due to a timeout on an UNDEPLOY command, reissue the same UNDEPLOY command.
If you receive a return code of 4 due to a timeout on a SET command, reissue the same SET command.

A timeout will result in a return code of 8 if the timeout occurs before the last step in processing a command has begun.

If you receive a return code of 8 due to a timeout on a DEPLOY command, issue an UNDEPLOY STATE(DISCARDED) command with a larger TIMEOUT value to remove the existing bundle or application, then reissue the DEPLOY command with a larger TIMEOUT value.
If you receive a return code of 8 due to a timeout on an UNDEPLOY command, reissue the UNDEPLOY command and specify a larger TIMEOUT value.
If you receive a return code of 8 due to a timeout on a SET command, reissue the SET command with a larger TIMEOUT value.

The TIMEOUT value that you choose depends on the context of your deployment, for example:

The type and number of JVM servers and Java™ components that are contained in the bundle or application.
The number of OSGi Java middleware bundles or Liberty profile features to be installed by JVM servers that are contained in the bundle or application.
The number of CP or zAAP engines available to the CICS® regions in the scope.
The number of CICS regions in the scope, and the workload those systems are processing.
Whether the workload has quiesced before you run an undeployment script (for TCPIPSERVICE, for example).

If there are errors in addition to the timeout, check the application management part records and the bundle part records for more information.

Note: Scripts may also timeout if any of the systems in the platform or scope are not responding to their connecting CMAS. Check the CMAS JESMSGLG logs to determine if any regions were not responding while the script was running.

Nonzero return code

If the DFHDPLOY log shows that CICS or CPSM encountered errors during deployment or undeployment, use this log to identify when the errors occurred.

The DFHDPLOY log contains several records that might help you troubleshoot:

The application management part records might identify which region types did not reach the target state.
The bundle part records might identify which regions did not reach the target state.

In each case, examine the CICS logs for the region where the errors occurred. For more information about application deployment errors, see Diagnosing application errors.

Note: If errors occurred during a deployment, undeploy the bundle or application before you attempt to deploy again.

Running out of memory

Specify REGION=100M or more when you run the DFHDPLOY job to avoid running out of memory while the job is processing. For complex scripts or large CICSplexes, consider making more memory available to DFHDPLOY.

Removing orphaned resource definitions if a deployment fails

When you use the DEPLOY BUNDLE command without specifying RESGROUP or CSDGROUP, a resource definition is created using Business Administration Services (BAS) for the duration of the deployment and deleted after the artifact reaches its specified target state.

If the deployment fails before reaching the specified target state, the resource definition might not be removed from the CICSPlex SM data repository using BAS. You can remove the resource definition in the normal way using CICS Explorer, an UNDEPLOY BUNDLE command, or another API program. Refer to message DFHRL2024I in the data repository used by the DEPLOY BUNDLE command to identify the definition name and version number of the definition you wish to remove.

Bundle resource definitions in Business Administration Services (BAS)

BAS supports up to 15 versions of the same resource definition NAME. If you specify RESGROUP when you deploy a bundle, the DFHDPLOY log contains records that show the BAS DEFVER attribute used by the definition:

DFHRL2024I BUNDLE definition(WEBSITE) VERSION(2) successfully created.

If the same deployment fails multiple times and you reach the resource definition version limit in BAS, you must remove one or more of the resource definitions before you can use DFHDPLOY to reattempt the same deployment. You can remove these resource definitions in the normal way using CICS Explorer, an UNDEPLOY BUNDLE command, or another API program. Refer to message DFHRL2024I in the data repository used by the DEPLOY BUNDLE command to identify the definition name and version number of the definition(s) you wish to remove.

Removing orphaned resource groups in Business Application Services (BAS) or CSD

If you specify CSDGROUP or RESGROUP when you deploy a bundle, but do not specify the same option again when you undeploy the bundle, the bundle definition is not removed and remains linked to the CSD group or BAS resource group. To remove the orphaned resource group, run the UNDEPLOY BUNDLE command again and specify the appropriate CSDGROUP or RESGROUP.

DFHDPLOY does not support the installation of a bundle defined by an existing resource definition.

Enabling trace and contacting support

Enable trace for DFHDPLOY by specifying the JCL DPLOYTRC data definition. If you still have issues, supply this trace when you contact the IBM® support center.

To enable trace, specify:

//DPLOYTRC DD SYSOUT=*

As in the following example, which deploys a bundle in an ENABLED state, with trace enabled:

//DFHDPLOY JOB CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID
//*
//DFHDPLOY EXEC PGM=DFHDPLOY
//*
//STEPLIB DD DISP=SHR,DSN=CICSTS51.CICS.SDFHLOAD
//        DD DISP=SHR,DSN=CICSTS51.CPSM.SEYUAUTH
//SYSTSPRT DD SYSOUT=*
//DPLOYTRC DD SYSOUT=*
//SYSIN DD *
*
SET CICSPLEX(MYPLEX);
*
DEPLOY BUNDLE(WEBSITE) BUNDLEDIR(/var/cicsts/bundles/Website_1.0.0)
CSDGROUP(BANKING) SCOPE(SYS1) STATE(ENABLED) TIMEOUT(60);
/*

dfhdploy_troubleshoot.html | Timestamp icon

Last updated: Thursday, 27 June 2019