186 lines
13 KiB
HTML
186 lines
13 KiB
HTML
|
<?xml version="1.0" encoding="UTF-8"?>
|
||
|
|
<!DOCTYPE html
|
||
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<meta name="security" content="public" />
|
||
|
|
<meta name="Robots" content="index,follow" />
|
||
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
||
|
|
<meta name="DC.Type" content="task" />
|
||
|
|
<meta name="DC.Title" content="Use the Java Native Interface for native methods" />
|
||
|
|
<meta name="abstract" content="You should only use native methods in cases where pure Java cannot meet your programming needs." />
|
||
|
|
<meta name="description" content="You should only use native methods in cases where pure Java cannot meet your programming needs." />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="othlang.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzahapaseexmplsmain.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzahateraspacemain.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="ilejava.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="javalang.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="interpro.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="invocapi.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="nmthread.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="nmjni.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="strings.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="jni" />
|
||
|
|
<meta name="DC.Language" content="en-us" />
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>Use the Java Native Interface for native methods</title>
|
||
|
|
</head>
|
||
|
|
<body id="jni"><a name="jni"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">Use the Java Native Interface for native methods</h1>
|
||
|
|
<div><p>You should only use native methods in cases where pure Java™ cannot
|
||
|
|
meet your programming needs.</p>
|
||
|
|
<div class="section"><div class="p">Limit the use of native methods by only using them under these
|
||
|
|
circumstances:<ul><li>To access system functions that are not available using pure Java.</li>
|
||
|
|
<li>To implement extremely performance-sensitive methods that can benefit
|
||
|
|
significantly from a native implementation.</li>
|
||
|
|
<li>To interface to existing application program interfaces (API) that allow Java to
|
||
|
|
call other APIs.</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<p>The following instructions apply to using the Java Native
|
||
|
|
Interface (JNI) with the C language. For information about using JNI with
|
||
|
|
the RPG language, see the following documentation:</p>
|
||
|
|
<blockquote> <p>Chapter 11
|
||
|
|
of the <a href="../books/sc092507.pdf" target="_blank">WebSphere<sup>®</sup> Development
|
||
|
|
Studio: ILE RPG Programmer's Guide, SC09-2507</a>.</p>
|
||
|
|
</blockquote>
|
||
|
|
<p>To use the Java Native
|
||
|
|
Interface (JNI) for native methods, do these steps:</p>
|
||
|
|
</div>
|
||
|
|
<ol><li class="stepexpand"><span>Design the class by specifying which methods are native methods
|
||
|
|
with the standard Java language syntax.</span></li>
|
||
|
|
<li class="stepexpand"><span>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.</span></li>
|
||
|
|
<li class="stepexpand"><span>Use the <samp class="codeph">javac</samp> tool to compile the Java source
|
||
|
|
into a class file.</span></li>
|
||
|
|
<li class="stepexpand"><span>Use the <samp class="codeph">javah</samp> 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.</span></li>
|
||
|
|
<li class="stepexpand"><span>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<sup>®</sup> 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 <a href="../books/sc092712.pdf" target="_blank">WebSphere Development
|
||
|
|
Studio: ILE C/C++ Programmer's Guide, SC09-2712</a>.</span></li>
|
||
|
|
<li class="stepexpand"><span>Write the native method code. See <a href="nmthread.htm">Java native
|
||
|
|
methods and threads considerations</a> for details about the languages
|
||
|
|
and functions that are used for native methods.</span><ol type="a"><li><span>Include the header file that was created in the previous steps.</span></li>
|
||
|
|
<li><span>Match the prototypes in the header file exactly.</span></li>
|
||
|
|
<li><span>Convert <a href="strings.htm">strings</a> to American
|
||
|
|
Standard Code for Information Interchange (ASCII) if the strings are to pass
|
||
|
|
to the Java virtual machine. For more information, see <a href="charenc.htm">Java character encodings</a>.</span></li>
|
||
|
|
</ol>
|
||
|
|
</li>
|
||
|
|
<li class="stepexpand"><span>If your native method must interact with the Java virtual
|
||
|
|
machine, use the functions that are provided with JNI.</span></li>
|
||
|
|
<li class="stepexpand"><span>Compile your C source code, using the CRTCMOD command, into a module
|
||
|
|
(*MODULE) object.</span></li>
|
||
|
|
<li class="stepexpand"><span>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.</span></li>
|
||
|
|
<li class="stepexpand"><span>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: </span> <img src="./delta.gif" alt="Start of change" /><ul><li>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. <ul><li>From the Qshell command prompt, type in: <p><samp class="codeph">export LIBPATH=<em>/QSYS.LIB/MYLIB.LIB</em></samp><br />
|
||
|
|
<samp class="codeph">java -Djava.version=1.5 <em>myclass</em></samp></p>
|
||
|
|
</li>
|
||
|
|
<li>Or, from the command line: <p><samp class="codeph">ADDENVVAR LIBPATH '<em>/QSYS.LIB/MYLIB.LIB</em>'</samp><br />
|
||
|
|
<samp class="codeph">JAVA PROP((java.version 1.5)) <em>myclass</em></samp></p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
<li>Or, supply the list in the <strong>java.library.path</strong> property. You can
|
||
|
|
change the java.library.path property in QShell and from the iSeries command
|
||
|
|
line. <ul><li>From the Qshell command prompt, enter: <p><samp class="codeph">java -Djava.library.path=<em>/QSYS.LIB/MYLIB.LIB</em> -Djava.version=1.5 <em>myclass</em></samp></p>
|
||
|
|
</li>
|
||
|
|
<li>Or, from the iSeries command
|
||
|
|
line, type in: <p><samp class="codeph">JAVA PROP((java.library.path '<em>/QSYS.LIB/MYLIB.LIB</em>') (java.version '1.5')) <em>myclass</em></samp></p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul><img src="./deltaend.gif" alt="End of change" />
|
||
|
|
<p>Where <em>/QSYS.LIB/MYLIB.LIB</em> is the library that you want
|
||
|
|
to load using the System.loadLibrary() call, and <em>myclass</em> is the name
|
||
|
|
of your Java application.</p>
|
||
|
|
</li>
|
||
|
|
<li class="stepexpand"><span>The path syntax for System.load(String path) can be any of these:</span> <ul><li>/qsys.lib/sysNMsp.srvpgm (for *SRVPGM QSYS/SYSNMSP)</li>
|
||
|
|
<li>/qsys.lib/mylib.lib/myNMsp.srvpgm (for *SRVPGM MYLIB/MYNMSP)</li>
|
||
|
|
<li>a symbolic link, such as /home/mydir/myNMsp.srvpgm which links to /qsys.lib/mylib.lib/myNMsp.srvpgm
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> This is equivalent to using the System.loadLibrary("myNMsp")
|
||
|
|
method.</div>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> The pathname is typically a string literal enclosed in quotation
|
||
|
|
marks. For example, you could use the following code:<pre> System.load("/qsys.lib/mylib.lib/myNMsp.srvpgm")</pre>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
<li class="stepexpand"><span>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 <span class="keyword">i5/OS™</span> PASE
|
||
|
|
executable that matches the library name. For example, <samp class="codeph">loadLibrary("myNMsp")</samp> results
|
||
|
|
in a search for a *SRVPGM named MYNMSP or an <span class="keyword">i5/OS</span> PASE
|
||
|
|
executable named libmyNMsp.a or libmyMNsp.so.</span></li>
|
||
|
|
</ol>
|
||
|
|
<div class="section"><p>For a complete description of the JNI, refer to the <a href="javaapi/guide/jni/index.html" target="_blank">Java Native
|
||
|
|
Interface by Sun Microsystems, Inc.</a>, and <a href="http://www.java.sun.com/" target="_blank">The Source for Java Technology java.sun.com</a>.</p>
|
||
|
|
<p>See <a href="jniex.htm">Examples: Use the Java Native Interface for native methods</a> for
|
||
|
|
an example of how to use the JNI for native methods.</p>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<ul class="ullinks">
|
||
|
|
<li class="ulchildlink"><strong><a href="invocapi.htm">Java Invocation API</a></strong><br />
|
||
|
|
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.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="nmthread.htm">Java native methods and threads considerations</a></strong><br />
|
||
|
|
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.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="nmjni.htm">Native methods and the Java Native Interface</a></strong><br />
|
||
|
|
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.</li>
|
||
|
|
<li class="ulchildlink"><strong><a href="strings.htm">Strings in native methods</a></strong><br />
|
||
|
|
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.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="othlang.htm" title="With Java, you have multiple ways to call code that was written in languages other than Java.">Java with other programming languages</a></div>
|
||
|
|
</div>
|
||
|
|
<div class="relconcepts"><strong>Related concepts</strong><br />
|
||
|
|
<div><a href="rzahapaseexmplsmain.htm" title="The iSeries Java virtual machine (JVM) supports the use of native methods running in the i5/OS PASE environment. Prior to V5R2, the native iSeries JVM used only ILE native methods.">IBM i5/OS PASE native methods for Java</a></div>
|
||
|
|
<div><a href="rzahateraspacemain.htm" title="The iSeries Java virtual machine (JVM) now supports the use of teraspace storage model native methods. The teraspace storage model provides a large process-local address environment for ILE programs. Using teraspace allows you to port native method code from other operating systems to i5/OS with little or no source code changes.">Teraspace storage model native methods for Java</a></div>
|
||
|
|
<div><a href="ilejava.htm" title="The Java environment on an iSeries server is separate from the integrated language environment (ILE). Java is not an ILE language, and it cannot bind to ILE object modules to create programs or service programs on an iSeries server.">Comparison of Integrated Language Environment and Java</a></div>
|
||
|
|
<div><a href="javalang.htm" title="Use the java.lang.Runtime.exec method to call programs or commands from within your Java program. Using java.lang.Runtime.exec() method creates one or more additional thread-enabled jobs. The additional jobs process the command string that you pass on the method.">Use java.lang.Runtime.exec()</a></div>
|
||
|
|
<div><a href="interpro.htm" title="When communicating with programs that are running in another process, there are a number of options.">Interprocess communications</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|