Tutorial: CICS Web Service Requester, SOAP Top-down Method

Restriction: This topic applies to Windows environments only.

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.

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.

Create the InvokeReverse project

Use the CICSWebServicesTemplate template project to create an Eclipse project for your CICS Web service requester.

  1. From the Enterprise Developer main menu, click File > New > Mainframe COBOL Project.
    Note: If Mainframe COBOL Project is not listed:
    1. Select Other.
    2. Expand Micro Focus COBOL.
    3. Select Mainframe COBOL Project; then click Next.
  2. In the Project name field, type InvokeReverse.
  3. Check Browse for template.
  4. Click the Browse button that corresponds to the Location field, and browse to and select the CICSWebServicesTemplate template project folder, located in the temporary directory where you extracted the CICSWebServicesTemplate_Eclipse.zip file in the previous tutorial; then click OK.
  5. Check Use default location; then click Finish.

    The COBOL Explorer now shows the InvokeReverse project, which 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 COBOL Explorer, click the InvokeReverse 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. From the Service type drop-down list, select CICS Web Service Requester (Top-Down); then click Next.

    The Project field should already show the InvokeReverse project name.

  4. Click the Browse button that corresponds to the Service definition field, and navigate to the reverse.wsdl file located in the wsdl project folder.
  5. Double-click reverse.wsdl. This populates the Service definition field.
  6. In the Program name field, type invkRev, which is the program name for the generated COBOL skeleton program.
  7. Click Finish.

Enterprise Developer generates the following CICS Web service components:

COBOL Programs\invkRev.cbl
A skeleton CICS program.
Copybooks\REQ01.cpy
A copybook containing the COBOL data structures required to send a SOAP request as input.
Copybooks\RESP01.cpy
A copybook containing the COBOL data structures required to receive a SOAP response message as output.
loadlib\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.

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.

  1. From the COBOL 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.

    Eclipse automatically builds the project to include your changes.

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.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type CWSREQ. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesTemplate.xml file located in the ESTemplates project folder.
  5. Double-click CICSWebServicesTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check InvokeReverse.
  7. Click Finish.

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

    Note: If CWSREQ is not showing, expand Local [localhost:86].

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 ES Monitor and Control (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 resource groups
Here, you add the DFHWEB and DFHPIPE resource groups to the startup list, and add the MYCWSPRV resource group name to the startup list. At this point, you have neither created nor defined the MYCWSPRV group and its respective resources. Those tasks are completed in the next few sections of this tutorial.
  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 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.
  5. In the new empty field, type DFHPIPE; then click Apply.
  6. In the new empty field, type MYCWSPRV; then click Apply.

    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: 
    ReverseMePlease
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables