IBM Toolbox for Java - JTOpen Version
Copyright (C) 1997-2003 International Business Machines Corporation and
others. All rights reserved.
File: README
Last updated: April 4, 2003
The term "JTOpen" refers to the open source software product
"IBM Toolbox for Java" (formerly "AS/400 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://oss.software.ibm.com/developerworks/opensource/jt400.
The terms "Toolbox" and "Toolbox LPP" refer to the IBM Licensed Program
Product "IBM Toolbox for Java" (formerly "AS/400 Toolbox for Java") which is
supported by IBM and can be obtained from the IBM Toolbox for Java web site:
http://www.ibm.com/servers/eserver/iseries/toolbox.
Contents
What is the Toolbox?
Why Open Source?
Differences between JTOpen and the Toolbox LPP
Download and installation of JTOpen
Requirements
Files
Building and Using JTOpen
Using the Toolbox LPP
Support information
What is the Toolbox?
The IBM Toolbox for Java is a set of Java classes that allow you to
access AS/400 or iSeries data through a Java program. With these classes,
you can write client/server applications, applets, and servlets that work
with data on your server. You can also run Java applications that use the
IBM Toolbox for Java on the OS/400 Java Virtual Machine.
The Toolbox is available as an installable licensed program for the AS/400
as of OS/400 V4R2 and the iSeries as of OS/400 V5R1. Here is a breakdown of
Toolbox releases versus operating system versions:
Toolbox Installs on Connects to
release LPP release OS/400 version OS/400 version
------- -------------- -------------- --------------
V4R2 5763JC1 V3R2M0 V3R2 and up V3R2 and up
V4R3 5763JC1 V3R2M1 V3R2 and up V3R2 and up
V4R4 5769JC1 V4R2M0 V4R2 and up V4R2 and up
V4R5 5769JC1 V4R5M0 V4R3 and up V4R2 and up
V5R1 5722JC1 V5R1M0 V4R4 and up V4R3 and up
V5R2 5722JC1 V5R2M0 V4R5 and up V4R5 and up
JTOpen 1.x Not applicable Not applicable V4R3 and up
JTOpen 2.x Not applicable Not applicable V4R4 and up
JTOpen 3.x Not applicable Not applicable V4R5 and up
JTOpen 4.x Not applicable Not applicable V5R1 and up
Newer versions of the Toolbox are backwards-compatible with earlier
versions. Upgrading to a newer version is usually recommended, with the one
main exception being that, starting in V4R4, the Toolbox is only supported
for connection to servers running either of the two prior releases of OS/400.
Why Open Source?
We are pursuing making the Toolbox code open source for the
following reasons:
1. To obtain new functions and features from the Toolbox user community.
2. To respond with customer and business partners requirements as rapidly
as possible.
3. To improve the ability for our customers to build and debug their own
applications when using the Toolbox functions.
4. To continue the drive to keep the iSeries a leader with Java technology
for application development.
Differences between JTOpen and the Toolbox LPP
1. The initial release of the source code for JTOpen uses the V4R5
Toolbox codebase. That is, the Java code in the open source repository
is the same code that is used to build the V4R5 Toolbox LPP. JTOpen 2.0x
uses the V5R1 Toolbox as its codebase. The latest release of JTOpen
(JTOpen 3.x) uses the V5R2 Toolbox as its codebase.
2. When bugs are reported, fixes will be committed to JTOpen as soon as
they are realized. When applicable, these same fixes will be committed
to the Toolbox LPP and made available in a future PTF or service pack.
3. Any new functionality that is committed to JTOpen will not be
automatically added into the Toolbox LPP. However, new function that
exists in future releases of the Toolbox LPP may also get submitted
to the JTOpen repository, at IBM's discretion. The end result is
JTOpen will become a superset of the Toolbox LPP.
Note: All changes to JTOpen are made under the control and at the
discretion of the JTOpen Core Team. All changes to the Toolbox LPP
are made under the control and at the discretion of IBM.
4. Initially, JTOpen only contained most of the classes from the
com.ibm.as400.access package. As of release 2.0x, it contains almost
all of the primary Toolbox packages:
com.ibm.as400.access
com.ibm.as400.data
com.ibm.as400.resource
com.ibm.as400.util.html
com.ibm.as400.util.servlet
com.ibm.as400.vaccess
utilities
As time permits, more code and packages from the Toolbox will be added
to this repository.
5. In general, the Toolbox LPP is supported directly by IBM. JTOpen
is supported by the JTOpen user community, of which IBM participates
and contributes, specifically through developer email, the JTOpen
mailing list, and the JTOpen web forum located at:
http://as400service.ibm.com/j_dir/JTOpen.nsf/By+Date?OpenView
6. Pursuant to the IBM Public License, programmers are free to alter the
JTOpen source code and to distribute it with their own applications.
Download and installation of JTOpen
Requirements
Briefly, the requirements for using the JTOpen code are as follows:
1. A Java Virtual Machine (JVM) with a 1.1.x or higher JDK/JRE. The JTOpen
team highly recommends moving to the latest release of the JDK/JRE, as
maintaining backwards-compatible code with older releases becomes
increasingly difficult to support over time.
2. Almost all JTOpen functions require a TCP/IP connection to an iSeries or
AS/400 server.
a. The server must be OS/400 V4R3 or higher.
b. The server must have the Option 12 Host Servers installed and
running. JTOpen uses the host servers as TCP/IP endpoints to
communicate with the server from a client.
c. If the Java application using JTOpen is being run directly on a server
running OS/400, then certain JTOpen functions might use native API and/or
local socket calls to improve performance. This will only occur under
certain conditions, and only if the jt400Native.jar is included in
the application's CLASSPATH.
3. For GUI programming, either Java 2 or Swing 1.1 or higher is required.
Files
JTOpen is comprised of the following files:
Jar file Contents
-------- --------
jtStubs.jar As of JTOpen 4.0 and JDK 1.4, this jar file is no longer required.
src.zip This is a zip file of all the source files in the repository. It is
not a Java jar file. The src.zip file has been replaced by the JTOpen
downloads available on the JTOpen developerWorks project site.
doc.zip This is a zip file of the javadoc (in HTML format) for the JTOpen
source files. It is not a Java jar file. The doc.zip file has been
replaced by the JTOpen downloads available on the
JTOpen developerWorks project site.
jt400.jar This is the main JTOpen jar file. It contains almost all open
source code (except for the few Toolbox classes that could
not be open-sourced), including the previously disparate
utilities package, and the JDBC driver.
jt400Micro.jar This contains the ToolboxME (Micro Edition) classes for
use on a handheld device.
jt400Native.jar Previously known as jt400Access.zip, this jar does not
contain the vaccess package. It does contain the native
optimization classes necessary for running performance-enhanced
applications on the OS/400 JVM.
jt400Proxy.jar This jar contains just the classes needed to run a client
application using the Toolbox proxy server. It is
especially useful in environments where a smaller jar
is needed.
jt400Servlet.jar This jar contains the html and servlet packages.
The first three files are available through the JTOpen web site
located at http://oss.software.ibm.com/developerworks/opensource/jt400. But
due to export regulations, the other jar files can only be downloaded from
the official Toolbox web site downloads page:
http://www.ibm.com/servers/eserver/iseries/toolbox/downloads.htm.
There are other jar files shipped in the download for JTOpen off of the Toolbox
downloads page. Those jar files do not (yet) contain JTOpen code. They are
provided as a convenience to the developer and to mirror the objects that ship
with the Toolbox LPP.
As of JTOpen 3.3, MD5 checksums are provided to verify download integrity.
Building and Using JTOpen
Instructions for using JTOpen:
1. Download the JTOpen jt400.jar.
2. Add it to your CLASSPATH.
3. Run your application.
Instructions for building all or part of the JTOpen source code:
1. Download the JTOpen jt400.jar.
2. Download any source files you want to change. The src.zip file includes
all of the source in the repository for convenience.
3. Download jtStubs.jar. This is needed ONLY at compile time, if at all.
4. Set up your CLASSPATH to include everything in the correct order:
a. Your source files should be in your CLASSPATH first. Note that you
cannot point to src.zip - you must unzip it, since it contains only
source files.
b. Next, add jt400.jar.
c. Finally, add jtStubs.jar.
d. It should look something like this:
CLASSPATH=C:\jt400\MyApp;C:\jt400\jt400.jar;C:\jt400\jtStubs.jar;...
5. Compile your source.
6. Remove jtStubs.jar from your CLASSPATH. If you don't, certain pieces of
code may not function correctly, namely JDBC and applets. It should now
look like this:
CLASSPATH=C:\jt400\MySource;C:\jt400\jt400.jar;...
7. Run your application.
Using the Toolbox LPP
For those interested in the Toolbox LPP version of this software:
The V5R2 Toolbox LPP ships the following files, which are available
for download off of the official Toolbox web site at
http://www.ibm.com/servers/eserver/iseries/toolbox.
Jar file Contents
-------- --------
jt400.jar Contains the access, data (PCML), resource, vaccess,
and security packages.
jt400Access.zip Contains the access, data, resource, security, HTML, and servlet
packages, along with Toolbox native optimization classes used
when running directly on the OS/400 JVM.
jt400Proxy.jar Contains proxy classes for the access package. Useful for
applets or environments where a small jar file is needed. A middle
tier machine running the Toolbox ProxyServer is required to forward
proxy client requests to the backend server.
jt400Servlet.jar Contains the HTML and servlet packages.
utilities package Contains various helper applications for the Toolbox,
such as JarMaker and AS400ToolboxInstaller.
data400.jar Contains the PCML runtime package as provided by
Operations Navigator.
jui400.jar Contains the PDML runtime packages as provided by
the Graphical Toolbox.
uitools.jar Contains the GUI Builder packages as provided by the
Graphical Toolbox.
util400.jar Contains various utilities.
x4j400.jar Contains the IBM XML Parser for Java.
composer.jar Contains XSL stylesheet composer classes.
reportwriter.jar Contains XSL report processor classes.
outputwriters.jar Contains PDF, PCL, and font classes.
tes.jar Contains the iSeries Graphical Debugger.
Instructions for using the Toolbox LPP:
1. Download the Toolbox and extract the jar file(s) you wish to use. This
will be jt400.jar in most cases.
2. Add it to your CLASSPATH.
3. Run your application.
Support information
Documentation for JTOpen can be found on the Toolbox
web site at http://www.ibm.com/servers/eserver/iseries/toolbox.
The JTOpen/Toolbox external web forum is available off of
http://as400service.ibm.com under the "Forums",
"Technology Forums" category. This is a direct link to it.
To receive updates on the latest JTOpen developments and news, the JTOpen
mailing list is jt400-news@oss.software.ibm.com.
To subscribe/unsubscribe or view information about the list, see
http://oss.software.ibm.com/developerworks/opensource/mailman/listinfo/jt400-news.
For bug reports, please use the Jitterbug forum located at
http://oss.software.ibm.com/developerworks/opensource/jt400/bugs.
Other enhancements or fixes can be sent to Chris Smith (csmith4@us.ibm.com)
or posted to the web forum.
Questions or comments regarding JTOpen can be sent to any of the JTOpen
Core Team members:
Name E-mail Company
------------------- --------------------------- ----------------------
Steve Johnson-Evers severs@everbrite.com Everbrite, Inc.
Joe Pluta joepluta@plutabrothers.com Pluta Brothers Design
Cheryl Renner cjpflug@us.ibm.com IBM Corporation
Chris Smith csmith4@us.ibm.com IBM Corporation
Bill Wiktor wiktor@us.ibm.com IBM Corporation