Using Open-Source Java From RPG

First it creates a new Java object named "email," calls methods to supply e-mail related information (i.e., addresses, subject, body of e-mail, e-mail host and port), and finally specifies to send the e-mail. Dismissing Java semantics, you can fairly easily see what's being accomplished. The next step is implementing the same sort of test program in RPG that makes use of this more concise set of Java methods.

Instead of going into gory details of how the RPG compiler implements Java interoperability, I'll give a high-level, concise approach to the subject. (Note: Also check out the WebSphere Development Studio: ILE RPG Programmer's Guide, SC09-2507-05 for more information. Chapter 11 describes how RPG and Java communicate.)

Generally what's accomplished in the wrapping of the Java program with RPG is that you must match each Java method with an RPG sub-procedure. For example, Code Samples 1 and 2 show how to create an RPG prototype that maps to a Java method. The RPG prototype is used to declare where the qualified path is of the Java method it's interfacing with. Using the EXTPROC keyword, identify that we're working with Java by specifying *JAVA. Next, state the full qualified path to the Java object (i.e., com.mowyourlawn.rpgmail.RPGMail). Lastly, give the actual Java method name you wish to interface with (i.e., setSubject). Now for the parameter named "text." This Java method receives in one string. In Java, a string isn't a native data type but instead considered an object. This means we must specify the string class location using the CLASS keyword (i.e., java.lang.String).

At this point we could call the prototyped method "setSubject," but I like to better wrap the method to hide any additional complexities that may take place. This provides for ease of use and to implement proper error handling. The following code shows how prototype "setSubject" is better wrapped with RPG sub-procedure "RPGMail_setSubject." The error handling is described later.

Once the Java program has been efficiently wrapped by RPG sub-procedures, sending an e-mail from your RPG program is as simple as the code in Code Sample 3. I think a simple walk-through is in order. The first /copy statement brings in the necessary prototypes for making calls to RPGMail sub-procedures. The second, /copy qsource,ErrorCp, is for "catching" errors thrown from programs further down in the call stack. Moving onto the mainline, RPGMail_init()sets up the environment needed to enable Java calls to be made. Essentially it sets the current directory to /java/ and adds the appropriate jar and class files to the classpath. If an error occurs during this step, processing is handed to the on-error clause, and sub-procedure Error_catch() goes out to the call stack and retrieves the most recent error. It returns it to the locally defined data structure named "error."

After the environment has been initialized, it's fair game to start using the RPGMail java object. First, "instantiate" the Java object so you have a reference to it in the program. "Instantiate" doesn't clarify the purpose of the statement; I instead like to think of it as the program now has access to make calls to RPGMail's methods via a handle of sorts (similar to doing a CHAIN to a file to get a record before you can start working on the fields in that record). Now that a Java object resides in the variable named "email" you can start calling the other sub-procedures to compose the e-mail. Notice how each call to the remaining RPGMail_*** sub-procedures has a first parameter of "email." Specify this so the background Java code knows which specific instance of the Java object you're referencing. This means you could do something like the following to have multiple Java e-mail objects: email2 = RPGMail_new();.

The adding of addresses and setting of subject and body text is pretty straightforward, but the SMTP host and port might be an area where more information is needed from your network administrator. Ask them which domain or IP you should send e-mail to along with the port. Port 25 is a common default.

Now we're at the actual sending of the e-mail. Up to this point, the Java code behind the scenes has been gathering all of the information we've been plugging into it via RPG sub-procedures but has done nothing in the area of sending the e-mail. When RPGMail_send(email) is executed, Sun's JavaMail APIs kick in and attempt to connect to the specified SMTP host and port to deliver the e-mail.

All of the source code for the RPGMail tooling can be downloaded online (

Aaron Bartell is Director of IBM i Innovation for Krengel Technology Inc. and an IBM Champion.

comments powered by Disqus



2017 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

Converting an IBM i Spool File to a PDF

A comprehensive four-step approach

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters