Tutorial: CICS Web Service Provider, JSON Request-Response 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 JSON requester tool.

Create the LoanJSON 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 LoanJSON.
  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 LoanJSON project directory you created.
  3. From the Enterprise Developer for Visual Studio 2017 main menu, click File > Open > Project/Solution.
  4. Browse to the new LoanJSON project directory, and select the CWSProject.cblproj project file; 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.

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

Create a Service Interface

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

  1. From the Solution Explorer in Visual Studio, right-click the LoanJSON 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, select Web Service from the Type of interface drop-down list.
  6. Check CWS-Type.
  7. Under Transport Type, click JSON.

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

  8. 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, select 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 LoanJSON project's root directory, but the output path is set to the project's loadlib directory, you need to move the file from the LoanJSON root directory to the project's loadlib directory:

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

Build the LoanJSON project

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

Configure the enterprise server region

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

Do one of the following:

  • If you did not complete Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, skip the instructions in this section, go back to Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, and complete the sections titled Create an enterprise server region and Configure CWSJSON resources. However, when selecting a project with which to associate the new region, check the LoanJSON project instead of the ReverseJSON project.
  • If you created and configured CWSJSON while completing Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, follow the steps in this section to update the dfhdrdat file and properly associate CWSJSON with the LoanJSON 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 LoanJSON project with this information, you can copy the file from the ReverseJSON project to the LoanJSON project:
  • Using Windows Explorer or at a command prompt, copy the dfhdrdat file located in the ReverseJSON project's system directory to the LoanJSON project's system directory, overwriting the existing file.
Associate the LoanJSON 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 ReverseJSON project, you need to change the association to the LoanJSON project.
  1. On the Server Explorer, right-click CWSJSON; then select Associate with project.
    Note: If a check mark shows next to ReverseJSON, click ReverseJSON to remove the association; then repeat this step and continue with step 2.
  2. Click LoanJSON to create an association.
  3. If you are prompted to restart the server, answer Yes; if you are not prompted, right-click CWSJSON and select Start from the context menu.

Verify Resources

After CWSJSON 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 CWSJSONenterprise 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 CWSJSON 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 is determined by the information stored in your project.

  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to JSONPIPE. The Pipeline resource sets the response wait period, identifies the JSON 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 JSON 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 JSON request to run the Web service. You can do this using any json requester tool.

  1. Create a JSON POST request that contains the following: 
    {
 "LOANPAYM" :
 {
  "LOANINP" :
  {
   "principal" : "50000",
   "loanterm" : "180",
   "rate" : "5.56"
  }
 }
}
  2. Submit the JSON request to the following endpoint URL:

    http://localhost:5639/cics/services/LOANPAYM

    You should receive the following JSON response: 

    {"LOANPAYMResponse": {"LOANOUT": {"monthlyPayment": "$410.13"}}}
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables