JNI provides a means for Java code to call native code. This interaction is useful in cases when native capabilities are more efficient than Java or when the specific code is already available in native and you want to use it. JNI provides JNI services (also referred as functions) via the JNI API to act on the Java data and use Java features.
The JNI also provides the native code with means to embed a JVM in the native code and to access Java features without having to link with the JVM.
JNI services and API
JNI provides many services for the native code to access Java features, such as class operations, calling methods, string and array operations, etc. It also provides services via the Invocation API to embed a JVM in the native application.
The JNI APIs are defined under a language-specific file that holds all API functions and the type mapping for the Java JNI types. For COBOL, the APIs are defined in the JNI copybook called JNI.cpy, which is typically located under the
/usr/lpp/cobol/include directory. To use the JNI services, the JNI copybook needs to be included.
There are two main JNI structures defined in the JNI APIs that are key to the JNI execution:
- The “JNI environment” structure– the JNI service API.
Accessing the JNI environment structure is done via two levels of indirection using an interface pointer (in COBOL, it is the special register, JNIEnvPtr). This pointer points to a per-thread JNI environment pointer (JNIEnv, in COBOL it is declared in the JNI copybook) that points to an array of JNI function pointers (a function table named JNINativeInterface) for accessing the callable service functions. The JNI environment pointer is thread-specific and cannot be passed from one thread to another. See the figure below.
- The “JavaVM” structure– the JNI Java VM service API that allows to create and destroy the JVM.
The JavaVM structure is accessed via an interface pointer, JavaVMPtr. This pointer points to a pointer that points to an array of JNI function pointers (a function table named JNIInvokeInterface) for accessing callable “invocation interface” functions.
Java for the z/OS platform provides an extended API to deal with strings due to the encoding differences. It defines the following extensions: NewStringPlatform, GetStringPlatformLength, GetStringPlatform.
These EBCDIC services are packaged as a dynamic link library (DLL) file that is part of the IBM® Java SDK. They are called directly and not dereferenced from the JNIEnv pointer (the JNIEnvPtr). This extended API is resolved through the libjvm.x DLL side file, provided with your IBM Java SDK, which needs to be included in the link-edit step