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.

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 applications, the Toolbox is supported on the following platforms:

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.setTraceOn(true);
Trace.setTraceDiagnosticOn(true);
Trace.setTraceInformationOn(true);
Trace.setTraceWarningOn(true);
Trace.setTraceErrorOn(true);
Trace.setTraceDatastreamOn(true);
Trace.setTraceThread(true);
Trace.setTraceJDBCOn(true);
**Trace JDBC method available starting in V5R1**

OR

Trace.setTraceAllOn(true);

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

OR

Set the following Java system properties:

For example:

java
-Dcom.ibm.as400.access.Trace.category=error,warning,diagnostic
-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 OS/400 V4R2 or later and with IBM i The Toolbox is installed into the Integrated File System in the directory structure: /QIBM/ProdData/HTTP/Public/jt400.

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:

/QIBM/ProdData/Java400/
/QIBM/UserData/Java400/ext/
/QIBM/ProdData/Java400/jdk14/lib/
/QIBM/ProdData/Java400/jdk14/lib/ext/
/QIBM/ProdData/OS400/Java400/ext/
/QIBM/ProdData/OS400/Java400/jdk/lib/ext/
/QOPT/WEBSPHERE/was/setup.jar

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:

/QIBM/ProdData/HTTP/Public/jt400/lib/jt400.jar
/QIBM/ProdData/OS400/jt400/lib/jt400Native.jar

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.

Why does it take so long to start my program when running on the IBM i JVM?

As with all Java virtual machines, the IBM i JVM must verify the byte codes of a class file and convert them to server instructions before running a Java program. On an IBM i system this is called creating a Java program . When a Java program that uses Toolbox functions is started, an IBM i Java program containing the Toolbox classes is created but is not saved. Startup time is longer because the IBM i Java program containing the Toolbox classes must be created every time. This startup processing can be avoided by saving the IBM i Java program for the Toolbox zip/jar once it is created. Use IBM i command CRTJVAPGM to create and save IBM i Java program containing the Toolbox classes. It may also be to your advantage to run CRTJVAPGM against the zip/jar/class files of your various Java applications that reside on the system.

Note 1: CRTJVAPGM has already been run against some of the Toolbox zip/jar files that are shipped with the Toolbox Licensed Program. Refer to this table to find out for each releaes the Toolbox files that have already had CRTJVAPGM run against them.

OS/400 or IBM i release Toolbox release Ship objects Installs with an associated JVAPGM?
V4R5 5769JC1
V4R5M0
jt400.jar No
jt400.zip No
jt400Access.zip Yes
jt400ntv.jar No
V5R1 5722JC1
V5R1M0
jt400.jar No
jt400.zip No
jt400Access.zip Yes
jt400Native.jar Yes
jt400ntv.jar No
jt400Servlet.jar Yes
V5R2 5722JC1
V5R2M0
jt400.jar No
jt400.zip No
jt400Access.zip Yes
jt400Native.jar Yes
jt400ntv.jar No
jt400Servlet.jar Yes
V5R3 5722JC1
V5R3M0
jt400.jar No
jt400Native.jar Yes
jt400Servlet.jar Yes
V5R4 5722JC1
V5R4M0
jt400.jar No
jt400Native.jar Yes
jt400Servlet.jar Yes
V6R1 5761JC1
V6R1M0
jt400.jar No
jt400Native.jar Yes
jt400Servlet.jar Yes

Note 2: The Toolbox zip/jar files can be optimized up to level 40. To be safe, optimize using option NoPreResolveExtRef, which is the default in v4r5. Using that option will load a class only when it is needed instead of loading all possible classes up front.

The command looks like:
CRTJVAPGM CLSF(jt400.jar) OPTIMIZE(40) LICOPT(NOPRERESOLVEEXTREF)

For more performance hints, see Toolbox Performance Hints.

What are Toolbox native optimizations?

Native optimizations are a set of functions that affect Toolbox operation when running on the IBM i JVM. The optimizations are:

The optimizations exist to make the Toolbox work the way a user would expect them to work when running on the IBM i. In the signon case, on a client when the default AS400 constructor is used, the Toolbox displays a graphical user interface to get userid and password from the user. On the IBM i there is no GUI but the Java program is running in an IBM i job and jobs have authentication information. It makes sense to pull the userid and password from the current job. In the other case, when the Java program and the IBM i resource (database file, data queue, or user space) is on the same machine, it makes sense to directly call an IBM i API instead of making a socket connection to a host server to carry out a request.

No change to the Java application is needed to get the optimizations. The Toolbox automatically enables them when appropriate. If the optimizations are not available the Toolbox works as if it is running on a client. You can disable the optimizations by removing the native optimizations classes or by using the setMustUseSockets() method on the AS400 object.

How do I eliminatee the 2-second delay in the data queue server?

Using DataQueue.read(int timeout) or DataQueue.peek(int timeout) where timeout is not zero may result in a two second delay before data is returned to the client. The delay happens because of the server's notification mechanism. If a timeout is specified and no entry exists on the queue, the server sets up a notification mechanism that (a) returns an item when one arrives on the queue, or (b) returns control to the client when the timeout period expires. It currently takes two seconds to establish this mechanism. So, if an item arrives on the queue just moments after the client request arrives, the item will not be returned to the client for two seconds.

The server reworked its notification mechanism to avoid the two second delay. To get the new mechanism, which avoids the delay, these are the delayed SLIC PTFs, with special instructions about how to disable the SLIC short wait:

How do I gain performance improvements when running on the IBM i JVM?

You can gain performance improvements for your Java programs when you use a version of the Toolbox for Java that matches the OS/400 or IBM i on your server. When the versions do not match, the Toolbox for Java still functions but is unable to take advantage of the performance improvements.

The table below shows which versions of the Toolbox for Java and OS/400 or IBM i you must run to get the performance improvements.

An 'X' indicates that performance enhancements are enabled for a given configuration of IBM Toolbox for Java and OS/400 or IBM i.

Level of OS/400 or IBM i Level of Toolbox for Java
V3R2M0 V3R2M1 V4R2 V4R5 V5R1 V5R2 V5R3 V5R4
V4R2 No Toolbox for Java performance enhancements are available.
V4R3   X X          
V4R4   X X          
V4R5       X        
V5R1         X      
V5R2           X    
V5R3         X X X  
V5R4             X X

Where can I post WebSphere specific questions?

For general information about WebSphere for IBM i, see the IBM WebSphere web site. You may also wish to read the IBM WebSphere for IBM i FAQs before posting a question to the WebSphere forum.

When running in WebSphere, why can't my servlet find my PCML files?

When running servlets under WebSphere, at least two different class loaders are at work: The system class loader, and the servlets or WebSphere class loader. A common practice is to have the Toolbox jar file (jt400.jar) in the system class loader's classpath. That way, all instances of WebSphere can share a single copy of the Toolbox. The application's servlets and .pcml files are typically in the servlet class loader's classpath. When the Toolbox tries to load the .pcml files, it uses the class loader that loaded the Toolbox (that is, the system class loader). The directory that holds the .pcml files is not in this classpath, however, so the system class loader cannot find the .pcml files.

For example, suppose the system classpath is /jt400/jt400.jar:/otherCommonStuff/,
and the WebSphere classpath is /myServlets/.
The application provider will put her servlets and .pcml files in /myServlets/ . The Toolbox will use the system class loader to find .pcml files, so it will only look in jt400.jar and /otherCommonStuff/ for the .pcml files. They aren't there, so the load fails.

The solution is to put the .pcml files in /otherCommonStuff/ (or some other directory), and add that directory to the system classpath.

Why is my applet throwing security exceptions?

When running a Toolbox applet using appletviewer there are certain security restrictions put in place by the Java "sandbox". One of these restrictions is to disallow any TCP/IP socket connections that are attempted by the applet. In order for the Toolbox to connect to an IBM i system, it must make a socket connection. So the sandbox must be told that the operation is allowed. (Note that different environments use different ways of notifying the applet when some code has tried to perform an operation that is not allowed by the sandbox. This just means that you won't get the same type of exception when running under Netscape Communicator as you would running under Sun's appletviewer.)

In any case,certains steps can be taken to allow your Toolbox applet to run. Specifically, you will need to tell the sandbox that the Toolbox applet is allowed to make a socket connection. There are different ways to enable the socket connection privilege depending on the environment:

Netscape Communicator (without Sun's Java Plug-in)

Microsoft Internet Explorer (without Sun's Java Plug-in)

Netscape Communicator or Microsoft Internet Explorer (using Sun's Java Plug-in)

appletviewer (JDK 1.1.x)

appletviewer (JDK 1.2.x or higher)
Java 2 uses a new security scheme that involves policy files. A policy file can be generated using the policytool tool provided by the JDK, but for Toolbox purposes, the policy file can be created by hand using a text editor. The policy file should contain the following code:

grant
{
permission java.net.SocketPermission "*",
"accept, connect, listen, resolve";
};

Note that the "*" is the server to which the Toolbox connects. Specifying "*" will allow the applet to make a socket connection to any host, so replace the "*" with "hostname" for a higher degree of security.

The policy file location can be specified on the command-line for appletviewer like this:

appletviewer -J-Djava.security.policy=mypolicyfile.txt myapplet.html
When running in VisualAge for Java, it is not possible to pass this argument to the appletviewer invocation. Therefore, it is easiest to edit the system-wide default policy file that appletviewer uses. (See the Sun policytool documentation for more information about default policy file paths.) In Windows NT, this file is usually C:\WINNT\Profiles\ username \.java.policy which may or may not already exist on your system.

Helpful Links
Sun's Java Applet Security FAQ
Netscape's Security FAQ
Netscape Capabilities and Privileges APIs
Package netscape.security javadoc
IBM applet performance and programming tips (included as part of the IBM SecureWay On-Demand Server documentation)
Deploying Java in Internet Explorer 4.0 and Netscape 4.0
Microsoft's Trust-Based Security for Java
Sun's Java Plug-in FAQs
Troubleshooting security issues with Sun's Java Plug-in

Why do I get an UnsupportedEncodingException when I try to do text conversion in a browser?

If you are doing something like this: AS400Text text1 = new AS400Text(10); byte[] byteArray1 = text1.toBytes("Some text");

and you are getting this error when running in a browser:

Unexpected CCSID returned from getBestGuessAS400Ccsid: 37 java.io.UnsupportedEncodingException at com/ibm/as400/access/ConvTable.getTableNoSwapChars

The problem is that browsers do not ship EBCDIC-Unicode conversion tables. JDKs and most JREs ship them but browsers don't.

The Toolbox does conversion by first asking the JVM to do it. Second it looks for a table shipped with the Toolbox, and third it downloads the table from the IBM i system. If the JVM cannot convert the string, and the Toolbox does not ship the table (it contains mostly double-byte EBCDIC tables that are not practical to download), the Toolbox can download the table from the IBM i system, but only if the AS400Text object contains an AS400 object. The AS400 object is the only 'path' to the IBM i system, so if AS400Text is not specified with an AS400 object, it cannot download the table.

In the above error scenario, the browser JVM did not contain conversion tables, the Toolbox did not ship the one you wanted to use, and there was no path to the server. AS400Text cannot convert and throws an unsupported encoding exception. The fix is to change the AS400Text instantiation to include an AS400 object:

myAS400 = new AS400("MYSYSTEM");
AS400Text text1 = new AS400Text(10, myAS400);
byte[] byteArray1 = text1.toBytes("Some text");

How do I use Toolbox JDBC in a Netscape applet (without a JDK 1.2 or 1.3 plugin)?

  1. Include the JDBC 2.0 classes in the applet's classpath. Why? Because Netscape's class verifier is overly strict and tries to verify the existence of all referenced classes, even ones that the user's application never uses. It is enough that they are in the Toolbox jar file. Since the Toolbox supports JDBC 2.0, and the 2.0 classes are referenced in the Toolbox, but are not available in the applet's 1.1.x JVM, then the verifier throws an error.

    We ship stubs for the JDBC 2.0 classes in jtStubs.jar, which is available off of the JTOpen web site. Or, the developer can hardcode their own if they wish. Using this jtStubs.jar will trick the Netscape class verifier into thinking that the JDBC 2.0 classes are indeed available.

    Here's a direct link to the stubs: http://jt400.sourceforge.net/jtStubs.jar
  2. Even though we have satisfied the verifier by putting stubs for the missing JDBC 2.0 classes in our CLASSPATH, we now run into a Netscape security issue. The rule we are violating is one that says that no applets are allowed to include classes in their CLASSPATH that are part of any package beginning with "java.". Since we have just included classes that belong to the java.sql package, we are violating the rule. The Netscape security manager will throw a security exception.

    In order to get around this, we have to turn off this rule. The only way we know of doing that is to enable the "30Capabilities" privilege. This tells Netscape's security manager to use Netscape 3.0 security rules instead of the new rules that are part of Netscape 4.x. This may open up some security holes for an applet, but it's the only way to get this to work without using a JDK plug-in.
  3. In order to enable the 30Capabilities privilege, you need to be able to load Netscape's privilege manager. Netscape won't let you do this unless the applet is trusted. If the applet is trusted, it means that the jar file you're using was digitally signed. So, in order to get it to work, you need to sign the jar file(s) you're using. Unfortunately, this can be a hassle.

    Another way around this is to enable a privilege in the Netscape preferences file that tells Netscape, "hey, treat my applet as if it is trusted, even though the jar file isn't signed." This will allow the code to load the privilege manager and enable the 30Capabilities privilege talked about in #2 above.

Follow these steps to resolve the VerifierError problem:

  1. Make sure all Netscape processes are gone (in Windows NT, you can use the Task Manager).
  2. Bring up a DOS prompt.
  3. Set CLASSPATH to nothing "set CLASSPATH=".
  4. Invoke netscape from command line, e.g. C:\Program Files\Netscape\Communicator\Program\netscape.exe.
  5. Clear your caches under the Preferences menu.
  6. At this point, we can safely say there is nothing cached and nothing superfluous is in Netscape's CLASSPATH.
  7. You need to enable the 30Capabilities privilege in your code. The Toolbox needs to enable the UniversalConnect privilege in our code. To do both of these, the PrivilegeManager needs to be loadable by the JVM. If the jar files being used are not signed then the JVM will not be able to load the PrivilegeManager at all because of applet security restrictions.

    To get around this, either sign the jar files or add the following line to the Netscape prefs.js and liprefs.js files found in C:\Program Files\Netscape\Users\default\ directory while no Netscape instances are running:
    user_pref("signed.applets.codebase_principal_support", true);
  8. We also recommend adding the following preference to those prefs.js and liprefs.js files for ease of debugging:
    user_pref("signed.applets.verbose_security_exception", true);
  9. Optionally, to enable 30Capabilities you can add this line to the preferences files:
    user_pref("signed.applets.local_classes_have_30_powers", true);
  10. Note that signing your jar files means that you don't have to add the above preferences to Netscapes prefs.js file, as long as you enable them in your code.
  11. To continue debugging, bring up the Java Console and type a '9' for maximum output messages.
  12. Surf to the web page that contains the applet that will run.
  13. At some point, Netscape will ask you to Grant/Deny the 30Capabilities and/or the UniversalConnect privileges. Grant both of them, of course.
  14. If you do not get a window asking you to Grant/Deny anything, then the applet console output probably contains messages like "Unable to load PrivilegeManager" and "Permission denied" and eventually the Toolbox will die with a ClassDefNotFound on one of the JDBC classes. Further up the trace, you will probably see a Verifier error on java.sql.BatchUpdateException.

    If you have verbose exceptions turned on in step 8 above, then you will also see an exception indicating that something in the package "java.sql" could not be loaded for security reasons. If any of these things happen, then you don't have a jar file signed, are using individual class files instead of a jar file, or don't have the preference in step 7 above in your preferences file.
  15. This will not work if you unzip the jar files because then the Netscape JVM doesn't think anything is signed, and puts more security restrictions in place. To get around this, either sign and use jar files, or use the preference in step 7 above.

Instead of doing step 9, you can enable the privilege programmatically like this:

void someMethod()
{
... // some code
// At this point, Netscape should pop up a Grant/Deny window
netscape.security.PrivilegeManager.enablePrivilege("30Capabilities");
... // more code that needs to do JDBC stuff
}

Note that you will need either Netscape's jar file or the jtStubs.jar in your CLASSPATH when you compile the above code, otherwise the netscape.security.PrivilegeManager class won't be found. (We ship a stub for it in jtStubs.jar).

Why do I get a verifier error when using JTOpen 2.x / V5R1 or later Toolbox inside Netscape?

This has been fixed as of JTOpen 2.03. If you have an earlier version of JTOpen or V5R1 and earlier Toolbox, read the following circumventions.

As of V5R1, the Toolbox now supports long passwords. This support requires a different type of password encryption. The Toolbox uses classes out of the java.security package to do this encryption. The java.security package is included with standard 1.1.x JDKs, but the default JVM that comes with Netscape does not contain these classes. There are two different ways to circumvent this problem:

  1. Load the Java Plug-in to upgrade the level of the JVM inside Netscape. The plugin contains the previously missing java.security classes, thus avoiding the verifier error. These classes will allow an applet using the Toolbox to properly connect to V5R1 or higher systems using long passwords.
  2. Get the jtStubs.jar. The stubs will get around the Netscape verifier error, but will not allow an applet using the Toolbox to connect to a V5R1 or higher system using long passwords. The applet will only be able to connect to systems using old style passwords.

For more information about the verifier error, read this FAQ.

Can I install Toolbox on an older version of OS/400 or IBM i?

Yes indeed. The Toolbox LP installs to the matching and two previous releases of OS/400 or IBM i. For example, V5R4 JC1 installs on V5R2 OS/400, and V5R3 and V5R4 levels of IBM i.

Which version of the Toolbox works with which release of OS/400 or i5/OS?

Refer to Release-to-release compatibility.

How do I use Toolbox with OS/400 JVM 1.2 / JVM1.3 on OS/400 V4R5 or later? OR Why is my native Java program throwing an AS400SecurityException: Password is not set?

Environment

OS/400 V4R5
OS/400 JVM Level 1.2 or 1.3
Java program running on the server

Requirements

PTF 5769SS1 SF62426
PTF 5769JV1 SF62531

Description

Java 2 introduces the concept of multiple classpath environment variables. You are familiar with the user specified classpath. Java 2 has two additional classpaths -- the boot classpath and extensions classpath. When Java 2 looks for a class file it first searches everything in the boot classpath, then everything in the extension classpath, then finally everything in the user classpath. When OS/400 V4R5 shipped, jt400Access.zip (the Toolbox access classes) was in the boot classpath. This greatly reduced the flexibility of using the Toolbox on the OS/400 or IBM i system. Since the boot classpath is searched before the user classpath, no user-specified version of the Toolbox files would be used. This limit plus additional class loading problems is a problem fixed in the above PTFs. Loading the above XPF and JV1 PTF will remove the Toolbox from the boot classpath. After applying the PTFs, the Toolbox must be added to the user classpath. This is actually no different than Java 1.1.x since in Java 1.1.x the Toolbox classes had to be in the user classpath. To get the native optimizations, one additional file must be added to the user classpath. Add /qibm/proddata/java400/jt400ntv.jar to the user classpath to get native optimizations.

This applies only to Java programs running on the OS/400 or IBM i system with Java 1.2 or 1.3. No change is needed if the Java program is running on a client or if the Java program is running on the OS/400 or IBM i system with JVM 1.1.x.

The default JVM level for V5R1 is 1.3 if 1.3 is installed. Also, in V5R1 the /qibm/proddata/OS400/jt400/lib/jt400Native.jar file can be used to get the native optimizations.

How does the Toolbox work with JVM 1.2 / JVM 1.3 on OS/400 V4R5 or later?

Java 1.1.x

The Toolbox works as it does under Java 1.1.x on all other releases of the OS/400 or IBM i:

Java 2 (JVM 1.2.x or 1.3.x)

Toolbox behavior under Java 2 on OS/400 V4R4 is different than its behavior under 1.1.x:

Table of Toolbox classes used by default when running under the OS/400 or IBM i JVM

OS/400 or IBM i version JDK version Toolbox in system CLASSPATH
V4R3 1.1.x not automatic
1.2.x /QIBM/ProdData/HTTP/Public/jt400/lib/jt400Access.zip
1.3.0 JDK 1.3.0 is not available on V4R3.
V4R4 1.1.x not automatic
1.2.x /QIBM/ProdData/HTTP/Public/jt400/lib/jt400Access.zip
1.3.0 /QIBM/ProdData/HTTP/Public/jt400/lib/jt400Access.zip
V4R5
or
V5R1
or later
1.1.x not automatic
1.2.x not automatic
1.3.0 not automatic
1.4.x not automatic
OS/400 or IBM i version JDK version Toolbox native optimizations in system CLASSPATH
V4R3 1.1.x /QIBM/ProdData/Java400/com/ibm/as400/access
1.2.x /QIBM/ProdData/Java400/com/ibm/as400/access
1.3.0 JDK 1.3.0 is not available on V4R3.
V4R4 1.1.x /QIBM/ProdData/Java400/com/ibm/as400/access
1.2.x /QIBM/ProdData/Java400/com/ibm/as400/access
1.3.0 /QIBM/ProdData/Java400/com/ibm/as400/access
V4R5
or
V5R1
or later
1.1.x /QIBM/ProdData/Java400/jt400ntv.jar
1.2.x not automatic
1.3.0 not automatic
1.4.x not automatic

Notes:

  1. Toolbox classes: In the cases where the regular Toolbox classes are not picked up by default with the system class loader, the user will have to manually add the Toolbox to the CLASSPATH. They can either supply their own Toolbox jar file or use the one from the installed licensed program product. This jar file can be found in /QIBM/ProdData/HTTP/Public/jt400/lib/jt400.jar.
  2. Toolbox native optimizations: In the cases where the Toolbox native optimizations are not picked up by default with the system class loader, the user will have to manually add them to the CLASSPATH. In V4R5, the native optimizations are packaged separately in /QIBM/ProdData/Java400/jt400ntv.jar.
  3. Toolbox releases: If the Toolbox licensed program is installed on a different version of OS/400 or IBM i than the one with which it shipped, native optimizations may not be used, despite the fact that they may be picked up by default. See the chart of native optimizations vs. Toolbox releases to check compatibility.

Toolbox being in the system classpath causes the following side effects:

What you can do:

What about V4R5:
The Toolbox jar used when running Java 2 on V4R4 is hard to modify because of the class loader change made in Java 2. Toolbox tried to fix the problem by adding jt400Access.zip to the system classpath. In many cases this is no better. In V4R5 another method is used to work within the restrictions of the Java 2 loader. As in 1.1.x, Toolbox is not in any classpath in V4R5. If you want to use Toolbox classes you must add the Toolbox jar to the classpath. Native optimizations are also out of the system classpath. If you want to use native optimizations you must add the jar file that contains the optimizations (jt400ntv.jar) to the user classpath. Since Toolbox is no longer in a classpath, the user has total control over which version of the Toolbox is used -- the one supplied by the Toolbox licensed program or the one provided by the application.

What about V5R1 or later:
Toolbox classes in V5R1 or later are now also shipped with OS/400 or IBM i in /qibm/proddata/OS400/jt400/lib/jt400Native.jar. The jt400Native.jar file contains both the normal Toolbox classes plus the native optimizations. Use jt400Native.jar instead of jt400.jar when running on the IBM i.

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 4.5, also known as "IBM Toolbox for Java" V5R3, PTF 5.

IBM Toolbox for Java:

Open Source Software, JTOpen 4.4, codebase 5722-JC1 V5R3M0.5

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.

Why is my native Java program throwing an AS400SecurityException: Password is not set?

Environment

OS/400 V4R5
OS/400 JVM Level 1.2 or 1.3
Java program running on the server

Requirements

PTF 5769SS1 SF62426
PTF 5769JV1 SF62531

Description

Java 2 introduces the concept of multiple classpath environment variables. You are familiar with the user specified classpath. Java 2 has two additional classpaths -- the boot classpath and extensions classpath. When Java 2 looks for a class file it first searches everything in the boot classpath, then everything in the extension classpath, then finally everything in the user classpath. When OS/400 V4R5 shipped, jt400Access.zip (the Toolbox access classes) was in the boot classpath. This greatly reduced the flexibility of using the Toolbox on the OS/400 or IBM i system. Since the boot classpath is searched before the user classpath, no user-specified version of the Toolbox files would be used. This limit plus additional class loading problems is a problem fixed in the above PTFs. Loading the above XPF and JV1 PTF will remove the Toolbox from the boot classpath. After applying the PTFs, the Toolbox must be added to the user classpath. This is actually no different than Java 1.1.x since in Java 1.1.x the Toolbox classes had to be in the user classpath. To get the native optimizations, one additional file must be added to the user classpath. Add /qibm/proddata/java400/jt400ntv.jar to the user classpath to get native optimizations.

This applies only to Java programs running on the OS/400 or IBM i system with Java 1.2 or 1.3. No change is needed if the Java program is running on a client or if the Java program is running on the OS/400 or IBM i system with JVM 1.1.x.

The default JVM level for V5R1 is 1.3 if 1.3 is installed. Also, in V5R1 the /qibm/proddata/OS400/jt400/lib/jt400Native.jar file can be used to get the native optimizations.

After upgrading to JTOpen 3.x / V5R2 Toolbox why do I get a NoClassDefFoundError or ClassNotFoundException when using SSL?

In order to use SSL connections, these versions of the Toolbox require the SSLight package that ships with V5R2 licensed programs 5722-CE2 and 5722-CE3.

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  
JDBC Database server QUSRWRK/QZDASOINIT (3)
IFS File server QSERVER/QPWFSERVSO  
NetServer NetServer server QSERVER/QZLSSERVER  

Notes:
(1) On pre-V4R4 OS/400, these host servers run in subsystem QSYSWRK.
(2) On pre-V5R2 OS/400, the DDM host server runs in subsystem QSYSWRK.
(3) On pre-V5R1 OS/400, the Database host server runs in subsystem QSERVER.
(4) The Central server is used for license management, obtaining CCSID maps, etc.

Contact IBM

Browse Power Systems

Next generation applications for big data and analytics and cognitive computing are providing unprecedented insights into opportunities, threats and efficiencies. IBM Power Systems is at the forefront of delivering solutions to gain faster insights from analyzing both structured information and unstructured big data. With the secure, flexible and open platform of IBM Power Systems plus solutions and software, organizations can outpace their competitors by delivering faster services, providing differentiated offerings and turning operational cost into investment opportunity.

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.

IBM and IBM Business Partner solutions exploit key benefits in IBM Power Systems’ unique design combined with systems software to provide support for next generation applications for big data and analytics and cognitive computing to providing unprecedented insights into opportunities, threats and efficiencies to your organization.

Over the last five years thousands of clients have migrated to IBM Power Systems. Learn how Power Systems has helped them support next generation applications for big data and analytics and cognitive computing on an open platform for choice while improving business performance, reducing risk, and establishing a platform for growth.

Additional information