Toolbox for Java and JTOpen

Using Java to Access IBM i


Toolbox for Java and JTOpen: Java Access to IBM i

Toolbox for Java Introduction

The IBM Toolbox for Java is a library of Java classes supporting the client/server and internet programming model to an IBM i system. The classes can be used by Java applets, servlets, and applications to easily access IBM i data and resources. The Toolbox does not require additional client support over and above what is provided by the Java Virtual Machine and JDK.

The IBM Toolbox for Java provides support similar to functions available when using the IBM i Access APIs. It uses the IBM i host servers that are part of the base IBM i operating system to access data and resources on an IBM i system. Each of these host servers runs in a separate job on the system, communicating with a Java client program using architected data streams on a socket connection. The socket interfaces are hidden from the Java programmer by the IBM Toolbox for Java classes. Since the socket connections are managed by Toolbox classes, IBM i Access is not needed on the workstation.

JTOpen is the open source version of the IBM Toolbox for Java licensed program product, and contains identical code. Both have been tested on a wide variety of platforms, including AIX, IBM i, Linux, Solaris, and Windows. Both JTOpen and the IBM Toolbox for Java are distributed under the IBM Public License (IPL). JTOpen can be downloaded from IBM provides the same level of support for both JTOpen and the IBM Toolbox for Java licensed program product. The level of support (voice/email/fax) is dependent on the type of service contract.

Access IBM i Resources

The IBM Toolbox for Java provides classes to access resources on an IBM i system. Before accessing any resources, a connection is established using an instance of the AS400 class. The AS400 class manages a set of socket connections to the server jobs on server and sign-on behavior for the server, including prompting the user for sign-on information, password caching, and default user management.

Classes are also provided for data description and conversion. The data description classes allow a Java program to describe the record format of a buffer of data with an object. That object is used to convert and handle the data. The conversion classes provide conversion between IBM i and Java data formats. Classes are available to convert both numeric and character data.

File Resources

IBM i provides file resources in two forms. The first is in the form of physical files that have a specified data format. These files are organized into libraries and can be viewed as relational database resources. The second form of file resource is a POSIX-like file system known as the Integrated File System or IFS. In the IFS, the files exist as a sequence of bytes without any data format specified by the file attributes. The IBM Toolbox for Java provides classes to access these two forms of file resources.

Database resources can be accessed using both JDBC and Record-level access. The DB2 for i database are accessed using a JDBC driver written to the interfaces defined by the JDBC 3.0 and JDBC 4.0 specification. This JDBC driver is a type 4 driver, meaning that it is a pure Java that communicates with the IBM i using a network protocol. The Record-level access classes create, read, update, and delete IBM i files and members. The AS400File class is the abstract base class for the record-level access classes. It provides the methods for sequential record access, creation and deletion of files and members, and commitment control activities. The KeyedFile class represents a system file that has access by key while the SequentialFile class represents a system file that has access by record number.

The AS400FileRecordDescription class provides methods for retrieving the record format of a system file. This class also provides methods for creating Java source code for subclasses of RecordFormat and for returning RecordFormat object which describe the record formats of files on the server.

The following sample code illustrates connecting to an IBM i system named MYSYSTEM using the “USER” userid and “PASSWD” password. After connecting to the system, one record is read from the SYSIBM/SYSDUMMY1 file.

          AS400 as400 = new AS400(“MYSYSTEM”,”USER”,”PASSWD”);

          SequentialFile file = 
             new SequentialFile(as400,                  
, 1, 
                    AS400File.COMMIT_LOCK_LEVEL_NONE );
          Record record =;
          Object field = record.getField(0);
          System.out.println("Field is "+field); 

Files in the Integrated File System are accessed using the file system classes. The IFSFile class provides methods that operate on a file as a whole. The IFSFileReader, IFSFileWriter, and IFSRandomAccessFile classes allow reading and writing to a file. Through the file system classes, a Java program can open an input or output stream, open a file for random access, list the contents of a directory, and do other common file system tasks.

Program Resources

IBM i provides several means to run executable programs on the system. The first is using IBM I program and service program objects that are created using languages like C and RPG. IBM i also provides commands to perform specific functions. IBM i also has the ability to run Java programs. The IBM Toolbox for Java provides the ability to run these different types of executable programs.

IBM i Program and Service Program objects can be access using the ProgramCall and ServiceProgramCall classes. Parameters can be passed to the IBM i program and data can be returned to the Java program when the server program exits. A program call framework is provided via a program call markup language (PCML), a tag language used for supporting the program call function of the Toolbox. The language fully describes all parameters, structures and field relationships necessary to call an IBM i program.

