Generating and deploying a web service on CICS

This topic describes how to generate and deploy a web service on z/OS® CICS®. Aside from setting up the relevant EGL build parts, you must set the following CICS definitions: TRANSACTION, TCPIPSERVICE, and PIPELINE.

For details about requirements for EGL or web services on z/OS CICS, see “Special considerations for generating EGL or web services in z/OS CICS environments.”

Follow these steps to generate and deploy a web service to z/OS CICS:

1. Create an EGL Service part.
2. In an EGL deployment descriptor, add a sharable protocol of the type CICSWS. For keystroke details, see “Creating and using a sharable protocol.”
3. Set the following attributes in the sharable protocol:

   transaction

   The name of a transaction for the web service to run under, with a minimum Transaction Work Area (TWA) of 1024 bytes. You will create this transaction later by copying the CPIH transaction and setting its TWA to 1024 bytes.

   userID

   The user ID the web service will run under (optional).

4. On the Web Service Deployment page of the EGL Deployment Descriptor editor, add the Service part to generate it as a web service. For keystroke details, see “Adding web service deployment information to the deployment descriptor.”
5. Set the Protocol field in the deployment descriptor to the CICSWS sharable protocol.
6. Set the URI field in the deployment descriptor to the relative path to which you want to deploy the service. The default is /services/ServicePartName, where ServicePartName is the name of the Service part.
7. In the project's build descriptor, set the following build descriptor options:

   deploymentDescriptor

   The name of the EGL deployment descriptor to which you added the sharable protocol and the Service part.

   destDirectory

   The root HFS directory containing folders that will receive the generated web services binding file and WSDL file. An example destDirectory value is /u/username/clients. CICS must have permission to read and write to this directory.

   The web services binding file is necessary to convert SOAP messages to COBOL at run time.

   destHost

   Specify the name or numeric TCP/IP address of the target system where the build server resides.

   destPassword

   Specifies the password that EGL uses to log on to the remote build server where your output will be prepared for deployment.

   destPort

   Specify the port on which a remote build server is listening for build requests.

   destUserID

   Specifies the user ID that EGL uses to log on to the remote build server where preparation occurs.

   genDirectory

   Specifies the fully qualified path of the directory into which EGL places generated output, control files, and results files.

   prep

   Set prep to YES.

   serverType

   Set serverType to CICS3.1.

   system

   Set system to ZOSCICS.

8. Generate both the Service part. You can generate or deploy the deployment descriptor, as described in “Introduction to EGL generation and deployment.”
9. On the CICS system, define a web service TRANSACTION with the name you specified in the CICSWS sharable protocol:
   1. Make a copy of the CPIH transaction with a command like the following:

      CEDA COPY TRANSACTION(CPIH) GROUP(DFHPIPE) AS(newName) TO(group)

      Use the name of the transaction for newName and the name of the group for group.
   2. Edit the copy of the transaction and set the TWA size to 1024 bytes.
10. Define a TCPIPSERVICE:
    1. Create a new TCPIPSERVICE with a command like the following:

       CEDA DEF TCPIPSERVICE(name) GROUP(group)

       Use the name of the new TCPIPSERVICE for name and the name of the group for group.
    2. Set the Portnumber field to a number between 2001 and 65535.
11. Define a web service PIPELINE:
    1. If you need to create a new PIPELINE for services, use the following command:

       CEDA DEF PIPELINE(name) GROUP(group)

       Use the name of the new PIPELINE for name and the name of the group for group.
    2. Set the Configfile field to /u/cicsts31/pipelines/basicsoap11provider.xml.
    3. Set the Shelf field to destDirectory/provider/shelf, where destDirectory is the value you used for the destDirectory build descriptor option.
    4. Set the Wsdir field to destDirectory/provider, where destDirectory is the value you used for the destDirectory build descriptor option.
12. Install the group with the following command:

    CEDA INSTALL GROUP(group)

    Use the name of the group for group.