Calling static Java methods from COBOL
In a CALL statement where the called subprogram is identified by a literal of the form 'Java.java-class-name-1.java-static-method-name-1', the call is interpreted as a call from COBOL to a static Java™ method with class name 'java-class-name-1' and method name 'java-static-method-name-1', where 'java-class-name-1' is a Java class name that must be fully-qualified with its package name if it belongs to a package.
- The literal prefix "Java." is not case sensitive, so prefixes like 'JAVA.' and 'jaVA.' are accepted. However, the remaining portion of the string is case sensitive and the fully-qualified class name and static method name must match what is used in Java.
- If the static method being called is part of one or more nested classes, then the name of each
nested class involved must be introduced in the literal with a $ character. For example, to call
static method "dumpData()" in class Util which is nested inside an outer class TestApp, the CALL
statement should be as follows:
CALL 'Java.TestApp$Util.dumpData' USING ...If TestApp is part of a package named com.acme, the CALL statement should be as follows:
CALL 'Java.com.acme.TestApp$Util.dumpData' USING ....
In this scenario, a Java call stub program that is automatically generated by the COBOL compiler will serve as an interface between the COBOL calling program and the static Java method that is the intended target of the call. At run time, when the CALL statement is executed, the call stub program is executed first, and the call stub program then uses Java Native Interface (JNI) routines to make the call to the specified static Java method.
The generated Java method call stub program is written to a z/OS UNIX directory that is specified by the JAVAIOP(OUTPATH(zos-unix-directory)) 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.
Java.java-class-name-1.java-method_name-1.cblHandling parameters and returned values
- If the CALL statement contains the USING phrase, indicating that arguments are being passed to the static Java method, the Java call stub program that is generated by the compiler automatically handles conversions between outgoing COBOL argument types and their corresponding Java types before calling the Java method. The conversions are performed according to the COBOL/Java type mapping defined in Legal COBOL types for Java interoperability and corresponding Java types. The conversion code is generated accordingly.
- If the CALL statement contains a RETURNING phrase, then after the Java static method is called, the Java call
stub program will automatically convert the returned Java
value to the type of the COBOL receiver indicated in the RETURNING phrase. This conversion is
performed according to the mapping defined in Legal
COBOL types for Java interoperability and corresponding Java types.Note: There is no type conformance checking at compile time or run time between outgoing COBOL arguments and Java method parameters or between incoming Java returned value and the type of the corresponding COBOL receiver. If outgoing COBOL arguments or incoming Java returned values are not in the correct format for the corresponding Java or COBOL receiver, unpredictable results, including program abend, can occur at run time.
Building Java call stub programs
Java call stub programs must be compiled along with any other stub programs for the application into a DLL using the cjbuild utility. See Compiling, linking, and running non-OO COBOL applications that interoperate with Java for details.
If it is possible for this call to Java to be executed in the application before any Java code is executed in the application, then it will be the Java call stub program for this call that is responsible for starting the Java virtual machine (JVM) for the enclave in these scenarios. To specify that non-default JVM initialization options are to be used when starting the JVM at run time, in addition to any other options used to compile the program making the call, specify option "JAVIOP(JVMINITOPTIONS(jvm-init-string))" as well. Alternatively, the COBJVMINITOPTIONS environment variable can be set at run time for the application.
- Literals of any kind are not permitted as arguments in calls to static Java methods.
- A single Java call stub program is generated for all calls to a particular static Java method in an application, so the static Java method cannot be overloaded and all calls to the static method must have the same argument types across the entire application; otherwise there may be unpredictable results at run time. It is the user's responsibility to ensure that this condition is met because the compiler cannot easily enforce this across all files of the application.
- All Java interoperability-related stub programs generated by the compiler for an application, including all Java call stub programs, must be built into a DLL using the cjbuild utility. If cjbuild is instructed to output the DLL to the z/OS UNIX file system, then the location of this DLL must be reflected in your LIBPATH environment variable at run time. On the other hand, if cjbuild is instructed to output the DLL to an MVS data set, then that data set must be included in your STEPLIB at run time. Furthermore, the CALL statement in the user COBOL program that calls the static Java method is always treated as a DLL call, regardless of the current value of the DYNAM and DLL compiler options in effect or any CALLINTERFACE directive that may be in effect at the time of the call.
Mapping between COBOL and Java data types for non-OO COBOL/Java interoperability
Compiling, linking, and running non-OO COBOL applications that interoperate with Java (Enterprise COBOL Programming Guide)
Running the cjbuild utility to build a DLL of Java stub programs (Enterprise COBOL Programming Guide)
JAVAIOP (Enterprise COBOL Programming Guide)
PARMCHECK (Enterprise COBOL Programming Guide)