AS/400 Links Partner with Rochester Institute Contact Us
Training Catalog Free Downloads Privacy / Usage

FREE AS/400, iSeries, and System i / iSeries Downloads
HOME >> FREE AS/400, iSeries, and System i / iSeries Downloads >> IBM Toolbox for Java
The right tools to have in your toolbox for Java development

IBM Toolbox for Java
The right tools to have in your toolbox for Java development

Author: Susan Funk - IBM

So you want to enter the world of Java and the Web, but you're not sure where to start? The IBM Toolbox for Java is a set of Java classes you can use to access iSeries resources such as jobs, printers, message queues, and data queues. Using the Toolbox for Java, you can run iSeries programs and call non-interactive iSeries commands from Java. In addition, the Toolbox for Java includes a JDBC driver to access your database information. This article gives you examples of how to run commands and programs from Java and how to use the Toolbox for Java JDBC driver to access a database

What is the IBM Toolbox for Java?

The IBM Toolbox for Java:


is delivered as both a traditional iSeries licensed product and as an open source product. The open source product, JTOpen, has the most recent version of code and contains the most recent fixes and enhancements. You can find out more about JTOpen at

The Toolbox for Java has a class library you can use to access your iSeries resources. The Toolbox for Java communicates between a client machine and your iSeries server using the OS/400 or i5/OS host servers. The V5R3 version of the Toolbox for Java connects back to V5R1 and later versions of OS/400 or i5/OS.

In addition to calling commands and running programs, you can: access files in the Integrated File System, access data queues, access printers, output queues, and spooled files, list jobs and view job logs, access messages and message queues, retrieve system values and status, access user spaces, view users and groups information, and access databases.

Java programs run within a Java Virtual Machine (JVM). You need to obtain a JVM for the machine you will be running Java programs on. (Note that the iSeries contains a built-in JVM.)

You use javadoc to find out information that describes Java classes and the methods available on each class. Javadoc for the JVM is available at Sun Microsystems' Java developers' page at
. The page also has tutorials for people new to Java.

You can view the javadoc in the V5R3 IBM Toolbox for Java's Programmers' Guide, which is available at:  (click the Javadocs link).

The Programmers' Guide also has code samples and detailed information about Toolbox for Java features.

The Toolbox for Java is a great way to get started in Java because it let you access the same iSeries resources you always have. The rest of this article shows you examples of the features you'll find within the Toolbox for Java.

Use ProgramCall to call an iSeries program and CommandCall to call an iSeries command

You can use the Toolbox for Java's AS400 object in almost every Toolbox for Java program you write because it represents a connection to the iSeries server. You can create a connection to an iSeries server with the following line of code:

AS400 myServer = new AS400("myServerName", "myUsername", "myPassword");

Note that the physical connection is not actually made to the server until it is needed.

An easy way to call existing RPG or CL programs from Java is to use Toolbox for Java's program call classes to call your iSeries program. You can specify input, output, and input/output parameters through Toolbox for Java's APIs. If the program fails to complete successfully, you can access returned data through output and input/output parameters and view messages. You can call any non-interactive program (with 35 parameters or fewer) from the Toolbox for Java (assuming the profile you are running under has sufficient authority to run that program).


// Create an object to represent the connection to the iSeries server
AS400 myServer = new AS400("myServerName", "myUsername", "myPassword");

// Create a program call object and specify the program you want to run
ProgramCall myProgram = new ProgramCall(myServer);

// If the program did not run successfully, print to screen the
// messages that came back from the server
if ( != true)
        AS400Message[] messageList = pgm.getMessageList();
 int numberOfMessages = messageList.length;
 for (int i = 0; i < numberOfMessages; i++)
  System.out.println("Message " + i + "= +

Code Example 1

Again, assuming the profile you're running under has sufficient authority to run the command, you call a non-interactive iSeries command using the Toolbox for Java's CommandCall class. The results are available as messages that are contained in AS400Message objects.


// Create an AS400 object with signon information
AS400 myServer = new AS400("myServerName", "myUsername", "myPassword");

// Create a CommandCall object to call a command
CommandCall cmd = new CommandCall(myServer);"CRTLIB MYLIB");

//Print out the messages that came back
AS400Message[] messageList = cmd.getMessageList();
int numberOfMessages = messageList.length;
for (int i = 0; i < numberOfMessages; i++)
 System.out.println("Message " + i + "= +

Code Example 2

Using Toolbox JDBC Driver

You can use the Toolbox for Java JDBC driver to access your iSeries DB2 database. The Toolbox for Java JDBC driver can be used natively on the same iSeries server as your iSeries database, remotely from a separate iSeries server, or remotely from any client machine that has a Java Virtual Machine. When you write a JDBC program, you write against JDBC interfaces and select an implementation. The Toolbox for Java supports the JDBC 3.0 specification. To view JDBC specifications, see Sun Microsystems's JDBC page at
The main JDBC class is Driver, which lets you make a connection to a database. Toolbox's implementation of the Driver interface is:

import java.sql.*;

// Specify which JDBC driver you wish to use by specifying the Driver
// implementation

// Create a connection object
Connection connection  = DriverManager.getConnection("jdbc:as400://mySystem");

//Execute a query
Statement select = connection.createStatement ();
ResultSet rs = select.executeQuery ("SELECT * FROM MYLIBRARY.MYTABLE");

// Print out the contents of the ResultSet to the screen
for (int i = 0;; i++)
 System.out.println("Customer number [" + i + "] = " +

Code Example 3

Alternatively, you can use the iSeries native JDBC Driver (which has the Driver implementation This driver is shipped as part of the IBM Developer Kit for Java (57xxJV1). You can only access the native JDBC driver from a Java program running on an iSeries, while the Toolbox driver runs on any Java Virtual Machine. The Native JDBC driver offers the best performance when the database and Java Virtual Machine both reside on the iSeries.

JDBC interfaces are implementation-independent. You can write a JDBC program once, then run it against different kinds of databases using different implementations of the JDBC interfaces.

The Toolbox for Java's Record Level Access classes are another iSeries-only option for database access, but they may be more familiar to RPG programmers because they allow sequential file access and keyed file access. Look at the javadoc for class and click on the example "Using the RecordFormat class with the record-level database access classes" for an example of how to use the Record Level Access classes.

Access other iSeries resources

Below is a quick summary of other Toolbox features you may want to use:

  • List files in a directory and view files using the Toolbox for Java's Integrated File System classes.
  • Access data queues, read them sequentially, or take items off a data queue using the Toolbox for Java's DataQueue classes.
  • Access your printers, hold or release print jobs, view output queues, and even view spooled files using the Toolbox for Java's print classes.
  • Create Web pages using the Toolbox for Java's HTML and Servlet classes.

What's new in Toolbox V5R3 and JTOpen 4.0

In V5R3 (JTOpen 4.0 or above), the Toolbox for Java added the Extensible Program Call Markup Language (XPCML), an enhancement to PCML (Program Call Markup Language). PCML allowed you to describe the parameters to a program, but XPCML goes one step further and lets you use XML schemas to specify input and output parameters and data.

In V5R3, you now can parse communications traces between clients and servers programmatically. The Toolbox for Java's V5R3 release also includes enhancements to its HTML classes and enhancements to its JDBC driver support.

V5R3 includes a new CommandHelpRetriever class:


which can be used to retrieve help documentation for OS/400 control language (CL) commands in either HTML or User Interface Manager (UIM) format.

The Bottom Line

The Toolbox for Java is a class library that makes it easy to move to Java. You can call the same commands and programs as you always have, but now from Java. With the Toolbox for Java, you can access your integrated file system, database, printers, jobs, and other OS/400 or i5/OS resources.

As you expand your Java knowledge, you can use the Toolbox for Java to help you build Web pages, view spooled files, and move into web services.

The bottom line is that the Toolbox for Java may be exactly the toolbox you need to move into Java development for your iSeries

Susan Funk is a staff software engineer for IBM Rochester, currently a team leader for the Virtualization Engine console. She was formerly the lead software designer and developer on the IBM Toolbox for Java JDBC driver, and she was part of the development team for the iSeries Access for Web alpha release.  Susan can be reached at