Tutorial: CICS Web Service Provider, Bottom-up Method

Prerequisite

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 for the LoanDemo project.
2. Extract the CICSWebServicesTemplate_VS.zip file to the new project directory.
   Important: If you do not have the CICSWebServicesTemplate_VS.zip file, contact Micro Focus SupportLine.
3. In Enterprise Developer, open the CWSProject solution.
4. From the main menu, click File > Open > Project/Solution.
5. Browse to the new project directory, and select the CWSProject.cblproj project file.
6. Click the Add to Solution option; then click Open. 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.

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

Generate WSDL and WSBIND files

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

1. From the Solution Explorer, right-click the LOANPAYM.cbl file; then select Compile from the context menu.
2. Click Next.
3. In the Program Name field, type LOANPAYM, which is the name defined in the program.
4. 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.

5. 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.

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

The LOANPAYM 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.

Move the LOANPAYM.wsbind file

Because the LOANPAYM.wsbind file is generated to the LOANPAYM folder, but the output path is set to the loadlib folder, you need to move the file from LOANPAYM to loadlib:

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

Add loadlib to the project

Now that you have a generated file, LOANPAYM.wsbind, in the loadlib directory, you can add it to the project:

1. In the Solution Explorer, right-click the InvokeReverse project; then select Add > Existing item.
2. From the drop-down list that corresponds to the File name field, select All Files (*.*).
3. Browse to the loadlib directory.
4. Double-click LOANPAYM.wsbind.

Exclude a file

In the LoanDemo project, a second copy of LOANPAYM.cbl is located in the LOANPAYM folder. You want to ensure that this file is not picked up by the service:

• In the LOANPAYM folder, right-click LOANPAYM.cbl; then select Exclude From Project.

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 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:

• 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 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 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 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.

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>