http://www.ibmsystemsmag.com/CMSTemplates/IBMSystemsMag/Pri...

close window

Print

Using Open-Source Java From RPG

Open source is a wonderful concept that has caught on in many areas of the IT industry. There are huge,
well-respected communities developing software for free that can be utilized by you and your company to
meet business needs. These communities are comprised of large corporations like IBM, Intel, Sun,
Borland, Computer Associates along with individuals who all have come to realization that if we combine
resources to make an end product, instead of going our separate ways, we can end up with tooling that is
second to none. Some of the more prominent initiatives are all of the projects being run at
www.apache.org, which houses the most widely used HTTP server (Apache) along with many other Java
tools, and the popular and ever-growing Integrated Development Environment (IDE) found at
www.eclipse.org (which is what WebSphere Development Studio Client is based on). And then there are
entire sites dedicated to hosting open-source initiatives like www.sourceforge.net, www.freshmeat.net and
www.hotscripts.com.
Where am I going with all of this? Simply put, we're living in an open-source age that's continuing to grow.
To date, the iSeries RPG community has seen very little adoption of open-source mediums in relation to
the rest of the IT world. A lot of this may have to do with the fact that we're used to writing everything
ourselves, but that just can't be the case as we move forward with our IT initiatives. We must learn to
leverage code developed by external entities within our programming practices. Think of open source as
an extension of your IT department equating to you having many thousands of programming resources at
your disposal.
With that, I shift into an example detailing how to utilize open-source Java to send e-mail from your
iSeries. As this is geared toward RPG programmers, it's necessary to first wrap the Java code with RPG
so it can be easily reused by other RPG programmers needing to send e-mail from their RPG programs.
The open-source Java program I'll be using is JavaMail and can be found online (http://java.sun.com
/products/javamail). Typically, a company would need an employee well versed in Java to interface RPG
with the JavaMail API, but by leveraging those who've gone before us, we can take open source, without
much Java knowledge, and be sending e-mails from RPG in no time. With this article, you'll realize
there's a small set of Java APIs to be aware of, and once the RPG code has been written against them
you'll also have an RPG open-source code set. For the purposes of this article, I'll refer to the RPG
open-source code set as RPGMail.
The JavaMail API documentation provides a lot of information about specific JavaMail objects and
methods, but it doesn't do such a good job of explaining when to use each Java API. I'll use another
piece of open source to address that by "normalizing" all those JavaMail APIs down to a handful of
easy-to-use Java objects and methods.
The following Java code example shows how to make use of a Java object named RPGMail to send an
e-mail.
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.)

1 of 2 25/10/2016 14:50
 http://www.ibmsystemsmag.com/CMSTemplates/IBMSystemsMag/Pri...

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 (http://mowyourlawn.com
/html/RPGMail.php.)

IBM Systems Magazine is a trademark of International Business Machines Corporation. The editorial content of IBM Systems Magazine is
placed on this website by MSP TechMedia under license from International Business Machines Corporation.

©2016 MSP Communications, Inc. All rights reserved.

2 of 2 25/10/2016 14:50