Tutorial: CICS Web Service Provider from JSON, Request-Response Bottom-up Method

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

To complete the Test the loanPaym Web service provider section of this tutorial, we recommend that you install a JSON requester tool.

Import the LoanDemoJSON project

1. In Eclipse, start the Team Developer Application Explorer.
2. From the main menu, click File > Import.
3. Expand General, and select Existing Projects into Workspace; then click Next.
4. Select Set root directory, then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Provider\BottomUp directory; then click OK.
5. On the Projects list, ensure that LoanDemoJSON is checked.
6. Under Options, check Copy projects into workspace; then click Finish.

   The Application Explorer now shows the LoanDemoJSON project, which is created in a LoanDemoJSON subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service provider components

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

1. From the Application Explorer, click the LoanDemoJSON 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:

   1. Select Other.
   2. Expand Micro Focus Service Interface.
   3. Select CICS Web Service; then click Next.
3. Under Service type, select JSON message processing.
4. From the drop-down list, select CICS Web Service Provider (Bottom-Up, Request-Response); then click Next.

   The Project field is already populated with the name of the current project, LoanDemoJSON.

5. Click the Browse button that corresponds to the Program location field.
6. Navigate to and select the loanPaym.cbl file, located in the LoanDemoJSON folder; then click OK.
7. In the Service location field, type /cics/services/json/loanpaym.
8. Select COMMAREA from the Program interface drop-down list; then click Next.

   In the Mapping group, you specify the copybooks that contain request and response data structures.

9. Click the Browse button that corresponds to the Request structure field.
10. Navigate to and select the LOANINP.cpy file, located in the LoanDemoJSON folder; then click OK.
11. Similarly, find and select the LOANOUT.cpy file to populate the Response structure field.

    In the Output artifacts group, you specify names and locations for request and response schema files and the location for the WSBIND file.

12. Click the Browse button that corresponds to the JSON request field.
13. Navigate to your project directory.
14. Click Make New Folder.
15. Name the new folder schema; then press Enter.
16. Double-click the schema folder to select it.
17. In the File name field, type loanDemoReq; then click Open.
18. Click the Browse button that corresponds to the JSON response field.
19. Navigate to the new schema folder.
20. In the File name field, type loanDemoResp; then click Open.
21. Click the Browse button that corresponds to the WSBIND file field.
22. On the Browse for WSBIND file dialog box, open the loadlib folder.
23. In the File name field, type loanPaym; then click Open.
24. Click Finish.

Configure the enterprise server region

This tutorial uses the JSONPROV 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 JSONPROV resources. However, when selecting a project with which to associate the new region, check the LoanDemoJSON project instead of the ReverseJSON project.
• If you created and configured JSONPROV 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 JSONPROV 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 LoanDemoJSON project with this information, you can copy the file from the ReverseJSON project to the LoanDemoJSON project:

• Using Windows Explorer or at a command prompt, copy the dfhdrdat file located in the ReverseJSON project's system directory to the LoanDemoJSON project's system directory, overwriting the existing file.

Associate the LoanDemoJSON 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 LoanDemoJSON project.

1. On the Server Explorer, right-click JSONPROV; 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 LoanDemoJSON to create an association.
3. If you are prompted to restart the server, answer Yes; if you are not prompted, right-click JSONPROV and select Start from the context menu.

Verify Resources

After JSONPROV 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 JSONPROV 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 JSONPROV 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/json/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" : "5000",
      "loanterm" : "36",
      "rate" : "5.5"
     }
    }
   }

2. Submit the JSON request to the following endpoint URL:

   http://localhost:5482/cics/services/json/loanPaym

   You should receive the following JSON response:

   {"loanPaymResponse": {"LOANOUT": {"monthlyPayment": "$150.97"}}}