Any non-interactive i5/OS command can be run using the CommandCall class. A list of IBM i messages generated by the command is available when the command completes. The following is an example of calling a command and retrieving the associated messages.

          CommandCall cmd = new CommandCall(as400);
          AS400Message[] messageList = cmd.getMessageList();
          for (int i = 0; i < messageList.length; i++) {

Java programs residing on the server can be run using the JavaApplicationClass class. Input to the Java program can be sent from the client to the server. The output of the Java program can also be read on the client.

Programmer Data Objects

IBM i provides support for several data object that are used by developing programs that communication with each other. A data queue object is used to send data from one program to another. The user space and data area objects provide persistent memory that can be accessed by several programs.

Both sequential and keyed sequential data queues can be access using the DataQueue and KeyedDataQueue classes. Entries can be added to and removed from a data queue, and data queues can be created or deleted on the system.

The UserSpace class is used to access IBM i user spaces. Using the UserSpace classe, users spaces can be created and deleted. A program can also read and write data into the user spaces on the system.

The CharacterDataArea, DecimalDataArea, LocalDataArea, and LogicalDataArea classes provide access to various kinds of data areas. The data area classes are used to read, write, create, and delete data areas on the system.

Print and Message Resources

IBM i has a print spooling system that manages the output of various programs. The IBM i also has a messaging system that programs use to communicate with users and other programs. IBM Toolbox for Java provides classes to access these IBM i resources.

Print resources can be accessed using the print classes: OutputQueue, Printer, PrinterFile, SpooledFile, and WriterJob. These print classes are used to retrieve lists of spooled files, output queues, printers, and other print resources. These classes can also work with output queues and spooled files, answer messages for spooled files and do other print related tasks. Additionally, classes are provided to create new spooled files on the system, and to generate SCS printer data streams. Writing directly to these classes, applications and applets can generate output on the IBM i spool system.

IBM i messages, message queues, and message files are accessed using the message classes. The message classes are used to retrieve messages generated by a previous operation such as a command call. The classes also allow access to information about a message on a message queue. A programmer can use the classes to interact with a message queue allowing messages to be sent, received, or replied to.

System Operation Information

The IBM i system also manages information crucial to the operation of the system. Information about users is available in user profiles. The IBM i system runs programs using jobs or processes. The resources used by jobs are group into system pools. The system also provides system values that are used to configure the operating systems. The IBM Toolbox for Java allows Java programs to access this system information.

Information about users and groups is available through user and group classes. The UserList class is used to retrieve a list of users and groups on the system. The User class provides detailed information about each user or group. For example, the following code will return the list of users on the system.

          UserList userList = new UserList( as400 );
          Enumeration e = userList.getUsers ();
          while (e.hasMoreElements ()) {
            User u = (User) e.nextElement ();
            System.out.println (u);

IBM i job information is accessed using the Job and JobList classes. The Job class is used to retrieve messages in a job log and information about a job such as name, number, type, user, status, job queue, and more. The JobList class provides a list of jobs based on selection criteria.

The SystemPool class allows the retrieval and change of system pool information. Using these classes, the name and size of the pool can be retrieved and changed.

The SystemStatus class retrieves system status information. The SystemStatus class can be used to retrieve information such as the total number of user jobs and system jobs currently running on the system, and the storage capacity of the system's auxiliary storage pool. For example, the following code returns the percentage of the system ASP that is used.

          SystemStatus systemStatus = new SystemStatus(as400);

The system value classes allow a Java program to review and change system values and network attributes. The SystemValue class allows the retrieving and setting of a single system value. The SystemValueList represents a list of system values on the server. A SystemValueList is retrieved using the SystemValueGroup class which represents a user-defined collection of system values and network attributes. A SystemValueGroup is a factory for generating and maintaining unique collection of system values. The following example, returns the values of the QTIME, QDATE, and QCCSID system values.

          SystemValue value = new SystemValue(as400, "QTIME");
          value = new SystemValue(as400, "QDATE");
          value = new SystemValue(as400, "QCCSID");


The IBM Toolbox for Java provides classes that Java programs can use to access resources on an IBM i. These classes allow access to IBM i file resources, both database files as well as IFS files. These classes also provide the ability to call programs, service programs, Java programs, and system commands on the IBM i. Java programs can use Toolbox classes to interact with other programs using data queue, user space, and data space objects on the IBM i. Print and message resources are also available. Finally, the Toolbox classes provide access to operational information about the system, including user, job, and system value information.


Downloadable resources


Sign in or register to add and subscribe to comments.

Zone=IBM i
ArticleTitle=Toolbox for Java and JTOpen