Toolbox for Java and JTOpen

What it is

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

How it works

The IBM Toolbox for Java provides support similar to functions available when using the IBM i Access APIs. It uses the i5/OS host servers that are part of the base i5/OS operating system to access data and resources on an i5/OS 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.

Java Beans are provided for most public interfaces.

Access i5/OS Resources

• Database
  • JDBC - DB2 for i data can be accessed using a JDBC driver written to the interface defined by the JDBC 3.0 specification.
  • Record-Level database access - Physical and logical files on the system can be accessed a record at a time using the interface of these classes. Files and members can be created, read, deleted, and updated.
• Integrated File System - The file system classes allow access to files in the Integrated File System. Through the Integrated File System file 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.
• Programs - Any i5/OS program can be called. Parameters can be passed to the i5/OS 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 i5/OS program.
• Commands - Any non-interactive i5/OS command can be run. A list of i5/OS messages generated by the command is available when the command completes.
• Data Queues - Access to both keyed and sequential data queues is provided. Entries can be added to and removed from a data queue, and data queues can be created or deleted on the system.
• Print - Access to i5/OS print resources is provided. Using the print classes you can retrieve lists of spooled files, output queues, printers, and other print resources. You can 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 i5/OS spool system.
• Jobs - Access i5/OS jobs and job logs. Using the job classes you can retrieve messages in a job log, information about a job (name, number, type, user, status, job queue, and more), or get a list of jobs based on your selection.
• Messages - Access i5/OS messages, message queues, and message files. Using the message classes you can retrieve a message that is generated from a previous operation such as a command call, information about a message on a message queue, and interact with a message queue allowing you to send, receive, and even reply to messages.
• Users and Groups - Access users and groups. The user and group classes allow you to get a list of users and groups on the system and information about each user.
• User Spaces - Access user spaces. Use the user space class to read, write, create, and delete user spaces on the system.
• Data Areas - Access various kinds of data areas (character, decimal, local, logical). Entries can be added to and removed from a data queue, and data queues can be created or deleted on the system. Use the data area classes to read, write, create, and delete data areas on the system.
• System Values - Query and reset system values and network attributes on the system.
• System Status - Retrieve system status information. Using the SystemStatus class you can 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.

Graphical User Interfaces Present Data to the User

The IBM Toolbox for Java provides a set of graphical user interface (GUI) classes to retrieve and present data to the user. The graphical user interface classes access and manipulate data on an i5/OS system by using the classes mentioned in the previous section along with Sun's Java Foundation Classes (JFC/Swing) to display the data to the user.

Server panes are components used to present and allow manipulation of one or more i5/OS resources. All panes extend on the Java Component class, thus they can be added to any Container, Window, or AWT Frame. The IBM Toolbox for Java provides the following panes:

• AS400ListPane - present a list of selectable i5/OS resources.
• AS400DetailsPane - present a list of i5/OS resources in a table where each row is selectable and contains information about a single resource.
• AS400TreePane - presents a tree hierarchy of selectable i5/OS resources.
• AS400ExplorerPane - combines a tree hierarchy and details view so that a resource selected in the tree is presented in the details.

Server panes can be used with the following i5/OS resources: Integrated File System, jobs, messages, print resources, users and groups.

In addition to server panes, the IBM Toolbox for Java provides other GUI components that extend JFC/Swing classes for the following i5/OS resources:

• Commands - present a button or menu item that calls a non-interactive i5/OS command.
• Data Queues - use a graphical text component to read or write to an i5/OS data queue.
• Integrated File System - present a dialog to select a file on the system or use a graphical text component to represent a text file on the system.
• JDBC
  • present a button, menu item, or text component to issue an SQL statement.
  • present the results of an SQL query in a form or table.
  • present an interactive tool for dynamically building SQL queries.
• Programs - present a button or menu item that calls an i5/OS program.
• Record Level Access - present a list of records from a server file in a form or table.
• Spooled Files - use a spooled file viewer to show print output.
• System Values - present a graphical view of a system value list.

Additional Classes

• Provide the infrastructure needed to manage sign-on information, create and maintain sockets connections to i5/OS services, and send and receive data.
• Provide 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 i5/OS and Java data formats. Classes are available to convert both numeric and character data.
• Provide for the installation and synchronization of the IBM Toolbox for Java package. When the user chooses to run the IBM Toolbox for Java package locally on the client workstation, classes are provided to install the package, and update the package on request, when a PTF is applied to the i5/OS system.
• Reduce the size of jt400.jar. The AS400ToolboxJarMaker utility will remove classes and other files from the Toolbox jar or zip file that are not used by an application. The result is a smaller jt400.jar file which improves download performance.

New classes

IBM Toolbox for Java V5R4 features many new classes in the existing access package. The new classes enable you to:

• Control the conversion of character set data by utilizing the BidiConversionProperties class.
• Read character files in the Integrated File System using the IFSFileReader class.
• Write character files in the Integrated File System using the IFSFileWriter class.
• View and navigate the Integrated File System using the IFSSystemView class.
• Query and modify the state and configuration of the NetServer.
• Create and work with a save file.
• Create and work with a subsystem.
• Work with an entry in the call stack of a specific thread of a server job.

For more information about new classes, see the associated package documentation.

Enhanced classes

IBM Toolbox for Java V5R4 also includes enhancements to existing classes. These enhancements offer:

• Improvements to IFS file name handling.
• Enhancements to the JarMaker and AS400ToolboxJarMaker utilities to make them more effective at reducing JAR sizes.
• Updates to FTP and AS400FTP to avoid possible hang conditions when trying to get a file that was not found.
• Changes to several JDBC classes. Notable changes include the following:
  • Increased the statement size limit from 65535 bytes to 2 megabytes, or 2097152 bytes.
  • Increased the size of column names supported for SQL tables from 30 bytes to 128 bytes. There is one exception where 128 byte column names will not be returned. When local package caching is used and column names exceed 30 characters, the server will return the column names as the system column name.
  • A new option was added to the JDBC driver to turn on database host server tracing. To support this feature, option "64" was added to the "server trace" connection property.
  • AS400JDBCConnection objects can now accept and IBM Enterprise Workload Manager (eWLM) correlator and pass it on to the host as a connection attribute correlator for use with the Application Response Measurement (ARM) APIs.

Deprecated Packages

Several packages have been deprecated since V5R3. These packages include:

• com.ibm.as400.resource
• com.ibm.as400.vaccess

Deprecated Classes

Several classes have been deprecated since V5R3. These classes include:

• utilities.AS400ToolboxInstaller
• com.ibm.as400.access.NetServer has been replaced by ISeriesNetServer.
• com.ibm.as400.access.IFSTextFileInputStream has been replaced by IFSFileReader.
• com.ibm.as400.access.IFSTextFileOutputStream has been replaced by IFSFileWriter.

Toolbox is Java

The IBM Toolbox for Java requires a Java virtual machine that fully supports JDK 1.1.8 or any later JDK, including Java 2. Many new IBM Toolbox for Java functions require using version 1.4 or higher of the JVM. If your program uses the Graphical Toolbox or classes in the vaccess package, Swing 1.1 is also required. For Java applications, the Toolbox has been tested on Java Virtual Machines on at least the following platforms:

• IBM OS/400 V4R5 or later
• IBM AIX 4.3.3.1
• Sun Solaris 5.7
• Red Hat Linux 7.0
• Microsoft Windows XP
• Microsoft Windows 2000

For Java applets, IBM Toolbox for Java no longer supports running in the default JVM in Netscape(R) Navigator or Microsoft(R) Internet Explorer. For your applet that uses Toolbox for Java classes to run in a browser, you should install a plug-in such as the Sun Java 2 Runtime Environment (JRE) 1.3.0 plug-in.

Toolbox for Java no longer includes data400.jar. The classes that were in data400.jar are now in jt400.jar. Remove data400.jar from your CLASSPATH statements.

You can not use this release of IBM Toolbox for Java to deserialize some objects that you serialized using releases prior to V5R1.

Secure Sockets

If you are using Secure Sockets Layer (SSL) to encrypt data flowing between the client and the server, you must use one of the following:

• Java Secure Socket Extension (JSSE)
• SSL objects delivered in a V5R2 or later version of IBM IBM i Client Encryption licensed program 5722-CE2 or 5722-CE3. This release of IBM Toolbox for Java does not work with V4R5 and earlier versions of IBM i Client Encryption.

Application Development

• The Toolbox includes a user interface framework to provide a productive development environment for building graphical panels. The framework automatically handles the exchange of data. The developer need only create one or more data beans and bind them to the panel components using tags using the Panel Definition Markup Language (PDML).
• A user interface framework is provided to create a platform- and technology-independent representation of graphical panels based on the Extensible Markup Language (XML). A pure Java framework for interpreting the XML and constructing user interface panels based on the Java Foundation Classes (JFC) is also provided.
• A resource script converter is provided which converts Windows dialogs to equivalent Java panels defined in XML.
• A graphical user interface builder tool is provided to develop Java GUIs. This tool is a WYSIWYG GUI editor.

i5/OS Requirements

In order to connect to the i5/OS system and access its data and services, the IBM Toolbox for Java requires both the TC1 Licensed Program (TCP/IP Connectivity Utilities for i5/OS) and the Host Server option of i5/OS to be installed and configured on the system.

A discussion facility that puts you in touch with other users of JTOpen and the Toolbox

Learn more