Tutorial: CICS Web Service Requester, Top-down Method

Prerequisites

Before attempting to complete this tutorial, you must first complete Tutorial: CICS Web Service Provider, Top-down Method. This tutorial picks up where it left off.

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

Create the InvokeReverse project

Use the CWSProject demonstration project to create a Visual Studio project for your CICS Web service requester.

1. Using Windows Explorer or at a command prompt, create a project directory for the InvokeReverse project.
2. Extract the CICSWebServicesTemplate_VS.zip file to the new project directory.
   Important: If you do not have the CICSWebServicesTemplate_VS.zip file, contact Micro Focus SupportLine.
3. From the Enterprise Developer main menu, click File > Open > Project/Solution.
4. Browse to the new project directory, and select the CWSProject.cblproj project file.
5. Click the Add to Solution option; 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.

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

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 Solution Explorer, right-click the InvokeReverse project; then select Generate CICS Web Service Interface.
2. From the Application Mode drop-down list, select Service requester (client); then click Next.
3. Click the Browse button that corresponds to the Service definition field, and navigate to the reverse.wsdl file located in the wsdl project folder.
4. Double-click reverse.wsdl. This populates the Service definition field.
5. In the Program name field, type invkRev, which is the program name for the generated COBOL skeleton program.
6. Click Finish; then click Close.

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

invkRev.cbl

A skeleton CICS program.

REQ01.cpy

A copybook containing the COBOL data structures required to send a SOAP request as input.

RESP01.cpy

A copybook containing the COBOL data structures required to receive a SOAP response message as output.

invkRev.wsbind

A bind file that maps the SOAP request to the data structure in REQ01.cpy, and maps the data structure in RESP01.cpy to the SOAP response message.

You should see the invkRev.cbl and the invkRev.wsbind files in the reverse project folder. The .cpy files are generated, but are not shown in the project folder.

Move the invkRev.wsbind file

Because the invkRev.wsbind file is generated to the invkRev folder, but the output path is set to the loadlib folder, you need to move the file from invkRev to loadlib so that Enterprise Server finds the correct file:

1. Using Windows Explorer or at a command prompt, change to the InvokeReverse project directory.
2. Copy or move invkRev.wsbind from the invkRev directory to the loadlib directory.

Add loadlib to the project

Now that you have a generated file, invkRev.wsbind, in the loadlib directory, you can add it to the project:

1. In the Solution Explorer, right-click the InvokeReverse project; then select Add > Existing item.
2. From the drop-down list that corresponds to the File name field, select All Files (*.*).
3. Browse to the loadlib directory.
4. Double-click invkRev.wsbind.

Implement the service

The generated skeleton program, invkRev.cbl, contains some basic functionality that is common to any CICS Web service requester. In this case:

• It puts the reverseRequest-input-parms data structure into the DFHWS-DATA container.
• It invokes the reverserequest operation from the reverse Web service provider.
• It populates the reverseRequest-output-parms data structure from the response in DFHWS-DATA.

To provide the program with a URI and port that directs the request to the enterprise server region that is running your Web service provider, you must edit the code.

1. From the Solution Explorer, double-click invkRev.cbl to open it in the COBOL editor.
2. In the LOCAL-STORAGE SECTION, change the value of ls-uri to:

   "http://localhost:5482/cwsDemo/reverseMe"

3. In the PROCEDURE DIVISION, WS-OP-1 section, add the following MOVE statements before the EXEC CICS PUT CONTAINER statement:

   move 1                      to myString-occurs
   move 'esaelPeMesreveR'      to myString(1)

4. After the EXEC CICS GET CONTAINER command for DFHWS-DATA, add the following code to send the reversed string back to the terminal:

    exec cics send text
         from(reversedString(1))
         freekb
    end-exec

5. Save the program and exit the editor.

Build the InvokeReverse project

• From the Solution Explorer, right-click the InvokeReverse 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. From 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 CWSREQ. 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 ESTemplates project folder.
6. Double-click CICSWebServicesTemplate.xml. This populates the Template field.
7. On the list next to Associate with projects, check InvokeReverse.
8. Click OK.

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

Configure CWSREQ resources

As with the CWSPROV enterprise server region created in the previous tutorial, you need to add the appropriate resources to the startup list and add and configure additional resources required by the CICS program.

Start the CWSREQ enterprise server region

1. Start Enterprise Server Administration from Server Explorer.
2. On Server Explorer, right-click CWSREQ; then select Start.
   Note: If an Enterprise Server Sign On dialog appears, click OK. The new enterprise server region does not use specific server credentials.

Start ESMAC

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

Add DFHWEB and DFHPIPE and MYCWSREQ to the startup list

1. Open the details for the DEMOSTRT startup list.
2. Add the DFHWEB, DFHPIPE, and MYCWSREQ resource groups.

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

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

Create and verify resources

The InvokeReverse program requires a resource to support a pipeline, and a PCT resource used to invoke the Reverse Web service from a TN3270 terminal emulator.

1. On the CICS Group MYCWSREQ page, click Pipeline.
2. Complete these fields:

   Name	REQPIPE
   Description	My CICS Requester Pipeline
   Resp Wait	DEFT
   Config file	$IDE_XML_LOC\basicsoap11requester.xml
   WebSvc Dir	$IDE_LOADLIB\

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

   Name	INVK
   Description	CWS transaction to invoke the reverse service
   Program Name	INVKREV

7. Click Add; then click Apply.
8. 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.

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

Start the CWSPROV Region

Because your new CICS Web service requester sends requests to the CICS Web service provider you created in the previous tutorial, start the CWSPROV region before proceeding.

Test the InvokeReverse 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. From the Enterprise Developer Server Explorer, right-click CWSREQ; then select Show TN3270 display.
2. If using Rumba, press F3 to bypass the CICS logon screen.
3. Enter INVK.
   The emulator should return your input string, reversed:

   PleaseReverseMe