Chapter 3: COBOL Web Services with the Microsoft SOAP Toolkit

This chapter explains how to use the Microsoft SOAP Toolkit, which is now deprecated. Microsoft recommends that you use the .NET Framework to create and access Web services. The information in this chapter is retained for users who are already using the SOAP Toolkit.

Introduction

The Microsoft SOAP Toolkit includes a set of COM components that provide access to existing Web services. It also includes a WSDL generator that generates WSDL files from an existing COM component and exposes that COM component as a Web service. Net Express includes support for accessing COM components from COBOL and creating new COM components in COBOL. This means you can use the Microsoft SOAP Toolkit from COBOL.

The COM and Java interoperability provided in Micro Focus COBOL makes use of the extensions to the COBOL syntax provided for object-oriented programming. However, you do not have to learn object oriented-programming. When creating Web services, the Class and Method Wizards provided with Net Express generate all of the OO syntax you need. When calling Web services from COBOL, the new verb invoke is used.

This chapter assumes a basic understanding of the support provided in Net Express for COM interoperability with COBOL. This support is covered in the COM, COBOL and .NET book.

This chapter contains two sections: they are on creating a COBOL Web service, and on invoking a Web service from COBOL.

Creating a COBOL Web Service

The recommended way to create a Web service in Net Express is the Interface Mapping Toolkit. For a detailed comparison of the alternative methods, see the chapter Application Extension with Distributed Computing. In brief, you might use the Microsoft SOAP Toolkit to create your Web service if you don't want to deploy it in the Enterprise Server. You can create a COM Object using Net Express, and then use the Microsoft SOAP Toolkit to expose that as a Web service.

A tutorial in your Getting Started - Additional Topics book demonstrates in detail how to create a COBOL Web service using the Microsoft SOAP Toolkit. For detailed instructions on using the SOAP Toolkit and the WSDL generator, refer to the User Guide that is supplied with the Microsoft SOAP Toolkit.

Using a Web Service from COBOL

This section covers calling a Web Service from COBOL using the Microsoft SOAP Toolkit.

This example accesses a Web service provided by xmethods (www.xmethods.net). This Web service uses the California Department of Transportation's Web site to return information on traffic conditions for roads in California. It provides a method called getTraffic, which takes a list of highway numbers separated by commas and returns a string containing the road conditions on each of the highways listed.

The SOAP Toolkit provides a COM component that uses the information provided in a WSDL file to make the methods provided by the Web service appear as COM methods to the client application. This means that any language that can call COM components can send SOAP requests to Web services. This includes Micro Focus COBOL.

The following is a listing of a simple COBOL application that accesses the Web service described above.

$set ooctrl(+p) 
 class-control.
     MSSOAP is class "$OLE$MSSOAP.SoapClient"
     olesup is class "olesup".
 working-storage section.
 01  Soap object reference. 
 78  WSDL-Url value 
     z"http://www.xmethods.net/sd/2001/CATrafficService.wsdl".
 01  WSML-Url pic x value x"00".
 01 Traffic-Conditions pic x(5000).

 procedure division.
     invoke MSSOAP "new" returning Soap
     invoke Soap "mssoapinit" using WSDL-Url
                                    z"CATrafficService" 
                                    z"CATrafficPort" 
                                    WSML-Url
     invoke olesup "setDispatchType" using by value 0 size 4
     invoke Soap "getTraffic" using z"101"
     returning Traffic-Conditions
     display Traffic-Conditions
     invoke Soap "finalize" returning Soap
     stop run.

When run, this program produces output on the traffic conditions on highway 101 in California. The following is an example:

 reported as of Friday, September 14, 2001 at 11:21 . 
 Slow for the Cone Zone

 US 101 
    [ LOS ANGELES & VENTURA CO.'S]
     NO TRAFFIC RESTRICTIONS ARE REPORTED FOR THIS AREA.

    [ CENTRAL COAST]
     NO TRAFFIC RESTRICTIONS ARE REPORTED FOR THIS AREA.

    [ SAN FRANCISCO BAY AREA]
     NO TRAFFIC RESTRICTIONS ARE REPORTED FOR THIS AREA.

    [ NORTHWEST CALIFORNIA]
     1-WAY CONTROLLED TRAFFIC AT VARIOUS LOCATIONS FROM 2.2 MI SOUTH 
     TO 8.8 MI NORTH OF THE JCT OF SR 1 (MENDOCINO CO) FROM 0800 
     HRS TO 1600 HRS THRU 9/14/01 DUE TO MAINTENANCE

This program shows the basic structure common to all COBOL programs that access a Web service using the SOAP Toolkit, as follows:

You may be wondering about the declaration of the class olesup and the use of the line:

    invoke olesup "setDispatchType" using by value 0 size 4

This is needed in this particular program because the name of the method, getTraffic, begins with the prefix "get". In Micro Focus COBOL, prefixing a method name with "get" or "put" when accessing a COM component is used to indicate that the method call should be interpreted as a property GET or property PUT. The use of the method setDispatchType is used to override this default behavior, so that the invoke of getTraffic is handled as a regular method call.

This is only needed if a method name begins with "get" or "put". For all other method names, you would not need to insert this line before the method call. For more information on the class olesup and the method setDispatchType, refer to the Net Express on-line documentation.


Copyright © 2006 Micro Focus (IP) Ltd. All rights reserved.