## IBM Toolbox for Java - JTOpen Version

###

###

###

###

###

####

####

####

###

    Copyright (C) 1997-2007 International Business Machines Corporation and
    others. All rights reserved.

    File: README
    Last updated: April 14, 2008

    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://jt400.sourceforge.net/

    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 i5/OS or OS/400 data through a Java program. With these classes,
    you can write client/server applications, applets, and servlets that work
    with data on your i5/OS or OS/400 system. You can also run Java applications that use the
    IBM Toolbox for Java on the i5/OS or 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
    V5R3(*)         5722JC1 V5R3M0  V5R1 and up     V5R1 and up
    V5R4(**)        5722JC1 V5R4M0  V5R2 and up     V5R2 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.0-4.2  Not applicable  Not applicable  V5R1 and up
    JTOpen 4.3-4.7  5722JC1 V5R3M0  V5R1 and up     V5R1 and up
    JTOpen 4.8+     5722JC1 V5R4M0  V5R2 and up     V5R2 and up
    JTOpen 6.1+     5761JC1 V6R1M0  V5R3 and up     V5R3 and up

    (*) Note: Toolbox release V5R3 is equivalent to JTOpen 4.3.
    (**) Note:  Toolbox release V5R4 is equivalent to JTOpen 4.8.

    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 the Toolbox is only supported
    for connection to servers running either of the two prior releases of i5/OS or OS/400.

    Why Open Source?

    We have chosen to make 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 used the V4R5
       Toolbox codebase. That is, the Java code in the open source repository
       is the same code that was used to build the V4R5 Toolbox LPP. JTOpen 2.0x
       uses the V5R1 Toolbox as its codebase. The latest release of JTOpen
       (JTOpen 6.x) uses the V6R1 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. In general, the Toolbox LPP is supported directly by IBM. JTOpen
       is supported by the JTOpen user community, in which IBM participates
       and contributes, specifically through developer email, the JTOpen
       mailing list, and the JTOpen web forum located at:
         http://www-912.ibm.com/j_dir/JTOpen.nsf/By+Date?OpenView

    5. 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.2.x or higher JDK/JRE. The JTOpen
       team highly recommends moving to the latest supported 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 i5/OS, or 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 i5/OS or 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
    --------          --------

    jtopen_x_x_source.zip  This is a zip file of all the source files in the repository.
                           It is not a Java jar file.

    jtopen_x_x_javadoc.zip This is a zip file of the javadoc (in HTML format) for
                           the JTOpen source files. It is not a Java jar file.

    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 utilities package,
                         and the JDBC driver (JDBC 3.0).

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

    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.

    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.

    jtopen_x_x_jdbc40.zip  This zip file contains versions of jt400.jar and
                           jt400Native.jar (along with source code) that are
                           compatible for use with JDBC 4.0, on Java 6.0 or higher.

    (*) Files contained in file jtopen_x_x.zip.

    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.

    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:
    Note: Complete build instructions are specified in the commentary in file /build/build.xml
    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.

    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://www-912.ibm.com/ under the "Forums" link.

    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
    https://lists.sourceforge.net/lists/listinfo/jt400-news.
    Please do not send queries to the mailing list, post them to the forum instead.

    For bug reports, please use the JTOpen bug database located at
    http://sourceforge.net/tracker/?group_id=128806&atid=712772.
    Other enhancements or fixes can be sent to rchjt400@us.ibm.com (monitored weekly)
    or posted to the web forum (monitored daily).

    While the preferred channel is the 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.
      Jeff Lee             jlee@us.ibm.com              IBM Corporation
      Joe Pluta            joepluta@plutabrothers.com   Pluta Brothers Design
      Cheryl Renner        cjpflug@us.ibm.com           IBM Corporation
      John Rud             jarud@us.ibm.com             IBM Corporation