Configuration for Web service enablement IBM-CICS

This section outlines the steps to enable the CICS system for running Web service support. In a basic scenario, HTTP protocol is used as the transport mechanism, although Web service transports are not limited to HTTP. Other transports such as WMQ or JMS could equally be used as well.

The following steps outline how we set up our CICS system to expose our sample application as a Web service provider.

a. Creating the HFS directories

Web service support requires two HFS directories to be created for our application:

  1. A pickup directory
  2. This contains the Web service wsdl and binding files associated with a Web service. The files are suffixed by .wsdl and .wsbind. The directory is specified as the output location for the CICS Web Services Assistant and is associated with a PIPELINE resource definition.

    When a PIPELINE is installed or a CEMT PERFORM SCAN is done on the PIPELINE, this directory is scanned and information in the bindings file is used to dynamically create the WEBSERVICE and URIMAP definitions associated with the PIPELINE. As part of this process, CICS copies any .wsbind files from this directory into a folder in the shelf directory, which is given a name by CICS, unique to the region.

  3. A shelf directory
  4. The shelf directory stores the Web service bindings files that are associated with the CICS WEBSERVICE resources. Each of these WEBSERVICE resources is associated with a CICS PIPELINE and this directory is managed by the PIPELINE. Several PIPELINES can use the same shelf directory.

    The directories created for our CICSWSAP application are as follows:

b.Creating the CICS Resources

Using the steps in this section, create and install the following resources in CICS:

  1. Configuring the PIPELINE resource
  2. The two components of this definition are the PIPELINE resource itself and a configuration file. The file contains details about the message handlers that will act on Web service requests and responses as they pass though the pipeline. This should contain the message handler programs and the SOAP header processing programs that CICS will invoke when it processes the pipeline.

    We start by using the CICS-supplied SOAP 1.1 handler to manage the SOAP envelopes of inbound and outbound requests of our Web service sample. CICS provides sample pipeline configuration files that can be used in both the service provider and service requester scenarios.

    In our scenario, we only require one PIPELINE resource for inbound requests, using our CICS Web service modules in a service provider role. We copied the PIPELINE definition for inbound requests from the CICS supplied group DFH$EXWS. We then altered the definition to suit our environment as shown in Example.

    Following are the attributes that we changed:

    • Configfile specifies the HFS path where the message handler programs and header programs are located.
    • Shelf specifies the HFS directory where CICS will store the installed wsbind files.
    • Wsdir specifies the HFS pickup directory where the installable wsbind and WSDL files are located.
    • Example: Our PIPELINE provider definition

      Example: Our PIPELINE provider definition
  3. Creating a TCPIPSERVICE
  4. When a client connects to our Web service over an HTTP service, a TCPIPSERVICE resource is needed to receive the inbound HTTP traffic. We created a TCPIPSERVICE definition using CEDA, or you can use the sample definition in the CICS supplied group DFH$EXWS.

    Following are the attributes that we verified or changed from the sample:

    • GROup to specify our resource group PJA6ADTX
    • STatus should be Open
    • POrtnumber to specify an unused port on the CICS system
    • PROtocol should be the default HTTP
    • TRansaction should be the default CWXN
  5. Creating WEBSERVICE and URIMAP resources
  6. Each function that is exposed as a Web service requires a WEBSERVICE resource to map between the incoming XML of the soap body and the COMMAREA interface of the program, and a URIMAP resource that routes the incoming requests to the correct PIPELINE and WEBSERVICE. Although you can use RDO to define and install these resources, you can also have CICS create them dynamically when you install a PIPELINE resource.

    We chose CICS to dynamically create these resources, but before we install the PIPELINE, we need to have the wsbind and WSDL files available

c. Generating the WSBind and WSDL files

In our example, we generate the wsbind and WSDL for one of our business logic functions ITSOGH03. This program simply generates an address hash from an address string passed in a commarea and returns the value in the same commarea. The data structure that maps the commarea is called ITSOGHCA. It is a simple function and can be transformed into a Web service.

The Web Services Assistant easily creates the files needed for the Web service runtime. We customized the supplied job DFHLS2WS, which takes a language structure as input and generates a WSDL file and a WSBIND file.

Following are the steps we took:

  1. Create an HFS directory in which to store the generated files—this was already done in a previous step and the name is as follows:
  2. Submit the DFHLS2WS job. The job that we ran to generate these files is shown in Example.

Example :The sample job DFHLS2WS

Example :The sample job DFHLS2WS

The input to the job includes the following:

PDSLIB - the name of the library that contains the high-level language structures that the application uses to describe the Web service request and the Web service response. In our example, as the structure is a C/370™ data structure, this is the PDS containing the INCLUDEs (rather than copy books for COBOL).

PGMNAME - the name of the program containing the business logic. LANG - the language of the program.

REQMEM and RESPMEM - the names of the INCLUDE members for data mapping of the request and response.

PGMINT - the type of program input—the method that CICS uses to pass data to the application (COMMAREA or container).

LOGFILE, WSBIND, and WSDL - the full path names of the files to be generated in the HFS.

URI - the relative HFS address that the client uses to access the Web service. The generated files are written to the pickup directory in the HFS as specified in the DFHLS2WS JCL.

d. Installing the PIPELINE resource definitions

When the PIPELINE definition is installed, CICS scans the pickup directory for wsbind files. When CICS finds the wsbind file, it dynamically creates and installs a WEBSERVICE resource definition for it. The name of the WEBSERVICE is derived from the name of the wsbind file.

Then, during the installation of the WEBSERVICE resource, CICS dynamically creates and installs a URIMAP definition, based on the URI specified in the input to DFHLS2WS.

  1. We installed the PIPELINE definition using CEDA:


  2. To check that the install of the WEBSERVICE and URIMAP were successful, display the WEBSERVICE using CEMT:


    Example shows our new WEBSERVICE resource, named to match the wsbind file in the pickup directory—in our case GetHash.

Example : The GetHash WEBSERVICE resource

Example : The GetHash WEBSERVICE resource

Similarly, the URIMAP resource can be viewed using the URI token from the WEBSERVICE definition as in Example:


Example : The URIMAP definition

Example : The URIMAP definition

e. Performing a scan on the PIPELINE

The PERFORM PIPELINE command initiates a scan of the Web service binding directory that is specified in the WSBIND attribute of the PIPELINE definition. CICS examines the Web service binding files in the directory to determine if they should be installed into the system:

  • CICS installs any files it finds that were not installed already.
  • If a file was installed already, but the file in the directory is newer than the one currently in use, then the one that is in use is discarded and the newer file is installed in its place.

Following is the command to perform the scan:


When we created wsbind and WSDL files for further Web services in our example, we used the same PIPELINE (by re-running the DFHLS2WS job). A PIPELINE SCAN was all that was needed to create the WEBSERVICE and URIMAP resources.

f. Verifying the HFS structure just created

We used WD/z to verify the structures created by CICS and the Web Services Assistant DFHLS2WS. This can also be done via UNIX System Services on the host, although the Remote Systems view gives a clearer picture of the files we created from the previous steps. This is shown in Figure.

WD/z Remote System view of our Web service HFS structure

WD/z Remote System view of our Web service HFS structure

From the view in Figure, there are a few points to note:

  • The DFHLS2WS job generated all the files in the pickup directory:


  • CICS generated all the directories and files in the shelf directory as a result of the PERFORM PIPELINE(WSPIPE01) SCAN :


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd Protection Status