Tutorial: CICS Web Service Provider, SOAP Bottom-up Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the bottom-up method to expose an existing CICS COBOL application, LOANPAYM, as a Web service. The LOANPAYM application accepts a principal amount, a loan term, and a rate as input values; then returns the calculated monthly loan payment.

Prerequisites

To complete this tutorial, you must first install the IBM CCSID Conversion Tables and configure accordingly. See CCSID Conversion Tables for more information.

To complete the Test the LOANPAYM Web service provider section of this tutorial, we recommend that you download and install the SOAPui Eclipse plugin, available from sourceforge.net.

This tutorial assumes that your Eclipse project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Create the LoanDemo project

Use the CICSWebServicesTemplate template project to create an Eclipse project for your CICS Web service.

  1. From the Enterprise Developer main menu, click File > New > Mainframe COBOL Project.
  2. In the Project name field, type LoanDemo.
  3. Check Browse for template.
  4. Click the Browse button that corresponds to the Location field, and browse to and select the CICSWebServicesTemplate template project folder; then click OK.
  5. Check Use default location; then click Finish.

    The COBOL Explorer now shows the LoanDemo project, which is built automatically by Eclipse.

Generate WSDL and WSBIND files

Use the New CICS Web Service wizard to generate the components of your Web service.

  1. From the COBOL Explorer, click the LoanDemo project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed, select Other; then locate and select CICS Web Service.
  3. From the Service type drop-down list, select CICS Web Service (Bottom-Up); then click Next.

    The Project field should already show the LoanDemo project name.

  4. Click the Browse button that corresponds to the Program location field, and navigate to the LOANPAYM.cbl file located in the cbl project folder.
  5. Double-click LOANPAYM.cbl. This populates the Program location field, and populates the Program name field with the name defined in the program.
  6. In the Service location field, type:

    http://localhost:5482/cics/services/loanpaym

    This is the endpoint URL that you use to invoke the Web service. It specifies the server, port, and a URI used to identify the Web service in Enterprise Server.

    The LOANPAYM program contains a COMMAREA interface; therefore, you can accept the default setting in the Program Interface field.

  7. Click Next.

    By default, the wizard assigns an operation name that consists of the program name followed immediately by Operation.

    The request and response structures for your Web service are contained in the LoanDemo project's two copybooks.

  8. Click the Browse button that corresponds to the Request structures field, and browse to the cpy project folder.
  9. Select LOANINP; then click OK.
  10. Repeat the process in the previous two steps to add the LOANOUT copybook to the Response structures field.
  11. Click Finish.

In your LoanDemo project, you should now see an entry for Web Services > LOANPAYM > LOANPAYMOperation.

The loadlib project folder should now contain the following generated files:

LOANPAYM.wsbind
A bind file that maps the SOAP request to the data structure in LOANIN.cpy, and maps the data structure in LOANOUT.cpy to the SOAP response message.
LOANPAYM.wsdl
The Web service definition file that describes the LOANPAYM application.

Configure the enterprise server region

This tutorial uses the CWSPROV enterprise server region created in Tutorial: CICS Web Service Provider, SOAP Top-down Method to run the Web service provider.

Do one of the following:

  • If you did not complete Tutorial: CICS Web Service Provider, SOAP Top-down Method, skip the instructions in this section, go back to Tutorial: CICS Web Service Provider, SOAP Top-down Method, and complete the sections titled Create an enterprise server region and Configure CWSPROV resources. However, when selecting a project with which to associate the new region, check the LoanDemo project instead of the Reverse project.
  • If you created and configured CWSPROV while completing Tutorial: CICS Web Service Provider, SOAP Top-down Method, follow the steps in this section to update the dfhdrdat file and properly associate CWSPROV with the LoanDemo project.
Update the dfhdrdat file
When you create an enterprise server region from the Enterprise Developer Server Explorer, it stores some configuration information in the project's system\dfhdrdat file. Therefore, to update the LoanDemo project with this information, you can copy the file from the Reverse project to the LoanDemo project:
  1. On COBOL Explorer, expand the Reverse project and locate the system\dfhdrdat file.
  2. Right-click dfhrdat; then select Copy.
  3. Expand the LoanDemo project and locate its system\dfhdrdat file.
  4. Right-click dfhrdat; then select Paste.
  5. Answer Yes to the prompt to overwrite the existing file.
Associate the LoanDemo project
In previous tutorials, you have associated your project with an enterprise server region as part of the steps to create the region. Because the region you are using here was previously associated with the Reverse project, you need to change the association to the LoanDemo project.
  1. On the Server Explorer, right-click CWSPROV; then select Associate with project.
    Note: If a check mark shows next to Reverse, click Reverse to remove the association; then repeat this step and continue with step 2.
  2. Click LoanDemo to create an association.
  3. If you are prompted to restart the server, answer Yes; if you are not prompted, right-click CWSPROV and select Start from the context menu.

Verify Resources

After CWSPROV is started, you can verify that the resources you have defined are installed and active.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box. If a Secure Storage prompt appears, click No.

    On the Home page, you should see the CWSPROV enterprise server region listed.

Start ES Monitor and Control (ESMAC)
  1. On the Enterprise Server Administration Home page, click the Details button located in the Status column for the CWSPROV region.
  2. On the Server > Control page, click ES Monitor & Control. This starts the ESMAC utility where you can view the defined resources.
View defined resources
  1. On the ESMAC menu, select Active from the drop-down list located under Resources.
  2. Click the WebSvc button. You should see the LOANPAYM Web service listed and marked as INSERVICE.
  3. Click the Details button that corresponds to the LOANPAYM Web service.

    Notice the value for WSBIND. This value is determined by the information stored in your project.

  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to PROVPIPE. The Pipeline resource sets the response wait period, identifies the SOAP configuration file, and the Web Service directory.
  5. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cics/services/loanpaym.

    Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins with a pounds-sterling symbol (£).

    To run your provider CICS Web service, you send a SOAP request to an endpoint URL that routes the request to your enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose Path value matches the URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name of the Web Service and its associated Pipeline, to process the request.

Test the LOANPAYM Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a SOAP request to run the Web service. You can do this using any SOAP requester tool such as the SOAPui Eclipse plug-in.

  1. Create a SOAP request that contains the following: 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:loan="http://tempuri.org/LOANPAYM">
   <soapenv:Header/>
   <soapenv:Body>
      <loan:LOANPAYMOperation>
         <loan:LOANINP>
            <loan:principal>50000</loan:principal>
            <loan:loanterm>180</loan:loanterm>
            <loan:rate>5.56</loan:rate>
         </loan:LOANINP>
      </loan:LOANPAYMOperation>
   </soapenv:Body>
</soapenv:Envelope>
  2. Submit the SOAP request to the following endpoint URL:

    http://localhost:5482/cics/services/LOANPAYM

    You should receive the following SOAP response: 

    <SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:loan="http://tempuri.org/LOANPAYM" 
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <LOANPAYMOperationResponse xmlns="http://www.LOANPAYM.com">
         <LOANOUT>
            <monthlyPayment>$410.13</monthlyPayment>
         </LOANOUT>
      </LOANPAYMOperationResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables