Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method

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 ReverseJSON Web service provider section of this tutorial, we recommend that you install a JSON requester tool.

Create the ReverseJSON project

Use the CWSProject demonstration project to create a project for your CICS Web service provider.

1. Using Windows Explorer or at a command prompt, create a project directory named ReverseJSON.
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 ReverseJSON project directory.
3. From the Enterprise Developer for Visual Studio 2017 main menu, click File > Open > Project/Solution.
4. Browse to the new ReverseJSON 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 ReverseJSON; then press Enter.

Generate CICS Web Service provider components

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

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 Service radio button.
5. In the Name field associated with the Service radio button, replace reverseReq with reverse, which is the name for the generated service interface.
6. In the Program group, check CICS.
7. In the Program group's Name field, type reverse, which is the name for the generated COBOL skeleton program.

   The Type radio buttons in the Program group enable you to specify the generation of either a Commarea or a Channel interface in the skeleton program. In this tutorial, you want to generate a Channel interface.

8. In the Type group, select the Channel radio button. This activates the Container name field.

   The default container name is DFHWS-DATA, which is the top-level container used in service provider applications for CICS Web services.

9. Click OK.

Enterprise Developer generates the following CICS Web service components in the reverse project folder:

reverse.cbl

A skeleton CICS program.

reverse.svi

A service interface file.

reverI01.cpy

A copybook containing the COBOL data structures required to send a JSON request as input. This file is generated but does not appear in the Solution Explorer.

reverO01.cpy

A copybook containing the COBOL data structures required to receive a JSON response message as output. This file is generated but does not appear in the Solution Explorer.

Generate and move the reverse.wsbind file

1. In the Solution Explorer, right-click the reverse.svi file; then select Generate WSBIND.

   Because the reverse.wsbind file is generated to the ReverseJSON project's json\reverse folder, but the output path is set to the project's loadlib folder, you need to move the file from the ReverseJSON project's json\reverse directory to the project's loadlib directory so that Enterprise Server finds the correct file.

2. Using Windows Explorer or at a command prompt, change to the ReverseJSON project directory.
3. Copy or move reverse.wsbind file from the project's json\reverse directory to the project's loadlib directory.

Implement the service

The generated skeleton program, reverse.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface. The Web service:

• Populates the request data structure (in reverI01.cpy) with the content of the DFHWS-DATA container.
• Populates the DFHWS-DATA container with the content of the response data structure (in reverO01.cpy).

To provide the required operation logic, you must code it manually by editing the program.

1. From the Solution Explorer, double-click reverse.cbl to open it in the COBOL editor.
2. Declare the following two variables in the Working-Storage section:

   01 ws-string-len               pic x(4) comp-5.
   01 ws-reversedString-len       pic x(4) comp-5.

3. Scroll down to the WS-OP-1 paragraph, and add the following COPY statement between the EXEC CICS GET and the EXEC CICS PUT statements:

   copy 'revJson.cpy'.

   Tip: reverse.cbl contains two comment lines between the two EXEC CICS statements. You can place your COPY statement between the comment lines.
4. Click File > Save reverse.cbl.
5. Close the COBOL editor.

Build the ReverseJSON project

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

Create an enterprise server region

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

1. In Enterprise Developer, activate the Server Explorer.
2. Expand Micro Focus Servers.
3. Right-click localhost; then select New Enterprise Server.
4. In the Name field, type CWSJSON. This is the name for the new enterprise server region.
5. Click the browse button that corresponds to the Template field, and navigate to the CICSWebServicesTemplate.xml file located in the ReverseJSON\ESTemplates project folder.
6. Double-click CICSWebServicesTemplate.xml. This populates the Template field.
7. On the list next to Associate with projects, check ReverseJSON.
8. Click OK.

   The Server Explorer should now show the CWSJSON enterprise server region listed under localhost.

   Note: If CWSJSON doesn't immediately appear, right-click Micro Focus Servers; then select Refresh from the context menu.

Configure CWSJSON resources

All enterprise server regions require access to certain resources, depending on the types of applications they run. Resources that are defined on a region's startup list are loaded during the startup routine, making them available for as long as the region is running.

JSON CICS Web services use the underlying resources provided by the standard Enterprise Server CICS Web interface (CWI) and CICS Web Services (CWS) support. However, the resource definition file supplied with the project does not include these resources; therefore, you need to add them manually. The CWI resources reside in a predefined resource group named DFHWEB. The CWS resources are in the predefined DFHPIPE group.

In addition, you need to create and define a resource group, CWSJSON, to contain the resources required by the reverse program.

Start Enterprise Server Administration

1. From Server Explorer, right-click Micro Focus Servers; then select Administration. This starts Enterprise Server 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 CWSJSON enterprise server region listed.

2. Back on the Server Explorer, right-click CWSJSON; then select Start.

   As the region is starting, the Enterprise Server Administration Home page should show log information in the region's Status Log column. When the region is fully started, this is indicated in the region's Status column.

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. This starts the ESMAC utility where you can edit the startup list.

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. This invokes a list of CICS Startup Lists in the right pane.

   The CWSJSON region uses the default startup list, named DEMOSTRT.

3. Click the Details button that corresponds to DEMOSTRT. This takes you to the CICS STARTUP - DEMOSTRT page.

Add resource groups

CICS Web Services are built on top of the CICS Web Interface (CWI) support, so you need to ensure that all CWS and CWI resources are available. These reside in the DFHPIPE and DFHWEB resource groups respectively, which are already defined, but not included in the startup list. Here you add these resource groups to the startup list.

In addition, you need to add a new resource group for the CICS provider resources named CWSJSON. At this point, the CWSJSON resource group is neither created nor defined. Those tasks are completed in the next few sections of this tutorial.

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 CWSJSON; then click Apply.

Create the CWSJSON 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 CWSJSON.
4. In the Description field, type CICS Web Services Provider Resources; then click Add. This invokes the CICS Group CWSJSON page where you can create and define resources for the group.

Define CWSJSON resources

The reverse program requires a resource for TCP/IP service, and a resource to support a pipeline.

1. On the CICS Group CWSJSON page, click TCPIPSv.
2. Complete these fields:

   Name	JSNTCPIP
   Description	My TCP/IP Service
   Port No	5639

3. Click Add. Enterprise Server returns Add successful.
4. Click Apply. Enterprise Server returns Update successful.
5. Click Group List to return to the CICS Group CWSJSON page.
6. Click Pipeline.
7. Complete these fields:

   Name	JSONPIPE
   Description	My CICS JSON Provider Pipeline
   Resp Wait	DEFT	This is the number of seconds that an application waits for a response from the service. DEFT indicates the default value, which is 10 seconds for HTTP and 60 seconds for MQ.
   Config file	$IDE_XML_LOC\jsonjavaprovider.xml	The IDE_XML_LOC environment variable in CWSJSON points to the xml project folder.1
   WebSvc Dir	$IDE_LOADLIB\	The IDE_LOADLIB environment variable points to the loadlib project folder, which contains the WSBIND file.1
   1 To see a list of environment variables defined for CWSJSON, from the ESMAC menu, click Env.Vars..

8. Click Add. Enterprise Server returns Add successful.
9. Click Apply. Enterprise Server returns Update successful.
10. Click Home to return to the Administration Home page.

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

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

Verify Resources

After CWSJSON is started, you can verify that the resources you have defined are installed and active.

1. In Enterprise Server, start ESMAC for the CWSJSON region.
2. On the ESMAC menu, select Active from the drop-down list located under Resources.
3. On the ESMAC menu, click the WebSvc button. You should see the reverse Web service listed and marked as INSERVICE.
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/reverse.

   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 ReverseJSON 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 request with the following endpoint URL:

   http://localhost:5639/cics/services/reverse

2. Set the Method to POST.
3. Enter the following JSON request:

   {"InputStrings" : {"myStrings":["olleH","NOSJ"]}}

   You should receive the following JSON response:

   {"OutputStrings" : {"myStrings":["Hello","JSON"]}}