If an application version that is deployed on a platform
does not have the expected status, follow this troubleshooting procedure
to take appropriate action.
Before you begin
Use the Cloud Explorer view in the CICS® Cloud perspective to check the status of
the application version.
Checking the status of an application explains
how to use the view and lists the possible values for the status of
an application version and of the management parts. An application
version is enabled if the CICS bundles
referenced by the management parts for the application version have
been installed in the CICS regions,
and all of them are enabled. In CICS regions
from CICS TS 5.2, an enabled
application version is not yet available to callers through its application
entry points. When the application version is made available, the
application entry points, and therefore the resources that they control
for the application, are available to callers.
Procedure
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- 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.
- 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, 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.
- 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.
- 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.
- 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.
- 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.
- 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 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.
- 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. 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.
- 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".
- 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.
- 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.
- 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.
- 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.
- 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.
You cannot use these methods to disable the resource
unless you have already performed the Disable action
on the CICS bundle.
- 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.