Chapter 11: Calling OO COBOL from Java

This chapter describes how you can access COBOL objects from Java programs. This is slightly different from the method for accessing procedural COBOL from Java programs (see the chapter Calling Procedural COBOL from Java for information about this).

Overview

You can write classes in OO COBOL which can be called from Java programs as though they were Java classes. You do this by providing a Java wrapper class, which provides a function for each method in the OO COBOL class. The Net Express Class and Method Wizards make this easy for you, by generating the Java code at the same time as the COBOL code.

The functions in the Java wrapper class put all the parameters for the method into a Java array, and then call one of the member functions of Java class com.microfocus.cobol.RuntimeSystem to invoke the method in the OO COBOL class and return the result. This is shown in the diagram below:

image under construction

Figure 11-1: Path of a Function Call from Java to a Method Invoked in COBOL

The rest of this chapter explains how you write the OO COBOL class and its Java wrapper, and shows you the type of code created by the Net Express wizards.

You need to have at least a basic knowledge of the Java language to be able to use this technology effectively. Sun's Java site is a good starting place.

Before You Start

Before starting, you need to set up your environment so that the COBOL and Java run-time systems can interact. See the section Setting Up the Environment for Java and COBOL in the chapter Using Java and COBOL Together.

Writing a Java Class in OO COBOL

To write a class in OO COBOL which can be called from Java, you need to do the following:

  1. Set the following directive in your program:
    $set ooctrl(+p-f)
  2. The OO COBOL class must inherit from javabase.

  3. Create a Java wrapper class for the OO COBOL class. The wrapper class must have the same class name as the filename of the OO COBOL class.

  4. Each method you create in your OO COBOL class must have a corresponding method in the Java wrapper class.

  5. You must package the class inside a .dll file when deploying it on Windows platforms.

    You can also use classes compiled to .int or .gnt, but this does not allow you to package several classes inside one file.

If you use the Net Express Class Wizard to create a Java class in OO COBOL, it creates the OO COBOL class with the correct inheritance and directives. It also creates the Java wrapper class. See Class Wizard.

Importing the COBOL Support

The support needed for the Java wrapper class to communicate with the OO COBOL class is in the com.microfocus.cobol package. The wrapper must include the following statement:

import com.microfocus.cobol.* ;

You must also ensure mfcobol.jar is on the Java classpath, or your Java programs will not compile or run. See the section Setting Up the Environment for Java and COBOL in the chapter Using Java and COBOL Together.

The Wrapper Class

The Java wrapper class must extend either microfocus.cobol.RuntimeObject or microfocus.cobol.RuntimeSystem. This affects the lifetime of the OO COBOL instances represented by instances of the Java wrapper class:

The wrapper class needs to be initialized with the library and filename of the COBOL class it is wrapping. You do this by including the following code inside the Java wrapper class:

 static
{
cobloadclass("libname", "filename", "fullJavaClassName") ;
}

where:

libname is the name of the .dll file which contains the OO COBOL class. You can leave this parameter as null if the class is not packaged inside a .dll file - for example, if it is running as .int or .gnt code.
filename is the filename of the OO COBOL class.
FullJavaClassName is the Java classname corresponding to the OO COBOL class.

There are three cobloadclass() methods altogether in microfocus.cobol.RuntimeSystem, which provide slightly different ways of identifying the library, COBOL file and the Java wrapper class.

Adding and Removing Methods

Every method you add to the COBOL class must have a corresponding function in the Java wrapper class. The Net Express Method Wizard adds methods to the Java wrapper class automatically if you use it to add methods to a COBOL Java class. However, if you subsequently delete a method from the COBOL class, you must delete it manually from the Java wrapper class.

See Class Wizard.


Note: When you use the Method Wizard to add a method that accepts String or StringBuffer parameters, the Method Wizard creates 32-byte data items (PIC X(32)) to receive these parameters. If the string passed is shorter than 32 bytes, it is terminated with a null byte (x"00") and the contents of the bytes between the null byte and byte 32 are undefined. As a result, you should determine the actual length of the passed string before processing it, by using code such as the following:

MOVE 0 TO received-length
INSPECT passed-string TALLYING received-length FOR CHARACTERS BEFORE INITIAL x"00"
MOVE passed-string(1:received-length) TO actual-string


The rest of this section describes how you code a Java function in the wrapper class by hand, without the use of the Method Wizard.

The Java function must do the following:

  1. Declare the exceptions which can be thrown from an invoke of a COBOL method.

    By default, these are Exception (thrown if you raise an exception in COBOL) and CobolException (thrown by the COBOL run-time system). If your class is to be deployed either as an Enterprise JavaBean, or using Java Remote Method Invocation (RMI), you should also add RemoteException.

  2. Construct a Java array containing the parameters to be passed from Java to the COBOL method.

    Parameters are passed from Java to the COBOL run-time system in a Java array.

  3. Invoke one of the cobinvoke_ or cobinvokestatic_ methods provided by the class RuntimeSystem.java.

    There is a cobinvoke_ and cobinvokestatic_ method corresponding to each possible return type from a Java function (for example, cobinvoke_int returns an int). Use the cobinvoke_ methods for invoking OO COBOL instances. Use the cobinvokestatic_ methods for invoking OO COBOL classes.

    See the Java Run-time Class Library Reference. for the full list of cobinvoke_ functions.

    You need to determine which Java data type maps to the return type from the COBOL method, and then choose the appropriate cobinvoke_ function. See the chapter Java Data Types for more information.

