When you add resource definitions to a CICS® bundle
project, CICS dynamically creates resources for you when you
deploy and install the bundle in the CICS region.
About this task
- Consideration for the bundle lifecycle
Some characteristics of CICS resources change because
they are defined in a CICS bundle and dynamically created as
part of a bundle deployment. The lifecycles of CICS resources
that are created in this way cannot be managed independently of the BUNDLE resource. They must be
managed through the CICS bundle. Because of bundle and
resource lifecycle interdependency, application architects must carefully consider which set of
resources for an application should have their lifecycle tied to the lifecycle of a CICS bundle. To understand more about the potential implications of defining
resources in CICS bundles, see
Characteristics of bundled resources in the CICS TS product documentation.
- Consideration for referencing multiple bundles in an application bundle
You can reference one or many CICS bundles
in an application bundle. By packaging your application in this way, you can deploy an application
and its bundles as a single entity to CICS, making it easier
to update and manage the application in CICS. A CICS bundle can be installed in CICS regions by more than one application if it contains only resources that are eligible for
multi-versioning. For more information on multi-versioning and supported resource types, see Multi-versioning applications in the CICS TS product documentation.
For unsupported resource types, you can design the application so
that the resource is managed outside the application. For example, if your application requires a
resource that is not supported for multi-versioning and the application has already been used in a
CICS bundle installed in the target region type in the
platform, you can create a new CICS bundle project and
declare the resource as a dependency for the new CICS
bundle. Then include the new CICS bundle project in your application project. For detailed instructions,
see Defining bundle
dependencies.
To define a resource in a CICS bundle project, follow
these steps:
Procedure
- In the Project Explorer view, right-click the CICS bundle project and click New.
- Select the resource that you want to add from the menu; for example, a program, library,
transaction, or URI map definition.
Tip: 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.
- Complete the required fields in the wizard.
- For a subset of CICS resources, you can add an
application operation if the resource is an entry point into an application.
- For a JVM server, you can choose to create a JVM profile by using one of
the supplied templates, OSGi, Axis2, or Liberty, or use an existing JVM profile
that is in the CICS bundle, or import an existing JVM profile
to the CICS bundle from elsewhere in the workspace or from
the local file system. 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. After you have completed
the wizard, edit the JVM profile to meet your system requirements, following the instructions in
Editing resources defined in a CICS bundle project.
- For a pipeline, you can choose to create a pipeline configuration file by
using one of the CICS-supplied sample pipeline configuration
files, or import an existing configuration file from the local file system or the local workspace.
After you have completed the wizard, edit the pipeline configuration file to add the message
handlers, header processing programs, and application handlers that you want to include in it,
following the instructions in Editing resources defined in a CICS bundle project.
- For a Node.js application, you first enter a name for the NODEJSAPP bundle part. This
name must be unique within the CICS region the bundle will be
installed into. Then, you select the JavaScript file to
run. Finally, you select a profile that specifies the configuration information that CICS uses. The fully qualified paths to the initial JavaScript file and the profile when exported to zFS cannot
be more than 255 characters.
- For a web service, you import a web service binding file from the local file
system or the local workspace to create the WEBSERVICE definition. You can choose to import a WSDL
document or WSDL archive file to be packaged in the bundle, and for a service provider you can
select the check box to include a PROGRAM definition in the bundle.
The web service is
created with the default setting that full validation of SOAP messages is not required, but you can
change this either in the resource editor or in CICS after
the resource has been installed.
- After you have created a WEBSERVICE definition, you can right-click it and
launch a wizard to generate the URIMAP definitions for the web service and create an alias
transaction:
- The path for the URIMAP is pre-populated based on the web service binding file, but you can
enter a different path if necessary.
- The host name and port number for the URIMAP are pre-populated based on the web service binding
file. If the host name cannot be retrieved, CICS
Explorer displays a warning message, and you must enter a value in the
Host field. If the port number cannot be retrieved, CICS Explorer provides a default value of 80 or 443, depending on the
URI schema.
- The default alias transaction is CPIH, but you can change this and you can select the check box
to generate a transaction definition. Transaction definitions will not be generated for CPIH or
CPIQ, even if the check box is selected. Other transaction names beginning with C are reserved for
CICS.
- To make the URIMAP resource into an application entry point, you can open the CICS Bundle Manifest Editor and switch to the Entry
Points tab, then add an entry point by specifying a unique operation name, URIMAP
resource type, and URIMAP resource name.
- For an URIMAP resource, you can create a URIMAP configuration file by the
New URI Map Definition dialog. Specify the host, path and choose the
usage.
- For a URIMAP definition that uses an HFS file to provide a static response, the file must be
packaged in the CICS bundle with the URIMAP resource. Specify
a relative file path that 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.
Absolute paths can be used, but this is strongly discouraged.
- Select the usage:
- To create a URIMAP definition for CICS as an HTTP server,
select Server. This type of URIMAP definition is used to map the URI of an incoming HTTP request from a web client to CICS resources. An application-generated response or a static response can be provided.
- To create a URIMAP definition for CICS as an HTTP client,
select Client. This type of URIMAP definition is used when CICS makes a request for an HTTP resource on a server, so that you can avoid
identifying the URI in your application program.
- To create a URIMAP definition for a web service, select Pipeline. This
type of URIMAP definition is used for an inbound web service request; that is, a request by which a
client invokes a web service in CICS. The URI of the incoming
request is associated with WEBSERVICE and PIPELINE resources, which specify the processing that is
to be performed on the message.
- To create a URIMAP definition for an Atom feed, select Atom. This type of
URIMAP definition is used for an incoming request for data that CICS makes available as an Atom feed. The URIMAP definition maps the request URI to an
ATOMSERVICE resource definition, which defines an Atom document.
- To create a URIMAP for a web application that is running in a JVM server, select JVM
Server. This type of URIMAP is used to map incoming application requests to a CICS transaction. If no URIMAP matches the URI of the incoming
request, CICS uses the CJSA transaction.
- To configure the URIMAP so that a static response is provided, select
File then select HFS File or Template
Name. The usage attribute is set to USAGE(SERVER).
For more information about the usage attributes, see URIMAP resource definitions in the CICS TS product documentation.
- To make the URIMAP resource an application entry point, select the Create an
application entry point check box and enter a unique operation name. Alternatively, you
can open the CICS Bundle Manifest Editor and switch to the
Entry Points tab, then add an entry point by specifying a unique operation
name, URIMAP resource type, and URIMAP resource name.
- Click Finish.
- If you want to view and edit the attributes for the resource immediately after you create
it, select the Open editor check box to open the resource editor when you
have finished the wizard.
If you want to do this later, you can open the resource editor from the Project
Explorer view.
- If you want to add, remove or order the defined resources in the bundle project, navigate
to the CICS Bundle manifest and use corresponding buttons in the
Defined resources section on the Overview
page.
Results
A resource definition is created in the CICS bundle
project and the bundle manifest is updated.
What to do next
To edit the resource in the resource editor, follow the instructions in Editing resources defined in a CICS bundle project.
When you have completed your resource definition for a Gradle-based or Maven-based CICS bundle project, you can deploy it as per the instructions
that are given in Deploying a CICS bundle using Gradle for Gradle plug-in and
instructions that are given in Deploying a CICS bundle using Maven for Maven plug-in.
When you have completed your resource definition for an Eclipse-based CICS bundle project, you can deploy it directly to zFS, or package the bundle
for deployment with an application or platform bundle. See Deploying a CICS bundle for more information.