Private resources for application versions

When you define certain CICS® resources in CICS bundles as part of an application installed on a platform, the resources are private to that version of that application. You can therefore install more than one resource of those types with the same name, at the same time, on the same platform instance.

For supported resource types, a CICS resource is private if the resource is defined in a CICS bundle that is packaged and installed as part of an application, either as part of the application bundle, or as part of the application binding. When you create a CICS resource in this way, the resource is not available to any other application or version installed on the platform, and it is not available to other applications in the CICS region. It can only be used by the version of the application where the resource is defined. These resources are known as private resources.

The following CICS resources are supported as private resources for applications:

LIBRARY resources, which represent one or more data sets, known as dynamic program LIBRARY concatenations, from which program load modules can be loaded.
POLICY resources, which represent one or more rules that manage the behavior of user tasks in CICS regions.
PROGRAM resources, which represent an application program. A program that is auto-installed by a task for an application that is deployed on a platform is also private to that version of the application.

CICS resources of other resource types that are defined as part of applications, and CICS resources that are defined by any other methods, are publicly available for all tasks. These resources are known as public resources. In applications that have only a single version, private resources that are declared as application entry points become public resources when the application entry point is made available. For multi-versioned applications, if the application is the highest available version, a program that is declared as an application entry point is public. The programs that are declared as application entry points for the other versions of the same application are private.

If you do not want a resource of the supported resource types to be private, do not package the resource definition as part of an application. Instead, define the CICS resource using a standalone CICS bundle, a CICS bundle that is installed at the level of a platform, the CICS CSD, or the CICSPlex® SM data repository. If an application requires the CICS resource to be available in the CICS region, add the resource as a dependency for the application or the application binding, in an <import> element of the bundle manifest.

Policies, which are not a CICS resource, have the same support as private resources when they are defined in a CICS bundle that is deployed as part of an application. You can therefore use policies with the same name in different applications and application versions.

Private resources relate to a particular version of the application, not just a particular application. They therefore enable the installation of multiple versions of applications on the same platform instance, at the same time. For more information about multi-versioning for applications, see Multi-versioning for applications deployed on platforms.

Managing private resources for applications

When you define a private resource in a CICS bundle that is packaged and installed as part of an application, the resource name does not have to be unique in your installation. You can use this facility to avoid resource name clashes between applications that were developed independently, but used the same resource names. The requirement for unique resource names for the supported CICS resources can be removed by managing the resources as part of applications deployed on a platform. You can use this process to assist with server consolidation.

When you make changes to an application, you use the CICS Explorer® to modify the relevant elements of the application that are packaged in CICS bundles, apply a new version number to those CICS bundles to identify the change, and then reversion and reinstall the application. You leave any unmodified CICS bundles at the same version number as before, because CICS manages the process of multiple installations of CICS bundles with the same ID and version number.

Reinstallation of unmodified CICS bundles is only available for CICS bundles that are installed as part of an application deployed on a platform. Standalone CICS bundles cannot be reinstalled if they are already installed with the same ID and version, or in the case of CICS bundles created in releases before CICS TS 5.1, installed with no ID and version. However, the same CICS bundle can be installed in CICS regions as a standalone CICS bundle, and also installed and reinstalled as part of one or more applications deployed on a platform.

Special CICS messages are issued when actions such as installing and discarding are performed on private resources. The messages provide the same information as for the corresponding actions on public resources of that type, but they also state the platform, application, and application version to which the private resource applies, so that you can audit or troubleshoot the actions in the relevant context.

To view the private resources for each installed version of an application, use the CICS Explorer. In the online application editor, you can view the private resources and the application entry points for the application by resource type, and filter them by CICS region or by CICS bundle to help locate particular resources. You can also view the DD names that z/OS® has generated for the LIBRARY concatenation of data sets for private LIBRARY resources.

You can inquire on or browse private resources using the EXEC CICS INQUIRE system programming command for the resource type. By default, CICS searches for the resources that are available to the program where the EXEC CICS INQUIRE command is issued. You can also choose to browse private resources for a specified application.