OO COBOL class methods are mapped onto static functions in the Java wrapper.

The two code samples below show a COBOL instance method, and the corresponding function in the Java wrapper. This is the COBOL method.

 method-id. "myMethod".
local-storage section.
*>---USER-CODE. Add any local storage items needed below.
linkage Section.
01 myParameter pic x(4) comp-5.
01 myReturnValue pic x(4) comp-5.

procedure division using by reference myParameter
returning myReturnValue.
*>---USER-CODE. Add method implementation below.
exit method.
end method "myMethod".

This is the Java wrapper method.

public  int myMethod (Integer myParameter) throws Exception, 
CobolException, RemoteException
{
// Parameters are passed to COBOL in an array
Object[] params = {myParameter};
return ((int) cobinvoke_int ("myMethod", params)); }

Although the name of a method is usually the same for the Java wrapper class and the COBOL class, it does not have to be. This enables you to implement method overloading in the Java wrapper.

Method overloading enables you to have several methods with the same name, but which take different types or numbers of parameters. Java supports method overloading, but COBOL does not. But you can add overloaded functions to the Java wrapper, and have them call differently named methods in the COBOL class.

For example, you could have these overloaded functions in your Java wrapper class:

public int add (int a, int b) 
{...}
public int add (int a, int b, int c)
{...}

And map them to methods "add2" and "add3" in your COBOL class.

When you use the Method Wizard in Net Express to add methods to a COBOL class which has been generated as a Java class, you have the option of giving the method a different name in the Java wrapper and the COBOL class.

Throwing Exceptions from COBOL

You can throw a Java exception from your COBOL code. The exception object can be any Java class. The methods for throwing exceptions are provided in the javasup class, which is documented in your Class Library Reference. .

You can use either of the following methods:

invoke javasup "throwException" using aCOBOLProxy

where:

aCOBOLProxy is a COBOL proxy to any Java object of type Throwable.

or:

invoke javasup "throwNewException" using javaclassname
description

where:

javaclassname is the name of the class of Java exception to throw.
description is a text description of the exception.

Using BY REFERENCE Parameters

When parameters to a method are declared as BY REFERENCE, the default behavior is for any updates to those parameters to be reflected in the corresponding Java objects in the calling Java class on return from the OO COBOL method.

If you do not want the Java objects to be updated, you can set the following static variable:

static boolean mfcobol.runtimeProperties.updateByRefParams;

The default value for this variable is true. Set it to false if you do not want the Java objects to be updated.


Note: In an earlier version of Net Express, the default behavior was for updates to BY REFERENCE parameters not to be reflected in the calling Java. If you have existing Java code that makes use of that behavior, you need to modify it to set mfcobol.runtimeProperties.updateByRefParams to false.


Net Express includes a demonstration program that illustrates the different ways of handling BY REFERENCE parameters. The folder NetExpress\Base\Demo\Javademo\OOCOBOL\Record contains all relevant files for the demonstration program, as well as a readme.txt file to explain the program in detail.

Passing Java Data to COBOL Structures

Net Express enables you to specify structures in the Linkage Sections of your COBOL programs and OO COBOL methods that you can use to pass data from a Java class. For more information on how to access Java data from your COBOL programs or OO COBOL methods in this way, see the section Using Structures in the chapter Java Data Types.

Working with Java Programs

This section contains important information you should know when using Net Express to work with Java programs.

Creating JAR Files

The JAR (Java archive) file format is widely used to distribute Java applications. If you want to distribute your Net Express-based Java classes as JAR files, you can do this in the same way as you would package files as Zip or executable files. 

Net Express lets you change the settings it uses when creating JAR files. By default, when creating a JAR file, Net Express uses the following options to the Jar command:

If you need to specify options other than the defaults, you can change these options in the same way as for other build settings.

Demonstration Programs

Net Express includes some demonstration programs that illustrate different aspects of calling OO COBOL from Java. These demonstration programs are contained in directories beneath NetExpress\Base\Demo\Javademo\OOCOBOL. Each directory includes all relevant program files, as well as a readme.txt file to explain the programs in more detail.

The following table shows the directories containing the demonstration programs and gives a brief description of the purpose of the demonstration:

Directory
Illustrates
arrayReceiving and accessing a Java array in OO COBOL.
Creating a Java array in OO COBOL and passing it to Java.
record
Writing a simple COBOL Java object.
Receiving structures in OO COBOL methods from Java objects that implement the DataType interface.
Passing parameters BY REFERENCE.
simpleWriting a simple COBOL Java object.
Calling both class and instance OO COBOL methods using Java.
sortWriting a simple COBOL Java object.
Calling OO COBOL methods using Java.
Calling Java methods using OO COBOL.
Dealing with Java objects as parameters and return values.


Copyright © 2003 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.