Tutorial: CICS Web Service Requester, SOAP 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, SOAP Top-down Method. This tutorial picks up where it left off.

Also, you must first install the IBM CCSID Conversion Tables and configure accordingly. See CCSID Conversion Tables for more information.

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

Generate CICS Web Service requester components

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

From the Solution Explorer, expand the Reverse project's wsdl folder.
Right-click the reverse.wsdl file; then select Generate Web Service.
In the Generate group, select the Client radio button.
In the Program group, check CICS. This activates the WEBSERVICE name field.
In the Program group's Name field, type invkRev, which is the name for the generated COBOL skeleton program.
In the WEBSERVICE name field, type invkRev, which is the name for the generated WSBIND file.
Click OK.

Enterprise Developer generates a new project in the solution named invkRevCICSClientApp. It contains the following files:

invkRev.cbl: A skeleton CICS program.
invkRI01.cpy: A copybook containing the COBOL data structures required to send a SOAP request as input. This file is generated but does not show in the Solution Explorer.
invkRO01.cpy: A copybook containing the COBOL data structures required to receive a SOAP response message as output. This file is generated but does not show in the Solution Explorer.
invkRev.wsbind: A bind file that maps the SOAP request to the data structure in invkRI01.cpy, and maps the data structure in invkRO01.cpy to the SOAP response message.

Implement the service requester

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.
Invokes the reverserequest operation from the reverse Web service provider.
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.

From the Solution Explorer, double-click invkRev.cbl to open it in the COBOL editor.
In the LOCAL-STORAGE SECTION, change the value of ls-uri to:
```
"http://localhost:5482/cwsDemo/reverseMe"
```
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)
```
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
```
Save the program and exit the editor.

Build the invkRevCICSClientApp project

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

Move the invkRev.dll file

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

Using Windows Explorer or at a command prompt, change to the Reverse project directory.
Copy or move the invkRev.dll file from the invkRevCICSClientApp\bin\x86\Debug directory to the loadlib directory.

Configure CWSDEMO resources

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

Start the CWSDEMO enterprise server region

Start Enterprise Server Administration from Server Explorer.
On Server Explorer, right-click CWSDEMO; then select Start.

Start ES Monitor and Control (ESMAC)

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

Add MYCWSREQ to the startup list

On the ESMAC menu ribbon, click the Resources drop-down list; then select by Group.
Click Startup.
Click the Details button that corresponds to the DEMOSTRT startup list.
On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type MYCWSREQ into the empty field at the bottom; then click Apply.
As with the previous tutorial, you need to create the MYCWSREQ resource group.

Create the MYCWSREQ resource group

On the ESMAC menu, click the Groups button located under Resources.
On the CICS Resource Groups page, click New.
In the Name field, type MYCWSREQ.
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.

On the CICS Group MYCWSREQ page, click Pipeline.

Complete these fields:

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

Click Add; then click Apply.
Click Group List to return to the CICS Group MYCWSREQ page.
Click PCT.

Complete these fields:

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

Click Add; then click Apply.
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.
From the Enterprise Developer Server Explorer, right-click CWSDEMO; then select Restart. This stops and then starts the CWSDEMO enterprise server region, automatically installing and loading the newly added resources on the startup list.
After CWSDEMO is started, use the ESMAC Active feature to verify that the MYCWSREQ resources are installed and active.

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.

From the Enterprise Developer Server Explorer, right-click CWSDEMO; then select Mainframe TN3270 Display.
If using Rumba, press F3 to bypass the CICS logon screen.
Enter INVK.
The emulator should return your input string, reversed:
```
ReverseMePlease
```