Creating the CICS infrastructure for a SOAP service requester

To create the CICS® infrastructure for a SOAP service requester, you must create a pipeline configuration file and create a number of CICS resources.

Before you begin

If you want to use a Java pipeline, ensure that a JVMSERVER resource exists with the JAVA_PIPELINE=YES option specified in the JVM Profile. See JVMSERVER resources.

A JVM server can handle SOAP processing for many Java pipelines.

About this task

You can define the PIPELINE resource in a local CICS region using CICS or CICSPlex® SM functions, or you can use the CICS Explorer® to define the PIPELINE resource either in a local CICS region or in a CICS bundle. When you use the CICS Explorer to define a PIPELINE resource in a CICS bundle, you also create the pipeline configuration file and package it in the CICS bundle, so you do not have to manage this file separately. PROGRAM, WEBSERVICE and URIMAP resources can also be defined in CICS bundles. When you define a WEBSERVICE resource in a CICS bundle, you can import a web service binding file and a WSDL document or WSDL archive file and package these in the bundle, and for a service provider you can choose to include a PROGRAM definition. You can also create URIMAP definitions to support the web service and package these in a bundle. For more help with using the CICS Explorer to create and edit resources in CICS bundles, see Working with bundles in the CICS Explorer product documentation.

Procedure

  1. Define the message handlers and header processing programs that you want to include in the pipeline configuration file to process inbound web service requests, and their responses.
    CICS provides the following handlers and header processing programs:
    1. SOAP message handlers, to process SOAP 1.1 or 1.2 messages.
      You can only support one level of SOAP in a service requester pipeline.
    2. MTOM handler, to process MIME Multipart/Related messages that conform to the MTOM/XOP specifications.
    3. Security handler, to process secure web service messages.
    4. WS-AT header processing program, to process atomic transaction messages.
  2. Optional: If you want to perform your own processing in the pipeline, you must create a message handler or header processing program. See Message handlers for details. If you decide to create custom message handler programs, to optimize performance you must make them threadsafe.
  3. Create an XML pipeline configuration file containing your message handlers and header processing programs.
    CICS provides two basic requester mode pipeline configuration file samples, basicsoap11requester.xml and basicsoap11javarequester.xml, which you can copy and edit as appropriate. These samples are provided in the library /usr/lpp/cicsts/cicsts54/samples/pipelines (where /usr/lpp/cicsts/cicsts54 is the default install directory for CICS files on z/OS UNIX). For more information about options available in the pipeline configuration file, see Pipeline configuration files
  4. Copy the pipeline configuration file to a suitable directory in z/OS® UNIX.
  5. Change the pipeline configuration file permissions to allow the CICS region to read the file.
  6. Repeat steps 3 to 5 for each different pipeline configuration that you require.
  7. Create a PIPELINE resource. See PIPELINE resources.
    The PIPELINE resource defines the location of the pipeline configuration file. It also specifies a pickup directory, which is the z/OS UNIX directory that contains the web service binding files and optionally the WSDL. You can also specify a timeout in seconds, which determines how long CICS waits for a response from web service providers. Repeat this step for each pipeline configuration file.
    When you create a PIPELINE resource, CICS reads any files in the specified pickup directory and creates the WEBSERVICE resources dynamically (see WEBSERVICE resources).
  8. Unless you use autoinstall PROGRAM definitions, create a PROGRAM resource for each program that runs in the pipeline. See PROGRAM resources.
    These programs include the service requester application program, which normally runs under transaction CPIH. The transaction is defined with the attribute TASKDATALOC(ANY). Therefore, when you link edit the program, you must specify the AMODE(31) option.
  9. Optional: Create a URIMAP resource (see URIMAP resources) for client requests to each URI that your service requesters use to make requests, following the instructions in Creating a URIMAP resource for CICS as a HTTP client.
    You can specify the URI directly on the INVOKE SERVICE command in your programs, instead of using a URIMAP resource. However, using a URIMAP resource means that you do not need to recompile your applications if the URI of a service provider changes. With a URIMAP resource you can also choose to implement connection pooling, where CICS keeps the client connection open after use, so that it can be reused by the application for subsequent requests, or by another application that calls the same service.

    CICS attempts to locate a matching client URIMAP if one was not specified on the INVOKE SERVICE command. CICS searches for a matching URIMAP based on the host, port and path of the current request. This allows system programmers to add capabilities from a URIMAP such as using specific certificates and ciphers without the need to update application code.

Results

Your CICS system now contains the infrastructure needed for each service requester.

What to do next

You can extend the configuration when you need to do so, to create additional pipelines.