Characteristics of resources in CICS bundles

Bundle and resource interdependency

When you use CICS bundles, the lifecycle of the installed resources follows the lifecycle of the bundle. When you make available or unavailable, enable or disable, or discard a CICS bundle, the same action is applied to all the resources that were dynamically created by the CICS bundle. In addition, if your CICS bundle is included in an application bundle, you manage the CICS bundle as part of the application.

When a CICS bundle dynamically creates and installs a resource into a CICS region, the state of the resource is managed through the CICS bundle by which the resource was installed. You enable or disable the dynamically created resource by performing that action on the CICS bundle. For resources in CICS bundles that are managed as part of an application, you also control users' access to the resources by declaring application entry points. PROGRAM, TRANSACTION, and URIMAP resources can be declared as application entry points, and can be set as available or unavailable to users. With application entry points, you can install the application including the CICS bundle and its resources, then enable them to verify the installation. When you choose to provide the service to users, you make the application containing the CICS bundle available using the CICS Explorer®. This action makes the application entry point, and the resources in the CICS bundle, available to callers. An individual CICS bundle that contains application entry points can also be made available by using the EXEC CICS SET BUNDLE command.

In general, you do not directly modify the attributes of a resource that was dynamically created and installed by a CICS bundle. Instead, you install a new version of the CICS bundle with the required changes. However, some long-lived resources, such as the FILE, TCPIPSERVICE, and JVMSERVER resources, that have been installed by a CICS bundle, can be modified directly using CICS system commands, although the changes are not recovered across a warm restart of CICS.

An exception is also made for JVMSERVER and TCPIPSERVICE resources to the rule about changing the state of resources that are defined in CICS bundles. By default, these resources are not disabled until all the current tasks have finished using them. In a situation that requires immediate removal of these resources, you can use the SET JVMSERVER PURGE, FORCEPURGE, or KILL command, or the SET TCPIPSERVICE IMMCLOSE command, on the dynamically created resource in the CICS region, to force completion of the disable process when the resources are still in use. You can only issue these commands against a dynamically created resource after you have attempted to disable the CICS bundle or the application with which it is deployed.

If an application or a CICS bundle requires a CICS resource to be available in the CICS region, but you do not want the lifecycle of the resource to be tied to the lifecycle of the CICS bundle, you can add the resource as a dependency for the CICS bundle. Dependencies, or imports, are specified in <import> elements in the bundle manifest. You can specify the action that CICS takes at bundle installation time if one of the required imports is not present in the CICS region; for example, the CICS bundle can remain disabled, or be enabled but with a warning message. For more information about dependencies, see Manifest contents for a CICS bundle.

Installed resources that are defined in CICS bundles cannot be overwritten by resource definitions with duplicate names. When the bundle part containing a resource has been installed, if you try to install a duplicate resource using another CICS bundle, or using RDO, EXEC CICS CREATE commands or other methods, the request is rejected. You also cannot overwrite installed resources with a duplicate resource that is defined in a CICS bundle. When you attempt to install the CICS bundle, if a resource with the same name and resource type exists, the bundle part containing the resource is not installed, and the CICS bundle is placed in an unusable state. Resources that are defined in CICS bundles are therefore protected against accidental overwriting by duplicate resource names.

Private resources in bundles

When you create the definition for certain resource types in a CICS bundle, and deploy the CICS bundle as part of an application on a platform, the dynamically created resource is private to that version of that application. Private resources are not available to any other application or version installed on the platform, and they are not available to other tasks in the CICS region. Resources deployed in this way do not require unique names, and multiple versions of the resources can be deployed as part of application versions, without the need to disable the previous version of the resources. For more information about private resources, and the resource types that are supported, see Private resources for applications.

Resources to deploy with platform bundles

TCPIPSERVICE resources, JVM servers, and pipelines are resources that are likely to be required in multiple CICS regions in a platform, and to be used to run more than one application. To enable convenient scaling of a platform, it is good practice to deploy the CICS bundles for TCPIPSERVICE, JVMSERVER, and PIPELINE resources as part of the platform bundle, rather than as part of an application. You can specify the CICS regions in the platform where the resource is to be installed. For new resources, you can add new CICS bundles to a running platform after the platform is installed.

Certain CICS resources, including PIPELINE and JVMSERVER resources, must be installed and enabled before you install other resources that depend on them. With these resources, you can use platform architecture to manage the dependency. Deploy the CICS bundles containing the definitions for the required resources as part of a platform bundle, and then deploy the CICS bundles containing the dependent resources as part of applications that are deployed on the platform. This architecture ensures that when the resources are first installed in a CICS region or if the CICS region is restarted, the required resources and the dependent resources are installed and enabled in the correct order.

Mixed case resource names

CICS bundles support mixed case names for resources where these are supported in CICS. However, your file system might not allow files with the same name but different cases to reside in the same CICS bundle project. If you require duplicate resource names that use different cases, define these resources in separate CICS bundle projects.

Escaped characters in resource names

When you save a CICS bundle in the CICS Explorer, certain characters in the resource names are escaped so that the resource can be used in different file systems. When you expand the CICS bundle in the CICS Explorer and view the resources defined in the CICS bundle, the resource names are displayed with the escape sequences. When you open the resources for editing, the resource names are displayed with the original unescaped characters.

FILE resources

The initial status of a FILE resource that is dynamically created from a CICS bundle is derived from the initial status of the CICS bundle that defines the resource. As a result, it is not possible to define a FILE resource with a STATUS of UNENABLED to inhibit the implicit opening of files by applications.

The PASSWORD attribute is not supported for dynamically created FILE resources.

When a file that is defined in a CICS bundle is installed, it is added to the catalog. CICS recovers the bundle installed files from the catalog during a warm or emergency restart. These recovered files are used for the CICS recovery only. After CICS completes the recovery, all these files are deleted. When the bundle is re-created, CICS picks up the definition from the bundle directory, and creates a new file. If a file recovered from the catalog has a retained lock, it cannot be deleted on completion of recovery, and as a result, the file becomes orphaned (does not belong to any bundle) and has to be deleted manually after CICS has completed restart.

JVMSERVER resources

For JVM servers that are packaged in CICS bundles, the JVM profiles are packaged with the resource definitions in the CICS bundles. You can therefore install the JVM server in any CICS region without needing to set up a JVM profile in the local JVM profile directory for the CICS region.

When creating a JVM server, you can create the JVM profile using sample templates for an OSGi JVM server, an Axis2 JVM server, or a Liberty JVM server, or import an existing JVM profile to the CICS bundle from elsewhere in the workspace or from the local file system.

The set of acceptable characters in the JVM profile name is more restricted when the JVMSERVER resource is defined in a CICS bundle. For details, see JVMSERVER attributes. The directory name for the directory where the JVM profile is stored is limited to 240 characters, which is the same limit that applies to JVM profiles that are not defined in CICS bundles.

A JVM server that is defined in a CICS bundle must be installed and enabled before you install OSGi bundles or other application artifacts for Java™ applications that run in it. It is good practice to deploy a CICS bundle containing the definition for a JVMSERVER resource as part of a platform bundle, and to then deploy the CICS bundles containing OSGi bundles or other Java application artifacts as part of applications that are deployed on the platform. This architecture ensures that when the resources are first installed in a CICS region or if the CICS region is restarted, the JVM server and the Java application resources are installed and enabled in the correct order.

LIBRARY resources

If a LIBRARY resource is included in a CICS bundle, it should only be used for loading the modules used by that CICS bundle. Although advisable, this requirement is not enforced for a stand-alone CICS bundle, but it is enforced for a CICS bundle that is packaged and installed as part of an application on a platform.

The BUNDLEPART resource associated with the LIBRARY resource does not report a status of DISABLED until the LIBRARY concatenation and all programs loaded from it have a use-count of zero. It might be necessary to purge work from CICS so that the bundle disable process can complete.

If a program is loaded from a LIBRARY concatenation that was defined and installed by a CICS bundle, that program is treated as though it was defined in the CICS bundle, even though the program might have been defined independently. The lifecycle of these programs conforms to the lifecycle of the CICS bundle in which the LIBRARY resource is defined. If a CICS bundle that contains a LIBRARY resource is disabled, all programs loaded from that LIBRARY concatenation are disabled.

PIPELINE resources

For pipelines that are packaged in CICS bundles, the pipeline configuration files are also packaged with the resource definitions in the CICS bundles. You can create a pipeline configuration file using one of the CICS-supplied sample pipeline configuration files, or import an existing pipeline configuration file from the local file system.

If a PIPELINE resource is packaged in a CICS bundle, it should be deployed as part of a platform for hosting WEBSERVICE resources that are defined using CICS bundles. PIPELINE resources that are defined in CICS bundles can only be used with WEBSERVICE resources that are defined in CICS bundles or created dynamically by a pipeline scan. WEBSERVICE resources defined using the CICS CSD or BAS are not compatible with PIPELINE resources that are defined in CICS bundles.

A PIPELINE resource that is packaged in a CICS bundle must be installed and enabled before you install the WEBSERVICE resources that require it. It is good practice to deploy a CICS bundle containing the definition for a PIPELINE resource as part of a platform bundle, and to then deploy the CICS bundles containing WEBSERVICE resources as part of applications that are deployed on the platform. This architecture ensures that when the resources are first installed in a CICS region or if the CICS region is restarted, the PIPELINE resource and the WEBSERVICE resources are installed and enabled in the correct order.

A PIPELINE resource that is defined in a CICS bundle can specify a WSDIR attribute, but this is discouraged. The SHELF attribute is not used for PIPELINE resources that are defined in CICS bundles.

PROGRAM resources

