Chapter 4: Generated COBOL Client for Web Services

You need to do the tutorials in this book in the order shown by the Tutorials Map.

Overview

In this chapter, you use the Generate Client feature in Net Express to generate a COBOL proxy program that can be used as a client to a particular Web service. You can call the generated proxy from a sample COBOL application that is generated with the proxy, or from your own client application. The proxy receives data from the calling application, invokes the Web service and returns any data back to the application.

Although clients communicate with Web services across the Web, this does not mean the client has to have a Web-type interface. The client application that is generated with the proxy is a simple character-mode application that uses ACCEPT/DISPLAY statements for its user interface.

In the chapter Deploying a Service, you deployed a Web service called wmapserv. In this chapter you create and run a client application that uses wmapserv.

Preparation

Minimize your Web browser and the console daemon. If the Net Express IDEService Interfaces window is minimized, restore it.

If Net Express, the project Mapdemo, and the Service Interfaces window aren't open, open them now - to open the Service Interfaces window, click File > Open Service Interfaces, then select mapdemo.mpr from Examples\Net Express IDE\mapdemo and click Open.

If the Service Interfaces window isn't open, open it now, using the command:

cobimtk

Make sure the ESDEMO enterprise server is started and the wmapserv service is deployed in it, as described in the chapter Deploying a Service.

Generate the Client

The Interface Mapping Toolkit provides two ways you can generate a COBOL client for a Web service. The more general way is to generate directly from the Web service’s WSDL file. This can be done for any Web service that you have the WSDL file for. Thus you can use the Interface Mapping Toolkit to generate a client for a published Web service whose WSDL file you have obtained from the Web.

When you have created and deployed a service using the Interface Mapping Toolkit, you can also generate a client from the service directly without seeing the WSDL.

In this tutorial we show both ways. There is no harm in generating twice. Alternatively, you might like to run this tutorial twice, doing it the two different ways.

To generate from the mapping:

Make sure wmapserv is selected in the Service Interfaces window, and then click Service > Generate Client > using Mapping.
You could alternatively right-click wmapserv and then click Generate Client. This goes straight to using the mapping without offering the choice of using the WSDL.
A dialog box opens. However, if you are repeating this part of this tutorial, and have generated wmapserv before, you do not get the dialog box - go straight to Step 4.
We want the generated client code to become part of the currently open project so, on the dialog box, ensure Use current Net Express project is selected and click OK.
The proxy file wmapserv-proxy.cbl, the sample application file wmapserv-app.cbl and a copybook file wmapserv-copy.cpy are generated and added (along with associated build objects) to the project.
Click OK on the message saying client generation has completed.

To generate from the WSDL:

Click Service > Generate Client > using WSDL.
A wizard opens.
Click Browse and select wmapserv.wsdl in Examples\Net Express IDE\mapdemo\repos\wmapserv.deploy, then click Open, then click Next.
This is the WSDL file that was created when you created wmapserv. You could use this facility to create a client for any Web service by using its WSDL file here.
Ensure Use current Net Express project is selected and click Next.
Click Finish.
The same files are generated as when you generated from the mapping.
Click OK on the message saying client generation has completed.

Build and Run the Client

Click Rebuild .
On the project window, select wmapserv-app.int and click Run on the popup menu.
The client application that Net Express generates uses numeric codes for the different operations.
Type 3 (for a Read operation), and press Enter.

Note that the code for Read is not the same as the code used in book.cbl and the service. A client knows nothing of the internal workings of the service.
You may remember from the chapter Creating a Service that the Read operation needs only one of title, author, or stock number to be supplied.
In response to the prompts, type 1111 for the stock number, and leave the title and author blank. Press Enter after each one.

After a few moments, the client displays the name and content of each field from the requested record. It has successfully called the Web service, which has looked up the record in the file and returned the data.

If you run this tutorial twice, generating once from the mapping and once from the WSDL file, you may notice minor differences in the behavior of the generated client. When you generate from the mapping, the picture-strings in the client are based directly on those in the original legacy program. When you generate from the WSDL, this direct link is not available, and the picture-strings in the client are based on the data types in the WSDL.

Try a few more operations. Recall from the chapter Creating a Service that the file as supplied contains records 1111 and 2222, and you may have added a record yourself - number 4444 if you used the example data suggested in that chapter.
When you've finished, close the Application Output window.

Before Continuing...

To see how to debug this service, continue at the chapter Debugging a Service.

If you want to take a break first, you can close Net Express and/or the project.