Tutorial: CICS Web Service Requester from JSON, Linkable Interface Top-down Method

In this tutorial, you use the top-down method to create a Web service requester that runs the provider Web service you created in the previous tutorial.

Prerequisites

Before attempting to complete this tutorial, you must first complete Tutorial: CICS Web Service Provider from JSON, Request-Response Top-down Method. This is required because the requester generated in this tutorial runs the provider Web service you created in the previous tutorial and that runs on the CWSJSON enterprise server region.

The Test the invkRevJCICSClientApp Web service requester section of this tutorial requires that you have access to a TN3270 emulator such as Rumba.

Note: CCSID conversion tables must also be installed before running this tutorial, but as these are also required to run the prerequisite Tutorial: CICS Web Service Provider, JSON Request-Response Method, they should already be installed.

Generate CICS Web Service requester components

Use the Generate Web Service dialog box to generate the components of your Web service requester.

  1. From the Solution Explorer, expand the ReverseJSON project's json folder; then Ctrl-click both the reverseReq.json and reverseResp.json files.
  2. Right-click the selected .json files; then select Generate Web Service from the context menu.
  3. In the Generate Web Service dialog box, ensure that reverseReq.json populates the (for request) field, and reverseResp.json populates the (for response) field.
  4. In the Generate group, select the Client radio button.
  5. In the Program group, check CICS.
  6. In the Program group's Name field, type invkRevJ, which is the name for the generated COBOL skeleton program.
  7. Click OK.

Enterprise Developer generates a new project named invkRevJCICSClientApp. It contains:

invkRevJ.cbl
A skeleton CICS program.
InvkRevJInBundle
A folder that contains generated input files.
jsbinds/invkRevI.json
A JSBIND file for converting between input JSON messages and COBOL data structures.
jsbinds/reverseReq.json
A copy of the input JSON that corresponds to the invkRevJ.cbl program.
META-INF/cics.xml
A reference file used by Enterprise Server to establish the structure of the input bundle directory.
InvkRevJOutBundle
A folder that contains generated output files.
jsbinds/invkRevO.json
A JSBIND file for converting between output JSON messages and COBOL data structures.
jsbinds/reverseResp.json
A copy of the output JSON that corresponds to the invkRevJ.cbl program.
META-INF/cics.xml
A reference file used by Enterprise Server to establish the structure of the output bundle directory.

Implement the service

The generated invkRevJ.cbl program should provide the functionality that is required to invoke the reverse service. Any JSON application that uses a linkable interface, including invkRevJ.cbl, is required to do the following:

  • Populate the request structure.
  • PUT that data into a CONTAINER named DFHJSON-DATA.
  • PUT the name of the JSONTRANSFRM resource used to transform the COBOL request data to JSON into a CONTAINER named DFHJSON-TRANSFRM.
  • LINK to DFHJSON, which includes:
    • Locating the appropriate JSBIND file by using the JSONTRANSFRM resource named in the DFHJSON-TRANSFRM CONTAINER.
    • Transforming the content of the DFHJSON-DATA CONTAINER into JSON using the JSBIND file and placing it into the DFHJSON-JSON CONTAINER.
  • SEND the request and RECEIVE the response, which includes:
    • Using WEB OPEN to open a connection to the server hosting the service.
    • Using WEB CONVERSE to SEND the request to the server and RECEIVE the response. This is done by supplying the request message via the DFHJSON CONTAINER and receiving the response message into the same CONTAINER.
    • Using WEB CLOSE to close the connection to the server.
  • PUT the name of the JSONTRANSFRM resource used to transform the JSON response message to COBOL into a CONTAINER named DFHJSON-TRANSFRM.
  • LINK to DFHJSON, which repeats the same procedure as before.
  • Populates the response structure by GETting the content of the DFHJSON-DATA CONTAINER.

To provide the program with an input and direct the output to your terminal, you must edit the code.

  1. From the Solution Explorer, double-click invkRevJ.cbl to open it in the COBOL editor.
  2. In the PROCEDURE DIVISION, WS-OP-1 section, add the following MOVE statements before the EXEC CICS PUT CONTAINER statement: 
    move 'esaelPeMesreveR'      to myString
  3. After the EXEC CICS GET CONTAINER command for DFHJSON-DATA, add the following code to send the reversed string back to the terminal: 
     exec cics send text
      from(reversedString)
      freekb
 end-exec
  4. Save the program and exit the editor.

Build the invkRevJCICSClientApp project

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

Move the invkRevJ.dll file

Because the invkRevJ.dll file is generated to the ReverseJSON project's invkRevJCICSClientApp\bin\x86\Debug directory, but the output path is set to the ReverseJSON project's loadlib directory, you need to move the file from invkRevJCICSClientApp\bin\x86\Debug directory to the project's loadlib directory so that Enterprise Server finds the correct file.

  1. Using Windows Explorer or at a command prompt, change to the ReverseJSON project directory.
  2. Copy or move the invkRevJ.dll file from the invkRevJCICSClientApp\bin\x86\Debug directory to the loadlib directory.

Configure CWSJSON resources

To run the invkRevJCICSClientApp Web service requester using the CWSJSON enterprise server region you created in the previous tutorial, you must add the appropriate resources to the startup list and add and configure additional resources required by the CICS program.

Start the CWSJSON enterprise server region
  1. Start Enterprise Server Administration from Server Explorer.
  2. On Server Explorer, right-click CWSJSON; then select Start.
Start ES Monitor and Control (ESMAC)
  1. After CWSJSON has started, on the 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.
Add CWSJSONR to the startup list
  1. On the ESMAC menu ribbon, click the Resources drop-down list; then select by Group.
  2. Click Startup.
  3. Click the Details button that corresponds to the DEMOSTRT startup list.
  4. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type CWSJSONR into the empty field at the bottom; then click Apply.

    As with the previous tutorial, you need to create the CWSJSONR resource group.

Create the CWSJSONR resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type CWSJSONR.
  4. In the Description field, type CICS Web Services JSON Requester Resources; then click Add.
Create and verify resources
The invkRevJCICSClientApp program requires a URIMap resource, a pair of Bundle resources, and a PCT resource used to invoke the Reverse Web service from a TN3270 terminal emulator.
  1. On the CICS Group CWSJSONR page, click URIMap.
  2. Complete these fields:
    Name reverseR
    Description My CICS Requester URIMap
    Usage Client
    Port 5639
    Host localhost
    Path /cics/services/reverse
  3. Click Add; then click Apply.
  4. Click Group List to return to the CICS Group CWSJSONR page.
  5. Click Bundle.
  6. Complete these fields:
    Name INVKRVJI
    Description Input bundle to map the data structure to a JSON request
    Bundle Dir $IDE_PROJECT_LOC\invkRevJCICSClientApp\invkRevJInBundle
  7. Click Add; then click Apply.
  8. Click Group List to return to the CICS Group CWSJSONR page.
  9. Click Bundle.
  10. Complete these fields:
    Name INVKRVJO
    Description Output bundle to map the JSON response to a data structure
    Bundle Dir $IDE_PROJECT_LOC\invkRevJCICSClientApp\invkRevJOutBundle
  11. Click Add; then click Apply.
  12. Click Group List to return to the CICS Group CWSJSONR page.
  13. Click PCT.
  14. Complete these fields:
    Name RVRS
    Description CWS transaction to invoke the reverse service
    Program Name invkRevJ
  15. Click Add; then click Apply.
  16. To return to the Administration Home page, click Home at the top of the ESMAC menu.

    You can install the new resources by stopping and starting the region.

  17. From the Enterprise Developer Server Explorer, right-click CWSJSON; then select Restart. This stops and then starts the CWSJSON enterprise server region, automatically installing and loading the newly added resources on the startup list.
  18. After CWSJSON is started, use the ESMAC Active feature to verify that the CWSJSONR resources are installed and active.

Test the invkRevJCICSClientApp Web service requester

Now that you have your Web service requester running with all of its resources active, you are ready to run it from a TN3270 terminal emulator.

  1. Optionally, test to confirm that the ReverseJSON provider is running by repeating the Test the ReverseJSON Web service provider section in the Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method tutorial.
  2. From the Enterprise Developer Server Explorer, right-click CWSJSON; then select Show TN3270 display.
  3. If using Rumba, press F3 to bypass the CICS logon screen.
  4. Enter RVRS.
    The emulator should return your input string, reversed: 
    Hello
JSON
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables