The javap command disassembles a class file. The output depends on the options selected. Here, we wanted the method signatures. The C module needs the signatures so it can get the method handles. The command and its disassembled output appear in the compressed file referenced previously. The dot (.) in the classpath option says to look for the Java class in the current directory. The –s option says to produce method signatures. The signature gives the data types of the method inputs and its return value. You must use the signatures exactly as shown in the output of the javap program in the JNI calls to get the method IDs.
C Module Compilation
There are several interesting items in this JCL. The compile parameter, OPTFILE, indicates where to look for additional compile options. The LANGLVL option is set to allow the use of C-type comments. That is, the /* -- */ format. The XPLINK option specifies use of the Extra Performance Linkage. According to the z/OS Language Environment Programming Guide, XPLINK “has the potential for a significant performance increase when used in an environment of frequent calls between small functions or subprograms.” The SEARCH option says where to look for additional includes. The SYSIN for the BIND step says to include the libjvm side-deck. This contains the exported functions in the libjvm.so. This shared object implements the calls to create and destroy the JVM. (To learn more, refer to the XL C/C++ User’s Guide.) Programs using XPLINK must reside in a Partitioned Data Set Extension (PDSE) or the Hierarchical File System (HFS). We’re interested only in a PDSE.
Running the Samples
Consider the options in the CEEOPTS Data Definition (DD) statement. XPLINK is turned on. This is required because we compiled the C module using XPLINK. Also, the ENVAR option indicates where to look for environment variables. In this case, we set the LIBPATH to the Java executables. You can learn more from the z/OS Language Environment Customization manual. The output appears in a file named output.txt in the compressed file you downloaded. What’s shown is the output of the Write To Operator (WTO) macros from the Assembler module and the output from the C module. A portion of the output from the JVM verbose option is also listed.
In the CEEOPTS DD statement specified in the execution JCL, you can specify the following options: TRAP(ON,NOSPIE),TERM(UAIMM). The TRAP option specifies how LE handles abends. The ON suboption fully enables the Language Environment (LE) condition handler. The NOSPIE suboption says that LE won’t issue the ESPIE macro. The TERM option is shorthand for “Terminating Thread Actions.” This option sets the information level when LE percolates an error condition. The UAIMM suboption tells LE to request a system dump of the original abend.
This article provided working examples of Assembler-to-Java using the JNI—a good starting point for developers wanting to take advantage of functionality available in Java code. The write-once, run-anywhere paradigm comes to z/OS.
Several items are left to the reader. The Assembler code isn’t re-entrant. The C code modifies character literals. There’s no discussion about permissions or defining users on USS. Performance techniques haven’t been employed in any of the code. The Java and C code use static calls, so this isn’t an example of creating an object instance using JNI. Even with these limitations, readers will have a leg up when writing their first programs using JNI on z/OS.
- z/OS Language Environment Programming Guide
- z/OS: Language Environment Run-Time Messages
- Language Environment Writing Interlanguage Communication Applications
- XL C/C++ Programming Guide
- XL C/C++ Language Reference
- XL C/C++ User’s Guide
- z/OS Language Environment Customization manual
- Java Stand-alone Applications on z/OS Volume II
- Petrolino, Thomas. “The Ins and Outs of Language Environment’s CEEPIPI Service.” SHARE, August 2009.
- Java Diagnostics information center: http://publib.boulder.ibm.com/infocenter/javasdk/v5r0/index.jsp
- IBM Developer Kit and Runtime Environment, Java 2 Technology Edition, Version 5.0 Diagnostics Guide
- Best practices for JNI: ibm.com/developerworks/java/library/j-jni
- Hints and tips for Java on z/OS: www-03.ibm.com/systems/z/os/zos/tools/java/faq/javafaq.html.