Tutorial: CICS Web Service Requester from JSON, Linkable Interface Top-down 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.

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 JSONPROV enterprise server region.

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

This tutorial assumes that your Eclipse project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Import the InvokeReverseJSON 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\Requester\TopDown directory; then click OK.
5. On the Projects list, ensure that InvokeReverseJSON is checked.
6. Under Options, check Copy projects into workspace; then click Finish.

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

Generate CICS Web Service requester components

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

1. From the Application Explorer, click the InvokeReverseJSON 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, select Other; then locate and select CICS Web Service.
3. Under Service type, select JSON message processing.
4. From the drop-down list, select CICS Web Service Requester (Top-Down, Linkable Interface); then click Next.

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

5. In the Service name field, type invkRevJ; then click Next.
6. Click the Browse button that corresponds to the JSON schema field.
7. Navigate to and select the reverse.json file, located in your project's schema folder.
8. In the Output artifacts group, type REQ into the Request file prefix field.
9. Click the Browse button that corresponds to the Bundle field.
10. Navigate to your project directory.
11. Click Make New Folder.
12. Name the new folder bundles; then press Enter.
13. Click the bundles folder.
14. Using the same method as before, create a new folder under bundles named REQBNDL.
15. Select the REQBNDL folder; then press Enter.
16. Click OK.
17. In the JSON transform field, type REVREQUEST; then click Next.
18. Click the Browse button that corresponds to the JSON schema field.
19. Navigate to and select the reverse.json file, located in your project's schema folder.
20. In the Response file prefix field, type RESP.
21. Click the Browse button that corresponds to the Bundle field.
22. Navigate to your project's bundles directory.
23. Using the same method as before, create a new directory under bundles named RESPBNDL.
24. Select the RESPBNDL folder; then press Enter.
25. Click OK.
26. In the JSON transform field, type REVRESPONSE; then click Finish.

Analyze the invkRevJ.cbl program

The supplied invkRevJ.cbl program already contains the functionality that is required to invoke the reverseJ 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.

Create an enterprise server region

Here you use Server Explorer to create an enterprise server region on which to run the requester Web service.

1. On the Server Explorer, right-click Local [localhost:86]; then select New > Enterprise Server.
2. In the Name field, type JSONREQ.
3. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesProjectTemplate.xml file located in the InvokeReverseJSON project folder.
4. Double-click CICSWebServicesProjectTemplate.xml.
5. On the list next to Associate with projects, check InvokeReverseJSON.
6. Click Finish.

   The Server Explorer should now show the JSONREQ enterprise server region listed under Local [localhost:86].

Configure JSONREQ resources

Start Enterprise Server Administration

1. On the Server Explorer, right-click JSONREQ; then select Start.

Start ES Monitor and Control (ESMAC)

1. After JSONREQ has started, on the Enterprise Server Administration Home page, click the Details button located in the Status column for the JSONREQ region.
2. On the Server > Control page, click ES Monitor & Control.

Open the DEMOSTRT startup list

1. On the ESMAC menu, click the drop-down list located under Resources; then select by Group.
2. Click Startup.
3. Click the Details button that corresponds to DEMOSTRT.

Add resource groups

As with the JSONPROV enterprise server region, the JSONREQ region requires the DFHWEB and DFHPIPE resource groups, and a resource group to contain the requester resources Here, you add these resource groups to the startup list.

1. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type DFHWEB into the empty field at the bottom; then click Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
2. In the new empty field, type DFHPIPE; then click Apply.
3. In the new empty field, type JSONREQ; then click Apply.

Create the JSONREQ 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 JSONREQ.
4. In the Description field, type CICS Web Services JSON Requester Resources; then click Add.

Create and verify resources

The invkRevJ 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 JSONREQ page, click URIMap.
2. Complete these fields:

   Name	REVRSURI
   Description	URIMAP for JSON reverseJ request
   Usage	Client
   Port	5482
   Host	localhost
   Path	/cics/services/json/reverse

3. Click Add; then click Apply.
4. Click Group List to return to the CICS Group JSONREQ page.
5. Click Bundle.
6. Complete these fields:

   Name	REQBNDL
   Description	Input bundle to map the data structure to a JSON request
   Bundle Dir	$IDE_BUNDLE_LOC\REQBNDL

7. Click Add; then click Apply.
8. Click Group List to return to the CICS Group JSONREQ page.
9. Click Bundle.
10. Complete these fields:

    Name	RESPBNDL
    Description	Output bundle to map the JSON response to a data structure
    Bundle Dir	$IDE_BUNDLE_LOC\RESPBNDL

11. Click Add; then click Apply.
12. Click Group List to return to the CICS Group JSONREQ page.
13. Click PCT.
14. Complete these fields:

    Name	INVJ
    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 JSONREQ; 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 JSONREQ is started, use the ESMAC Active feature to verify that the JSONREQ resources are installed and active.

Test the invkRevJ 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. If not already started, start the JSONPROV enterprise server region from the Server Explorer.
2. 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.
3. From the Enterprise Developer Server Explorer, right-click JSONREQ; then select Show TN3270 display.
4. If using Rumba, press F3 to bypass the CICS logon screen.
5. Enter INVJ.
   The emulator should return your input string, reversed:

   Hello
   JSON