To compile COBOL source code that uses JNI services or contains OO syntax such as INVOKE statements or class definitions (that is, COBOL code that directly communicates with Java):

• Use the following compiler options: RENT, DLL, THREAD, and DBCS.
  The RENT and DBCS options are IBM-supplied defaults.
• Set PGMNAME(LONGMIXED) for long name support.
• Set the RECURSIVE attribute on COBOL classes and methods or on COBOL programs that invoke Java methods.

Compiling the COBOL with DLL affects the overall COBOL program structure. In general, DLL-linkage-built COBOL programs can only call out to other external DLL-linkage-built programs. Similarly, dynamic call built COBOL programs can only call out to other external dynamic call built programs. However, static linking of objects with either two of these external program call mechanisms is allowed. This provides the bridging between the DLL linkage that Java requires and the traditional COBOL dynamic call.

The link step creates an executable DLL module. It is required to link the object file with the following two DLL side files:

• libjvm.x, which is provided with your IBM Java SDK
• igzcjava.x, which is provided in the lib/ subdirectory of the COBOL directory in the HFS. The typical complete path is /usr/lpp/cobol/lib/igzcjava.x.
  This DLL side file is also available as the member IGZCJAVA in the SCEELIB PDS (part of Language Environment).

If the application starts with a Java program or the main factory method of a COBOL class, the XPLINK environment is automatically started by the java command that starts the JVM and runs the application.

If an application starts with a COBOL program that invokes methods on COBOL or Java classes, you must specify the XPLINK(ON) runtime option so that the XPLINK environment is initialized. XPLINK(ON) is not recommended as a default setting. Use XPLINK(ON) only for applications that specifically require it.

In older versions of COBOL, using the COPY statement required the compiler option ‘lib’. This option is not required in Enterprise COBOL v5 and up, and it is always in effect.

For more information, see “Compiling, linking, and running OO applications” in the Enterprise COBOL for z/OS Programming Guide.

Java and COBOL under z/OS UNIX

When you compile, link, and run OO applications in a z/OS UNIX environment, application components reside in the HFS. The compilation and linking is done using z/OS UNIX shell commands, and application is launched via a shell command prompt or with the BPXBATCH utility from JCL or TSO/E.

For compilation use: cob2 -c -qdll,thread
For linking use: cob2 -bdll

The -bdll option specifies that the executable module is to be a DLL. In addition:

• The COBOL compiler uses the compiler options DLL, EXPORTALL, and RENT, which are required for DLLs.
• The link step produces a DLL definition side file that contains IMPORT control statements for each of the names exported by the DLL.

You need to specify the include subdirectory of the JNI.cpy by using the -I option of the cob2 command or by setting the SYSLIB environment variable. The JNI.cpy resides under the include subdirectory of the COBOL installation directory (typically, /usr/lpp/cobol/include).

Example: Java calling procedural COBOL

Process pgmname(longmixed),lib,dll,thread

       IDENTIFICATION DIVISION.
       PROGRAM-ID.    "Java_StringTest_printStrings" is recursive.

       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.

       INPUT-OUTPUT SECTION.
       DATA DIVISION.
       Local-storage section.
       01 I pic s9(9) binary.
       01 P pointer.
       01 SAelement pic s9(9) binary.
       01 SAelementlen pic s9(9) binary.
       01 Sbuffer pic X(50) .
       01 rc Pic s9(9) Comp-5.


       LINKAGE SECTION.
       01 SA  PIC S9(9) BINARY.
       01 SAlen pic s9(9) binary.
       01 ENV-PTR   USAGE POINTER.
       01 OBJECT-REF  PIC S9(9) BINARY.

       COPY JNI SUPPRESS.

       PROCEDURE DIVISION USING BY VALUE ENV-PTR //two JNI 'hidden' parms
                                     OBJECT-REF
                                     SA
                           RETURNING SAlen.

           Set address of JNIEnv to ENV-PTR
           Set address of JNINativeInterface to JNIEnv


           Call GetArrayLength using by value ENV-PTR SA
              returning SAlen
           Display " >> COBOL method entered array len: " SAlen

           Perform varying I from 0 by 1 until I = SAlen
              Call GetObjectArrayElement
                 using by value ENV-PTR SA I
                 returning SAelement
              Call "GetStringPlatformLength"
                 using by value ENV-PTR
                                SAelement
                                address of SAelementlen
                                0
                 returning rc
              Display "Returned from GetStringPlatformLength"
              If rc Not = zero Then
              Display "Error occurred retrieving len of jstring object"
              Stop run
              Else
              Display "The length of returned string is:"
              SAelementlen
              End-if
              Call "GetStringPlatform"
                 using by value ENV-PTR
                                SAelement
                                address of Sbuffer
                                length of Sbuffer
                                0
              Display Sbuffer(1:SAelementlen)
           End-perform

            .
           GOBACK.

