Toolbox for Java™ & JTOpen

Overview

Downloads

Support

News

Frequently Asked Questions

General:

• Where do I report problems and what information should I provide?
• What platforms are supported?
• What are my choices for accessing Toolbox class files?
• How do I obtain trace information from my Java program using the Toolbox?
• How do I turn off the JIT?
• What server ports does the Toolbox use to communicate with an i5/OS system?
• May I bundle and redistribute the Toolbox classes with my application?
• How do I install the Licensed Program on i5/OS?
• What is the difference between JTOpen and the Toolbox LP?

Performance:

• Why does it take so long to load my program when running on i5/OS's JVM?
• What are Toolbox native optimizations?
• How do I eliminate the 2-second delay in the data queue server?

Websphere and browsers:

• Where can I post WebSphere specific questions?
• When running in WebSphere, why can't my servlet find my PCML files?
• Why is my applet throwing security exceptions?
• Why do I get an UnsupportedEncodingException when I try to do text conversion in a browser?
• How do I use Toolbox JDBC in a Netscape applet (without a JDK 1.2 or 1.3 plugin)?
• Why do I get a verifier error when using JTOpen 3.x / V5R2 Toolbox inside Netscape?

Toolbox and OS/400 or i5/OS versions:

• Can I install Toolbox on an older version OS/400 or i5/OS?
• Which version of the Toolbox works with which release of OS/400 or i5/OS?
• How do I use Toolbox with JVM 1.2 / JVM 1.3 on OS/400 V4R5 or later?
• How does the Toolbox work with JVM 1.2 / JVM 1.3 on OS/400 V4R5 or later?
• How do I determine which version of Toolbox/JTOpen I have?

Troubleshooting:

• Why can't I connect to an i5/OS system?
• How do I debug an i5/OS Program Call problem?
• When I do WRKACTJOB, why is the host server job running under QUSER instead of the profile specified on the AS400 object?
• Why is my native Java program throwing an AS400SecurityException: Password is not set?
• After upgrading to JTOpen 3.x / V5R2 Toolbox why do I get a NoClassDefFoundError or ClassNotFoundException when using SSL?
• How do I get more information about an error that occurred on my i5/OS system?

JDBCFAQs.
Record-Level Database Access FAQs.
Toolbox performance hints

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.

• To which OS/400 or i5/OS release you are connecting?
• Turn off the JIT(Just in Time compiler) .
• Which toolbox modification/PTF level are you using? If you don't already know, you can use the AboutToolbox utility to find out for you.
• Turn Toolbox tracing on. This will trace a lot of configuration and execution information regarding how the Toolbox is being used. This includes any exception stack traces.

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/i/software/toolbox/.

How do I obtain trace information from my Java program using the Toolbox?
Turn tracing on by doing the following inside of your Java 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**

Trace.setTraceAllOn(true);

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

• DATASTREAM
  This category is used by Toolbox classes to log data flow between the local host and the remote system. It is not intended for use by classes that use Toolbox classes.
• DIAGNOSTIC
  This category is used to log object state information.
• ERROR
  This category is used to log errors that cause an exception.
• INFORMATION
  This category is used to track the flow of control through the code.
• WARNING
  This category is used to log errors that are recoverable.
• CONVERSION
  This category is used by Toolbox classes to log character set conversions between Unicode and native code pages. It is not intended for use by classes that use Toolbox classes.
• THREAD
  This category is used to log thread information.

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 install the Toolbox Licensed Program on an i5/OS system?
The Toolbox licensed program is included with OS/400 V4R2 or later and with i5/OS The Toolbox is installed into the Integrated File System in the directory structure: /QIBM/ProdData/HTTP/Public/jt400.

Can I install Toolbox on an older version of OS/400 or i5/OS?
Yes indeed. The Toolbox LP installs to the matching and two previous releases of OS/400 or i5/OS. For example, V5R4 JC1 installs on V5R2 OS/400, and V5R3 and V5R4 levels of i5/OS.

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:

• IBM OS/400 V5R2 or later compatible version
• IBM OS/2 Warp 4.0 or later compatible version
• IBM AIX 4.1.4 or later compatible version
• Sun Solaris 2.5 or later compatible version
• Microsoft Windows 95/98 or later compatible version
• Microsoft Windows NT or later compatible version
• Red Hat Linux 5.2 or compatible distributions (and Toolbox Modification 3 or later)

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.

• Download the Toolbox jar file to the workstation. The AS400ToolboxInstaller class provided by the Toolbox can be used to install the file and keep it up to date when PTFs are applied to the i5/OS system.
• 
  
• Leave the Toolbox jar file on the i5/OS system and access it via an IBM System i™ Access network drive.
• 
  
• Copy the jar file to a network server and use the client's network file support (network drives, NFS, etc.) to access the file.

For Java applets , you have the following choices:

• Use support built into browsers to access a file on the HTML server. The codebase parameter of the applet HTML tag tells the browser where to look for classes. The Toolbox classes are in the jt400.jar file. Update the applet tag to point to jt400.jar.
• 
  
• Use servlets. A servlet is a Java program running on a system called by an HTML page running on a client (a servlet is a more powerful, Java version of CGI-bin programs). The servlet will use the Toolbox classes to access i5/OS data instead of an applet running on the client. The servlet gets program parameters from the client, uses the Toolbox classes to access data on the i5/OS system, and then returns results to the client in an updated HTML page. The Toolbox classes are used only by the system running the servlet so they can be on the system’s local drive or on a network which the system can access.
• 
  
• Many browsers can access the client's CLASSPATH environment variable or have their own CLASSPATH variable. As in Java applications, the CLASSPATH variable can be updated to point to the Toolbox zip file which is copied to the workstation or is on a network the workstation can access.

Why does it take so long to start my program when running on i5/OS's JVM?
As with all Java virtual machines, the i5/OS JVM must verify the byte codes of a class file and convert them to server instructions before running a Java program. On an i5/OS system this is called creating a Java program . When a Java program that uses Toolbox functions is started, an i5/OS Java program containing the Toolbox classes is created but is not saved. Startup time is longer because the i5/OS Java program containing the Toolbox classes must be created every time. This startup processing can be avoided by saving the i5/OS Java program for the Toolbox zip/jar once it is created. Use i5/OS command CRTJVAPGM to create and save i5/OS 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.

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.

Why can't I connect to an i5/OS system?
See trouble shooting for this information.

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:

• the License Information document for the JC1 product (document number GC52-0369-02); and
• the International Programming License Agreement (Z125-3301-10).

JDBC FAQs:
See JDBC FAQs and trouble shooting for this information.

Record-Level Database Access FAQs:
See trouble shooting for this information.

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 i5/OS 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 i5/OS system, but only if the AS400Text object contains an AS400 object. The AS400 object is the only 'path' to the i5/OS 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");

Where can I post Websphere specific questions?
For general information about WebSphere for i5/OS, see the IBM WebSphere web site. You may also wish to read the IBM WebSphere for i5/OS 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.

How do I use Toolbox with OS/400 JVM 1.2 / JVM1.3 on OS/400 V4R5 or later?

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 i5/OS 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 i5/OS 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 i5/OS 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 Toolbox work with OS/400 JVM 1.2 / JVM1.3 on OS/400 V4R5?

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

• The Toolbox jar is not part of any system-delivered classpath so it must be added by the user. This is true for both the Toolbox jar delivered with the Toolbox Licensed Program (57xxJC1) and a Toolbox jar that is delivered with the application.
• Class files to support Toolbox native optimizations are automatically in the classpath. These files are in directory /QIBM/ProdData/Java400/com/ibm/as400/access. The same class files work under Java 1.1.x and Java 2.

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:

• Toolbox jar /QIBM/ProdData/HTTP/Public/jt400/lib/jt400Access.zip is in the system classpath.
• Class files to support Toolbox native optimizations are automatically in the system classpath. These files are in directory /QIBM/ProdData/Java400/com/ibm/as400/access. The same class files work under Java 1.1.x and Java 2.

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

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 i5/OS 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:

• Application-supplied versions of the Toolbox are probably ignored. Applications can ship their own version of the Toolbox and add that version to the user classpath. But, since the system classpath is searched before the user classpath and jt400Access.zip is in the system classpath, Toolbox classes will come out of jt400Access.zip instead of the application supplied jar.
• Application-supplied versions of the Toolbox cannot use native optimizations. A change in the Java specification for Java 2 states objects loaded because they are in the system classpath cannot reference objects loaded because they are in the user classpath. The native optimization classes are in the system classpath. Application-supplied Toolbox is in the user classpath. Since the native optimizations are in the system classpath they cannot be used by the application-supplied version of the Toolbox.

What you can do:

• Use the Toolbox that comes with the Toolbox licensed program. It all works when you use the licensed program version of the Toolbox. The Toolbox licensed program is built to install on various releases of the OS/400 or i5/OS, so if you want to use V5R4 Toolbox functions load the V5R4 Toolbox LP on your V5R4 i5/OS.
• Use your own version of the Toolbox. To use your own copy of the Toolbox you must:
  1. Remove the Toolbox licensed program or rename jt400Access.zip.
  2. Move the native optimizations. If you still want to use the optimizations reference them in the user classpath after moving them.

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 i5/OS 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 iSeries.

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.

Native Optimizations
Native optimizations are a set of functions that affect Toolbox operation when running on the i5/OS JVM. The optimizations are:

• Signon -- if no userid or password is specified in the AS400 object, the current job's userid and password are used.
• Record-level database access, data queues, program call, command call, and user space -- if security requirements are met, functions are performed by directly calling i5/OS APIs instead of making a socket calls to host servers to carry out a request.

The optimizations exist to make the Toolbox work the way a user would expect them to work when running on the i5/OS. 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 i5/OS there is no GUI but the Java program is running in an i5/OS 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 i5/OS resource (database file, data queue, or user space) is on the same machine, it makes sense to directly call an i5/OS 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.

Performance improvements when running on the i5/OS 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 i5/OS 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 i5/OS 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 i5/OS.

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 i5/OS 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)

• The Toolbox includes code that will automatically enable the socket connect privilege when the applet is running inside Communicator. Your code may need to manually enable other privileges if it needs to perform other restricted operations. See the Netscape documentation on how to enable these privileges. The Toolbox uses the netscape.security.PrivilegeManager class to enable the "UniversalConnect" privilege. Typically, Communicator will display a Grant/Deny window to the user when the Toolbox requests this privilege (unless it has already been granted for the current session). Communicator can be configured so that privileges are either always granted or always denied, so the Grant/Deny window will not appear. If the privilege is denied (either the user clicks the Deny button or Communicator is configured to always deny the privilege), the sandbox will throw a security exception and the Toolbox will be unable to make a socket connection.

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

• The Toolbox includes code that will automatically enable the socket connect privilege when the applet is running inside Internet Explorer. Again, your code may need to manually enable other privileges. See the Microsoft documentation on how to enable these privileges . The Toolbox uses the com.ms.security.PolicyEngine> class to assert the com.ms.security.PermissionID.NETIO permission. In reality, the easiest way to get your applet to run in Internet Explorer is to configure IE to ignore applet security altogether. There are various options that can be set by choosing the "View" menu, then "Internet Options..." and then the "Security" tab.

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

• When running with the Java Plug-in, security control is in the hands of the plugin instead of the browser. The easiest way to get your applet running is to either (1) sign the applet or (2) use a policy file as described below. See Sun's Java Plug-in documentation for more details on how to configure the plug-in.

appletviewer (JDK 1.1.x)

• Adjust the security level of appletviewer itself. In appletviewer, under the "Applet" menu, choose "Properties". In the "AppletViewer Properties" window, set the value for the "Class access" field to "Unrestricted".

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

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 iSeries Navigator to view all of the server jobs, which will list the current user of each job. You can also use iSeries Navigator to look at the server jobs being used by a particular user.

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:

• MF24942 - V4R3
• MF24475 - V4R4
• MF24728 - V4R5
• V5R1 and later - no PTF needed.

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.

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 i5/OS system?
If you turn on Toolbox tracing, that may give you enough additional info to determine what's wrong.

If an i5/OS 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 i5/OS system through Host Servers, which are jobs running on the System i that listen for requests and forward them on to i5/OS.

The table below lists the job names for each Host Server.
Hint: To view job logs, signon to the i5/OS 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.