Tutorial: CICS Web Service Provider, 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 provider that sends one or more character strings in the form of a SOAP request to a generated CICS application. The application reads and then reverses each string, and sends the reversed strings back to the Web service as a SOAP response message.

To use the top-down method, you supply a WSDL file that describes the CICS application you want to access. The project template used in this tutorial to create your Enterprise Developer project contains the reverse.wsdl file for this purpose.

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 Reverse Web service provider section of this tutorial, we recommend that you download and install the SOAPui Eclipse plugin, available from sourceforge.net.

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

Create the Reverse project

Use the CICSWebServicesTemplate template project to create a project for your CICS Web service provider.

  1. Extract the CICSWebServicesTemplate_Eclipse.zip file, located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS directory by default, to a temporary directory.
  2. In Eclipse, start the COBOL Explorer.
  3. 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.
  4. In the Project name field, type Reverse.
  5. Check Browse for template.
  6. Click the Browse button that corresponds to the Location field, and browse to the location where you extracted the CICSWebServicesTemplate_Eclipse.zip file.
  7. Select CICSWebServicesTemplate template folder; then click OK.
  8. Check Use default location; then click Finish.

    The COBOL Explorer now shows the Reverse project, which is created in a Reverse subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service provider components

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

  1. From the COBOL Explorer, click the Reverse 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:
    1. Select Other.
    2. Expand Micro Focus Service Interface.
    3. Select CICS Web Service; then click Next.
  3. From the Service type drop-down list, select CICS Web Service Provider (Top-Down); then click Next.

    The Project field should already show the Reverse project name.

  4. Click the Browse button that corresponds to the Service definition field, and browse 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 reverse, which is the program name for the generated COBOL skeleton program.

    You need to provide a URI that Enterprise Server can use to identify and locate the appropriate Web service upon receiving a request or a response. This information goes into the Service location field.

  7. In the Service location field, type /cwsDemo/reverseMe.

    The Request file prefix and Response file prefix fields are completed for you by default. These are the names of the generated copybooks that support the generated skeleton program file, one for request data structures, and one for response data structures.

    The Program interface field enables 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. From the Program interface drop-down list, select CHANNEL. 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 Finish.

Enterprise Developer generates the following CICS Web service components:

COBOL Programs\reverse.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\reverse.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

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

  • It checks the operation name by retrieving the content of the DFHWS-OPERATION container.
  • If the returned operation name matches the name expected by the program (in this case, reverserequest), the program:
    • Populates the request data structure (in REQ01.cpy) with the content of the DFHWS-DATA container.
    • Populates the DFHWS-DATA container with the content of the response data structure (in RESP01.cpy).

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

  1. From the COBOL 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 to the bottom of the program and add the following COPY statement after the last exit program. statement: 
    copy 'revLogic.cpy'.
  4. Scroll up to the WS-OP-1 paragraph, and add the following PERFORM statement between the EXEC CICS GET and the EXEC CICS PUT statements: 
    Perform reverse-logic
    Note: reverse.cbl contains two comment lines between the two EXEC CICS statements. You can place your PERFORM statement between the comment lines.
  5. Click File > Save.
  6. Close the COBOL editor.

    Eclipse automatically builds the project to include your changes.

Create an enterprise server region

Here you use the Server Explorer in Enterprise Developer 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 CWSPROV. 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 Reverse.
  7. Click Finish.

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

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

Configure CWSPROV 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.

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 CICSWebServicesTemplate used to create the CWSPROV region does not include these resources on the startup list; 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, MYCWSPRV, to contain the resources required by the Reverse program.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page. 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 CWSPROV enterprise server region listed.

  2. Back on the Server Explorer, right-click CWSPROV ; 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 CWSPROV has started, on the Administration Home page, click the Details button located in the Status column for the CWSPROV 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 CWSPROV 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
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 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 MYCWSPRV; then click Apply.
Create the MYCWSPRV 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 MYCWSPRV.
  4. In the Description field, type CICS Web Services Provider Resources; then click Add. This invokes the CICS Group MYCWSPRV page where you can create and define resources for the group.
Define MYCWSPRV resources
The Reverse program requires a resource for TCP/IP service, and a resource to support a pipeline.
  1. On the CICS Group MYCWSPRV page, click TCPIPSv.
  2. Complete these fields:
    Name CWSTCPIP
    Description My TCP/IP Service
    Port No 5482
  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 MYCWSPRV page.
  6. Click Pipeline.
  7. Complete these fields:
    Name PROVPIPE
    Description My CICS 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\basicsoap11provider.xml The IDE_XML_LOC environment variable in CWSPROV points to the xml project folder.1
    WebSvc Dir $IDE_LOADLIB\ The IDE_LOADLIB environment variable points to the loadlib project folder.2

    1 To see a list of environment variables defined for CWSPROV , from the Administration Home page, click the Edit button that corresponds to the CWSPROV region. The list appears in the Configuration Information field on the Server > Properties > General page.

    2 The IDE_LOADLIB environment variable is set automatically when you start the enterprise server region from the Enterprise Developer Server Explorer.

  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 CWSPROV ; then select Restart. This stops and then starts the CWSPROV enterprise server region, automatically installing and loading the newly added resources on the startup list.

Verify Resources

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

  1. Start ESMAC.
  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 ENABLED.
  4. Click the Details button that corresponds to the reverse Web service.

    Notice the value for WSBIND. This value is taken from the information you provided when you created the Web service.

  5. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to PROVPIPE. The Pipeline resource sets the response wait period, identifies the SOAP configuration file, and the Web Service directory.
  6. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cwsDemo/reverseMe.

    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 SOAP 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 Reverse Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a SOAP request to run the Web service. You can do this using any SOAP requester tool such as the SOAPui Eclipse plug-in.

  1. Create a SOAP request that contains the following: 
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                  xmlns:cws="http://tempuri.org/reverse">
   <soapenv:Header/>
   <soapenv:Body>
      <cws:reverseRequest>
         <cws:InputStrings>
            <cws:myString>dlroW olleH</cws:myString>
            <cws:myString>esaelP eM esreveR</cws:myString>
         </cws:InputStrings>
      </cws:reverseRequest>
   </soapenv:Body>
</soapenv:Envelope>
  2. Submit the SOAP request to the following endpoint URL:

    http://localhost:5482/cwsDemo/reverseMe

    You should receive the following SOAP response: 

    <SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
                   xmlns:cws="http://tempuri.org/reverse" 
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <reverseResponse xmlns="http://tempuri.org/reverse">
         <OutputStrings>
            <reversedString>Hello World</reversedString>
            <reversedString>Reverse Me Please</reversedString>
         </OutputStrings>
      </reverseResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables