Sat, Apr
5 New Articles

Using JNI to Call RPG from Java

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Wouldn’t it be nice to dump all your RPG and C code and develop all your applications in Java? That suggestion should raise a few eyebrows from discerning developers. The fact is that it’s not a completely “caffeinated” world yet and it’s not likely to be for quite some time. Many programmers still prefer a native 5250 user interface over a Web browser or client/server user interface, and others are chained to an OS/400 version that does not have a Java Virtual Machine (JVM). So, in order to be competitive in these markets (assuming this is your concern), you must provide support for these options for a prospective customer. Yet it could become cost-prohibitive to maintain two separate versions of your software. Additionally, until the recent release (V4R4), Java performance precluded developing serious (competitive-edge) applications. So what is a developer to do?

Ever Heard of Java Native Interface?

A little jewel known as Java Native Interface (JNI) enables you to reuse procedural code written in languages such as RPG IV or C as native methods in Java classes. That is to say, you can use RPG subprocedures as plug-ins for Java functions. The native methods, however, must be developed as ILE service program functions or procedures to be accessible using JNI. A service program is essentially a Dynamic Link Library (DLL) on the AS/400. All JNI services are provided via an AS/400 service program QJVAJNI in the QSYS library, with roughly 216 functions. But why choose JNI over dynamic program calls and a pure Java solution?

The advantage of using JNI is that both the calling program and the called program run in the same process (job) on the AS/400 system while the other methods start a new process (job). This makes JNI calls faster at startup time and less resource-intensive. However, because Java applications run in the Technology Independent Machine Interface (TIMI) and user native methods require a user address space to run, some overhead is required initially to create a user environment that uses 16-byte address pointers instead of the 8-byte pointers used below TIMI. So what does this all mean? It simply means that your reasons for using JNI should be based on more than performance.

Your reason may be the need to preserve a large investment in legacy code. However, a Java toolbox class will enable a dynamic program call, right? And, as stated,

JNI requires the native procedures to be in a service program before they can be addressed as native methods, meaning that you might have to do some reengineering of your existing code to translate it into a service program consisting of a set of subprocedures. How much reengineering you’ll have to do will be based on the modularity of your existing code. So where is the preservation?

Why Use JNI?

At this point, you should be asking yourself, “Why use JNI if I have to rework my code anyway? Why not just do a Java Toolbox program call?” There are two reasons why you would want to use JNI over a pure Java solution and a Java Toolbox program dynamic call. For one, the function required does not exist as a bindable Java option, and the Java Toolbox program call does not yield the required level of performance. (JNI does create some runtime overhead, but it is minimal compared to a Java Toolbox program call.) Another reason is that you must provide “caffeine-free” access to your application to be competitive in serving less developed IS shops (i.e., you must be able to provide a marketable solution where Java is not an accepted standard). In today’s AS/400 applications market, that means being able to provide a user interface access paradigm that can be adapted to both the older green-screen style of access and the newer browser-based access method.

However, you can’t afford to develop core functionality in some ILE native methods and then turn around and develop the same code in Java. Given that you should be addressing the same back-end database using either method, you can ensure better data integrity by being consistent in addressing and handling data with the same data access functions. Keeping features in sync between two releases is difficult enough without having multiple versions (one pure Java and one totally “caffeine-free”) of the same product. JNI allows you to code your back-office code in RPG to be accessed directly from both a Java front-end and an RPG front-end.

What’s the Plan?

You should review the following factors that will determine the amount of effort required to reengineer your existing code for JNI native methods:

• How modular is your code?

• What is the lowest level of OS/400 you are required to support?

• How much data must be shuffled back and forth?

• What is the required response time of the application?

• Must results be real-time, or is batch update allowed?

Answering these questions will determine whether only JNI-level access is needed, client/server data queues or Sockets are required (with the data queue or Socket server task running in background), or batch update is necessary. In truth, your solution will probably lie in the combination of all of these methodologies.

Constructing a Java Shell

An example application I’ve provided takes a customer number passed as an argument and uses back-end native methods (implemented as RPG subprocedures) to retrieve information from a customer master file. Figure 1 shows sample output from the execution of the Java class running in Qshell (QSH) that I will present later. My example Java application uses five native methods, developed using RPG IV, to perform necessary functions that, you

should assume for purposes of this example, could not be accomplished in Java with the same required performance or functionality. Figure 2 shows the Java class CustProcs and the five native methods (Section B). This simple application takes only one argument (custid, the customer number), parses out the integer value of this argument using parseInt (Section C), creates a new instance of CustProcs class (Section D), and finally calls each of the native methods in turn to get the required customer information that each function supplies. Note that, before any native functions can be called, the service program that contains the native methods is loaded with the System.loadLibrary method (Section A). The loadLibrary method is usually invoked in the class initializer because, much like the *INZSR in RPG, the class initializer is automatically called the first time the class is accessed. Methods are bound dynamically on the first call, and subsequent calls are as fast as statically bound calls. Note also that the object cp presented in Figure 2 (Section D) can be reused as many times as required, so you need not create a new object each time you wish to call one of the native methods again. Actually, the object cp is really not required in the example application—because there are no member variables or methods, just the static native methods I have defined—but I have included it here to avoid confusion. Those of you who have been working with Java will have already realized this. However, for purposes of demonstration, you should assume the existence of other member variables and functions requiring an object instantiation. In Figure 2, Section E, the native method calls are made inside the System.out.println function to execute and display the results returned by each of those functions. Finally, System.exit(0) shuts down the CustProcs application.

What Does the Native Code Look Like?

Figure 3 shows a code snippet of the logic necessary to implement the native functionality required by CustProcs. For example, look at the getName function.

I should first point out that you must code the NoMain H-spec keyword in Section F to avoid initialization code from being generated for your service programs. Next, I have coded a compiler directive in Section G that will enable me to use the same source code to generate both a threadsafe version of the service program and a single-threaded version for pure native applications. This is done to enable Java threads of execution to be serialized for each call instance of your native methods. (That is, program variable instances will be marked for a particular thread.) Yet you will want to avoid serialization when other RPG programs call your service program. All that is required to generate the two different binary versions is to pass the javaIncluded text for the DEFINE parameter of the Create RPG Module (CRTRPGMOD) command to generate the threadsafe version and leave it off for the pure native version. Each threadsafe binary has the same name as the single-threaded binary plus an “_r” using the same notation that IBM uses to denote threadsafe C functions. This enables both versions to reside in the same library for distribution. Service program documentation instructs programmers on the proper way to create these binaries.

Note that getName takes an unsigned integer as an input argument (Section I) to represent the customer number in the customer master file. It returns a 30-byte alpha field (Section H) that will contain the name as retrieved from the customer master file. This would be fine if not for a couple of things. For one, JNI cannot call the native methods in this manner and provide access in the other direction (access to Java classes and objects from native methods) without passing additional arguments not required by the native functions. Also, Java applications use a data encoding method (called Universal Translation Format-8 [UTF-8]) that is closer to ASCII than it is to EBCDIC. So, for a native method to understand text data passed to it, a translation from ASCII to EBCDIC must occur. Likewise, any text data (referred to as a String object) returned to the Java application must be encoded using the UTF-8 or Unicode data encoding format. So how do you handle these requirements for Java applications but not impose any superfluous requirements on your pure native applications?

Wrap It Up

Recall the reason(s) why you are using JNI. The idea is to preserve native functionality with as little modification for the JNI interface as possible. To do this, you must create a shell or JNI wrapper for the native functions. One reason for doing this is that the JVM passes two arguments that your native methods will not require when running in pure native mode: 1) a pointer to the JNI function table (which contains an array of pointers to JNI functions) and 2) a reference to a class (if the method is called from a class-static method) or a reference to an object (if the method is called from an instance of a class). After that, any arguments the native method requires are specified. Another reason for the wrapper is to provide the necessary services of data extraction or encapsulation (as in the case of a String object) and translation for textual data passed to (ASCII to EBCDIC) and returned from (EBCDIC to ASCII) native methods. Because running in pure native mode does not require data extraction (encapsulation) or translation, the wrapper serves to encapsulate only the functionality that is required for the Java application. Figure 4 shows the wrapper (CustProc_J service program) required for the getName function.

Note in Figure 4 that the name of the wrapper function for the getName function (Section J) is Java_PentaSafeSysPkg_CustProcs_getName. This four-part name (the parts are separated by a single underscore) is required by JNI and consists of Java designated as the language library, the name of the package (in my example, PentaSafeSysPkg, as shown in the first statement in Figure 2) containing the referenced native method, the name of the class (CustProcs) declaring the native methods, and, finally, the name of the native method to be called (getName).

The first argument passed (Figure 4, Section J) to the getName function is JNIEnv, followed by classParm typecast as a jobject. After these two required parameters, any native method arguments are specified. In the case of getName, all that is required is the custid typecast as a jint. For a complete list of Java reference types used in JNI, refer to the copy member JniMD_h included in the downloadable material for this article. (You can download the specified code at www.midrangecomputing.com/mc.)

What about the return value for getName? In the procedure prototype (Section J) and procedure interface (Section K) lines, I defined the return value as a jstring type. This will actually be a “reference” to the String object created with a call to the NewString JNI function. Now take a look at the procedural section. The first thing it does is assign the pointer to the JNI function table that was passed from the JVM to the basing pointer JNIEnv@ (Section M), which is associated with the Java_JNI_Env data structure in the jni_h copy member shown in the snippet in Figure 5. (The full source code, along with the SQL necessary to create and load the customer file, is downloadable from the MC Web site at www.midrangecomputing.com/mc.) You’ll need at least one pointer out of the array of pointers that is passed to create a new String object that will contain the name of the customer retrieved from getName. The first pointer in this array points to an array of pointers that point to each of the 216 functions in the QJVAJNI service program.

Before you can create the String object, you must first call the wrappered native function getName (Figure 4, Section N) and convert the returned text from EBCDIC to Unicode as required by the JNI function NewString (Section O). To accomplish this conversion, simply use the RPG IV built-in function %UCS2 that was added in V4R4. (If you are not at V4R4, you can convert the text to a straight ASCII, null-terminated string and use NewStringUTF instead; however, this does not accommodate all national languages as Unicode does.) The Unicode data is placed in a UCS2-compliant field named dNameOut (Section L) defined as a c data type. Finally, after creating the String object, you return a reference to this new object to the CustProcs Java application as shown in Section

You’ll Want to Read This

There are many other JNI functions besides the ones presented in this article. For example, the GetStringChars and GetStringUTFChar JNI methods enable your native methods to extract a Unicode and UTF-8 character set string, respectively, from a String object passed to them. Integers and floats are primitives and can be passed as such to native methods. (All that you need to know is whether they are short or long.) Zoned and packed numeric fields must be converted, using a related helper class (in the AS/400 Java Toolbox), to integers and floats of the same magnitude, since zoned and packed data types are not supported by Java.

Prior to my experience with JNI, I had been warned often by many that JNI was too difficult to be implemented by mortal man. Yet I found it extremely easy. Programming by nature is a detail-oriented process, and JNI is just another tool that can be exploited to accomplish the magic you are always expected to conjure for your users. In that endeavor, you will find on the AS/400 Redbooks Web site (www.redbooks.ibm.com) a Redbook entitled Building AS/400 Applications with Java. This book was invaluable in my quest to utilize JNI to call RPG IV native methods on the AS/400. It also gives some tips on establishing your environment for compiling and running Java applications. (See my sidebar “I Was Just Following Orders” at www.midrangecomputing.com/mc.) I strongly recommend you download the PDF version of the Redbook and additional related materials and upload the save file containing a complete functioning application implementing JNI. I challenge you to take the techniques from this article and IBM’s Redbook and further explore the functionality provided by JNI on the AS/400.

References and Related Materials

• Building AS/400 Applications with Java, Redbook (SG24-2163-02)

• Essential JNI: Java Native Interface. Rob Gordon. Colorado Springs, Colorado: Prentice- Hall, 1998

• IBM AS/400 Developer Kit for Java Web site: www.as400.ibm.com/developer/java/devkit/rzaha.htm

• Java 2 SDK, Standard Edition, Documentation, Web site: java.sun.com/products/jdk/1.2/download-docs.html

> java PentaSafeSysPkg.CustProcs 133568

Customer Number: 133568

Name: Smith Mfg.

City/State: Portland, OR

Credit Limit: $1500

Discount: 5.0%

Account Status: Active


Figure 1: Java applications can benefit from legacy “native” application code.

package PentaSafeSysPkg;

import java.io.*;
import java.lang.*;

class CustProcs {

try {
// Load service program for dynamic binding


catch(Error e) { System.out.println("CUSTPROC_J not loaded!");


// Native methods contained in CustProcs Service program

static native String getName(int custid);
static native String getAddress(int custid);
static native int getCreditLimit(int custid);
static native float getDiscount(int custid);
static native String getStatus(int custid);

public static void main(String[] parameters)
// Parse out custid - integer
int custid = Integer.parseInt(parameters[0], 10);
// Create a new CustProcs instance

CustProcs cp = new CustProcs();
// Call each native function to get customer information

System.out.println("Name: " + cp.getName(custid));
System.out.println("City/State: " +
System.out.println("Credit Limit: $" +
System.out.println("Discount: " +
cp.getDiscount(custid) + "%");
System.out.println("Account Status: " +








Figure 2: You can use RPG subprocedures to provide code implementations for Java methods.

H NoMain

** Compiler Include Directives
*/If Defined( javaIncluded )
H Thread(*Serialize)


FCustomer if e k disk Rename(Customer:CustRec)
F UsrOpn :


*P getName b Export

*D pi 30a
D custno 10u 0 Value

** Local function variables and return value definition.
*D custid s 7p 0

*C Open Customer
C Eval custid = custno
C Custid Chain Customer
C Close Customer
C If ( Not %Error And %Found )
C Return Name
C Else
C Return '*Error - No Name found'
C EndIf

*P getName e





Figure 3: Modularized back-office RPG code can be used by both Java and RPG front-ends.

H NoMain Thread(*Serialize) :


** Prototype for getName_().
*D getName_ pr ExtProc(
D 'Java_PentaSafeSysPkg_CustProcs+
D _getName')
D Like(jstring)
D JNIEnv * Value
D classParm Value Like(jobject)


D custid Value Like(jint)

*P getName_ b Export

*D pi Like(jstring)
D jniEnv * Value
D classParm Value Like(jobject)
D custid Value Like(jint)

** Local function variables and return value definition.
*D dName s 30a
D dNameOut s 31c
D nameObj s Like(jstring)

*C EVAL JNIEnv@ = jniEnv
C EVAL MyClass = classParm

C Eval dNameOut = %Ucs2(getName(custid))
C + %Ucs2(x'00')
C Eval nameObj = NewString(JNIEnv@
C : %Addr(dNameOut)
C : %Size(dName))

C Return nameObj

*P getName_ e*---------------------------------------------------------------








Figure 4: Each RPG subprocedure requires a wrapper to convert EBCDIC to Java data types.


D Java_JNI_Functions...

D *

D Java_JNI_Env_filler_1... :


D Java_Function_Pointers...

D DS BASED(Java_JNI_Functions) :


D NewString@...




D*D* jstring (*NewString)

D* (JNIEnv *env, const jchar *unicode, jsize len);

D*D NewString PR LIKE(jstring) EXTPROC(NewString@)


D unicode * VALUE

D len LIKE(jsize) VALUE

Figure 5: To use the JNI environment, you’ll need access to a copy book of data structures.



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: