Use the Java Native Interface for native methods

You should only use native methods in cases where pure Java™ cannot meet your programming needs.

1. Design the class by specifying which methods are native methods with the standard Java language syntax.
2. Decide on a library and program name for the service program (*SRVPGM) that contains native method implementations. When coding the System.loadLibrary() method call in the static initializer for the class, specify the name of the service program.
3. Use the javac tool to compile the Java source into a class file.
4. Use the javah tool to create the header file (.h). This header file contains the exact prototypes for creating the native method implementations. The -d option specifies the directory where you should create the header file.
5. Copy the header file from the integrated file system into a member in a source file by using the Copy From Stream File (CPYFRMSTMF) command. You must copy the header file into a source file member for the C compiler to use it. Use the new stream file support for the Create Bound ILE C/400^® Program (CRTCMOD) command to leave your C source and C header files in the integrated file system.For more information on the CRTCMOD command and the use of stream files, see the WebSphere Development Studio: ILE C/C++ Programmer's Guide, SC09-2712.
6. Write the native method code. See Java native methods and threads considerations for details about the languages and functions that are used for native methods.
   1. Include the header file that was created in the previous steps.
   2. Match the prototypes in the header file exactly.
   3. Convert strings to American Standard Code for Information Interchange (ASCII) if the strings are to pass to the Java virtual machine. For more information, see Java character encodings.
7. If your native method must interact with the Java virtual machine, use the functions that are provided with JNI.
8. Compile your C source code, using the CRTCMOD command, into a module (*MODULE) object.
9. Bind one or more module objects into a service program (*SRVPGM) by using the Create Service Program (CRTSRVPGM) command. The name of this service program must match the name that you supplied in your Java code that is in the System.load() or System.loadLibrary() function calls.
10. If you used the System.loadLibrary() call in your Java code, perform one the following task that is appropriate for the J2SDK you are running:
    • Include the list of the libraries that you need in the LIBPATH environment variable. You can change the LIBPATH environment variable in QShell and from the iSeries™ command line.
      • From the Qshell command prompt, type in:

        export LIBPATH=/QSYS.LIB/MYLIB.LIB
        java -Djava.version=1.5 myclass

      • Or, from the command line:

        ADDENVVAR LIBPATH '/QSYS.LIB/MYLIB.LIB'
        JAVA PROP((java.version 1.5)) myclass

    • Or, supply the list in the java.library.path property. You can change the java.library.path property in QShell and from the iSeries command line.
      • From the Qshell command prompt, enter:

        java -Djava.library.path=/QSYS.LIB/MYLIB.LIB -Djava.version=1.5 myclass

      • Or, from the iSeries command line, type in:

        JAVA PROP((java.library.path '/QSYS.LIB/MYLIB.LIB') (java.version '1.5')) myclass

    

    Where /QSYS.LIB/MYLIB.LIB is the library that you want to load using the System.loadLibrary() call, and myclass is the name of your Java application.

11. The path syntax for System.load(String path) can be any of these:
    • /qsys.lib/sysNMsp.srvpgm (for *SRVPGM QSYS/SYSNMSP)
    • /qsys.lib/mylib.lib/myNMsp.srvpgm (for *SRVPGM MYLIB/MYNMSP)
    • a symbolic link, such as /home/mydir/myNMsp.srvpgm which links to /qsys.lib/mylib.lib/myNMsp.srvpgm
      Note: This is equivalent to using the System.loadLibrary("myNMsp") method.
    Note: The pathname is typically a string literal enclosed in quotation marks. For example, you could use the following code:

         System.load("/qsys.lib/mylib.lib/myNMsp.srvpgm")

12. The libname parameter for System.loadLibrary(String libname) is typically a string literal in quotation marks that identifies the native method library. The system uses the current library list and LIBPATH and PASE_LIBPATH environment variables to search for a service program or i5/OS™ PASE executable that matches the library name. For example, loadLibrary("myNMsp") results in a search for a *SRVPGM named MYNMSP or an i5/OS PASE executable named libmyNMsp.a or libmyMNsp.so.

• Java Invocation API
  The Invocation API, which is part of the Java Native Interface (JNI), allows non-Java code to create a Java virtual machine, and load and use Java classes. This function lets a multithreaded program make use of Java classes that are running in a single Java virtual machine in multiple threads.
• Java native methods and threads considerations
  You can use native methods to access functions that are not available in Java. To better use Java with native methods, you need to understand these concepts.
• Native methods and the Java Native Interface
  Native methods are Java methods that start in a language other than Java. Native methods can access system-specific functions and APIs that are not available directly in Java.
• Strings in native methods
  Many Java Native Interface (JNI) functions accept C language-style strings as parameters. For example, the FindClass() JNI function accepts a string parameter that specifies the fully-qualified name of a classfile. If the classfile is found, it is loaded by FindClass, and a reference to it is returned to the caller of FindClass.