Manifest contents for a CICS bundle
Each CICS® bundle contains a bundle manifest that describes the contents of the bundle. A bundle manifest describes which resources to create in the CICS region and the location of the supporting artifacts, which prerequisites are required for the CICS bundle to run successfully, and any services that the CICS bundle can offer to other bundles.
The manifest for a CICS bundle is called cics.xml and is in the META-INF directory of the deployed bundle on z/OS® UNIX. The bundle manifest is written in XML and conforms to a schema. For more information, see The bundle manifest schema. The bundle manifest is encoded in UTF-8 and contains information about the bundle itself, as well as definitions, exports, imports, application entry points, and policy scopes.
- Bundle information
- The manifest can contain an optional <meta-directives> element that contains information about the bundle; for example, it can contain a time stamp of the time when the bundle was created.
- Definitions
- Every resource in the bundle is defined by its name, resource
type, and location in a <define> element:
- The name of the artifact is defined in the tooling.
- The resource type is defined as a URI.
- The location is defined as a relative file path, including the file name, to the artifact that provides the definition and metadata for the resource.
Some definitions lead to CICS creating one or more resources dynamically; for example a
https://www.ibm.com/xmlns/prod/cics/bundle/EVENTBINDINGresource type creates an EVENTBINDING resource and one or more CAPTURESPEC resources. Other definitions, such as thehttps://www.ibm.com/xmlns/prod/cics/bundle/SCACOMPOSITEresource type, are used by CICS only in runtime processing and have no equivalent CICS resource definition. - Exports
- The <export> element provides additional information about the resources or services that a bundle can provide. CICS does not use export statements in its processing of bundles. You can view the list of exports in the CICS Explorer®.
- Imports
- The <import> element defines references to resources that are
required by the bundle. Each reference has a name and a type, but
no path attributes. The reference also has an attribute that describes
how CICS handles the BUNDLE
resource installation if one of the required imports is not present
in the CICS region. The BUNDLE
resource can remain disabled, enable with warning messages, or enable
with no warnings. The default behavior is that all imports are required;
the BUNDLE resource can be installed but not enabled.
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.
- Application entry points
- If your CICS bundle is
part of a CICS application,
you can define one or more application entry points in the bundle
manifest. An application entry point identifies a resource that is
an access point to an application. Application entry points are used
to control users' access to different versions of an application that
is deployed on a platform. They are also used to create an application
context to monitor the resource usage for applications and to identify
an application being run.
The <entrypoint> element in the <modify> element defines an application entry point. The bundle manifest can contain 0 to many <modify> elements for application entry points. The <entrypoint> element specifies the name of the CICS resource, the type of resource, and the application operation. Resources that are specified as application entry points do not have to be defined in the bundle or specified as imports.
- Policy scopes
- A policy scope is used to limit a policy to a specific application
operation. When a policy is deployed with an application scope, the
policy applies to all user tasks within the platform that have the
matching platform, application and application version information
in their application context. A policy scope is used to further limit
a policy to only those user tasks that also match the operation.
The <policyscope> element in the <modify> element defines a policy scope for a policy. The bundle manifest can contain 0 to many <modify> elements for policy scopes. The <policyscope> element specifies the name of the application operation and the name of the policy to apply to user tasks for that operation. The name of the operation must be defined by a separate <entrypoint> element and the policy must be defined by a <define> element either in the same bundle or in a separate bundle which is deployed with the bundle defining the policy scope.
Example of a manifest
The following example shows a manifest for a CICS bundle that contains a program definition that is also an application entry point, together with a policy and policy scope for user tasks for that application entry point.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<manifest xmlns="https://www.ibm.com/xmlns/prod/cics/bundle"
build="IntB-201402121955" bundleRelease="0" bundleVersion="1"
bundleMicroVer="0" bundleMinorVer="0" bundleMajorVer="1" id="EXAMPLE">
<meta_directives>
<timestamp>2014-03-12T13:17:23.988Z</timestamp>
</meta_directives>
<import
warn="true"
optional="false"
type="https://www.ibm.com/xmlns/prod/cics/bundle/PROGRAM"
name="BASESCOP"/> 1
<import
warn="true"
optional="true"
type="https://www.ibm.com/xmlns/prod/cics/bundle/FILE"
name="BNDRES07"/> 2
<import
warn="false"
optional="true"
type="https://www.ibm.com/xmlns/prod/cics/bundle/TRANSACTION"
name="BR14"/> 3
<define
path="MYPROG.program"
type="https://www.ibm.com/xmlns/prod/cics/bundle/PROGRAM"
name="MYPROG"/> 4
<define
path="MYPOL.policy"
type="https://www.ibm.com/xmlns/prod/cics/bundle/POLICY"
name="MYPOL"/> 5
<modify>
<entrypoint
operation="READ"
type="https://www.ibm.com/xmlns/prod/cics/bundle/PROGRAM"
name="MYPROG"/> 6
</modify>
<modify>
<policyscope
operation="READ"
type="https://www.ibm.com/xmlns/prod/cics/bundle/POLICY"
name="MYPOL"/> 7
</modify>
</manifest>- The bundle imports a program that is required in the CICS region. If this PROGRAM resource is not present in the CICS region, the bundle installs successfully but is placed in a disabled state. CICS also issues a warning message.
- The bundle imports a file that is optional. If this FILE resource is not present in the CICS region, the bundle installs successfully but is placed in a disabled state. CICS also issues a warning message.
- The bundle imports a transaction that is optional. If this TRANSACTION resource is not present in the CICS region, the bundle installs successfully but no warning message is issued by CICS.
- The bundle defines a PROGRAM resource, including the name of the resource and the path to the XML file that defines the resource attributes.
- The bundle defines a POLICY resource, including the name of the policy and the path to the XML file that defines the policy attributes.
- The bundle declares a PROGRAM resource as an application entry point for a particular operation.
- The bundle declares that the POLICY is to be applied only to tasks which match the specified operation.