Diagnosing platform deployment errors

If you experience any errors when attempting to create a platform definition or install a platform, follow this procedure to diagnose the problem and take suitable action.

About this task

When you create a platform definition, CICSPlex® SM creates a PLATDEF resource object in the data repository that points to the location of the platform bundle in zFS. When you install the platform definition, CICSPlex SM creates a PLATFORM resource object in the data repository. CICSPlex SM also creates the region types for the platform, adopting any existing system groups and creating any new ones identified in the platform bundle. CICSPlex SM attempts to install any CICS® bundles that are deployed with the platform bundle into the regions in each region type.

Each CICS system group (CSYSGRP) that you include as part of a platform must meet the following requirements:

The group has not already been adopted by a platform that is already installed. If the group is associated with a platform, it cannot be used as a region type.
The group does not contain any subgroups.
The group will not require modification (for example, a group that is involved in WLM or RTA). Platforms require a lock on the groups that are used as region types.
All the CICS regions in the group have the CICSPlex SM system parameter MASPLTWAIT(YES) specified. MASPLTWAIT(YES) is also required for Business Application Services. This parameter is required to automatically install resources for an application or platform when the CICS region is initialized.

If you have CICS regions in a CSYSGRP that does not meet these requirements, and you want to adopt the CICS regions as part of the platform, add their system definitions (CSYSDEFs) to a new CSYSGRP that you create specifically for the platform.

If an error occurs when you create or install a platform, the installation fails and all resources modified to that point get restored to their original state. Errors are reported in CICS Explorer® and you can use these errors as a starting point for troubleshooting.

CICS Explorer issues the error message CNX0592E for errors that occur when you are creating or installing a platform. This message is always preceded in the Error Log view by a CNX06xxE message that describes the action performed. When you receive message CNX0592E, review the attribute and error information in the message, and review the Error log view to determine the failing command and condition.

CICSPlex SM issues error messages to the CICSPlex SM output log (the EYULOG) for the maintenance point CMAS.

Look up the error codes for platforms in the PLATDEF Resource Table in the CICS TS V5.4.0 product documentation for platform definitions (PLATDEF), and the PLATFORM Resource Table in the CICS TS V5.4.0 product documentation for PLATFORM resources.

Procedure

If you experience a problem when you are creating a platform definition (PLATDEF), check that your specified values are valid:
1. Check that the platform NAME value is valid. Only alphanumeric, national, and special characters are valid.
2. Check that the platform directory has a valid UNIX System Services path. The PLATDIR field uses CICSPlex SM PATH validation to validate the platform directory. Click Browse to navigate to a valid path.
  For more information, see Creating a platform home directory in zFS.
If you are installing a platform, and the platform install fails, check the CICSPlex SM output log (the EYULOG) for details of the problem that occurred while the platform was being installed.
1. Messages beginning with EYUTI are issued when there is a problem with the platform descriptor XML. For example, the XML files might contain region types or CICS regions with duplicate names, or an invalid value might be present in one of the definitions for a created CICS region. The message explains how to correct the problem. When you have checked and fixed the XML files in the platform bundle, export the platform bundle again and retry the platform install.
2. If your platform 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 you have exported the platform bundle and created the platform home directory on a different sysplex from the sysplex where you are installing the platform. Ensure that the platform home directory is on the sysplex where you are installing the platform.
  For more information, see Creating a platform home directory in zFS.
3. 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 you are installing a platform, and the platform install succeeds, but the enable status of the platform is displayed as INCOMPLETE or EMPTY, there is a problem with the CICS bundles that should be installed with the platform. Investigate the individual CICS bundles that are named in each management part:
1. 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.
2. 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. If the CICS regions are available, check the definition for the CICS bundle for any errors.
3. Check the CICSMSG log for the CICS regions in the region type of the affected CICS bundle, and look for messages that provide more information about why the CICS bundle was not installed.
4. If the CICS bundle cannot be found, check your zFS setup as described previously for the platform bundle. This error can occur if the platform home directory in the zFS file system is not shared across the sysplex, or if the platform home directory is on a different sysplex from the sysplex where you are installing the platform.

What to do next

Following a successful platform install, the status of the platform might be displayed as PARTIAL or INACTIVE, and the enable status might be displayed as DISABLED or SOMEDISABLED. If any of these status values are shown and they are not as expected at this stage of your platform install, follow the procedure in Diagnosing platform runtime errors to diagnose the problem and take suitable action.