Toolbox for Java and JTOpen

Frequently asked questions

Where do I report problems and what information should I provide?

Customers using the licensed program should report problems through the normal service channels. JTOpen feedback/problems can be posted to the JTOpen forum.

For problem reports, submit at least the following information if possible. Normally this is enough to isolate the problem.

  • Turn off the JIT(Just in Time compiler).

What platforms are supported?

The IBM Toolbox for Java is written in Java so it will run on any platform that fully supports the Java JVM. This means IBM Toolbox for Java is portable to the various platforms with a Java virtual machine.

For Java applets, a web browser that has a fully supported JVM is required.

What are my options for accessing Toolbox class files?

For Java programs , you have the following choices. In either case, the CLASSPATH environment variable on the workstation must be updated to point to the Toolbox jar file.

For Java applets , you have the following choices:

How do I obtain trace information from my Java program using the Toolbox?

Turn tracing on by doing the following inside of your Jav a program near the beginning of execution:

**Trace JDBC method available starting in V5R1**



This will enable tracing and then enable tracing for each individual trace category. Each trace category is described below:


Set the following Java system properties:

For example:

java,warning,diagnostic (If the Trace.file property isn't set, the output will go to "standard output".)

Note: The caller can enable or disable specific trace categories (by default all trace categories are disabled). Enabling or disabling one category does not affect other categories. When submitting problems, please enable all trace categories.

NOTE : If you are using JDBC, you will need to turn JDBC tracing on. This will trace JDBC configuration and execution information, which includes any exception stack traces. The easiest way to do this is to add " ;trace=true " to the end of your URL. In V5R1 you can also use the Trace.setTraceJDBCOn(true) method to turn JDBC tracing on.

How do I turn off the JIT?

Refer to Turning off the JIT.

What server ports does the Toolbox use to communicate with an IBM i system?

Refer to Server ports used.

May I bundle and redistribute the Toolbox classes with my application?

As part of the license agreement for the Toolbox, you are allowed to freely redistribute the Toolbox with your applications, either in whole or in part.

JTOpen can also be freely redistributed with your application, either in whole or in part. The JTOpen project is licensed under the IBM Public License, which has been approved by the Open Source Initiative.

For all the details, see the license agreement that is sent hardcopy with the Toolbox product:

How do I install the Toolbox Licensed Program on IBM i?

The Toolbox licensed program is included with IBM i OS. The Toolbox is installed into the Integrated File System in the directory structure for IBM i 7.1 and later: /QIBM/ProdData/OS400/jt400/lib.

Where should the Toolbox jar files be installed on IBM i?

There have been many situations in the past where problems were caused because users had old versions of the Toolbox jar files installed in non-standard locations on their systems, but didn't realize it.

Here are some locations where "rogue copies" of Toolbox jars and classes have been found on customers' IBM i systems:


Putting jars in extensions directories is dangerous and a frequent cause of hard-to-diagnose problems, because classes are found there before they are found in the application's normal Java classpath.

Note that some users have expanded the Toolbox jars into separate class files. So when hunting for rogue Toolbox classes, also look for files with pathnames such as .../com/ibm/as400/access/<className>.class

If your Java application is invoked from with Qshell, you could specify the "java -verbose" option. The output will be "noisy" on the screen, but afterwards you can press F6 to print the scroller, and then search the spool file for Toolbox classes to see where they are being loaded from.

To keep things simple, we recommend that the Toolbox jar files only be installed in their official locations:


What is the difference between JTOpen and the Toolbox LPP?

The term "JTOpen" refers to the open source software product "IBM Toolbox for Java" plus any additional enhancements provided by the open source community. JTOpen, which is governed by the IBM Public License, as well as its Java source code, is contained in the open source repository located off of

The terms "Toolbox" and "Toolbox LPP" refer to the IBM Licensed Program Product "IBM Toolbox for Java" which is supported by IBM and can be obtained from the IBM Toolbox for Java web site located at

How do I determine which version of Toolbox/JTOpen I have?

You can use the AboutToolbox utility, which is delivered as part of the Toolbox (in the package named "utilities"). Just run the following command:

java utilities.AboutToolbox

It will produce something similar to the following output. In this case, the user has JTOpen release 8.7, also known as "IBM Toolbox for Java" IBM i 7.2, PTF 7.

IBM Toolbox for Java:

Open Source Software, JTOpen 8.7, codebase 5770-SS1 V7R2M0.00 built=20151102


Supports JDBC version 3.0

Toolbox driver version 10.7

You may also use the java.lang.Package class to query the release of JTOpen / Toolbox that you have.

Why can't I connect to an IBM i system?

See trouble shooting for this information.

How do I debug an IBM i Program Call problem?

Refer to Debugging Program Calls.

When I do WRKACTJOB, why is the host server job running under QUSER instead of the profile specified on the AS400 object?

To improve performance, the host server jobs are prestarted jobs running under QUSER. When the Toolbox connects to a host server job in order to perform an API call, run a command, etc, a request is sent from the Toolbox to an available prestarted job. This request includes the user profile specified on the AS400 object that represents the connection. The host server job receives the request and swaps to the specified user profile before it runs the request. The host server itself originally runs under the QUSER profile, so output from the WRKACTJOB command will show the job as being owned by QUSER. However, the job is in fact running under the profile specified on the request. To determine what profile is being used for any given host server job, you can do one of three things:

  1. Display the job log for that job and find the message indicating which user profile is used as a result of the swap.
  2. Work with the job and display job status attributes to view the current user profile.
  3. Use Navigator for i to view all of the server jobs, which will list the current user of each job. You can also use Navigator for i to look at the server jobs being used by a particular user.

How do I get more information about an error that occurred on my IBM i system?

If you turn on Toolbox tracing, that may give you enough additional info to determine what's wrong.

If an IBM i program or command failed, examine the messages returned by your ProgramCall or CommandCall object. Call the getMessageList() method and examine each returned AS400Message object. Hint: Call the load() method on the AS400Message object before examining it.

The other place to get error information is in the job log of the appropriate "Host Server". The Toolbox communicates with the IBM i system through Host Servers, which are jobs running on the IBM i that listen for requests and forward them on to IBM i.

The table below lists the job names for each Host Server.
Hint: To view job logs, signon to the IBM i system, do WRKACTJOB, and press F14 to include prestart jobs in the listing.
Note: There may be several instances of each kind of Host Server running on your system, so you may need to look through a few job logs before finding the right one.

Toolbox Component Host server name Job Notes
Connect Signon host server QUSRWRK/QZSOSIGN (1)
ProgramCall, CommandCall Remote Command host server QUSRWRK/QZRCSRVS (1)
DataQueue Data Queue host server QUSRWRK/QZHQSSRV (1)
(various) Central server QUSRWRK/QZSCSRVS (1) (4)
Record-Level Access DDM host server QUSRWRK/QRWTSRVR (2)
Print Network Print server QUSRWRK/QNPSERVS  
NetServer NetServer server QSERVER/QZLSSERVER  

The Central server is used for license management, obtaining CCSID maps, etc.

Contact an IBM Sales Specialist

To draw insights and make better decisions, businesses rely on the secure, flexible and open platform of IBM Power Systems. Built with the first processor designed for big data workloads, the design of Power Systems combines the computing power, memory bandwidth and I/O in ways that are easier to consume and manage, building on strong resiliency, availability and security.

IBM Power Systems deliver flexibility and choice of operating systems to enable your business to support the next generation applications for big data and analytics and cognitive computing that are transforming how organizations work today. Whether running 1, 2, or all 3 - coupled with PowerVM, they maximize the benefit of Power Systems in your business.

Transform your business with Systems Software that enables virtualization, high availability, flexibility, security and compliance on Power Systems™. IBM’s integrated approach to developing Systems and Systems Software together delivers optimized results with Power Systems.

As an open innovation platform, Power Systems is optimized for big data and analytics performance and to deliver scale-out economics and security for the cloud. IBM and IBM Business Partner solutions exploit key capabilities in IBM Power Systems.

Over the last five years thousands of clients have migrated to IBM Power Systems for choice and flexibility. Learn how Power Systems has helped them revolutionise the way IT is developed and delivered, optimise for big data and analytics, and support private, public and hybrid offerings for scale-out or scale-up implementations all while improving business performance, reducing risk, and establishing a platform for growth.

Additional information