When you issue an EXEC CICS INQUIRE command from a public program, information is returned about the named public resource. If the resource is not available as a public resource, a not found response is returned.
When you issue an EXEC CICS INQUIRE command from a program that is running under a task for an application deployed on a platform, information is returned about the named private resource for that application, if it exists. If the application does not have a private resource with that name, information is returned about a public resource with the specified name. If the resource is not available as a private resource for that application or as a public resource, a not found response is returned.
When you use an EXEC CICS INQUIRE command in browse mode from a public program, if you do not specify any other input parameters, the set of public resources of the specified type is returned. If the same browse command is issued from a program that is running under a task for an application deployed on a platform, the browse returns a set of resources consisting of any private resources of the specified type for the application, and the public resources of the specified type.
To browse the private resources for an application, from either a public program or a private program, issue the EXEC CICS INQUIRE command with the START option and specify as input the application context, consisting of the platform, application, and application version. The browse returns a set of resources consisting of only the private resources of the specified type for the application. If no application is found with the specified application context, the APPNOTFOUND condition is returned.

For more information about browsing private resources, including examples of browsing resources for a different application from the application where you issue the command, see Browsing resource definitions.

To support private resources in CICSPlex SM's real-time analysis (RTA) function, you must specify the application context parameters PLATFORM, APPLICATION, APPLMAJORVER, APPLMINORVER and APPLMICROVER in the evaluation definition (EVALDEF) for the resource. For instructions to create and maintain real-time analysis definitions using user-defined CICSPlex SM WUI views and resource objects, see Real-time analysis.

CICS produces separate statistics records for private resources. A statistics record for a private resource has information about the application for which the resource was defined. The statistics DSECTs and DFHSTUP reports for public program and library resources have corresponding DSECTs and DFHSTUP reports for private resources. Programs that are declared as application entry points are identified and reported in both the public and private statistics, because, while the entry point is publicly accessible, it is also part of the application.

Private resources as dependencies

Start of change In a CICS bundle that is packaged as part of an application deployed on a platform, public or private resources can be defined as dependencies, including private programs that are autoinstalled by an application. CICS checks first for a private resource with the specified type and name in the same application as the CICS bundle that contains the <import> element in the bundle manifest file. If more than one version of the application is installed, the current application context determines the version of the private resource that is imported. If the resource is not found as a private resource for the application, CICS checks for a public resource in the CICS region that matches the specified type and name, and imports that resource. You cannot import private resources from other applications. End of change

Private LIBRARY resources

LIBRARY resources represent one or more data sets, known as dynamic program LIBRARY concatenations, from which program load modules can be loaded. The LIBRARY resource is supported as a private resource for an application version. Each version of an application should include at least one private LIBRARY resource representing the version-specific data sets containing the load modules for the application.

When a task for an application deployed on a platform requires a program load, the private LIBRARY concatenations defined for that version of the application are searched first, so that the correct version of the program is loaded. If multiple LIBRARY concatenations are defined for the same application version, they are searched in order of their ranking.
If there are no LIBRARY concatenations defined in the application, or the program is not found in any of the private LIBRARY concatenations, the public LIBRARY concatenations defined for the whole CICS region (including DFHRPL) are searched.
For a task that is not associated with an application deployed on a platform, only the public LIBRARY concatenations are searched, so all program load modules that are resident in private LIBRARY concatenations are not available.

If any of the private LIBRARY concatenations for an application are disabled, because the CICS bundle that defines the relevant LIBRARY resource is disabled, CICS does not search any other private LIBRARY concatenations, or any public LIBRARY concatenations that are defined for the whole CICS region. All subsequent program loads by the application therefore fail until the CICS bundle that defines the LIBRARY resource is enabled.

