Diagnosing application errors
If an application version that is deployed on a platform does not have the expected status, here are some possible causes.
Finding diagnostic information about applications
See Setting up an application for information about the processing that is involved in setting up an application.
In CICS Explorer®, use the Cloud Explorer view in the CICS® Cloud perspective to check the status of the application version. Application states explains the possible values for the status of an application version and of its management parts.
The status of an application version is FAILED
Check the CICSPlex® SM output log (the EYULOG) for details of the problem that occurred while the application version was being installed or discarded.
The CICSPlex SM data repository for the CMAS might be full, in which case you need to increase its size. To expand the data repository, use the REPRO function of the IDCAMS utility. An example of the JCL to do this is in the EYUJXDRP member of the CICSTS56.CPSM.SEYUSAMP library. In that JCL, on the RECORDS(xx,yy) statement, specify a primary (xx) and a secondary (yy) value that are appropriate for your environment.
The status of an application version is DISABLED or SOMEDISABLED
Try to enable the whole application version. In the Cloud Explorer view, right-click the application version and select Enable. CICSPlex SM attempts to enable all the CICS bundles for the application version in all the CICS regions. If the application version is still not enabled, investigate the individual CICS bundles that are named in each management part. In the Cloud Explorer view, working with the application hierarchy, expand each region type displayed under the application to show the Bundles list for the region type. Expand each Bundles list to display the management parts for the application.
The status of a management part is DISABLED or SOMEDISABLED
Try to enable the individual CICS bundles in each CICS region where they are installed. Double-click the management part to open the CICS Bundles view, which displays the installed CICS bundles. Alternatively, right-click the management part and click Show Installed Bundles. In the CICS Bundles view, select the record for the CICS bundle in the CICS region where you want to enable it, right-click and select Enable.
not foundresponse is returned to the task. This action avoids the possibility of loading the wrong program and enables workload management to route work away from the CICS region. All CICS bundles containing definitions for LIBRARY resources must therefore be enabled in order to carry out program loads for the application.
The status of an application version is INCOMPLETE or EMPTY
- If the status of a management part is INVALIDSCOPE, check the definition for the CICS bundle to see whether the target CICS system group was specified correctly.
- If the status of a management part is EMPTY, check whether the CICS regions where the CICS bundle should have been installed are active and connected to the CMAS. To check whether the CICS regions are active, switch to the platform hierarchy in the Cloud Explorer view. For the platform where the application is installed, expand the region types, then expand the Regions list for each region type to show the CICS regions and their status. If the CICS regions are available, check the definition for the CICS bundle for any errors.
- If the status of a management part is INCOMPLETE, check the CICSMSG log of the CICS regions in the region type of the affected bundle for more information
about why the bundle was not installed. If the CICS bundle
cannot be found, check your zFS setup. This error can occur if:
- A platform is spread across different systems (LPARs) in the same sysplex, but the platform home directory in the zFS file system is not shared across the sysplex. You must either use FTP by using a connection to the same zFS that your CMAS is running on, or set up sysplex-wide sharing of your platform home directory.
- The platform home directory is on a different sysplex from the sysplex where the platform is installed. Ensure that the platform home directory is on the sysplex where you have installed the platform.
You are having problems with private resources
Investigate the individual private resources. In the Cloud Explorer view, double-click the name of the installed application version to open it in the online application editor, and select the Private Resources tab. Select the appropriate tab for the resource type to view the private resources installed for the application. Check that each expected private resource exists in all the appropriate CICS regions, and check the status and detailed information for the private resource for any anomalies.
If your application has private LIBRARY resources, select the Library DS Names tab to view the DD name that z/OS® has generated for each LIBRARY concatenation of data sets. Check that these data sets have been created correctly.
The application status doesn't change to AVAILABLE
If you perform the Make Available action to make an application version available to callers, but the availability status is not displayed as AVAILABLE, first verify that the action was required. If the availability status of the application version is not displayed at all, this is correct for CICS regions that are still at CICS TS 5.1. The Make Available action does not apply to applications in those regions, and they are available to callers as soon as they are in ENABLED status.
If the availability status of the application version is displayed as No entry points
(which is the status NONE), the application has no application entry points, so the Make
Available action is not required. Application entry points are used to control users'
access to application versions in a multi-versioning environment, so you should declare application
entry points for PROGRAM, TRANSACTION or URIMAP resources in the application.
- If the availability status of a management part is displayed as
No entry points
(which is the status NONE), the CICS bundle does not contain any statements of application entry points, so you do not need to investigate it. - If the availability status of a management part is displayed as AVAILABLE, the application entry points declared in the CICS bundle have been successfully made available to callers, so you do not need to investigate it.
- If the availability status of a management part is displayed as UNAVAILABLE or SOMEAVAIL, check the status of the individual CICS bundles and bundle parts, which represent the resources installed for a CICS bundle.
- An application entry point is declared in the CICS bundle
with an operation name that duplicates an operation name used elsewhere within the application. To
avoid this situation, ensure that operation names are unique within an application. Operation names
are case sensitive, so you may use operation names that are differentiated only by case, such as
browse
andBrowse
. - A URIMAP resource that is declared in the CICS bundle as an application entry point either does not exist, or is already reserved as an application entry point for a different application. To avoid these situations, define the URIMAP resource with a unique name in your environment.
- A program that is declared in the CICS bundle as an application entry point is a private program defined in one of the CICS bundles deployed with the application version. However, a program with that name is already installed as a public program in the CICS region. Programs that are declared as an application entry point must have a unique PROGRAM resource name in your environment. To avoid this situation, rename the private program in its resource definition and in the application entry point declaration to make its name unique. Multiple versions of the same private PROGRAM resource defined as an application entry point can be installed for multiple versions of the same application, because CICS manages the promotion of private PROGRAM resources to public status for the versions of an application.
- A previous version of the application declared as an application entry point a program that was not defined in one of the CICS bundles deployed with the application version, and was already installed as a public program. When the application version was enabled, CICS reserved the installed public program as an application entry point. However, CICS cannot now automatically manage the application entry points for new versions of the application, because a public program that was installed before the application cannot become a private program. To update the application to a new version, you will need to disable and discard the existing version. To avoid this situation, you can arrange that the public program is autoinstalled by the application installation process, in which case it can become a private program and allow future application versions to be installed at the same time. Alternatively, you can define the program in one of the CICS bundles deployed with the application version, ensuring that it has a unique name, and so make it a private program.
You cannot disable an application version
Check that the Make Unavailable action has been performed for the
application version where required. In CICS regions from CICS TS 5.2, if the availability status of the application
version is displayed as AVAILABLE, you must perform the Make Unavailable
action to make the application version unavailable to callers before you disable it. If your
platform includes any CICS regions that are still at CICS TS 5.1, the Make Unavailable action
does not apply to applications in those regions. Their availability status is not displayed. If any
of your applications have no application entry points, the Make Unavailable
action is not required for those applications. Their availability status is displayed as No entry
points
.
- In the Cloud Explorer view, working with the application hierarchy, expand each region type displayed under the application to show the Bundles list for the region type. Expand each Bundles list to display the management parts for the application. Locate any CICS bundle that is not yet disabled. Select the record for the CICS bundle in the CICS region where it is not yet disabled, right-click and select Disable.
- If the CICS bundle is still not disabled, view its bundle parts in the Bundle Parts view to identify and check on the status of the individual resources that were installed for the CICS bundle. Check on the status of any LIBRARY or PROGRAM resource that is defined in the CICS bundle. The BUNDLEPART resource associated with a LIBRARY resource does not report a status of DISABLED until the dynamic program LIBRARY concatenation and all programs loaded from it have a use-count of zero. For a PROGRAM resource, although CICS disables the program when the disable operation is carried out on the CICS bundle from which it was installed, the associated BUNDLEPART resource remains enabled until the use-count for the program reaches zero. If the use-count does not reach zero after an acceptable interval, it might be necessary to purge work from CICS so that the bundle disable process can complete.
- Check on the status of any JVMSERVER or TCPIPSERVICE resource that is defined in the CICS bundle. By default, these resources are not disabled until
all the current tasks have finished using them.
- For a JVMSERVER resource, if you want to disable the JVM server immediately and purge the tasks that are running in it, use the SET JVMSERVER PURGE, FORCEPURGE, or KILL command on the dynamically generated resource in the CICS region. You can perform this action in CICS Explorer.
- For a TCPIPSERVICE resource, if you want to disable the service immediately and close all the connections, use the SET TCPIPSERVICE IMMCLOSE command on the dynamically generated resource in the CICS region. You can perform this action in CICS Explorer.
- Check on the status of any FILE resource that is defined in the CICS bundle, and also check the CICS
message log for message DFHFC6043. CICS
issues this message when you have attempted to disable a file defined in a CICS bundle, but the file is still in use, or there is a retained lock on the
file.
- If the file is in DISABLED state and CICS has issued message DFHFC6043, for a recoverable file, check and resolve the retained lock. For a nonrecoverable file, check on the tasks that are using the file, and either purge the tasks or allow time for them to complete. When the appropriate process is complete, the CICS bundle moves to DISABLED state.
- If the file is in DISABLING state, you can issue any of the following commands to purge the
tasks that are using the file and disable the file:
- EXEC CICS SET FILE DISABLED FORCE
- EXEC CICS SET FILE CLOSED FORCE
- CEMT SET FILE FORCECLOSE