/usr/lpp/java/IBM/J7.1/bin/javac StringTest.java
/usr/lpp/java/IBM/J7.1/bin/java -Djava.library.path=. StringTest

class StringTest
{
   static {
     System.loadLibrary("StringTest");
   }

static native int printStrings(java.lang.String[] SA);

public static void main(String argv[]) throws Exception
   {
    int i;
    String[] a = new String[3];
    a[0] = "John";
    a[1] = "White";
    a[2] = "1234567890";
    StringTest st = new StringTest();
    i = StringTest.printStrings(a);
    System.out.println("Number of elements printStrings read:" +i);
    return;
   }
} 

This example demonstrates how an object-oriented COBOL application invokes a Java program on UNIX System Services (USS).

For COBOL applications calling Java, you need the LIBPATH to point to the path for the Java libraries.

LIBPATH=/usr/lpp/java/IBM/J7.1/bin/classic:$LIBPATH

Also, use the _CEE_RUNOPTS environment variable to set the XPLINK(ON) option :

_CEE_RUNOPTS="XPLINK(ON)"

Exporting _CEE_RUNOPTS=”XPLINK(ON)” so that it is in effect for the entire z/OS UNIX shell session is not recommended, however. Suppose for example that an OO COBOL application starts with a COBOL program called App1. One way to limit the effect of the XPLINK option to the execution of the App1 application is to set the _CEE_RUNOPTS variable on the command-line invocation of App1Driver as follows:

_CEE_RUNOPTS="XPLINK(ON)" App1

The following example demonstrates how an OO COBOL application invokes a Java program by using INVOKE.

The COBOL program is compiled and linked as follows, where a typical installation path for COBOL is /usr/lpp/cobol and a typical installation path for Java is /usr/lpp/java. Replace with your own paths for your environment.

/usr/lpp/cobol/bin/cob2 -c -qthread,dll helloTest.cbl
/usr/lpp/cobol/bin/cob2 -bdll helloTest.cbl -o hello /usr/lpp/java/IBM/J7.1/bin/j9vm/libjvm.x /usr/lpp/cobol/lib/igzcjava.x -I /usr/lpp/cobol/include

helloTest.cbl

Process thread,pgmname(longmixed)
IDENTIFICATION DIVISION.
PROGRAM-ID. "HELLOWORLD" is recursive.
*
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. RM-COBOL.
OBJECT-COMPUTER. RM-COBOL.
       
Repository.
    Class HelloJ is "HelloJ".
DATA DIVISION.
FILE SECTION.
       
PROCEDURE DIVISION.
       
MAIN-LOGIC SECTION.
BEGIN.
    DISPLAY " " .
    INVOKE HelloJ "sayHello".
    DISPLAY "Hello world!".
    STOP RUN.
MAIN-LOGIC-EXIT.
    EXIT.

The following HelloJ.java program is compiled and exported by using the following commands in USS:

/usr/lpp/java/IBM/J7.1/bin/javac HelloJ.java

export _CEE_RUNOPTS="XPLINK(ON)"
export LIBPATH=/usr/lpp/java/IBM/J7.1/bin:/usr/lpp/java/IBM/J7.1/bin/classic:$LIBPATH
export CLASSPATH=:$CLASSPATH

HelloJ.java

class HelloJ {
   public static void sayHello() {
     System.out.println("Hello World, from Java!");
   }
}