Start of change For a private LIBRARY resource that is defined in a CICS bundle that is packaged and installed as part of an application bundle or application binding bundle, the name of the LIBRARY resource is not used as the DD name for the LIBRARY concatenation of data sets. Instead, CICS requests a unique DD name for the LIBRARY concatenation of data sets when the application is installed on the platform. The resource name can therefore be the same as LIBRARY names used elsewhere in the installation, or by different versions of the application. CICS issues message DFHLD0518 to state the DD name that z/OS has generated for the LIBRARY concatenation. You can also view the data set names for an installed application in the CICS Explorer. End of change

Private POLICY resources

POLICY resources represent one or more rules that manage the behavior of user tasks in CICS regions. A policy is an XML definition that contains one or more rule types with associated thresholds and actions. The policy rules describe the controls or actions that can be applied to one or more tasks. A condition and action pair make up a policy rule, and one or more policy rules can be defined within a policy. A policy is defined in a CICS bundle and a CICS bundle can consist of one or more policies.

CICS performs the action that is specified in the policy when tasks that are running exceed defined thresholds for resource usage. You can deploy policies to monitor the resource utilization of a user task, and to automatically respond when resource usage exceeds the thresholds you define. As long as a task is relinquishing control to CICS by issuing EXEC CICS commands, excessive resource usage, and looping and runaway transactions, can be detected and dealt with appropriately.

Policies are always defined in CICS bundles, which are always deployed to a specific scope. The scope can be an application, an operation within the application, or a platform.

Policies define a contract about how you want aspects of an application or system to behave. Policies apply to instances of user tasks, and different groups of tasks can share a common set of policies, thus allowing sections of the workload to be controlled in different ways. The collection of policy rules that are associated with tasks that are running in an application or platform define the boundaries within which a task can safely execute. They allow systems administrators to set, in advance, limits on the behavior of user applications. In this way, policies enable CICS to measure, react to, and enforce the behavior of tasks that transgress any of the rules that are defined in the policies that apply to them, as they execute.

For more information about Polices, see Policies.

Private PROGRAM resources

A PROGRAM resource represents a program load module that is stored in the program library. The PROGRAM resource is supported as a private resource for an application version. A program that is auto-installed by a task for an application that is deployed on a platform is also private to that version of the application.

Only one copy of each version of each program is loaded in CICS storage. Before loading a private program, CICS checks whether that version of the program has already been loaded from the same data set (PDS or PDSE) with a matching PROGRAM resource definition. If so, CICS uses the existing copy. The following rules therefore apply when you are reusing PROGRAM resource names:

Multiple applications that are intended to share the same program loaded from the same PDS or PDSE must use the same attributes in the PROGRAM resource definition.
If multiple applications use the same name for different program resources, each application must load the programs from a different data set (PDS or PDSE).

If you specify RELOAD=YES in the PROGRAM resource definition for a private program, its behavior for program loading changes to be the same as for a public program. A program control link, load, or XCTL request brings a fresh copy of the program into storage. RELOAD(YES) programs cannot be reused, and they cannot be shared by multiple applications. Each of the program copies must be removed from storage explicitly, using a storage control FREEMAIN request, when it is no longer required and before the transaction terminates.

If a program that is required by an application is not found in the private program directory for the application, CICS searches the public program directory.

When the EXEC CICS LINK, XCTL, LOAD, and RELEASE commands are issued by a program that is running under a task for an application deployed on a platform, CICS searches first for the named program in the private program directory for the application. If the named program is not found there, CICS then searches the public program directory.

Programs that are declared as an application entry point must have a unique PROGRAM resource name in your environment. To enable these programs to be called from outside the application, they must be public resources. When you make an application available that contains an application entry point for a private PROGRAM resource, the PROGRAM resource that is named as the application entry point changes from a private resource to a public resource. Only one instance of a public resource with a particular name can exist in a CICS region. The PROGRAM resource therefore cannot have the same name as a public program that is installed in the CICS region, or the same name as a public program that is defined as an application entry point by a different installed application. However, multiple versions of the same PROGRAM resource defined as an application entry point can be installed for multiple versions of the same application, because CICS manages the promotion of PROGRAM resources to public status for the versions of an application.