Tutorial: CICS Web Service Provider, Bottom-up Method

Prerequisites

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 Provider (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, Top-down Method to run the Web service provider.

Do one of the following:

• If you did not complete Tutorial: CICS Web Service Provider, Top-down Method, skip the instructions in this section, go back to Tutorial: CICS Web Service Provider, 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, Top-down Method, follow the steps in this section to properly associate it 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.
2. Click Reverse to remove the association.
3. Repeat step 1.
4. Click LoanDemo to create an association.
5. 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 Store Credentials is not checked, check it. Checking Store Credentials prevents this dialog box from showing by default when you subsequently start an enterprise server region. Then click OK. If a Secure Storage prompt appears, click No.

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

Start 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 ENABLED.
3. Click the Details button that corresponds to the LOANPAYM Web service.

   Notice the values for WSBIND and Endpoint. These are 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>