Adding resources to a CICS bundle project

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.

Before you begin

Create a CICS bundle project before you can add resources to it. For more information, see Creating a CICS bundle project.

This topic is about adding resources to a CICS bundle project. For detailed instructions on how to add a project to a CICS bundle project, see Adding a project to a CICS bundle project.

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

  1. In the Project Explorer view, right-click the CICS bundle project and click New.
  2. 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.
  3. Complete the required fields in the wizard.
    1. For a subset of CICS resources, you can add an application operation if the resource is an entry point into an application.
    2. 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.
    3. 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.
    4. 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.
    5. 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.
    6. 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.
    7. 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.
  4. Click Finish.
  5. 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.
  6. 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.