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

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 install a SOAP requester tool.

Create the LoanDemo project

Use the CWSProject demonstration project to create a Visual Studio project for your CICS Web service.

  1. Using Windows Explorer or at a command prompt, create a project directory named LoanDemo.
  2. Extract the CICSWebServicesTemplate_VS.zip file, located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS directory by default, to the new LoanDemo project directory.
  3. From the Enterprise Developerfor Visual Studio 2013 main menu, click File > Open > Project/Solution.
  4. Browse to the new LoanDemo project directory, and select the CWSProject.cblproj project file. This starts the Solution Explorer.

    Here, you rename the project to match the name of the service interface you are going to create. This is not mandatory in general, but done here to differentiate between tutorial projects.

  5. In the Solution Explorer, right-click the CWSProject project; then select Rename.
  6. Type LoanDemo; then press Enter.

Create a Service Interface

Map the input and output data areas of the LOANPAYM program.

  1. From the Solution Explorer, right-click the LoanDEMO project; then click Add > New Item.
  2. In the left pane, expand COBOL > Native; then click Mainframe Subsystem.
  3. In the center pane, click Service Interface.
  4. In the Name field, type LOANPAYM; then click Add.
  5. On the Service Interface dialog box, check CWS-Type.

    The LOANPAYM program contains a Commarea interface; therefore, you can accept the default setting in the Type of source field.

  6. Click OK.

    Enterprise Developer creates the service interface and loads it into the Interface Mapper.

Define a Service Interface

  1. With the Interface Mapper in focus, click Operation > New from the Enterprise Developer main menu.
  2. In the Operation Name field, type LoanOperation.
  3. In the Select program/copybook box, select LOANPAYM.
  4. In the Select input data area box, click LOANPAYM(2).
  5. In the Select output data area box, select LOANPAYM(3).
  6. CICS Web Services always use default mappings; therefore, be sure that both Create Default Mappings check boxes are checked (default).
  7. Click OK to create the LoanOperation operation.
  8. Click File > Save LOANPAYM.svi to save the completed operation.

Generate and move the LOANPAYM.wsbind file

  1. From the Solution Explorer, right-click LOANPAYM.svi; then select Generate WSBIND.

    Because the LOANPAYM.wsbind file is generated in the LoanDemo project's root directory, but the output path is set to the project's loadlib directory, you need to move the file from the LoanDemo root directory to the project's loadlib directory:

  2. Using Windows Explorer or at a command prompt, change to the LoanDemo project directory.
  3. Copy or move LOANPAYM.wsbind from the LoanDemo directory to the LoanDemo\loadlib directory.

Build the LoanDemo project

  • From the Solution Explorer, right-click the LoanDemo project; then select Build.

Configure the enterprise server region

This tutorial uses the CWSDEMO 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 CWSDEMO 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 CWSDEMO 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 CWSDEMO 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:
  • Using Windows Explorer or at a command prompt, copy the dfhdrdat file located in the Reverse project's system directory to the LoanDemo project's system directory, overwriting 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 CWSDEMO; 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 CWSDEMO and select Start from the context menu.

Verify Resources

After CWSDEMO 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 Micro Focus Servers; then select Administration.
    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 CWSDEMO 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 CWSDEMO 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.

  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