Toolbox for Java: Public Beta 3 Readme


Contents:

Workstation Requirements

  • For applications, a Java Virtual Machine that supports JDK 1.1 or later. The following environments have been tested:
    • Windows 95
    • Windows NT Workstation 4.0
    • AIX Version 4.1.4.0
    • Sun Solaris Version 2.5
    • OS/2 Warp 4.0

  • For applets, a browser that fully supports JDK 1.1 or later. We successfully ran with:
    • JavaSoft's HotJava browser
    • Netscape Communicator 4.04 with the JDK 1.1 patch from http://developer.netscape.com.
    • Internet Explorer 4.0.

OS/400 Requirements

Note - the following information has not changed from beta 2. If you set up your AS/400 for use with beta 2 of the AS/400 Toolbox for Java, no additional setup is needed for beta 3.

  • OS/400 Version 3 Release 2, OS/400 Version 3 Release 7, or OS/400 Version 4 Release 1.
    • For V3R2, OS/400 at cumulative PTF level C7126320 or later
    • For V3R7, OS/400 at cumulative PTF level C7105370 or later

  • TC1 Product (TCP/IP Connectivity Utilities for AS/400) installed and configured on the AS/400.

  • Host Servers option of OS/400 installed on the AS/400.

    • The print support in AS/400 Toolbox for Java requires additional function in the OS/400 print server. The required function is supplied via PTFs. Select the appropriate PTFs from the following list:

    • For V3R2, 5763SS1 PTF SF42344 and PTF SF42515
    • For V3R7, 5716SS1 PTF SF42316 and PTF SF42516
    • For V4R1, 5769SS1 PTF SF41926 and PTF SF42518

    The OS/400 data queue server requires fixes to correctly perform peek functions. Select the appropriate PTF from the following list:

    • For V3R2, 5763SS1 PTF SF43295
    • For V3R7, 5716SS1 PTF SF42398
    • For V4R1, 5769SS1 PTF SF42813

    A PTF is required to enable a TCP/IP sockets interface to the OS/400 record-level access server. Select the appropriate PTF from the following list:

    • For V3R2, 5763SS1 PTF SF42337
    • For V3R7, 5716SS1 PTF SF42338
    • For V4R1, 5769SS1 PTF SF42498

    The following commands must be run on the AS/400 system after the PTF has been applied:
    • CRTCTLAPPC CTLD(QCNSKSVR) LINKTYPE(*LOCAL)
    • CRTDEVAPPC DEVD(QCNSKSVS) RMTLOCNAME(QCNSKSVT) LCLLOCNAME(QCNSKSVS)
      •            CTL(QCNSKSVR)  APPN(*NO) MODE(BLANK)
    • CRTDEVAPPC DEVD(QCNSKSVT) RMTLOCNAME(QCNSKSVS) LCLLOCNAME(QCNSKSVT)
      •            CTL(QCNSKSVR)  APPN(*NO) MODE(BLANK)
    • VRYCFG CFGOBJ(QCNSKSVR) CFGTYPE(*CTL) STATUS(*ON)

Recommendations

There are many combinations of operating systems, browsers, program types (applet/application), and html servers possible. We tested many of them with varying levels of success. Based on our testing and experience, we recommend the following for this beta code:
  • If an applet fails in one browser, try it in another before giving up and reporting a problem. If something fails on Windows 95, try it on Windows NT if possible. We are aware of cases where code that works in one browser or in a JVM on one platform does not work in others. It can be difficult to figure out which behavior (working or failure) is appropriate and then whether the error is in your code, the IBM-supplied beta code, or the JVM.
  • Your program should issue System.exit() as the last instruction before it ends. This is because AS/400 Toolbox for Java uses user threads when connecting to the AS/400. Failure to issue System.exit() can keep your application from shutting down properly.

Client Setup

Upgrading from Public Beta 2

The best way to upgrade from Public Beta 2 is to delete the beta 2 version of the AS/400 Toolbox for Java classes, then re-install the beta 3 package.
  • Delete all beta 2 class, jar, zip and documentation files from the client.
  • Delete all beta 2 class, jar, and zip files from the AS/400 if you copied the files to the AS/400.
  • Re-install AS/400 Toolbox for Java using the beta 3 package.
  • If using VisualAge for Java, re-import jt400.jar.

