Using Rational Developer for System z to create a CICS COBOL Web service provider

Using IBM® Rational® Developer for System z™, you will learn how to map an existing service interface to an IBM CICS COBOL application to create a CICS COBOL Web service provider.

Share:

Enterprise service tools capability in IBM® Rational® Developer for System z™ is used to create service-oriented applications from enterprise artifacts.

These are the major Web services enablement scenarios that are typical for service-oriented architecture (SOA):

  • Bottom-up development (enable existing enterprise applications as Web services)
  • Meet-in-middle development (map to an existing service Interface)
  • Top-down development (create a Web service implementation for a Web service)

This article focuses on the meet-in-middle approach.

Overview of the meet-in-middle approach

The "meet-in-middle" approach comes into the picture when an existing service interface data definition (in the schema) and the high-level language data structure definition are different (for example, different layouts or the same layouts with different names). With XML-to-COBOL mapping tools, you can enable existing COBOL applications to process and produce XML documents when data structures defined by an existing XML schema definition (or some of its derivatives, such as XML instance documents) do not identically match the COBOL data items in terms of names or even data types. This happens in various situations, for instance:

  • An existing enterprise application is required to process an XML document described by a schema originating from a third party, such as a standards committee.
  • One company acquires or merges with one or more other companies and intends to merge and consolidate various parts of the enterprise information systems (EIS) resulting from the merger or acquisition. The interfaces between various enterprise applications most likely do not precisely match.

Download the sample Web service description and CICS COBOL application

In the Download section of this article, you'll find a Web Services Description Language (WSDL) file that describes a stock Web service (STOCK.wsdl) and stock quote IBM® CICS® program (STOCK.cbl). This is an example where the response message defined by the element of a complex STOCKINFO type and the data structure represented by the output COBOL language data structure COMPANY-STOCK-INFO are named differently, the two data structures also use different layouts, and the request message definition and the input COBOL language data structure in the samples do not match either. differently. Mapping allows data to be transformed from some or all of the fields in COMPANY-STOCK-INFO to the fields in STOCKINFO.

Generate Web service provider artifacts

Reminder:
Extract the WebServicesforCICSMeetInMiddleSample.zip file included with this article (see Downloads) to your C: drive before proceeding to the steps that follow.

To proceed with generating the service provider artifacts, follow these steps:

  1. Open the Resource perspective in Rational Developer for System z, and import the project interchange (File > Import > Project Interchange) using the WebServicesforCICSMeetInMiddleSample.zip file (see Figure 1).
Figure 1. Importing the project interchange
Importing the project interchange

A new project should appear in the Navigator.

  1. Right-click the STOCK.wsdl file, and select Enable Enterprise Web Service.
  2. When the Enterprise Service Tools wizard opens:
    1. In the Host runtime list, select Web Services for CICS.
    2. In the Development scenario list, select Map an Existing Interface (meet-in-middle).
    3. In the Application mode list, select Web Service Provider.
    4. In the Conversion type list, select Compiled XML Conversion.
  3. Then click Start.
  4. Specify the two files that contain the request message definition and the input high-level-language data structure that you want to use in the inbound mapping session file (also see Figure 3.).
    1. The mapping source file will be automatically selected for you.
    2. For mapping target, click Browse, and select STOCK.cbl (Figure 2).
  5. Click Next.
Figure 2. New XML to COBOL mapping session
New XML to COBOL mapping session
  1. Specify the element that defines the request message definition and the input high-level-language data structure (Figure 3):
    1. Service: STOCKService
    2. Port: STOCKPort
    3. Operation: STOCKOperation
    4. Message: STOCKOperationRequest
    5. Part: STOCKINFO-QUERYPart
    6. Selected element: STOCKINFOQUERY
    7. Target language structure: Select STOCK-QUOTE-QUERY
  2. Click Next.
Figure 3. Selecting the root XML element and language structure
Selecting the root XML element and language structure
  1. Specify the mapping file location (Figure 4):
    1. For Mapping file folder, browse to select ...Source.
    2. For Map file name, type STOCK.
Figure 4. Specifying the mapping file
Specifying the mapping file
  1. Go ahead and click Finish. This will result in generation of the inbound mapping file (STOCK.mapping) that contains a request message definition (XML schema definition) and the input high-level-language data structure. The mapping file should automatically open in the mapping editor (Figure 5).
Figure 5. Mapping editor
Mapping editor
  1. Create data mappings in the inbound mapping session file. Use the mapping editor (Figure 6) to indicate how you want data mapped from the request message definition (XML schema definition) to the input high-level-language data structure in the inbound mapping session file. For each mapping that you want to create, drag an element in the source data to an element in the target data. Alternately, select an element in the source data, then pressing the Ctrl key, select the element in the target data and then click the "Create a new Transform" icon. The editor displays a connecting line between the source element and the target element to indicate that a mapping exists.
    1. For STOCK.mapping, specify the following mapping: symbol = REQ-SYMBOL
  2. Click Next.
  3. Save the mapping file.
Figure 6. Specifying the mappings
Specifying the mappings

Create an outbound mapping file

  1. Right-click the STOCK.cbl file, and select Enable Enterprise Web Service.
  2. When the Enterprise Service Tools wizard launchpad opens (Figure 7):
    1. In the Host runtime list, select Web Services for CICS.
    2. In the Development scenario list, select Map an Existing Interface (meet-in-middle).
    3. In the Application mode list, select Web Service Provider.
    4. In the Conversion type list, select Compiled XML Conversion.
    5. Click Start.
  3. Specify the two files that contain output high-level-language data structure and the response message definition that you want to use in the outbound mapping session file.
    1. The Mapping source file will be automatically selected for you.
    2. For Mapping target, click Browse, and select STOCK.wsdl.
  4. Click Next.
Figure 7. Enterprise Service Tools wizard
Enterprise Service Tools wizard
  1. Specify the element that defines the output high-level-language data structure and the response message definition (also see Figure 8):
    1. Source language structure: Browse to select COMPANY-STOCK-INFO.
    2. Enter this information in the fields under "Select the target XML element from the Web service definition:":
      • Service:STOCKService
      • Port: STOCKPort
      • Operation:STOCKOperation
      • Message:STOCKOperationResponse
      • Part: STOCKINFOPart
      • Selected element: STOCKINFO
  2. Click Next.
Figure 8. Specifying the XML element and language structure
Specifying the XML element and language structure
  1. Specify the mapping file location (Figure 9).
    1. For Mapping file folder, browse to select ...Source.
    2. For Map file name, type STOCK2.
Figure 9. Specifying the mapping file location
Specifying the mapping file location
  1. Go ahead and click Finish. This will result in generation of the outbound mapping file (STOCK2.mapping) that contains the output high-level-language data structure and the response message definition. The mapping file should automatically open in the mapping editor as Figure 10 shows.
Figure 10. Mapping editor showing the STOCK2.mapping file
Mapping editor showing the STOCK2.mapping file
  1. Create data mappings in the outbound mapping session file. Use the mapping editor to indicate how you want data mapped from the output high-level-language data structure to the response message definition in the outbound mapping session file.
    1. For each mapping that you want to create, drag an element in the source data to an element in the target data. Alternately, select an element in the source data, then pressing the Ctrl key, select the element in the target data and then click the "Create a new Transform" icon. The editor displays a connecting line between the source element and the target element to indicate that a mapping exists.
    2. For STOCK2.mapping, specify the following mappings (Figure 11):
      • RPY-SYMBOL-DESC = symbol_desc
      • RPY-SHARE-PRICE = share_price
  2. Save the mapping file.
Figure 11. Specifying the mappings
Specifying the mappings

Generate the Web service provider artifacts

Mapping is the process of relating parts of two existing data structures to one another. Typically, the result of the mapping process is a generated runtime code that moves the data between mapped elements. The next task is to generate the Web service provider artifacts.

  1. You are dealing with a REQUEST-RESPONSE operation Web service; therefore, select the inbound mapping file (STOCK.mapping) and the outbound mapping file (STOCK2.mapping).
  2. Right-click and select Generate Conversion Code (Figure 12)
Figure 12. Generating conversion code
Generating conversion code
  1. When the Enterprise Service Tools wizard launchpad opens (Figure 13), click Start.
Figure 13. Enterprise Service Tools wizard launchpad
Generating conversion code
  1. When the Generation of conversion code wizard opens, verify that the correct inbound and outbound mapping files are selected.
  2. Then click Next.
  3. Under the XML Converts tab, specify identification attributes and character encodings (Figure 14):
    1. Specify identification attributes:
      • Converter program name prefix: STOCK
      • Author name: WD4Z
      • Service program name: STOCK
    2. Specify character encodings:
      • Inbound code page: Select 1140 (Default)
      • Host code page: Select 1140 (Default)
      • Outbound code page: Select 1140 (Default)
Figure 14. Specifying attributes and encodings
Specifying attributes and encodings

Note:
The Advanced Options tab allows you to specify inbound and outbound XML converter behavior and compiler-related preferences.

  1. Click Next.
  2. Under the Basic options tab, specify these options for the WSBind file (also see Figure 15):
    1. Targets for WSBind file:
      • WSBind file container: Select /WebServicesforCICSMeetInMiddleSample/Source
      • WSBind file name: STOCK
      • Log file name: STOCK
    2. Application program properties:
      • Program interface: COMMAREA
      • Container name: Not applicable (Disabled field)
    3. Service interface properties:
      • Local URI: /cics/services/STOCK
Figure 15. Specifying the options for the WSBind file
Specifying the options for the WSBind file

Note:
After you complete the tasks in the wizard, you will need to put the WSBind file in the pickup directory of a provider-mode Pipeline. Alternatively, if you have a connection to a z/OS system through the Remote Systems navigator in the z/OS Projects perspective, the Browse dialog will show the pickup directory.

  1. Click Next.
  2. Specify the location of the converter and driver files (Figure 16). You can generate the converters and the driver to a single program.
    1. Converter file container: Browse to /WebServicesforCICSMeetInMiddleSample/Source
    2. Converter driver file name: STOCKD
    3. Inbound converter file name:STOCKD
    4. Outbound converter file name:STOCKD
    5. Check the box next to Generate all to driver.
Figure 16. Caption
Screen capture

Note:
If you have a connection to a z/OS System via Remote Systems navigator in z/OS Projects perspective, the Browse dialog will show the MVS® system to which the converters and the driver could be generated directly.

  1. Go ahead and finish the tasks in the wizard. This will result in generating Web service provider artifacts (Figure 17):
    1. STOCK.log: The log file provides verbose detail about the internal processing of the Web Services Assistant.
    2. STOCK.wsbind: The WSBind file is a resource that describes to CICS the specifics of the Web service.
    3. STOCKD.cbl: The conversion program that consists of a driver and two XML converters (inbound and outbound). The XML converters convert an input XML document to COBOL language structure and convert the output COBOL data to the output XML document. The driver program manages the communication between CICS and the XML converters.
Figure 17. Generated Web service provider artifacts
Generated Web service provider artifacts

Test the Web service provider

After you have completed the following steps, you can test the new Web service by using the Services Explorer in Rational Developer for System z Web (or by other means):

  1. Copy the STOCK.cbl and STOCKD.cbl files to the CICS/MVS system.
  2. Compile and link-edit STOCK.cbl (Web service provider application) and STOCKD.cbl (conversion program) into a load data set within the DFHRPL (library) concatenation of CICS.
  3. Define a Program resource in CICS called STOCK and install it.
  4. Define a Program resource in CICS called STOCKD and install it.
  5. Copy the STOCK.wsbind file to a CICS provider-mode Pipeline pickup directory. If you use FTP, make sure to transfer the file in binary mode.
  6. Issue a scan of the provider-mode Pipeline to install the Web service: CEMT PERFORM PIPELINE(PROVPIPE) SCAN
  7. To ensure that the Web service is in service, issue the CEMT INQUIRE WEBSERVICE(*) command, and look for STOCK.
  8. You will need to modify the service location in the STOCK.wsdl file to this:
    http://your.system.ip:cics_tcpipservice_port/cics/services/STOCK
  9. To test the Web service using the Web service explorer, right-click the STOCK.wsdl file in the /Source directory of the WebServicesforCICSMeetInMiddleSample project.
  10. In the drop-down menu, select Web Services > Test with Web Services Explorer, as Figure 18 shows.
Figure 18. Start testing the Web service
Start testing the Web service
  1. Select an operation to test in the tree view displayed on the left (Navigator pane). A corresponding input form will be displayed on the right (Actions pane).

Tip:
Be sure that the full URI in the WSDL file represents the physical location of the CICS system where the Web service is running (Figure 19).

Figure 19. Operation to test and corresponding input
Operation to test and corresponding input

Download

DescriptionNameSize
WSDL sample project for this articleWebServicesforCICSMeetInMiddleSample.zip10KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, WebSphere
ArticleID=270643
ArticleTitle=Using Rational Developer for System z to create a CICS COBOL Web service provider
publish-date=11272007