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.
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:
-Dcom.ibm.as400.access.Trace.file=/tmp/toolboxTrace.txt (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:
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 http://jt400.sourceforge.net/.
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 http://www.ibm.com/systems/power/software/i/toolbox/index.html.
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:
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:
- Display the job log for that job and find the message indicating which user profile is used as a result of the swap.
- Work with the job and display job status attributes to view the current user profile.
- 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)|
|Network Print server||QUSRWRK/QNPSERVS|
The Central server is used for license management, obtaining CCSID maps, etc.