Calling Java from COBOL

Java Data Types

Chapter 4: Calling Object COBOL from Java

This chapter describes how you can access COBOL objects from Java programs. This is slightly different to the method for accessing procedural COBOL from Java programs (see the chapter Calling Procedural COBOL from Java for more information about this). It also describes how you can create Enterprise JavaBeans using COBOL.

4.1 Overview

You can write classes in Object 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 method for each method in the Object 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 methods in the Java wrapper class put all the parameters for the method into a Java array, and then call one of the methods of Java class mfcobol.runtime to invoke the method in the Object COBOL class and return the result. This is shown in Figure 4-1:

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

The rest of this chapter explains how you write the Object COBOL class and its Java wrapper, and shows you the type of code created by the Net Express wizards. The last section describes the additional things you need to do if you want to make an Object COBOL class suitable for use as an Enterprise JavaBean (EJB).

You must have set up your COBOL and Java environments before you can use this technology; see the chapter Before You Start.

4.2 Writing a Java Class in Object COBOL

To write a class in Object COBOL which can be called from Java, you need to:

1. Set the following Compiler directive in your program:

   $set ooctrl"+p-f"

2. Ensure that the Object COBOL class inherits from javabase.

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

4. Ensure that each method you create in your Object COBOL class has a corresponding method in the Java wrapper class.

5. 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 Object COBOL, it creates the Object COBOL class with the correct inheritance and directives. It also creates the Java wrapper class. For more information about the Class Wizard, click Help Topics on the Net Express Help menu, then look up Class Wizard in the index.

4.2.1 Importing the COBOL Support

The support needed for the Java wrapper class to communicate with the Object COBOL class is in the mfcobol package. The wrapper must include the following statement:

import mfcobol.* ;

You must also ensure mfcobol.jar is on the Java classpath, or your Java programs will not compile or run (this is covered in the chapter Before You Start).

4.2.2 The Wrapper Class

The Java wrapper class must extend either mfcobol.runtimeObject or mfcobol.runtime. This affects the lifetime of the Object COBOL instances represented by instances of the Java wrapper class:

• When the wrapper inherits from mfcobol.runtimeObject, if a wrapper object is destroyed by the Java garbage collector, the corresponding Object COBOL instance is finalized.

• When the wrapper inherits from mfcobol.runtime, the Object COBOL instance is finalized whenever execution exits from a method, losing any instance data.

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("shared-obj-name", "filename", 
        "fullJavaClassName") ; 
 }

where the parameters are:

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

4.2.3 Adding and Removing Methods

Every method you add to the COBOL class must have a corresponding method 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.

For more information about the Method Wizard, click Help Topics on the Net Express Help menu, then look up Method Wizard in the index.

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

The Java method 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 runtime.java.

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

   See the section Java Support Classes for COBOL in your 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_ method. See the chapter Java Data Types for more information.

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

The two code samples below show a COBOL instance method, and the corresponding method 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 methods to the Java wrapper, and have them call differently named methods in the COBOL class.

For example, you could have these overloaded methods 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.

4.2.4 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 the section Java Domain Class Library in your Class Library Reference

You can use either of the following methods:

invoke javasup "throwException" using aCOBOLProxy

where :

or:

invoke javasup "throwNewException" using javaclassname
description

where :

4.2.5 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 Object 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 Server 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.

Server Express includes a demonstration program that illustrates the different ways of handling BY REFERENCE parameters. For further information see the section Demonstration Programs.

4.2.6 Passing Java Data to COBOL Structures

Server Express enables you to specify structures in the Linkage Sections of your COBOL programs and Object 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 Object COBOL methods in this way, see the section Using Structures in the chapter Java Data Types.

4.3 COBOL Enterprise JavaBeans

You can create COBOL Enterprise JavaBeans either by hand, just using the facilities provided within Server Express, or by using the Net Express Class Wizard. We recommend that you use the Net Express Class Wizard. For assistance with creating COBOL Enterprise JavaBeans by hand, contact Product Support.

The Net Express Class Wizard enables you to create a COBOL class for use as an Enterprise JavaBean (EJB). EJBs are software components which run on application servers. The application server is responsible for all the services required by the bean, such as security, transaction integrity and persistence, so that EJBs only need to implement business logic. For more information about EJBs, see Sun's Java site.

When you check Enable for Enterprise JavaBeans on the Java Details page of the Net Express Class Wizard, it creates the following files:

• classname.cbl

  The COBOL file for your class. You have the option of having a filename different from the classname.

• classname.java

  The Java wrapper class.

• classnameHome.java

  The home interface to your Java wrapper.

• classnameRemote.java

  The remote interface to your Java wrapper.

When you generate an EJB, the Class Wizard also adds five methods to your class:

• ejbRemove
• ejbActivate
• ejbPassivate
• setSessionContext
• ejbCreate

These methods are part of the SessionBean interface, which is implemented by all EJBs. You need to add code to the first three of these methods; the wizard adds default code to setSessionContext to store a Java context object as part of the instance data of your COBOL class.

ejbCreate is a method which can be overloaded in an EJB, enabling you to provide different parameters for initializing a Java bean on instantiation. The wizard adds an ejbCreate method, which takes no parameters, to your EJB and a corresponding create method to the remote interface class (classnameRemote.java). The create method on the classnameRemote.java returns a remote interface object.

Each method you add to the COBOL class must be added to the Java wrapper class, and also to the remote interface class. If you use the Net Express Method Wizard, it updates the wrapper and remote interface automatically for you.

4.4 Demonstration Programs

Server Express includes some demonstration programs that illustrate different aspects of calling Object COBOL from Java. These demonstration programs are contained in directories beneath $COBDIR/demo/java/oocobol. Each directory includes all relevant program files, as well as a text file for each demonstration to explain the program in more detail. The text files have names of the form demonstration-name.txt, where demonstration-name is the name of the demonstration program. These demonstration programs are also supplied in Net Express, in directories under Base\Demo\Javademo\Oocobol in the directory where Net Express was installed.

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

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

Calling Java from COBOL

Java Data Types