Diagnosing application errors

If an application version that is deployed on a platform does not have the expected status, follow this troubleshooting procedure to take appropriate action.

• If 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 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 CICSTS51.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 initial values are 500 and 3000.
• If the status of an application version is DISABLED or SOMEDISABLED, try to enable the whole application.
  1. In the Cloud Explorer view, right-click on the application version and select Enable. If the application version is open in the online application editor, use the Enable button on the Overview tab. CICSPlex SM attempts to enable all the CICS bundles for the application version in all the CICS regions.
  2. Check the new status to see whether the application version is now enabled. If the application version is not enabled, investigate the individual CICS bundles that are named in each management part. In the Cloud Explorer view, use the switch hierarchy drop-down list to switch to the application hierarchy. 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.
• If 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.
  1. Double-click on 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.
  2. 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.
  3. If the CICS bundle remains disabled, check its definition to see if it has a dependency on an import for a resource that is not present in the CICS region.
  Tip: If a CICS bundle containing the definition for a private LIBRARY resource for an application is disabled, CICS does not attempt to load program modules from any other private LIBRARY concatenations for the application, or from the public LIBRARY concatenations in the global search order. Instead, a "not found" response 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.
• If the status of an application version is INCOMPLETE or EMPTY, investigate the individual CICS bundles that are named in each management part:
  1. In the Cloud Explorer view, use the switch hierarchy drop-down list to switch to the application hierarchy. 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. To work with the installed CICS bundles, double-click on the management part to open the CICS Bundles view. Alternatively, right-click the management part and click Show Installed Bundles.
  2. 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.
  3. 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, use the switch hierarchy drop-down list to 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.
  4. 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 when 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.
     • This error can also occur if 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.
• If you are experiencing a problem with a private resource that has been installed in a CICS region for an application version, investigate the individual private resources.
  1. 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. To filter the private resources by the CICS region where they are installed, select the region hierarchy in the Structure pane. Alternatively, to filter the private resources by the CICS bundle where they are defined, select the bundle hierarchy in the Structure pane.
  2. 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. To work with a private resource, double-click the resource name to open it in an editor.
  3. 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.
• 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.
  1. 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.
  2. 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 or URIMAP resources in the application.
• If you perform the Make Available action to make an application version available to callers, and the action was required, but the availability status of the application version remains as UNAVAILABLE or SOMEAVAIL for an extended period, investigate the individual management parts for the application version. 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.
  1. 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.
  2. 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.
  3. 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. To work with the installed CICS bundles, double-click on the management part to open the CICS Bundles view. Alternatively, right-click the management part and click Show Installed Bundles. To view the bundle parts for the individual resources that were installed for the CICS bundle, right-click the CICS bundle name in the Bundles view and click Show Bundle Parts. Check whether any of the following situations apply:
     • 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" and "Browse".
     • 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.
• If you cannot disable an application version, check that the Make Unavailable action has been performed for the application version where required.
  1. 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.
  2. 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.
  3. 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".
• If your application has been made unavailable where required, and you have performed the Disable action, but the application version remains in DISABLING state, investigate the individual CICS bundles that are named in each management part.
  1. 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. To work with the installed CICS bundles, double-click on the management part to open the CICS Bundles view. Alternatively, right-click the management part and click Show Installed Bundles.
  2. In the CICS Bundles view, 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.
  3. 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. To view the bundle parts, right-click the CICS bundle name in the Bundles view and click Show Bundle Parts.
  4. 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.
  5. 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.
     You cannot use these methods to disable the resource unless you have already performed the Disable action on the CICS bundle.
  6. 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
       When the tasks have been purged, the CICS bundle moves to DISABLED state. Note that closing a file using the FORCE option causes tasks of any current users of the file to be stopped immediately by the CICS task FORCEPURGE mechanism. Data integrity is not guaranteed with this mechanism. In some extreme cases (for example, if an error occurs during backout processing), CICS might end abnormally. For this reason, close files using the FORCE option only in exceptional circumstances.