CICS resources for Web services IBM-CICS

We now look in more detail at what CICS resources a systems programmer must implement in order to enable Web services in a CICS environment.

1. URIMAP

The URIMAP resource definition defines one of three different Web-related facilities in CICS. It is the value of the USAGE attribute on a URIMAP definition that determines which of the three facilities that particular definition controls.

  1. Requests from a Web client to CICS as an HTTP server URIMAP definitions for requests for CICS as an HTTP server have a USAGE attribute of SERVER. These URIMAP definitions match the URLs of HTTP requests that CICS expects to receive from a Web client, and they define how CICS should provide a response to each request. You can use a URIMAP definition to tell CICS to do the following:
    • Provide a static response to the HTTP request, using a document template or z/OS UNIX® System Services HFS file
    • Provide a dynamic response to the HTTP request, using an application program that issues EXEC CICS WEB application programming interface commands
    • Redirect the request to another server, either temporarily or permanently
  2. For CICS as an HTTP server, URIMAP definitions incorporate most of the functions that were previously provided by the analyzer program specified on the TCPIPSERVICE definition. An analyzer program may still be involved if the processing path is required.
  3. Requests to a server from CICS as an HTTP client
    URIMAP definitions for requests from CICS as an HTTP client have a USAGE attribute of CLIENT. These URIMAP definitions specify URLs that are used when a user application, acting as a Web client, makes a request through CICS Web support to an HTTP server. Setting up a URIMAP definition for this purpose means that you can avoid identifying the URL in your application program.
  4. Web service requests URIMAP definitions for Web service requests have a USAGE attribute of PIPELINE. These URIMAP definitions associate a URI for an inbound Web service request—a request by which a client invokes a Web service in CICS—with a PIPELINE or WEBSERVICE resource that specifies the processing to be performed.

You can use a URIMAP with a USAGE attribute of PIPELINE to specify the following:

  • The name of the transaction that CICS uses for running the pipeline alias transaction (the default is CPIH)
  • The user ID under which the pipeline alias transaction runs Figure illustrates the purpose of a URIMAP resource definition for Web service requests.

URIMAP relationships

URIMAP relationships

You can create URIMAP resource definitions in the following ways:

  • Use the CEDA transaction.
  • Use the DFHCSDUP batch utility.
  • Use CICSPlex SM Business Application Services.
  • Use the EXEC CICS CREATE URIMAP command.

When you install a PIPELINE resource, or when you issue a PERFORM PIPELINE SCAN command (using CEMT or the CICS system programming interface), CICS scans the directory specified in the PIPELINE’s WSDIR attribute (the pickup directory), and creates URIMAP and WEBSERVICE resources dynamically. For each Web service binding file in the directory, that is for each file with the wsbind suffix, CICS installs a WEBSERVICE and a URIMAP if one does not already exist. Existing resources are replaced if the information in the binding file is newer than the existing resources

2. PIPELINE

A PIPELINE resource definition provides information about the message handlers that will act on a service request and on the response. The information about the message handlers is supplied indirectly. The PIPELINE definition specifies the name of an HFS file, called the pipeline configuration file, which contains an XML description of the message handlers and their configuration.

The most important attributes of the PIPELINE definition are as follows:

WSDIR

The WSDIR attribute specifies the name of the Web service binding directory (also known as the pickup directory). The Web service binding directory contains Web service binding files that are associated with the PIPELINE, and that are to be installed automatically by the CICS scanning mechanism.

When the PIPELINE definition is installed, CICS scans the directory and automatically installs any Web service binding files it finds there.

If you specify a value for the WSDIR attribute, it must refer to a valid HFS directory to which the CICS region has at least read access. If this is not the case, any attempt to install the PIPELINE resource will fail.

If you do not specify a value for WSDIR, no automatic scan takes place on installation of the PIPELINE, and PERFORM PIPELINE SCAN commands will fail.

SHELF

The SHELF attribute specifies the name of an HFS directory where CICS will copy information about installed Web services. CICS regions into which the PIPELINE definition is installed must have full permission to the shelf directory: read, write, and the ability to create subdirectories.

A single shelf directory may be shared by multiple CICS regions and by multiple PIPELINE definitions. Within a shelf directory, each CICS region uses a separate subdirectory to keep its files separate from those of other CICS regions. Within each region’s directory, each PIPELINE uses a separate subdirectory.

After a CICS region performs a cold or initial start, it deletes its subdirectories from the shelf before trying to use the shelf.

CONFIGFILE

This attribute specifies the name of the PIPELINE configuration file.

The figure illustrates the purpose of the PIPELINE resource definition.

The PIPELINE resource relationships

The PIPELINE resource relationships

You can create PIPELINE resource definitions in the following ways:

  • Use the CEDA transaction
  • Use the DFHCSDUP batch utility
  • Use CICSPlex SM Business Application Services
  • Use the EXEC CICS CREATE PIPELINE command

Pipeline configuration file

When CICS processes a Web service request, it uses a pipeline of one or more message handlers to handle the request. The configuration of a pipeline used to handle a Web service request is specified in an XML document, which is known as a pipeline configuration file. Use a suitable XML editor or text editor to work with your pipeline configuration files. The exact configuration of the pipeline will depend upon the specific needs of the application.

There are two kinds of pipeline configuration files:

  • One describes the configuration of a service provider pipeline
  • The other describes the configuration of a service requester pipeline.

Each is defined by its own schema, and each has a different root element. The root element for a provider pipeline is, while the root element for a requester pipeline is .

The immediate child elements of the element are as follows:

  • A mandatory element, which specifies the message handlers that are invoked for every request, including the terminal message handler. The terminal message handler is the last handler in the pipeline.
  • An optional element, which specifies message handlers that are selected at run time based upon the resources that are being used for the message transport. For example, for the HTTP transport, you can specify that CICS should invoke the message handler only when the port on which the request was received is defined on a specific TCPIPSERVICE definition. For the WebSphere MQ transport, you can specify that CICS should invoke the message handler only when the inbound message arrives at a specific message queue.
  • An optional element, which specifies the name of the program that the terminal message handler will link to by default, that is, the name of the target application program (or wrapper program) that provides the service.

Message handlers can specify a different program at run time by using the DFHWS-APPHANDLER container, so the name coded here is not always the program to which it is linked.

  • An optional element, which specifies the name of the program that the terminal message handler will link to by default, that is, the name of the target application program (or wrapper program) that provides the service.

Message handlers can specify a different program at run time by using the DFHWS-APPHANDLER container, so the name coded here is not always the program to which it is linked.

The element is used when the last message handler in the pipeline (the terminal handler) is one of the CICS-supplied SOAP message handlers.

If you do not code an element, one of the message handlers must use the DFHWS-APPHANDLER container to specify the name of the program.

Important: When you use DFHLS2WS or DFHWS2LS to deploy your service provider, you must specify DFHPITP as the target program.

DFHPITP will get the name of your target application program (or wrapper program) from the wsbind file.

An optional element, which contains parameters that CICS makes available to the message handlers in the pipeline via container DFH-SERVICEPLIST.

Example shows the sample service provider pipeline configuration file basicsoap11provider.xml.

Pipeline configuration file

Following are the immediate sub-elements of a element:

  • An optional element, which specifies the message handlers that are invoked for every request
  • An optional element, which specifies message handlers that are selected at run time, based upon the resources that are being used for the message transport.
  • An optional element, which contains parameters that CICS makes available to the message handlers in the pipeline via container DFH-SERVICEPLIST.

Example shows the sample service requester pipeline configuration file basicsoap11requester.xml.

service requester pipeline configuration fileservice requester pipeline configuration file

3. WEBSERVICE

The following three objects define the execution environment that allows a CICS application program to operate as a Web service provider or a Web service requester:

  • The Web service description
  • The Web service binding file
  • The pipeline

The following three objects are defined to CICS on the following attributes of the WEBSERVICE resource definition:

  • WSDLFILE
  • WSBIND
  • PIPELINE

The WEBSERVICE definition has a fourth attribute, VALIDATION, which specifies whether full validation of SOAP messages against the corresponding schema in the Web service description should be performed at run time.

VALIDATION(YES) ensures that all SOAP messages that are sent and received are valid XML with respect to the XML schema.

If VALIDATION(NO) is specified, sufficient validation is performed to ensure that the message contains well-formed XML.

Important: Validation of a SOAP message against a schema incurs considerable processing overhead, and you should normally specify VALIDATION(NO) in a production environment.

Figure illustrates the purpose of the WEBSERVICE resource definition.

Webservice resource

Webservice resource

You can create WEBSERVICE resource definitions in the following ways:

  • Using the CEDA transaction
  • Using the DFHCSDUP batch utility
  • Using CICSPlex SM Business Application Services
  • Using the EXEC CICS CREATE WEBSERVICE command

When you install a PIPELINE resource or when you issue a PERFORM PIPELINE SCAN command (using CEMT or the CICS system programming interface), CICS scans the directory specified in the PIPELINE’s WSDIR attribute (the pickup directory) and creates URIMAP and WEBSERVICE resources dynamically. For each Web service binding file in the directory—each file with the wsbind suffix—CICS installs a WEBSERVICE and a URIMAP if one does not already exist. Existing resources are replaced if the information in the binding file is newer than the existing resources.

The CEMT INQUIRE WEBSERVICE command obtains information about a WEBSERVICE resource definition. The data returned depends on the type of Web service.

Web service binding file

A Web services description contains abstract representations of the input and output messages used by the service. When a service provider or service requester application executes, CICS needs information about how the content of the messages maps to the data structures used by the application. This information is held in a Web service binding file.

Web services binding files are created in the following manners:

  • By utility program DFHWS2LS when language structures are generated from WSDL
  • By utility program DFHLS2WS when WSDL is generated from a language structure

At run time, CICS uses information in the Web service binding file to perform the mapping between application data structures and SOAP messages.

The resources that are required to support a particular application program depend upon the following:

  • Whether the application program is a service provide or a service requester
  • Whether the application is deployed with the CICS Web services assistant, or you write your own code to map between your application data and SOAP messages

The table is a checklist of resource definitions.

Table Resource checklist

Table Resource checklist


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

IBM-CICS Topics