This white paper is the full user documentation on using CapeStudio to deploy a COBOL application as a Web service.
This white paper is an extension to the user documentation for the Cape Clear products CapeStudio and CapeConnect. That documentation is included with these products, and can also be read on Cape Clear's Web site at http://www.capeclear.com/products/manuals. We assume you are familiar with that documentation, and with using CapeStudio and CapeConnect. We assume you are reasonably familiar with the COBOL and Java programming languages.
The facility to deploy a COBOL application as a Web service is an extension to CapeStudio and CapeConnect. The extension to CapeStudio is called the COBOL-to-Java Mapping Tool, and enables you to create a Java wrapper for the COBOL application, so that CapeStudio can treat it as a Java application. The extension to CapeConnect is in the form of underlying supporting software.
These extensions are provided by Micro Focus. Micro Focus's product, Net Express, is a COBOL development environment. You must have Net Express on the same machine as CapeStudio and CapeConnect. Then, by adding service packs to both Net Express and the Cape Clear software, you enable CapeStudio and CapeConnect to handle COBOL programs.
For ordering and pricing information for Net Express and for the Cape Clear software, and for their service packs, please contact Micro Focus (http://www.microfocus.com) and Cape Clear (http://www.capeclear.com) respectively.
You need the following software setup to be able to install and use the Cape Clear and Micro Focus software:
You must use the following versions of the software:
To install the COBOL Web services extension:
The enabling tool mfcc.exe was added to your Start menu when you installed Net Express 3.1 Service Pack #1.
On CapeStudio's Design menu, you should see an extra function, Generate WSDL from COBOL. At this point all functions on the Design menu are dimmed because no project is open.
If Generate WSDL from COBOL is still dimmed even with a project open, check the above steps. The most likely cause is that MFCC ON did not run correctly.
The deployment environment, CapeConnect, is designed to expose Java components as Web services. To expose a COBOL program interface as a Web service, it must be wrapped by a Java class and that class deployed to CapeConnect. This is what the combination of the COBOL-to-Java Mapping Tool (Mapping Tool for short) and CapeStudio does - the former generates a Java wrapper for the COBOL application and the latter does the deployment.
When you use CapeStudio to deploy a Java application, CapeStudio generates a deployment package consisting of a WSDL file, data conversion information and an implementation package. When a SOAP message is received asking to invoke a Web service, CapeConnect under the guidance of the deployment package calls the Java application, converting the data from the SOAP message into Java datatypes and passing them on to the Java application as parameters.
When you use CapeStudio to deploy a COBOL application, the Mapping Tool generates the Java wrapper and then CapeStudio generates the deployment package, containing both the Java wrapper and COBOL implementation files. When a SOAP message is received asking to invoke the Web service, CapeConnect under the guidance of the deployment package calls the Java wrapper, converting the data from the SOAP message into Java datatypes and passing them on to the Java wrapper as parameters. The wrapper then converts them to COBOL data types and calls the COBOL application.
Your main task in preparing a COBOL application for deployment as a Web service is to use the Mapping Tool to generate the Java wrapper. You must show how the parameters to the Java wrapper will map onto the parameters to the COBOL program.
This section is a tutorial on using the COBOL Web services extension in CapeStudio and CapeConnect.
In this tutorial, you take a COBOL application and deploy it as a Web service. In real life, it might be a legacy application or one specially written for the purpose. It must be appropriate for use as a Web service - for example, an application that expected local input from ACCEPT statements would not be appropriate.
In this white paper, if we include the drive in a path we generally show it as x, since we don't know which drive you chose. You should replace x by the correct drive letter.
In this tutorial, we assume that Net Express is installed in x:\Net Express, the JDK in x:\jdk1.3.1_01, CapeStudio in x:\CapeClear\CapeStudio3.0, and CapeConnect in x:\CapeClear\CapeConnect3.5. If you have installed them elsewhere, please adjust the examples accordingly.
This tutorial uses the supplied sample application, a COBOL program called b-read.cbl. Once the service packs are installed, you will find this program (together with several other example programs) in directory x:\Net Express\Base\Demo\WEBSERVICES\Bookdb. It is a simple program that looks up a book in a stock file such as might be in use at a book retailer. The caller supplies the book's ISBN or title or author, and the program looks it up in an indexed file and returns full details of the book. If the book is not on file or there is a problem in reading the file, the program returns a file status showing the error.
You might want to look at the COBOL source while reading. You can display it in any text editor. The copyfile that it uses, b-rec.cpy, is in the same directory. The record defined by b-rec.cpy is used both as a file record and as the Linkage Section input and output.
Things to note about this program are:
As it stands, this interface is not suitable for a Java-wrapped Web service, because in Java all input parameters are expected to be initialized and only one output parameter is allowed (the return value). You will use the Mapping Tool to map the parameters to a parameter layout suitable for a Web Service.
For convenience, we will work in the Cape Clear software's Projects directory rather than in the Net Express directory where the example program is supplied.
So the path to b-read.cbl is now x:\CapeClear\Projects\Bookdb\b-read.cbl.
In this sample session you:
We start by building the program in Net Express or from the command line. For this example, we compile it to int-code, the machine-independent byte code that Net Express can generate. This enables us to deploy it to any Cape Connect server environment.
To compile the program from the command line:
cobol b-read.cbl noobj anim;
The program compiles with no errors, and a file b-read.int is created in x:CapeClear\Projects\Bookdb.
To create a project:
The project view appears.
To start the Mapping Tool:
The first page of the Mapping Tool appears, as shown in Figure 1.
Once this field has been filled in, the Select COBOL Program field displays all the COBOL programs in this source file. You need to select one, and one only, to be turned into a Web service. Because b-read is the only one in this source file, it is already selected.
Because you are creating a new Web service, not updating an existing one, there is no pre-existing mapping file; so leave the Existing Mapping File field blank.
Figure 1 : First Page of the COBOL-to-Java Mapping Tool
The second page of the Mapping Tool appears, as shown in Figure 2.
Figure 2 : Second Page of the COBOL-to-Java Mapping Tool
The panes on this page are as follows:
Figure 3 : With the Tree View Expanded
Let's look at what is in this pane. A COBOL program has one main entry point, its Program-Id. Its parameters are defined in the Procedure Division header. Any additional entry points are defined together with their parameters in ENTRY POINT statements. This program has just its Program-Id b-read, which has two parameters called lnk-b-details and lnk-file-status. This information was derived from the program source automatically when you started the Mapping Tool. If the program had additional entry points, they and their parameters would also appear here.
The layout of each parameter in a COBOL program is described in the Linkage Section. Each parameter appears there as a record. The COBOL Program pane shows all the records in the Linkage Section and their structure, that is, their subordinate data items. Linkage Section records need not all be used, but in this case we see that both are used - in the tree view, the two records lnk-file-status and lnk-b-details shown under Records both appear as parameters to b-read.
Each entry point in the COBOL program can be made into a function (also called an operation) in the Web service:
The Mapping Tool is now as shown in Figure 4.
Figure 4 : Default Layout of the Parameters to b-read
Notice that all hyphens in the left-hand pane have become underscores in the right-hand panes. Hyphens are commonly used in COBOL, but are not allowed in names in Java; so the Mapping Tool automatically replaces them by underscores.
The new operation has two parameters, corresponding to the two parameters to the COBOL entry point. Both are initially assumed to be input parameters, as shown by the next to them.
The Types pane defines the types of the Java objects that will be passed. The name of each elementary data item in COBOL has been used as the name of a type, based on the item's picture-string and equating to a suitable Java simple type. Leaving the mouse pointer over one of these types for a moment displays a tooltip showing its COBOL picture-string and Java type. The name of each record has been used as the name of a Java complex type, consisting of all the simple types corresponding to the record's elementary subordinate items.
Notice that the names of the types corresponding to records all start with capital letters. This is mandatory for these types.
This has produced the default mapping of the entry point b-read onto a Web service, but, as noted above, it cannot be used as it stands. This COBOL program uses lnk-b-details as both an input and output parameter - data is passed to the program in lnk-b-title, lnk-b-type, or lnk-b-author, and then the program fills in the rest of the record. In an all-COBOL system, the calling program could then read this record after the COBOL program returns. But in a Web service one SOAP message is received with the input data, and another must be sent back with the output data.
This also causes the input parameter Lnk_file_status to be deleted from under b_read in the Operations pane.
This leaves the screen shown in Figure 5.
Figure 5 : After Turning Lnk-b-details into a Purely Input Parameter
So we now have an input parameter that fits our specification of the b-read interface. We simply have to construct our output parameter to include the entire lnk-b-details record plus lnk-file-status.
This creates a new type, Lnk_b_details1, corresponding to this record.
This gives us a type, Out_type, that has all the fields the Web service needs to return.
This gives b_read an input parameter called Out_type, of type Out_type.
You are left with the screen shown in Figure 6.
Figure 6 : After Constructing the Input and Output Parameters
Sometimes you need to modify the types that have been created:
A tooltip appears showing the type's COBOL picture-string and the corresponding type of Java object. If you move the mouse pointer slowly from item to item you will see that all are mapped to String except for lnk_b_sold, which is mapped to BigDecimal. If you leave the mouse pointer over the name of a record, nothing happens.
The dialog box shows the type of Java object that data items of type lnk_b_retail will be mapped to. This numeric-edited type will be converted to a String type for Java. This is probably the correct behavior for an output parameter, but on input or for an output parameter that needs to be easily manipulated it might make more sense to have this seen in Java as a BigDecimal. You can do this easily by using the dropdown list in this property dialog.
Now specify the files to be generated and packaged for deployment:
The third page of the Mapping Tool appears.
If the data file were maintained by some other application, it couldn’t be deployed along with the application code - the application would need to make references to it outside of the Cape Connect deployment environment. However, for a static file or database, or one fully managed by the Web service, it's convenient to deploy it with the COBOL application.
We will accept the defaults for all other fields on this screen. The screen is now as shown in Figure 7.
Figure 7 : Ready to Generate
CapeStudio now generates all the Java classes and packages them in b_read.jar. CapeStudio also generates the .wsdl, .wsml, and .map files that it generates for any Web service. The Mapping Tool closes and you are returned to the CapeStudio Developer Center project window. It shows all the files that have been generated, as shown in Figure 8. The service is called B_read_service, and it is in a Java package called b_read.
Figure 8 : Generated Files Ready to be Deployed
To deploy the Web service:
The Create a WSAR File dialog box appears. This shows that b_read.jar, the COBOL deployment files, the .wsdl file, the .wsml file, and the .map file will be packaged together in b_read.B_read_service.wsar.
The Deploy Service dialog box appears. We will accept the defaults.
This deploys the Web service, by unzipping its .wsar file into CapeConnect's deployment directory.
Use the Web Services Tester in CapeStudio to test the new Web service. We'll ask the service for details of a book called Patterns in Java:
to insert the book title Patterns in Java, so that it reads:
<lnk_b_title xsi:type="xsd:string>Patterns in Java</lnk_b_title>
The Tester is now as shown in Figure 9.
Figure 9 : SOAP Request Ready to be Sent to our COBOL Web Service
The Tester sends the SOAP request to the Web service, and then displays in its right-hand pane the SOAP response returned by the service. Patterns in Java is the title of a book that is in the data file, so our COBOL Web service B_read_service finds it and returns its details, as shown in Figure 10. If you were to name a book not in the file, you would get the response shown in Figure 11, returning a file status of "23" - the COBOL file status value for "record not found".
Figure 10 : SOAP Request and the Response Returned from our COBOL Web Service
Figure 11 : Response Showing a Book is not in the File
The directory Net Express\Base\Demo\WEBSERVICES\Bookdb contains two other programs besides b-read.cbl. b-init.cbl is simply the program that created the indexed file initially. b-write.cbl adds a new record passed as a parameter. You might like to deploy b-write.cbl as a Web service for a further exercise.
b-write.cbl has the same physical interface as b-read.cbl, but a different logical interface. Its Procedure Division has two parameters with the following protocols:
This section gives detailed reference material on the COBOL Web Services feature.
For some time, it has been possible to write distributed systems in which software components are called by remote client applications across the Internet. However, you've always had to know the details of how a component was deployed - its language, whether it is an EJB or COM object, etc - and write your client application accordingly. The Web Services architecture does away with this need. All communication between client and component is done by passing text files containing data formatted in XML.
Many COBOL applications, because of the functions they include, would make useful Web services. To enable you to expose COBOL applications as Web services, Micro Focus has developed the COBOL-to-Java Mapping Tool, also known as the Mapping User Interface (MUI) or simply the Mapping Tool. The Mapping Tool is an extension to CapeStudio, a Web service development environment from Cape Clear.
CapeClear's CapeStudio exposes Java, EJB and CORBA components as Web services via a Web Services server platform called CapeConnect. An XML engine in CapeConnect converts SOAP messages from clients into the appropriate native method invocation for the Web service's functions - for example, for Java classes it converts them into Java local method invocations.
You use the Mapping Tool to extract and expose entry points and records from a legacy COBOL program. You can also narrow the COBOL records to remove superfluous data items from specific function calls. Once you've done this, the Mapping Tool generates Java classes that wrap the COBOL entry points and records you chose for exposure.
For more in-depth information on Web Services, see http://www.w3.org for discussions and the latest specifications of WSDL, SOAP, UDDI, etc.
Figure 12 shows how CapeConnect exposes a COBOL Web service.
Figure 12 : CapeConnect Exposing a COBOL Web Service using a Java Wrapper
The enabling tool mfcc.exe is installed by the Net Express 3.1 Service Pack #1. You can run it from the command line or from the Start menu. You use it to add the Mapping Tool to the CapeStudio menus. You also use it if you ever want to remove the Mapping Tool from the CapeStudio menus.
From the command line:
mfcc /on x:\CapeClear
where x:\CapeClear is the directory where CapeStudio and CapeConnect are installed, adds the function Generate WSDL from COBOL to the Design menu in CapeStudio.
mfcc /off x:\CapeClear
removes this function from the menu.
From the Start menu, clicking Start > Programs > Micro Focus Net Express > Configuration > MFCC ON brings up a prompt where you enter the directory where CapeStudio and CapeConnect are installed. The default is c:\CapeClear. Once you press Return at this prompt, it adds the function Generate WSDL from COBOL to the Design menu in CapeStudio.
Similarly, Start > Programs > Micro Focus Net Express > Configuration > MFCC OFF brings up a prompt where you enter the directory where CapeStudio and CapeConnect are installed. The default is c:\CapeClear. Once you press Return at this prompt, it removes this function from the menu.
You must restart CapeStudio for the change to take effect.
There are certain restrictions on the COBOL application. These are mostly common sense, arising from the fact that the program is being used as a self-contained component being called by remote users.
Before trying to expose a legacy COBOL application as a Web service, you must determine whether the application is suitable. Examine all the functions you intend to expose, and make sure they conform to the requirements in this section. You may need to do some restructuring.
In a large application, this might be be a major operation, involving considerable analysis of the application. For a discussion of analyzing legacy COBOL applications for Web deployment, see the white paper Web-enabling COBOL Applications with Net Express on the Micro Focus Web site.
These restrictions concern:
A Web service must be a pure function, that is, it must receive input data only via input parameters and must return its results only via the output parameter - there cannot be any user interaction. In other words, the COBOL application must not accept or display user data via ACCEPT and DISPLAY statements.
A Web service must be well-behaved - that is, it must run to completion, return its results to the client, and exit so that control returns to the server. Remember that one Web service stopping or crashing might well bring down the whole server.
Therefore, the COBOL application must handle all errors by returning an error indication in the output parameter, never by stopping. Care should be taken that all error conditions are detected - for example, use the FILE STATUS clause, declarative procedures, etc - so that the program does not crash or otherwise abort.
Similarly, the COBOL application should not contain a STOP RUN statement. When encountered during Web service execution, the STOP RUN statement is effectively a quit statement, making the program exit at once.
Multiple threads might well be requesting the same Web service at the same time. Therefore, every program in an application to be used as a Web service must be compiled with either the Reentrant or Serial directive. If a program is compiled as Reentrant(1) then access to Working Storage should be synchronized with a mutex or monitor - see the Net Express documentation for details.
The COBOL application must not create threads. Each Web service is intended to run in its own thread. When the Web service completes, the system cannot clean up anything other than the thread directly called by the Web service processor - therefore creating additional threads could cause memory leaks.
The COBOL application must not register procedures such as error procedures.
When you compile your COBOL application using Net Express, you need to choose which format to package it in:
Once you have compiled and packaged your COBOL application in Net Express and have finished using the Mapping Tool in CapeStudio, deployment is exactly as for a Java application. You use Deploy > Package to put the .jar file and all other files for deployment into a .wsar file, then Deploy > Service to deploy it, placing it into CapeConnect's deployment directory. You can then use Deploy > Web Service Tester to test it. Except for the mention of COBOL files in the list of files on the Create a WSAR File dialog box displayed by Deploy > Package, the fact that the application is actually in COBOL is invisible.
The program gets deployed as a stateless Web service, that is, one with no memory of previous invocations by the same client.
This section formally defines how you use the fields on the three steps of the Mapping Tool.
The three steps are:
In this Step you specify the source of the application to be deployed as a Web service, and if you are modifying a Web service created earlier you specify the file containing its existing mapping.
This Step has the following fields:
COBOL Source File
Name of the COBOL source file containing the program to be turned into a Web service.
You must set this using the Browse button, not by typing - using Browse causes the Select COBOL Program field to get set automatically.
Existing Mapping File
Name of an XML file showing how the parameters of the program(s) in the COBOL source file are mapped to Java.
Leave this blank if you are creating a new Web service - you will create the mapping at the next step. This file exists only if you have already created this Web service - specifying it here causes the mapping to be loaded at the next step, so you can modify it.
Select COBOL Program
Lists the source programs in the file specified in the COBOL Source File field.
The list gets put here when you set Selected Source File using Browse. Click to select the program you want to make into a Web service.
In this Step you choose the COBOL entry points to become functions in theWeb service, and you show how parameters to the Web service (in SOAP mapped directly into parameters to the Java wrapper) are to be mapped onto the parameters to the COBOL program.
If you specified a mapping file at Step 1, it is reloaded here. Otherwise, this page is initialized to the default mapping, as described below.
This section talks about how parameters to an entry point of the COBOL program map onto the parameters of the method that calls it in the Java wrapper. Bear in mind that when a SOAP message invokes a function of a Web service, the SOAP input parameters are passed to the Java method in the method's input parameters, and the method's return value is passed back as the result in the SOAP message that is returned to the client.
To use Properties on an item you right-click the item, click Properties on the popup menu, make the desired change, and click OK.
This Step has the following panes:
A tree view showing the program's entry points with their parameters, and the program's Linkage Section records with their subordinate items.
You use this as the source pane from where you drag items to the two other panes to make them into functions of the Web service or map them onto Java data types.
See the sections on those panes for details.
There are some restrictions:
Shows each function of the Web service, with its parameters. Drag an entry point into here from the COBOL Program pane to expose it as a function of the Web service.
Initially, no functions are defined. When you drag an entry point into here, its parameters become parameters to the Web service. If there is only one parameter, it becomes both an input and output parameter. If there is more than one, they all become input parameters.
You normally need to rearrange the parameters to make them suitable for the Web service. Note that, like a Java class, a Web service can have only one output parameter - whereas in COBOL any USING parameter passed BY REFERENCE can be used to return data.
A Java method is generated to call this entry point, and entries are added to this service's WSDL file so that in response to SOAP messages requesting this function CapeConnect will invoke this method.
Lists the Java data types available for use as input parameters or return values for the functions of the Web service.
Initially, contains a data type for each elementary data item and each record in the Linkage Section:
You do most of the work of specifying the mapping in here, creating Java types from the types generated initially to correspond to the COBOL data items.
When using the Web Services Tester, if you pass an input parameter with a null value (by not inserting anything between its tags in the SOAP request), the null value is used rather than the parameter's default value. This generally results in a NullException if the parameter is required to be set. To use the default value you must actually delete the parameter from the incoming message.
For example, in the Web service shown in the above tutorial, if lnk_b_author were defined with a default value, the default value would be used only if you deleted the line:
from the SOAP request shown in the section Test the Web Service.
In this Step you specify the files to be deployed, and how they are to be packaged.
This Step has the following fields:
Name of the directory that the files are to be generated into.
Java Wrapper Class
Name for the Java wrapper to be generated.
Java Package Name
Name for the package to contain the wrapper class.
Also contains some associated generated Java classes.
Name for the .jar file to contain the wrapper class.
Also contains some associated generated Java classes.
Name for the file to store the mapping that you did in Step 2 of the Mapping Tool.
You reload this if you later want to modify the mapping.
COBOL Files to Deploy
All files needed to run the COBOL program.
Its executable file such as its .int file, and any data files it needs.
Copyright © 2002 Micro
Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.