JAVA-CALLABLE

General rules

The JAVA-CALLABLE directive must appear before the PROCEDURE DIVISION header for the outermost program of a compilation unit, and in a file that contains multiple compilation units, the JAVA-CALLABLE directive can only be used in the first function or program compilation unit in the file..

Since a Java-callable program is invoked dynamically by the call stub, the program name must be 8 characters or less.

The generated native method call stub program is written to a z/OS UNIX directory that is specified by the JAVAIOP(OUTPATH(zos-unix-directory)) compiler option. If that option is not in effect, the default output location is the current directory if the compiler is being run from the cob2 utility; otherwise, the output location is the home directory of the userid under which the compiler is running.

<cobol-program-name>_java_native.cbl

where cobol-program-name is the name of the COBOL program that is being compiled as specified in the program's IDENTIFICATION DIVISION.

Handling parameters and returned values

• If the COBOL program containing the JAVA-CALLABLE directive specifies parameters through the USING phrase of its PROCEDURE DIVISION header, the native method call stub program that is generated by the compiler automatically handles conversions between incoming Java arguments and the parameter types of the user COBOL program before calling that program. Using the data definition of the COBOL program's parameters, the compiler assumes the incoming Java argument values are in a format that adheres to the COBOL/Java type mapping and code to do the conversion is generated accordingly. For mapping details, see Legal COBOL types for Java interoperability and corresponding Java types.
  Note: For parameters that are fixed length tables, if the numbers of elements in the incoming Java array argument does not match the number of elements indicated in the OCCURS clause of the table definition in the corresponding COBOL parameter, a runtime error will occur. For mapping details, see Legal COBOL types for Java interoperability and corresponding Java types.
• If the COBOL program containing the JAVA-CALLABLE directive also contains a RETURNING phrase in its PROCEDURE DIVISION header, then after the user program is called, the native method call stub program will automatically convert the returned COBOL value to its corresponding Java value that is then returned to the Java caller. For mapping details, see Legal COBOL types for Java interoperability and corresponding Java types.
  Note: When a call is made from a Java program to a COBOL program compiled with the JAVA-CALLABLE directive, the Java program will use a signature for the COBOL native method that is generated by the COBOL compiler itself and is based on the definition of the COBOL program and its parameters and possible returned value. This allows the Java program to perform compile-time checking to ensure that only arguments of the appropriate Java type can be passed to the COBOL program.

Data access properties

Some data types are treated as read-only data items and some are treated as read/write data items when passed as parameters in the following cases:

• A COBOL parameter that corresponds to a primitive Java type (that is, byte, short, int, long, float, double or boolean) is treated as a read-only data item in a COBOL/Java interoperable application, regardless of whether the parameter is defined as BY REFERENCE, BY VALUE, or BY CONTENT. If a COBOL program modifies such a parameter value, the change is not reflected in the Java caller. This also applies to COBOL parameters that correspond to the immutable Java classes java.lang.String and java.math.BigDecimal.
• A COBOL parameter that corresponds to a single-dimension array of a primitive Java type (that is, byte[], short[], int[], long[], float[], double[], or boolean[]). If the COBOL program modifies such a parameter value, the change is reflected in the Java caller. This behavior is consistent with the semantics of arrays of primitive types when they are used as parameters in a pure Java application.
• Changes to a COBOL parameter that is an alphanumeric group item will be reflected in the Java caller.

Building COBOL native method call stub programs

The COBOL native method call stub program, along with any other COBOL stub programs that are generated by the compiler for the application, must be compiled into a Java native method DLL using the cjbuild tool. See Building and running non-OO applications that interoperate with Java in Enterprise COBOL Programming Guide for more details. This native method DLL will be loaded into the JVM at run time when a call is made to a COBOL program from Java. If the output location of the DLL is specified as a data set to cjbuild, then that data set must be in your STEPLIB at run time. If the output location of the DLL is specified as a z/OS UNIX directory, then JVM property java.library.path should be set to indicate that directory, which can be done by adding -Djava.library.path=<path> to the "java" command used to execute the Java application.

Invoking COBOL programs from Java

COBOL programs containing the JAVA-CALLABLE directive are considered to be native methods in a class called "progs". The class is part of a package whose name is provided to the cjbuild utility. If no package name is specified when using cjbuild, the name of the package defaults to enterprise.COBOL.

import enterprise.COBOL.*;

:

enterprise.COBOL.progs.COBPROG1(...);

If the name of a Java-callable COBOL program is not specified as a literal in the IDENTIFICATION DIVISION, then the name of the corresponding COBOL native method in Java will be the upper-cased version of the program name. If the name of the Java-callable program is specified as a literal in the IDENTIFICATION DIVISION, then the case of the letters in the corresponding COBOL native method name in Java will match the case of the letters in the literal exactly.