If a program is in use and the CICS bundle from which it was installed is disabled, CICS disables the program, and no new work can be started by that program. However, the associated BUNDLEPART resource remains enabled until the use-count for the program reaches zero. As a result, during this period the BUNDLEPART resource, and the program both report different states. If the use-count for the program 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.

When the bundle state has changed from DISABLING to DISABLED, the CICS bundle can be discarded. However, if you discard the CICS bundle, the program that was installed by the bundle is discarded and becomes unavailable until the CICS bundle is reinstalled.

The PROGRAM NEWCOPY and PROGRAM PHASEIN processes are not available for programs installed from CICS bundles. The process for a program defined in a CICS bundle is to install a new version of the CICS bundle, or of the application with which the CICS bundle was deployed. For PROGRAM resources defined in stand-alone CICS bundles, you must uninstall the previous version of the CICS bundle before you install the new version. When you deploy PROGRAM resources defined in CICS bundles as part of an application on a platform, you can install new versions of the PROGRAM resource without uninstalling the previous versions, and manage the availability of the new versions for users. For more information about multi-versioning for applications, see Multi-versioning for applications deployed on platforms.

Programs that are installed by CICS bundles are not suitable for invocation from the PLT.

PROGRAM resources can be declared as application entry points, although the PROGRAM resource does not have to be defined in a CICS bundle to be declared as an application entry point. Programs that are declared as an application entry point must have a unique PROGRAM resource name in your environment. For more information about programs as application entry points, see Application entry points.

TRANSACTION resources

A transaction might be allocated work that is due to be started, by an EXEC CICS START command, at a scheduled time. If that work is scheduled to start after the CICS bundle is disabled, the scheduled work is canceled, and no new work is allowed to start for that transaction. If the CICS bundle is then re-enabled, the canceled work is not rescheduled, and remains canceled.

TRANSACTION resources can be declared as application entry points, although the TRANSACTION resource does not have to be defined in a CICS bundle to be declared as an application entry point. A TRANSACTION that is declared as an application entry point must have a unique TRANSACTION resource name in your environment. For more information about TRANSACTION's as application entry points, see Application entry points.

URIMAP resources

A WEBSERVICE resource is normally associated with at least one URIMAP resource. The URIMAP resources can be packaged in the same bundle as the WEBSERVICE resource, but it can be preferable to package them in a separate bundle that can be customized for each platform to which the WEBSERVICE resource is deployed. For example, you might want to use a different URI in a quality assurance platform than is used in a production platform, or define a mirror transaction for the WEBSERVICE resource in the production platform but not in the unit testing platform.

When you define a URIMAP resource in a CICS application bundle, you can use an application entry point declaration to control users' access to the service provided by the URIMAP resource. In this situation, when you install and enable the application, the service provided by the URIMAP resource is not yet available to callers. When you choose to provide the service to users, use the CICS Explorer to make the application containing the CICS bundle available. This makes the application entry point, and therefore the service provided by the URIMAP resource, available to callers.

You can also declare as an application entry point a URIMAP resource that is defined outside the application. In this situation, the service becomes available to users as soon as you install and enable the URIMAP resource.

When you are using a URIMAP resource to provide a static response from CICS as an HTTP server, the HFSFILE attribute specifies the name of a z/OS® UNIX System Services zFS file that forms the body of the response. For a URIMAP resource that is defined in a CICS bundle, the zFS file must be packaged in the CICS bundle with the URIMAP resource. The HFSFILE attribute should specify a relative file path, which is relative to the root directory of the CICS bundle. For a relative file path, do not use a slash at the beginning of the path. For more information, see Referencing zFS artifacts in a bundle. Absolute references to zFS locations outside of the bundle are possible, but strongly discouraged.

WEBSERVICE resources

For web services that are packaged in CICS bundles, you can import a web service binding file and a WSDL document or WSDL archive file to be packaged in the bundle along with the resource definition. To support the web service, you can use a WEBSERVICE definition packaged in a CICS bundle to generate a URIMAP definition in a separate bundle. You can also create an alias transaction for the URI map, and an optional URIMAP definition for WSDL discovery.

Web services that are packaged in CICS bundles have additional states of DISABLING and DISABLED, which do not apply to web services created using other methods. When disabling is in progress for a CICS bundle, WEBSERVICE resources defined in the bundle enter DISABLING state. Work that is currently executing is allowed to complete, but the web service does not accept new work. When the web service is no longer in use, the WEBSERVICE resource enters DISABLED state. Requests to a web service in DISABLING or DISABLED state are rejected and a SOAP fault, Web service is not in service, is sent. If CICS is the web service requester, the INVOKE SERVICE command returns a RESP code of INVREQ and a RESP2 value of 8.

If the CICS bundle is enabled again, the WEBSERVICE resource returns to INSERVICE state. Otherwise, the WEBSERVICE resource can be discarded by discarding the CICS bundle. You can inquire on the state of a WEBSERVICE resource using the EXEC CICS or CEMT INQUIRE WEBSERVICE command, the CICSPlex® SM web user interface, or the CICS Explorer, but you cannot set it manually.