Setup Instructions

  1. Download jt400_beta3.class to your workstation. This is a self-extracting class file. Run Java against this class file to start the installation program. This will unpack the programmers guide, class documentation, readme file, the zip file containing the class files, and the jar file containing the class files.
  2. Add the AS/400 Toolbox for Java classes to your classpath. For example, add /jt400/jt400.zip to your classpath.
  3. The supplied documentation is a Programmers's Guide coded in HTML that links to class documentation created using Javadoc. The starting point for this information is /jt400/doc/api_users_guide.html.

Java Applets

Java applets were tested both with AS/400 Toolbox for Java classes on the client and on the server. To access the classes on the client, the CLASSPATH environment variable must be set such that the browsers find the classes on the workstation. To access the classes on the AS/400, the HTTP server must be set up such that it can serve the classes. See HTTP Server Setup for more information.

OS/400 Configuration and Setup

Note - the following information has not changed from beta 2. If you set up your AS/400 for use with beta 2 of the AS/400 Toolbox for Java, no additional setup is needed for beta 3.

Starting the OS/400 Servers

  • The AS/400 host servers must be running. Use the AS/400 command 'STRHOSTSVR *ALL' to start the host servers.
  • The QUSER user profile must be enabled and have a valid password. QUSER is used by the servers at startup time.

HTTP Server Setup

You must set up the HTTP server and copy the jar file to the AS/400 to serve HTML pages and the AS/400 Toolbox for Java class files from an AS/400.
  1. Clean up the CLASSPATH environment variable on your workstation so that the AS/400 Toolbox for Java classes are served from the AS/400 instead of the workstation. To do this, remove references to the AS/400 Toolbox for Java classes from the CLASSPATH environment variable.
  2. Copy the AS/400 Toolbox for Java package to the AS/400:
    • Copy jt400.jar to the AS/400. You can copy it to any place in the AS/400 directory structure. We recommend copying the file to /QIBM/ProdData/HTTP/Public/jt400/lib because eventually the jar will be installed to this location.
    • Use AS/400 command 'WRKHTTPCFG' to configure the HTTP server on the AS/400. By default the HTTP server denies access to all files in the integrated file system. The HTTP server uses the 'pass' directive to determine which files can be served. The 'pass' directive must match where you put the AS/400 Toolbox for Java jar file and is case sensitive with respect to the path typed in the browser. Add the following entries to the file:
      • Enable POST
      • Pass /QIBM/ProdData/HTTP/Public/*
  3. End and restart the HTTP server using AS/400 commands:
    • ENDTCPSVR *HTTP
    • STRTCPSVR *HTTP
  4. User profiles QTMHHTP1 and QTMHHTTP must be enabled.
The HTTP server is now ready to serve jt400.jar. Reference the jar file using the ARCHIVE parameter of the APPLET tag in your HTML file.

Set Up to Use the jt400Installer Class

To work correctly, the jt400Installer class requires certain files on the AS/400. For this beta you must set up the AS/400 system if you want to use the jt400Installer class. Do the following:
  1. Create these directories on the AS/400:
    • QIBM/ProdData/HTTP/Public/jt400
    • QIBM/ProdData/HTTP/Public/jt400/lib
  2. Copy jt400\lib\jt400.zip to QIBM/ProdData/HTTP/Public/jt400/lib/jt400.zip
  3. Copy jt400\lib\jt400.jar to QIBM/ProdData/HTTP/Public/jt400/lib/jt400.jar
  4. Copy jt400\utilities\files\*.* to QIBM/ProdData/HTTP/Public/jt400/*.* (Four files should be copied)

    5. The directory tree on the AS/400 should now contain: 

    /QIBM/ProdData/HTTP/Public/jt400/access.lvl
/QIBM/ProdData/HTTP/Public/jt400/access.lst
/QIBM/ProdData/HTTP/Public/jt400/jt400.pkg
/QIBM/ProdData/HTTP/Public/jt400/v3r2m0.lst
/QIBM/ProdData/HTTP/Public/jt400/lib/jt400.zip
/QIBM/ProdData/HTTP/Public/jt400/lib/jt400.jar
  5. Add "jt400\utilities" to your CLASSPATH environment variable.
  6. Configure and start the HTTP server on the AS/400. See HTTP Server Setup for more information.

Restrictions

Record-Level Database Access

The record-level database access classes can be used only by Java applications. They cannot currently be used in a Java applet.

VisualAge for Java

  • AS/400 Toolbox for Java cannot convert DBCS data when running inside VisualAge for Java. To use DBCS data you must export your program and run it in a JVM that has DBCS support.
  • The default setting in VisualAge for Java does not allow applets to connect to servers. An exception is thrown if an applet running in VisualAge for Java's applet viewer uses an AS/400 Toolbox for Java class that accesses the AS/400.

    • To change this behavior:

    • Start an applet in VisualAge for Java
    • When the applet window comes up, select 'Applet'
    • Select 'Properties' from the applet pulldown
    • Set network access to unrestricted

Known Problems

Record-Level Database Access

  • The server program for V3R2, V3R7 and V4R1 is submitted to run in job queue QSYSNOMAX. Any user profile connecting for record level access must have *USE authority to the QSYSNOMAX job queue.

VisualAge for Java

  • VisualAge for Java stores resource files in the file system. Instead of storing them in the workspace or the repository, VisualAge for Java creates a directory for each project and stores the resources in that directory. VisualAge for Java does not correctly search for resource files when there are multiple projects in the workspace. When a program in one project uses AS/400 Toolbox for Java classes imported into a different project, the AS/400 Toolbox for Java classes may not be able to find their resources. This will cause the AS/400 Toolbox for Java classes to fail. VisualAge for Java reports the error as "Uncaught exception (java.lang.ExceptionInInitializerError)"

    • For example, suppose the AS/400 Toolbox for Java classes are imported to a project called 'jt400' and an application that uses these classes is imported to a project called 'myApp'. myApp will fail when it uses an AS/400 Toolbox for Java class.

    Refer to the Visual Age for Java documentation for a way to work around this problem. Here are a couple of suggestions:
     

    1. Update the classpath environment variable inside Visual Age for Java so it points to the toolbox resources. When you run your class inside Visual Age for Java, the first dialog provides an option to update classpath. Append ..\project_resources\jt400 to classpath where 'jt400' is the name of the Visual Age project containing the toolbox classes.

    2. Copy the property files from the AS/400 Toolbox for Java project to each application project. Suppose VisualAge for Java was installed to d:\vajava. To make myApp from the previous example work do the following: 
        md d:\vajava\ide\project_resources\myApp\com
    md d:\vajava\ide\project_resources\myApp\com\ibm
    md d:\vajava\ide\project_resources\myApp\com\ibm\as400
    md d:\vajava\ide\project_resources\myApp\com\ibm\as400\access
    copy d:\vajava\ide\project_resources\jt400\com\ibm\as400\access\*.*
        d:\vajava\ide\project_resources\myApp\com\ibm\as400\access\*.*

  • The com.ibm.as400.vaccess.IFSFileDialog class does not work inside VisualAge for Java. VisualAge for Java reports the error as "Uncaught exception (java.lang.InternalError: (Ex02))". We are investigating this problem but do not have a solution at this time. Programs using IFSFileDialog must be run outside of VisualAge for Java.

  • The system name and userid are not uppercased on the Sign-On dialog. To work around this problem, AS/400 Toolbox for Java internally uppercases the system name and userid so that correct information is passed to the AS/400.

Changes from Public Beta 2

  • The AS/400 Toolbox for Java classes are now in the "com.ibm.as400.access" package.
  • Changes were made in the JDBC driver to better support DBCS data.
  • Changes were made to download EBCDIC to Unicode conversion tables from the AS/400 when the JVM does not have the tables. In beta 2, an UnsupportEncodingException was thrown.
  • Changes were made to the record-level database access classes to support caching for KeyedFile objects and to fix caching in SequentialFile objects.