Writing JNI applications

Valid Java™ Native Interface (JNI) version numbers that programs can specify on the JNI_CreateJavaVM() API call are: JNI_VERSION_1_2(0x00010002) and JNI_VERSION_1_4(0x00010004).

Restriction: Version 1.1 of the JNI is not supported.

This version number determines only the level of the JNI to use. The actual level of the JVM that is created is specified by the JSE libraries (use the java -version command to show the JVM level). The JNI level does not affect the language specification that is implemented by the JVM, the class library APIs, or any other area of JVM behavior. For more information, see https://docs.oracle.com/javase/8/docs/technotes/guides/jni/.

If your application needs two JNI libraries, one built for 32-bit (31-bit on z/OS®) and the other for 64-bit, use the com.ibm.vm.bitmode system property to determine if you are running with a 32-bit (31-bit on z/OS) or 64-bit JVM and choose the appropriate library.

Information specific to Linux systems

To compile and link a local application, use the following command: 
gcc -Ijava_install_dir/include -Ljava_install_dir/jre/lib/j9vm 
-ljvm -ldl -lpthread <JNI program filename>
The -ljvm option specifies that libjvm.so is the shared library that implements the JVM. The -lpthread option indicates that you are using native pthread support; if you do not link with the pthread library, a segmentation fault (signal SIGSEGV) might be caused when you run the JNI program.

Information specific to z/OS systems

For more information about writing 64-bit applications, see the IBM® Redpaper z/OS 64-bit C/C++ and Java Programming Environment at http://www.redbooks.ibm.com/abstracts/redp9110.html.

ASCII and EBCDIC issues: On z/OS, the Java virtual machine is essentially an EBCDIC application. However, string literals that are used with JNI routines must be in ASCII format. Do not create JNI routines as enhanced ASCII C or C++ methods because you will be operating in a bimodal environment; your application will be crossing over between ASCII and EBCDIC environments.

There are two ways to create ASCII literals:
  • When using the XL C/C++ compiler:
    • Use the XL C/C++ compiler option -Wc,convlit(ISO8859-1). For more information about this option, see options-convlit-noconvlit in the z/OS XL C/C++ user's guide. This option creates all string literals in ASCII format, but this process can be suspended or resumed to obtain EBCDIC literals by using pragmas (#pragma) in the program.
  • When using Open XL C/C++ compiler:
    • Use the Open XL C/C++ compiler option -fexec-charset=ISO8859-1. For more information about this option, see IBM Open XL C/C++ for z/OS Compiler reference. This option creates all string literals in ASCII format, but this process can be suspended or resumed to obtain EBCDIC literals by using pragmas (#pragma) in the program.
      Note: When -Wc,convlit(ISO8859-1) or -fexec-charset=iso8859-1 is in effect, library functions such as printf expect EBCDIC characters.
  • Convert EBCDIC literals explicitly by using __etoa(), __etoa_l(), __e2a_s(), or __e2a_l(). For more information about these functions, see the z/OS XL C/C++ Runtime Library Reference.

The inherent problem with bimodal programs is that, in the z/OS runtime environment, threads are designated as either EBCDIC or enhanced ASCII and are not intended to be switched between these modes in typical use. Enhanced ASCII is not designed to handle bimodal issues. You might get unexpected results or experience failures when the active mode does not match that of the compiled code. There are z/OS runtime calls that applications might use to switch the active mode between EBCDIC and enhanced ASCII (the __ae_thread_swapmode() and __ae_thread_setmode() functions are documented in Language Environment® Vendor Interfaces, see the SA22-7568-06 Red Book: https://publibz.boulder.ibm.com/epubs/pdf/ceev1160.pdf). However, even if an application is carefully coded to switch modes correctly, other bimodal issues might exist.