                  Golden Code (R) Run Time Environment (RTE)
                      and Software Development Kit (SDK)
            for the Java (TM) 2 Platform Standard Edition 1.4.1_07
                                   README

                                July 28, 2004

-----------------------------------------------------------------------------

Contents

   1.  Introduction
   2.  Product Description
   3.  Hardware/Software Requirements
   4.  Directory Structure of the CD or Downloadable Version
   5.  Installation/Configuration
   6.  Directory Structure of the Product
   7.  Tested Configurations
   8.  Unique Features
   9.  Timezone Processing
   10. Modifying Font Processing
   11. Avoiding Flicker in Graphical Programs
   12. Incomplete or Missing Function
   13. Known Problems - GCD JVM
   14. Known Differences from the IBM JVM 1.3.1
   15. Known Differences from the Sun J2SE 1.4.1
   16. Performance Comparison
   17. Developer Notes
   18. Submitting Problem Reports
   19. Contacting Golden Code
   20. Trademarks

-----------------------------------------------------------------------------

1.  Introduction

Thank you for using the Golden Code Run Time Environment (RTE) and Software
Development Kit (SDK) for the Java (TM) 2 Platform Standard Edition.

This document describes a variety of important topics related to this
release, its installation and proper use.  Please review this document
carefully BEFORE using this product.

This is the third production release of this product.  We believe you will
find it a powerful and reliable solution for all Java technology needs on
OS/2.

Please review the COPYRIGHT and LICENSE files in this same directory. They
have important information regarding your rights and responsibilities with
this software.

-----------------------------------------------------------------------------

2.  Product Description

This product consists of a Run Time Environment (RTE) and a Software
Development Kit (SDK) for OS/2 (R), which will allow you to run and develop,
respectively, programs written for the Java (TM) 2 Platform Standard Edition,
version 1.4.1_07.

The OJI plugin for use in Mozilla 1.4 and above (or compatible browsers)
is included in this product.  This is a native plugin that provides complete
browser-based applet support for the Java 1.4.1 platform.  This plugin
supports both VisualAge C++ Mozilla builds (e.g. Mozilla 1.4.1 or IBM Web
Browser 2.0.2) and GCC Mozilla builds (e.g. Mozilla 1.5 or above).  Please
see the file plugin.txt in this same directory, for more information.

This product also includes a complete, native, well tested implementation of
the Java Web Start 1.2.0_02 technology.  This product is stored in the
java141\jre\javaws-1.2.0_02-os2.zip file and is separately installed. Please
see the file webstart.txt in this same directory for details on the 
installation, configuration and operation of Web Start.

Source code for this product was licensed from Sun Microsystems, Inc. This
code was carefully analyzed and the operating system specific or dependent
portions were written from scratch to operate properly using native OS/2
system APIs and resources.  Since the resulting product was designed and built
specifically for OS/2, it integrates well into the OS/2 environment and it
takes advantage of all the native features to which an OS/2 application
environment has access.

Both the RTE and SDK components have been tested and certified on OS/2 for
Java compatibility. Compatibility testing was performed using the Java
Compatibility Kit (JCK), licensed from Sun Microsystems.  See section 7 for
a specific list of certified configurations.

This product includes both the HotSpot (TM) client compiler as well as the
higher performance HotSpot server compiler. The client compiler is designed
for faster load time and a smaller working set. However these design points
are achieved by limiting the runtime performance of the resulting compiled
code.  As may be expected, the HotSpot server compiler is designed to
maximize the performance of compiled Java code, but it does so at the
expense of additional working set (memory) and a slower application startup.
Both compilers have been extensively tested and explicitly certified using
the Sun JCK.

This product has also been designed for and tested on a wide variety of
system configurations.  For example, this product has been certified Java
Compatible on SMP configurations.  This is the only J2SE 1.4.x based product
to achieve such a certification.

In many cases, programs written for earlier editions of the Java platform
will function normally in this JRE implementation; however, programs which
use deprecated interfaces, or which rely upon less stringent error checking
in previous versions of Java may not run correctly. Likewise, Java programs
written for J2SE 1.4.1, may not run correctly on older versions of the Java
2 Platform Standard Edition.  If your program runs properly on the Sun Java
1.4.1 distribution, you will find the same results in this GCD product.

Version 1.4.1 of the Java 2 Platform Standard Edition contains many
enhancements over previous versions. Feature improvements include:

- New I/O support. A new, high performance I/O architecture rivals the I/O
  performance of native C/C++ applications:
  * Network I/O threading improvements.
  * File I/O, including memory-mapped files.
  * Java Native Interface improvements.
  * Improved reflection performance.

- Client improvements:
  * Java 2D graphics pipeline architecture rewritten.
  * JFC/Swing:
    + New Swing components: spinners, scrollable tabbed panes, indeterminate
      progress bar controls.
    + Clipboard supported across applications.
    + Drag and drop supported across all Swing components and across
      applications.
    + New API for JavaBean long term persistence.
    + New Preferences API.
    + Redesigned focus architecture.
    + Undecorated frames feature.
    + New Print Service API.

- Open Java Interface (OJI) Plugin 1.4.1_07 for Mozilla 1.4 or above,
  including GCC builds (1.5 and later).

- Java Web Start 1.2.0_02.

- Improved Debugging Facilities:
  * Assertions.
  * Full speed debugging.

- Enhanced Troubleshooting and Runtime Information:
  * New logging API.
  * Chained exceptions.
  * Java-level deadlock detection.
  * Improved error reporting.
  * Garbage collection logging.

- New security features:
  * Java GSS-API with Kerberos V5
  * Java Certification Path API
  * Support for dynamic security policies

- Security features previously available as extensions which are now core:
  * Java Authentication and Authorization Service (JAAS).
  * Java Secure Socket Extension (JSSE).
  * Java Cryptography Extension (JCE).

- Connectivity and Data Interchange improvements:
  * Built-in XML support, including XML parsing facilities and support for
    SAX 1.0 and 2.0, DOM 1.0 and 2.0, and XSLT support.
  * JDBC 3.0 support.
    + Connection pool configuration improvements.
    + Statement pooling for pooled connections.
    + Description of migration path from Service Provider Interface to J2EE
      Connector Architecture
  * CORBA improvements.
  * Java Naming and Directory Interface improvements.
  * New URI API.

- Regular expressions support.

- Internationalization:
  * Unicode 3.0 support
  * New currency class

The above list is not exhaustive. For further information about enhancements
provided in J2SE 1.4.1, please refer to:

  http://java.sun.com/j2se/1.4/datasheet.1_4.html

-----------------------------------------------------------------------------

3.  Hardware/Software Requirements

CPU        : Pentium or equivalent CPU or later. Systems as slow as Pentium II
             450MHz have been extensively tested and work well. See section 5
             below for details on how to run on pre-Pentium CPUs.

Memory     : No specific minimum is specified. If the system was previously
             able to run Java applications, then it should be able to run
             them in the Golden Code JVM. Generally, the memory usage is quite
             similar to the IBM JVM 1.3.1.

Disk       : The entire product (without documentation) consumes
             approximately 50MB of disk space.

Video      : 8-bit color depth is required (256 colors or greater).  Some
             Java2D features will only work properly at 16-bit color depth
             or above. This is a limitation inherited from the Sun Java2D
             implementation and it only affects a small number of APIs.

OS         : By default, the JVM will only load on systems that are the
             equivalent of OS/2 Warp v4 with Fixpak 13 or higher.  With an 
             optional environment variable (details in Section 5), pre-fixpak
             13 systems can also be supported (with limitations).  In
             particular, the absolute minimum OS/2 version at this time is
             OS/2 Warp v4 GA (no fixpaks).

             Usage on systems meeting only the minimum requirements (Warp v4
             or Warp v4 + FP13, based on the optional environment variable),
             is subject to limitations.  Warp v4 systems (with no fixpak) are
             subject to greater limitations than Warp v4 + FP13 systems.

             Fixpak 15 and above is the RECOMMENDED OS/2 level.  Operation on
             such systems will occur without any limitations. All systems
             prior to Fixpak 15, will be unable to simultaneously operate
             multiple different versions of the Golden Code JVM. To do this
             requires OS/2 Warp v4 + Fixpak 15 or later.  See section 5 for
             details on these limitations.

Networking : 32-bit TCP/IP v4.21 or later required for full compliance with
             the J2SE 1.4 specification. Earlier 32-bit TCP/IP (v4.1 or v4.2)
             is usable but will not support multicast sockets. 16-bit TCP/IP 
             is usable, but some socket options are not available (IP_TOS and 
             SO_REUSEPORT). No TCP/IP installation is required when running 
             Java applications which do not use any of the J2SE networking 
             interfaces. However, note that many Java applications that would
             not be considered networking applications, still may call J2SE
             networking interfaces for such services as obtaining the system's
             hostname.  The usage of such interfaces will only work if the
             TCP/IP support is properly installed as listed above.

             In particular, in cases where an application determines the IP 
             address of the machine on which it runs, startup pauses can be
             seen on systems with an improper TCP/IP configuration. In such
             cases it is important to have the resolved name and IP address 
             of the machine available before the Java application starts. A
             long pause (75 seconds or more) can occur if the current TCP/IP
             configuration depends upon a DNS which is not available at the
             time the application starts.  This can be seen in situations 
             where a TCP/IP connection is not yet established (e.g. a dialup
             environment).  If there is such possibility, the solution is to
             insert BOTH the host name / IP address for the current machine
             AND the loopback name ("localhost") / IP address (always set to
             127.0.0.1) in the %etc%\hosts file.  This file is located in the
             directory declared in ETC environment variable (usually
             x:\mptn\etc where x: is your boot drive). Most importantly, one
             must also direct the system to use the HOSTS file first before
             trying a DNS. This can be done by adding "SET USE_HOSTS_FIRST=1"
             to the CONFIG.SYS file.  

             This behavior is not a bug in the JVM or J2SE implementation, 
             rather it is only seen when applications requiring a properly 
             working TCP/IP environment run on a system in which the TCP/IP
             environment is misconfigured at the time the JVM is started.

-----------------------------------------------------------------------------

4.  Directory Structure of the CD or Downloadable Version

readme.txt                  --> this document
gcd-java-141-20040728.zip   --> binaries and configuration files
gcd-java-141-docs.zip       --> J2SE 1.4.1 API documentation
unzip.exe                   --> the "installer", provided as a convenience

-----------------------------------------------------------------------------

5.  Installation/Configuration

This product is "unzip and run".  There is no reason to have an install
program, since the only requirement is to place the software's complete
directory structure on the system's disk drive.  Since InfoZip is a freely
available tool and ZIP is a very common format, we have chosen to distribute
using this mechanism.

The gcd-java-141-20040728.zip file contains the entire directory structure of
the Golden Code JVM under a top-level directory of java141\*.  This directory
can be unzipped at any location on a system's drive. The path to this
directory does not matter.  For example, one may unzip this file to the X:\
or to X:\BOGUSDIR and the JVM will operate properly.

The volume upon which the product is installed MUST support long filenames
at this time.

There is no configuration required if the system is locally installed. The
CONFIG.SYS DOES NOT need to be modified, nor are there any entries in the
OS2.INI or OS2SYS.INI.  As you shift your usage to this JVM, you may find
it useful to change your PATH to include the java141\bin directory but this
is completely optional.

DO NOT change your LIBPATH. This is unnecessary and will provide no
benefits.

The CLASSPATH environment variable will be honored if set, but this variable
does NOT need to be set in order for the GCD JVM to properly function. In
fact, if the CLASSPATH includes the standard IBM JVM 1.1 entries, these
*should* be removed as they can cause a NoClassDefFoundError to be thrown
when the JVM tries to load the main class for the Java application. This can
be seen in both the IBM JVM 1.3.1 as well as the GCD JVM 1.4.1. Another 
symptom of this problem is the message "could not find main class" when trying
to launch a JVM. This is caused by a conflict in the JAR files provided by the
IBM JVM 1.1, which when removed from the CLASSPATH, will eliminate the issue.  

This JVM includes and relies upon license control technology. If you are
licensed to use this product, then you have been separately provided a
license file named "license.jvm". Place this file in the \java141\jre\bin
directory of your GCD JVM installation.  This is all that is necessary to
enable the product's proper function.  The program will not run without this
license file.  To test if this was done successfully, run the following
command:

   \java141\bin\java -Xlicenseverify

The proper output will appear similar to the following:

   Golden Code RTE and SDK for J2SE 1.4.1 Release 1.1
   S/N JVM-006756-1, licensed to Network Operations Dept.,
   Acme Corporation

WARNING Regarding License Files from Prior Versions          
---------------------------------------------------

Starting in the 1.4.1_07 release, LICENSE FILES FROM PREVIOUS RELEASES
CANNOT BE USED. This means that the old "license.jvm" files MUST NOT
EXIST in the new release's directory tree NOR CAN THEY EXIST IN THE
CURRENT DIRECTORY FROM WHICH YOU RUN ANY JAVA PROGRAMS.  The GCD JVM
looks first in the current directory for the license.jvm file, if found
this file is used in preference to any such file located in
\java141\jre\bin.  FAILURE TO FOLLOW THIS REQUIREMENT WILL RESULT IN
A FAILURE OF THE JVM TO LOAD OR OPERATE.

Special Considerations for WorkSpace On-Demand Installations
------------------------------------------------------------

For WorkSpace On-Demand (WSOD) customers, there are two writable locations
in the directory tree.  These directories are:

java141\jre\
java141\jre\prefs\

The first directory is the default value for the user.home property. The
user.home is designed to specify the current user's home directory. Many
operating systems have a built-in concept of user.home, however OS/2 does
not.  Due to this oversight, the JVM "falls back" to a known location on
the drive to ensure that in the absence of other configuration information,
the user.home property will always have a value.  Please see below for
details on specifying an alternate location for user.home.

The second writable directory is the new preferences directory.  This is a
new feature of J2SE 1.4.x and should not be confused with user.home. The
idea is to create a location for user specific and system-wide preferences.

On a FAT client, this directory will be created the first time it is needed,
but it can be placed on WSOD clients manually.  It must be made writable for
the WSOD clients. It has two subdirectories:

java141\jre\prefs\.systemPrefs
java141\jre\prefs\.userPrefs

The user preferences location should be made workstation unique.  Testing
has not yet been done to determine what issues may present themselves if
the system preferences location is made read-only (and thus shared between
multiple WSOD clients). It may not be possible to do this without
modifications inside the JVM.  Please contact Golden Code if such
functionality is required.

The locations of these two directories can be individually controlled using
the following environment variables:

SET JAVA_SYSTEMPREFS=<fully_qualified_systemprefs_path>
SET JAVA_USERPREFS=<fully_qualified_userprefs_path>

Controlling the Location of User Home
-------------------------------------

Please note that the new preferences feature of J2SE is *not* the same thing
as the user.home property.  The user.home property specifies the location of
the user's home directory.  This is a directory in which many applications
normally write configuration files, save user-specific data or otherwise
make use of during normal processing.  It should be a directory which is
unique to the user and which is writable.

The JVM will check for the existence of the USER_HOME environment variable
at startup.  If it exists, it will be used to set the user.home property.

If USER_HOME is not found, the HOME environment variable is checked.  If that
is not found, then the JVM will fallback to the java.home property and finally
to the JAVA_HOME environment variable.

If none of these values are set and there is no override on the command line
(e.g. -Duser.home=d:\home) then the JVM will use:

java141\jre\

Please note that this is the same as the default java.home property.

Using High Memory
-----------------

The Java heap is now located in high memory (above 512MB) by default. This
has a huge impact on reducing the memory allocations in the size-limited
low memory private and shared arenas.  However, this feature can be disabled
if necessary by using the JAVA_HIGH_MEMORY environment variable.

High memory can be disabled using:

SET JAVA_HIGH_MEMORY=0

High memory is enabled using:

SET JAVA_HIGH_MEMORY=1

Please note that as enabling high memory is the default, it is only necessary
to use this environment variable to force the Java heap into low memory.

Note that by using high memory, very large heap sizes can now be achieved.
Heap sizes over 1GB are easily handled as long as one has properly configured
the high memory area accessible to applications.  Specifically, the
VIRTUALADDRESSLIMIT= statement is used to define this value.  It defaults to
512 and the maximum is 3072 (these sizes are in MB).

Setting Command Line Options Globally
-------------------------------------

If there are a set of command line options that must always be passed to the
JVM launchers, this can be simplified by using the GCD_JAVA_OPTIONS
environment variable.  If set, the value of this environment variable is
added dynamically to the command line options passed to the JVM.  Options
set using this environment variable will be overridden by the same options
when passed on the actual command line of the JVM launcher (e.g. java.exe).
Thus, one may set a default option globally and override it on the launch of
a specific JVM.

There is a _JAVA_OPTIONS environment variable which also provides a global
mechanism for specifying options.  The only difference between this and the
GCD_JAVA_OPTIONS is that options specified using _JAVA_OPTIONS CANNOT be
overridden using the command line.  This is a design choice by Sun.  So if
the global option should be used always (without the ability to override it)
then the _JAVA_OPTIONS is the best choice.

Otherwise, use GCD_JAVA_OPTIONS which operates as a set of defaults.  This is
the more flexible approach.

Running on a Pre-Fixpack 13 System
----------------------------------

It is possible to run GCD JVM on a Warp v4.0 system with some limitations.
A Warp v4.0 system is a Warp v4.0 GA system with or without a fixpack (1
through 12) applied.

By default, the JVM will refuse to load on these older systems.  To enable
this support, one must specify the following environment variable:

SET GCD_JAVA_PRE_FP13_SUPPORT=1

This tells the JVM to allow loading on pre-fixpak 13 systems.  It also forces
the following limitations (due to lack of proper OS/2 facilities in the older
systems):

- No high memory (above 512MB) support due to lack of OBJ_ANY support by
  DosAllocMem().

- No large file (>2GB) support due to lack of support by the file system
  APIs.

- No ability to load multiple different GCD JVMs simultaneously due to the
  lack of LIBPATHSTRICT support.  This means that for a given JRE root path
  (e.g. e:\java141\ ), one may run any number of JVM processes so long as
  all of them are loaded from this same path.  While any one JVM process is
  loaded from a specific JRE root path, no GCD JVM from any other JRE root
  path will be able to load.

- Missing API WinQueryKbdLayout() PMMERGE ordinal 5479 leads to the inability
  to dynamically query the current keyboard layout if more than one layout is
  configured in the CONFIG.SYS DEVINFO statement. To workaround this 
  limitation, the following environment variable is checked:

  SET GCD_JAVA_KBD_LAYOUT=

  If not defined, it defaults to the value 0 (Neutral language). Otherwise, it
  should be set to the layout to be used.

- On SMP systems, the calculation of the number of active processors is not 
  dynamic due to the lack of the DosQueryThreadAffinity() API.  Rather, the
  JVM relies upon a static predetermined value for the total number of
  installed CPUs.

Running on a Pre-Pentium CPU System
-----------------------------------

It is possible to run GCD JVM on a pre-Pentium system with limitations.

By default, the JVM will refuse to load on these older systems.  To enable
this support, one must specify the following environment variable:

SET GCD_JAVA_PRE_PENTIUM_SUPPORT=1

This tells the JVM to allow loading on pre-Pentium systems.  It also forces
limitations in function due to lack of certain CPU instructions and/or
facilities.  In particular, instructions such as rdtsc are missing and this
causes problems with any J2SE facility that uses random numbers (often seen
in security/encryption related applications).  It is expected that using
this JVM on pre-Pentium systems may fail or otherwise incorrectly operate.
The most likely symptom of this the XCPT_ILLEGAL_INSTRUCTION trap of the
JVM.  Other failures can occur as well.

THIS OPTION IS UNSUPPORTED AND SHOULD NOT BE USED IN A PRODUCTION
ENVIRONMENT.  IT IS PROVIDED AS A CONVENIENCE ONLY.  USING THIS OPTION IS
HIGHLY LIKELY TO BREAK THE PROPER OPERATION OF THE JVM. IT MAY EVEN
CONTRIBUTE TO HANGS UNDER SOME CONDITIONS. GOLDEN CODE IS NOT RESPONSIBLE
FOR ANY PROBLEM OR DAMAGE THAT OCCURS AS A RESULT OF THIS OPTION.

DO NOT SUBMIT PROBLEM REPORTS ON ANY FAILURE THAT IS SEEN ON A SYSTEM WHERE
THIS ENVIRONMENT VARIABLE IS SET.  

-----------------------------------------------------------------------------

6.  Directory Structure of the Product

This product conforms very closely to the Sun J2SE directory structure,
which is slightly different from how IBM ships their 1.3.1 JDK. The key
difference is in the placement of the EXE modules.  IBM does not duplicate
the runtime EXE modules in both the bin and jre\bin directories, where GCD
follows Sun's approach and duplicates these modules.

The following lists the functionality of the core directories in the
product:

java141\bin               --> all EXE modules reside here, including those
                              used for development
java141\demo              --> the source code to some useful sample
                              applications and applets
java141\include           --> C/C++ header files for use in the development
                              of native applications that access the JVM as
                              well as for JNI modules to be used by Java
                              applications
java141\jre               --> the entire Java Runtime Environment (JRE)
                              resides in this directory
java141\jre\bin           --> all DLL modules reside here, the subset of
                              EXE modules that is needed for runtime use
                              are duplicated here
java141\jre\lib           --> the primary root of all configuration-related
                              files and subdirectories
java141\jre\prefs         --> the persistent storage location for system and
                              user preferences (new in 1.4.1), which is
                              created at first usage
java141\lib               --> .lib files for linking to the JVM.DLL and the
                              JAWT.DLL; JAR files used only for development
                              purposes.

-----------------------------------------------------------------------------

7.  Tested Configurations

    ----------------------------------------------------------------
    |  NLS         |  OS/2 Version  | HotSpot Compiler | CPU Type  |
    ----------------------------------------------------------------
    | U.S. English | MCP2           | C1 (client)      | UNI       |
    | U.S. English | MCP2           | C1 (client)      | SMP       |
    | U.S. English | MCP2           | C2 (server)      | UNI       |
    | German       | MCP2           | C1 (client)      | UNI       |
    ----------------------------------------------------------------

-----------------------------------------------------------------------------

8.  Unique Features

- Full support for symmetric multiprocessor (SMP) systems. This product
  has been successfully tested (certified Java Compatible) on multiprocessor
  systems.  The Golden Code JVM is the only J2SE 1.4 based product on OS/2
  that supports SMP.

- In addition to the full, native graphical implementation of AWT/Swing, the
  GCD JVM has the following graphical/multimedia features:
  - Drag and Drop support between native OS/2 applications (e.g. EPM, WPS)
    and Java applications (both AWT and Swing) running in the GCD JVM.
  - Input Method is fully implemented and has been tested in some but not
    all DBCS environments.
  - Robot is completely functional (see section 12 for the one exception to
    this statement).
  - Native, complete JAWT interface.
  - JSound implementation that supports sound device sharing for both
    applications and applets.  This is a major improvement over the more
    standard exclusive mode implementation.

- Debugging/Profiling
  - JDB is fully functional.
  - Standard external interfaces are available to native OS/2 applications:
    - JVMDI (JVM Debugger Interface)
    - JVMPI (JVM Profiler Interface)
  - JDWP (Java Debugger Wire Protocol) is completely supported and tested. A
    TCP/IP sockets based JDWP (DTSOCK) is provided.
  - JVMSTAT/VISUALGC support is fully functional
    - The interface required for these tools is provided by the GCD 
      implementation of the HotSpot Virtual Machine.  This "PerfData"
      facility provides a lightweight performance and capacity monitoring
      implementation that has very little overhead and thus is suitable
      for use with a wide range of applications and scenarios. It is not
      a standardized interface but is instead a proprietary Sun interface
      that is not guaranteed to remain the same in the future. In fact,
      Sun may arbitrarily remove this interface in future versions.
    - jvmstat and visualgc are tools that are provided "AS IS" by Sun to
      help with performance and capacity profiling/tuning.  They are also
      useful in detecting memory leaks or design problems that cause bad
      garbage collection behavior.  The tools can be obtained from Sun at:
      http://developers.sun.com/dev/coolstuff/jvmstat
    - The GCD JVM has been enhanced to fully support these tools. To enable
      a JVM to be profiled/inspected via this interface, add the VM option
      -XX:+UsePerfData to the command line invocation.  Once the JVM is
      launched, use a tool such as the OS/2 pstat.exe to identify that JVM's
      process ID (PID). The PID is normally reported in hexadecimal format,
      so you MUST convert it to a decimal integer before using it in the
      next step!  Assuming you have the jvmstat tool installed in x:\jvmstat,
      run the following command to run the jvmstat tool (note the command has
      been split into multiple lines to make it easier to read, but it is
      only a single command line):
      java.exe -XX:+UsePerfData -Xbootclasspath/p:x:\jvmstat\classes\boot.jar
         -jar x:\jvmstat\classes\jvmstat.jar <decimal_pid_of_target_jvm>
      There are many options and capabilities so consult the documentation
      included at x:\jvmstat\docs\index.html. Usage of visualgc is done 
      exactly the same as jvmstat with the exception that visualgc.jar
      should be substituted for jvmstat.jar in the above command line.
  - Dynamic thread state dumping.
    - The HotSpot JVM as designed by Sun, provides a facility to display the
      state of all threads to the console. This is triggered via the sending
      of the SIGBREAK signal to a specific JVM process. Normally this is
      handled via the CTRL-BREAK key sequence on the console of the specific
      JVM process in question.  This is how the facility works in Windows
      for example.
    - In OS/2, all PM programs and VIO windows (which run in the PM screen
      group) are operating in a mode where a SIGBREAK signal cannot be
      generated by the user.  The CTRL-BREAK key combination is instead
      delivered as a SIGINT which is the same as a CTRL-C.  This normally
      causes the JVM to abort and exit.  Because of this OS/2 limitation,
      the GCD JVM was enhanced with a facility that enables the thread
      dumping output of the HotSpot JVM, without using the SIGBREAK signal.
      This facility is provided via a separate tool named dumpthreads.exe.
    - The tool is located in \java141\jre\bin and is provided on an "AS IS"
      basis.
    - In most cases, its use will provide the following:
      - A listing of each running thread (both JVM internal threads and all
        Java Threads).
      - Each thread's state and an associated Java stack trace (if the thread
        is a Java Thread).
      - The results of a deadlock analysis.  If the JVM finds a deadlock,
        additional information is displayed showing the exact threads that
        are deadlocked, the resources they are waiting for, and the thread/
        Java method in the stack trace that owns those resources.  With this
        deadlock analysis, deadlock problems become easier to debug and
        resolve.
    - This tool can be used on a running JVM without any prior preparation
      (e.g. no additional -X options to turn on debug).
    - WARNING: the processing of this facility involves the interruption of
      the "main" thread (TID 1) of the target process.  If that thread is
      currently processing inside certain OS/2 API calls, this interruption
      can cause those APIs to fail with an ERROR_INTERRUPT return code. This
      may or may not be handled without disruption on the part of J2SE or the
      JVM.  This means that it is possible to cause the JVM to exit or abort
      by using this facility.  As such, it is best to use this in a
      non-production environment OR to test its use thoroughly on the
      specific Java application in question to determine if it is safe to
      run this in production.  For many (if not most) Java applications,
      no harmful impact will occur on the JVM at all.  This is especially
      true for applications where the main() method ends before the rest of
      the application.  In this case, the TID 1 will not actually exit but
      will be blocked inside a JVM function called DestroyJavaVM().  This
      is known to work properly in regards to the dumpthreads facility.
    - To use the tool:
      - Start the target application as normal.  If you are not already
        redirecting the standard output (stdout) and standard error (stderr)
        of the process to a log file, this would be a good idea as the
        dumped information is quite verbose (it will run off the screen).
        Add "> logfilename 2>&1" (without the double quotes) to the end of
        the command line to achieve this result.
      - Use PSTAT, Theseus or some other inspection/query tool to identify
        the target JVM's process ID (PID) in either decimal or hexadecimal
        format.
      - Run the tool using either of these two forms:
          dumpthreads.exe <decimal_pid>
          dumpthreads.exe 0x<hexadecimal_pid>
      - The tool will report the success or failure of the operation.  If the
        target JVM "ignores" the signal, the JVM itself may be "hung".  
        Otherwise, as long as the PID is valid and properly specified, the
        result should be successful.
    - This tool is provided for debugging only.  You use it at your own risk.
      Golden Code Development is NOT responsible for any problems, failures,
      loss of data, downtime or any other issues due to this tool's usage.
      Do not use it in a production environment without testing.  Golden Code
      provides NO WARRANTIES in regards to dumpthreads.exe or its usage.

- A complete JVM interface is available to native OS/2 applications. These
  APIs are accessed using the header files in \java141\include and the
  resulting native programs can be linked using the LIB files in
  \java141\lib.  The full set of native facilities is available including
  the ability to write a custom or 3rd party application that launches
  the GCD JVM in-process.  In other words, the HotSpot virtual machine has
  native linear executable (LX) entry points for all Sun specified exports
  that the JVM has on other platforms. This is in addition to full support
  for natively written JNI modules.

- The new Java preferences facility is available. These preferences are
  stored in the file system, in a location that is controllable by the
  user (see section 5 for details).  This eliminates any reliance upon the
  binary OS/2 INI files (or the WIN32 Registry as is done in the Windows
  JVM), which makes the system more reliable and easier to maintain.

- Process launching under the GCD JVM is superior to that found in any other
  OS/2 JVM.
  - The GCD JVM honors any specified working directory. This will be of value
    to applications such as ANT.
  - Starting multiple types of sessions (VIO, PM...) works properly in the
    GCD JVM.
  - Using waitfor() on multiple child processes does not cause a hang in the
    GCD JVM.
  - In the GCD JVM multiple child processes are started in different sessions
    rather than in the same session. This *really* helps when starting
    multiple text mode apps!
  - In a VIO java.exe, starting child processes with the same session type
    as the JVM doesn't cause conflict with video output (related to previous
    comment).
  - Process launching options such as background/foreground launching and
    minimized launching are under user control via -XprocessLaunchingOptions
    (see below).

- The JAVA.EXE "launcher" provides a facility where the user can specify
  a fully-qualified path to a class file. This is a convenience not found
  in the Sun implementation.  The following would work in the GCD JVM:

    java.exe d:\path1\path2\HelloWorld

  For Sun's JVM, the equivalent command line is:

    java.exe -classpath d:\path1\path2 HelloWorld

- The product is designed for "unzip and run". This simplifies the
  installation and eliminates the need to provide an installer. Note that
  there is NO required configuration information stored in ANY location
  outside of the \java141\ directory structure. In addition, there is no
  need to modify any of the configuration in \java141\ either. All launchers
  are self aware and dynamically setup the environment to ensure that no
  effort beyond unzipping the files is required.  This design point allows
  easy installation via CID or in any unattended/remote setting (e.g.
  NVDM/2).

- Multiple installations of this JVM can co-reside and simultaneously operate
  on the same system without limitations.  This means that new versions can
  be deployed with little risk as the old versions can be retained and will
  continue to function without change.  While multiple JVM instances that are
  started from the same root path (e.g. x:\java141) will share some resources
  such as DLLs and certain read-only resources or files, there is no global
  sharing of configuration, files, memory or other resources between JVM
  instances that are loaded from different root paths. This was a deliberate
  design point to ensure that multiple installations (of different versions
  or even of the same version) can be completely independent of one another.

- Non-standard HotSpot options:

  -Xlicenseverify                 This option displays a report on the status
                                  and contents of your license file. In order
                                  for the JVM to operate properly, the file
                                  license.jvm must exist in the
                                  \java141\jre\bin directory. This file is 
                                  digitally signed and encodes information 
                                  specific to each customer. DO NOT attempt to
                                  modify this file as this will be detected 
                                  and the JVM will refuse to operate.
                                  
  -XdisableMMFjars                Use this option to reduce the memory
                                  footprint of the JVM. It will save many 
                                  megabytes (~12MB) of RAM but it will also
                                  increase application load time as a result.

  -XOS2argLengthWorkaround=<nnn>  This option changes the JVM limit on the 
                                  length of characters that can be passed as
                                  command line arguments to a child process 
                                  when that child process is launched. Make
                                  sure that there are NO SPACES before or
                                  after the "=". The <nnn> is specified as a
                                  decimal integer and is interpreted as the
                                  maximum number of bytes to allow as
                                  arguments. See the known issues (section
                                  13) below for details on when this may be
                                  useful AND for details on the limitations
                                  and dangers of this option.

                                  Please note that the format for specifying
                                  the argument to this option has changed
                                  between the 1.4.1_06 release and the
                                  1.4.1_07 release. The addition of an "="
                                  was made to make the format more standard
                                  between multiple -X options.

  -XprocessLaunchingOptions=<nnn> Provides a mechanism to control child 
                                  session background/foreground and other
                                  visibility attributes. Make sure that there
                                  are NO SPACES before or after the "=". The 
                                  <nnn> is specified as a decimal integer with
                                  a value between 0 (the default) and 31. The
                                  value represents a bit mask with the 
                                  following bits defined:

                                  .... ...X (1)  if set, session is invisible
                                  .... ..X. (2)  if set, session is maximized
                                  .... .X.. (4)  if set, session is minimized
                                  .... X... (8)  if set, session window remains open
                                  ...X .... (16) if set, session is in background

                                  To calculate the correct mask, sum the
                                  decimal values of each of the options to
                                  be set.

  -XoverrideThreadPriorityScheme;[x],[x],[x],[x],[x],[x],[x],[x],[x],[x],[x];

                                  Provides the ability to exactly specify the
                                  mapping between the OS/2 priority scheme and
                                  the Java priority scheme. Java has 11 levels
                                  (0-10) of priorities and each one has a comma 
                                  separated "slot" in the -X option. 

                                  [x] is an optional hexadecimal value for 
                                  the OS/2 priority to override that specific
                                  slot (1st slot is the Java priority 0 ...).
                                  Note that all commas and semicolons are
                                  required whether or not a priority override
                                  has been specified for that slot. As an
                                  example of the a hexadecimal priority value
                                  0200 is the value most often associated with
                                  the "normal" application priority. The high
                                  byte is the priority class (from 1 to 4) and
                                  the low byte is the priority rank within the
                                  specified class (0 to 31).  Remember that
                                  a priority class of 03 (time critical) is 
                                  HIGHER than 04 (foreground server).  Do not
                                  put any whitespace or the chars 0x in your
                                  hexadecimal value!

                                  IF YOU HAVE NO IDEA WHAT THE HEXADECIMAL
                                  OS/2 PRIORITY VALUE SHOULD BE THEN YOU HAVE
                                  NO BUSINESS USING THIS FEATURE!  DO NOT 
                                  CONTACT GOLDEN CODE WITH ANY PROBLEMS THAT
                                  OCCUR AS A RESULT OF YOUR USAGE.

                                  THIS OPTION IS UNSUPPORTED AND SHOULD NOT BE
                                  USED IN A PRODUCTION ENVIRONMENT.  IT IS
                                  PROVIDED AS A RESEARCH TOOL ONLY.  USING
                                  THIS OPTION IS HIGHLY LIKELY TO BREAK THE
                                  PROPER OPERATION OF THE JVM. IT MAY EVEN
                                  CONTRIBUTE TO HANGS UNDER SOME CONDITIONS.
                                  GOLDEN CODE IS NOT RESPONSIBLE FOR ANY
                                  PROBLEMS OR DAMAGE THAT OCCURS AS A RESULT
                                  OF THIS OPTION.

  -XdumpStackUsage                Provides a mechanism to track native thread
                                  stack usage in the JVM. At JVM exit, a report
                                  will be displayed showing the maximum stack
                                  size and usage for each thread. This is for
                                  debugging usage only.

- All instances of a JVM loaded from the same root path (e.g. x:\java141)
  share a single read-only, in memory copy of critical J2SE jar files. This
  saves memory when using more than 1 Java applications simultaneously. It
  also improves application load time.

- Coexistence of both the HotSpot server (C2) and client (C1) compilers. The
  Sun JVM architecture tightly couples the HotSpot compiler and the JVM
  itself. This is why there are two different JVM.DLLs shipped.  The current
  product can only run one or the other from the same root path (e.g.
  \java141\) and steps are taken to ensure that attempting to run both will
  result in a safe option being chosen. For example, if you run the following
  commands:

  java.exe MyProgram
  java.exe -server -version

  The first command will load a C1 JVM by default. This would be the same as
  if you had specified -client on the command line.  All subsequent runs of
  the same JVM (from the same root path) will cause the C1 JVM to be used,
  until all of these JVMs have been unloaded. The user will see the following
  warning if the specification of -server has been overridden:

  "A JVM of type '-client' is already loaded. Ignoring '-server' option!"

  If there is a pre-existing C2 JVM already running when the user attempts to
  run a -client (or default) JVM, the following warning will be seen:

  "A JVM of type '-server' is already loaded. Ignoring '-client' option!"

  These warnings are not real errors. They only indicate that the JVM has
  overridden the user's request for a specific compiler. In fact, there are
  memory footprint and load time advantages to running multiple instances
  of the same JVM. The JVM DLLs and JAR files will only be loaded once
  and then shared across all JVM instances (loaded from the same root path).

  If one requires running both the client and server compilers
  simultaneously, the following workaround is possible:

  Duplicate the \java141\ directory tree (e.g. \java141_server).  Run one
  compiler (e.g. -client) from the original directory tree and a second
  compiler (e.g. -server) from the new directory.  All JVM instances started
  from the original path will use the same compiler (in this example,
  -client) and all instances started from the new duplicated tree will be
  using the other compiler (-server).  This should not normally be necessary,
  since there are no real advantages to running both compilers
  simultaneously and there are definite disadvantages (increased working set
  and reduced load time for the second JVM instance).

-----------------------------------------------------------------------------

9. Timezone Processing

The GCD JVM defaults to GMT if the TZ environment variable is not set.

If the TZ variable is set properly, there should not be any issues with
timezone processing.  However, if the daylight savings time values are
not encoded in the TZ variable and the defaults for your timezone are
not acceptable, you will need to set the TZ environment variable using
the format below.  More importantly the GCD JVM is dependent upon the
IBM VisualAge C++ CRT library. This library has been shown to yield
inconsistent results in some cases, unless the TZ environment variable
is fully specified. Once encoded properly, this will be detected and will
override the defaults. IF YOU FIND ANY PROBLEMS, MAKE SURE TO FULLY
ENCODE YOUR DST INFORMATION INTO THE TZ ENVIRONMENT VARIABLE.

To include DST information, use the following format (much of the
TZ format information comes from the IBM VisualAge C++ documentation):

SET TZ=<SSS>[[-|+]h[:m[:s]]][DDD][,sm,sw,sd,st,em,ew,ed,et,shift]

Where:

 <SSS>                       Standard-timezone identifier.  It must be
                             three characters, must begin with a letter,
                             and can contain spaces.
 [-|+]                       Optional sign which indicates the direction
                             of offset from GMT. + is west of GMT and -
                             is east.

 [h[:m[:s]]]                 Optional difference in hours) between the
                             standard time zone and GMT. Minutes and
                             seconds can also be optionally specified.
 [DDD]                       Optional daylight saving time (DST) zone
                             identifier. It must be three characters, must
                             begin with a letter, and can contain spaces.
 sm                          Starting month (1 to 12) of DST.
 sw                          Starting week (-4 to 4) of DST.  Use negative
                             numbers to count back from the last week of
                             the month (-1) and positive numbers to count
                             from the first week (1).
 sd                          Starting day of DST.
                             0 to 6 if sw != 0
                             1 to 31 if sw = 0
 st                          Starting time (in seconds) of DST.
 em                          Ending month (1 to 12) of DST.
 ew                          Ending week (-4 to 4) of DST.  Use negative
                             numbers to count back from the last week of
                             the month (-1) and positive numbers to
                             count from the first week (1).
 ed                          Ending day of DST.
                             0 to 6 if ew != 0
                             1 to 31 if ew = 0
 et                          Ending time of DST (in seconds).
 shift                       Amount of time change (in seconds).

If you give values for any of sm, sw, sd, st, em, ew, ed, et, or shift, you
must give values for all of them. If any are missing, the entire statement
is considered not valid, and the time zone information is not changed.

In order to limit the possible impact of these known problems in the IBM CRT
library, the JVM will attempt to detect if the TZ environment variable has
sufficient DST definitions.  When the JVM detects that the DST indicator is
missing, it will add the DST indicators for popular timezones, based on this
list:

 TZ         Default DST Indicator
-----  -------------------------------
EST    ",4,1,0,3600,10,-1,0,7200,3600"
CST    ",4,1,0,3600,10,-1,0,7200,3600"
MST    ",4,1,0,3600,10,-1,0,7200,3600"
PST    ",4,1,0,3600,10,-1,0,7200,3600"
HST    "" (no DST indicator)
CET    ",3,-1,0,7200,10,-1,0,7200,3600"
MEZ    ",3,-1,0,7200,10,-1,0,7200,3600"
MET    ",3,-1,0,7200,10,-1,0,7200,3600"
WET    ",3,-1,0,3600,10,-1,0,3600,3600"
EET    ",3,-1,0,3600,10,-1,0,3600,3600"
BST    ",3,-1,0,3600,10,-1,0,3600,3600"
IST    ",3,-1,0,3600,10,-1,0,3600,3600"

This ensures that there are reasonable defaults for well known timezones. It
also allows for full configuration control by the user through the normal
TZ environment variable.

If there are other appropriate timezone codes in use that aren't in the above
table, the user should be sure to include it in their TZ environment variable.
Customers with a support contract can specify updates to this list and GCD will
provide these at no additional charge.  At the current time these defaults are
not user-configurable.

-----------------------------------------------------------------------------

10.  Modifying Font Processing

All Adobe Type 1 and TrueType fonts installed on the target system are
supported and are accessible programatically. This implementation of J2SE
will use fonts which are installed in the \PSFONTS directory of the boot
drive and those, if any, installed in the \OS2\MDOS\WINOS2\SYSTEM directory
on the boot drive.

Default fonts have been selected based upon their rendering quality across a
range of different systems, and based upon their supported character sets.
The physical fonts in use are those specified by one of the font.properties
variants found in \JAVA141\JRE\LIB. These files define the physical fonts
which are used to represent the five standard, logical, composite font types
provided by Java: Serif, SansSerif, Dialog, DialogInput, and Monospaced.

The most locale-specific variant of font.properties will be used to determine
the makeup of the five composite fonts. Currently, the only locale-specific
font properties file is font.properties.ja, for Japanese font support. The
font.properties file will be used in all other locales.

Font rendering quality may vary widely between systems. Based on customer
feedback, three alternative font.properties files are provided. These may be
found in the \JAVA141\JRE\LIB\FONTPROP directory:

font.properties.def  - The default font.properties file; uses Arial family
                       for Dialog and SansSerif composite fonts. Requires
                       a high quality set of TrueType Arial fonts to be
                       installed (see below). This file is simply a backup
                       copy of the font.properties file installed in
                       \JAVA141\JRE\LIB.
font.properties.alt1 - Should be used if no high quality Arial TrueType fonts
                       are installed on the target system; uses Lucida Sans
                       family for Dialog and SansSerif composite fonts. Note
                       that this font is wider than Arial, and may affect the
                       layouts of applications which have been tuned to Arial
                       or a similar font.
font.properties.alt2 - Uses Arial family instead of Lucida Sans for Dialog
                       and SansSerif composite fonts, like *.def file.
                       However, uses Arial (plain) for both plain and bold
                       styles. This works around a problem where using
                       certain versions of Arial Bold result in poor
                       rendering quality for bolded Dialog and SansSerif
                       text.

To use one of the alternative sets of font properties, simply copy it over
the font.properties file in java141\jre\lib as follows:

Assuming J2SE 1.4.1 is installed on the current drive in the \JAVA141
subdirectory...

  cd \java141\jre\lib\fontprop
  copy font.properties.alt1 ..\font.properties

To revert back to the default font setup...

  cd \java141\jre\lib\fontprop
  copy font.properties.def ..\font.properties

Both the default and *.alt2 variants rely on a set of high quality, Arial
TrueType fonts already being installed, either in OS/2 or WINOS2. The
font.properties.alt1 has no such prerequisite; the fonts it references
are guaranteed to be available on standard OS/2 systems. Older versions
of TrueType Arial family fonts installed with WINOS2 will typically
result in poor font rendering quality, especially in Swing applications.
If the only TrueType Arial fonts installed on your system are older than
than 1998 (see ARIAL*.TTF in \OS2\MDOS\WINOS2\SYSTEM on the boot drive),
this will probably be the case. In this circumstance, font.properties.alt1
or font.properties.alt2 should be used instead of the default.

Any use of Java2D font processing in J2SE (e.g. use of Swing applications
or other lightweight components) uses a font path (a list of directories
delimited by ';') to search for TrueType and Adobe Type 1 fonts.  Since 
Java2D loads and renders fonts using its own pure Java font rendering
engine, it only needs to be told where to look for fonts.  It does not use
the OS/2 GPI or any OS/2 native font processing at all.

The AWT on the other hand does NOT use the portable Java2D font engine.  It
uses the OS/2 GPI directly, for both the enumeration and processing of all 
fonts.  This is why AWT applications and Swing applications will have
different font rendering for the same fonts.

Beginning with the 1.4.1_07 build the Java2D font path searching algorithm
operates as follows:

  1. If GCD_JAVA_DISABLE_WINOS2_TTF is not defined, the use of WINOS2\SYSTEM
     TTF fonts are enabled, and this directory (both ECS and OS2) will be at
     the beginning of the font path.
  2. Then the paths to vector fonts from the PM_Fonts application in OS2.INI
     are added to the list. 
  3. If it is not possible to get the font paths from OS2.INI, the \PSFONTS;
     path is used as a last resort. 

Prior releases did not use the OS2.INI in the font path.

In some cases, it may be useful to disable the loading of WINOS2 TTF fonts.
For example, some versions of the WINOS2 TTF fonts provide invalid character
sets for the Polish locale.  To remove the WINOS2 directory from the font
loading path, the environment variable GCD_JAVA_DISABLE_WINOS2_TTF can be
defined in CONFIG.SYS. When the value is equal to 1, additional TrueType 
fonts from \OS2\MDOS\WINOS2\SYSTEM directory on the boot drive will not be
loaded. This solves some possible problems with character rendering for
non-US locales. It can be used as a workaround if after running of Swing 
applications there are problems with text rendering in native OS/2 text 
processors.

It is also possible to COMPLETELY override this default font path searching.
If the environment variable JAVA_FONTS is defined:

  SET JAVA_FONTS=c:\somepath0;e:\somepath1;

then the JVM will load the fonts from these directories instead of the way
which is implemented inside JVM.  Please note that the fonts from the 
\java141\jre\lib\fonts cannot be overridden, they are always loaded.

The Java2D font engine (as implemented by Sun) has limitations and can not 
properly handle some existing TrueType fonts. During initialization of the
font engine it runs consistency checks on all fonts in the font path.  If
the font engine cannot handle a font or a font is detected as corrupt then
that font is skipped.  If you are expecting certain fonts to be available to
lightweight components but cannot access these fonts, this may be the cause.
No error messages are produced in this case. The font engine does provide a
mechanism to determine such situations.  By setting the environment variable
JAVA2D_DEBUGFONTS (to anything non-null), font engine internal tracing is
enabled and on standard error output one will see an initialization log which
contains various details about loaded and rejected fonts. An example:

  SET JAVA2D_DEBUGFONTS=ON

There are fonts which are shipped with various versions of OS/2 which will
fail the font engine consistency tests. In particular, the MYGJO.TTF shipped
with Korean OS/2 Warp 4.0 is not supported by the Java2D font engine and will
not be loaded.

The JVM does not load any files directly from the \JAVA141\JRE\LIB\FONTPROP
directory; the files in this directory are provided only for the purpose of
copying over the font.properties file in the \JAVA141\JRE\LIB directory as
described above. Thus, changes to any file in the \JAVA141\JRE\LIB\FONTPROP
directory will have no effect on the operation of the J2SE environment,
unless the changed file is subsequently copied over the font.properties
file in \JAVA141\JRE\LIB.

NOTE TO USERS WITH JAPANESE LOCALE: DO NOT copy any of the files provided in
the \JAVA141\JRE\LIB\FONTPROP directory over font.properties.ja. These files
were only meant to replace the default font.properties file in the
\JAVA141\JRE\LIB DIRECTORY.

-----------------------------------------------------------------------------

11. Avoiding Flicker in Graphical Programs

Due to the screen painting implementations of some graphical programs, you
may notice a visible flicker when the content of certain windows or dialogs
is updated. We have noticed this in several Swing-based applications, but it
is not necessarily limited to Swing.

These programs may benefit from setting the 'sun.awt.noerasebackground'
property to 'true'. This setting disables an extra clearing of the screen
between paints, which can result in usability and performance improvements
in many programs which use Java2D to completely paint the contents of a
window. Most Swing-based programs will benefit from this change.

However, use this technique with caution. Setting this property to 'true'
globally is NOT recommended. Many applications, particularly those that use
heavyweight AWT (i.e., pre-Swing) components, depend upon this extra screen
clearing to occur between paints. These will experience serious paint
corruption problems with this property set to 'true'.

We recommend using this technique on a case-by-case basis in the command
line parameters when launching an application, as follows:

    java -Dsun.awt.noerasebackground=true MyProgram

The situation is a little more complicated for applets, as this requires a
more pervasive system change, using the 'gcd_java_options' environment
variable, as in:

    set gcd_java_options=-Dsun.awt.noerasebackground=true

If you are going to do this:

1) Do not set the variable in CONFIG.SYS; this would affect all applications
   as well as applets.
2) Make the change in a separate .CMD file specific to your OJI plugin
   configuration, so that the change will affect only applets (for details,
   see the Installation and Configuration section in plugin.txt).
3) Test the applets you want to run with the new setting to make sure none
   of them are adversely affected.

-----------------------------------------------------------------------------

12.  Incomplete or Missing Function

- Full-screen exclusive mode in AWT is an optional feature which is not
  supported at this time.

- Applications that load a JVM "in-process" using the JNI/JVM interfaces
  are known as "3rd party launcher" applications.  These applications are
  can be written with the current product, however there are additional
  requirements that are currently undocumented and are subject to change in
  the future.  If you have a requirement for such an application, please
  contact Golden Code Development (see section 19 below).

- The use of high memory (addresses above 512MB) is almost complete.  While
  the Java heap and some other miscellaneous large memory requests have been
  moved to high memory, the CRT heap and each thread's stack are still
  allocated below 512MB.  However, the vast majority of the memory used in
  the JVM comes from the Java heap.  By moving this to high memory, it will
  only be possible to see private process address space contention in the
  cases where a single JVM creates significantly more than 1000 threads.  At
  this time we have no plans to move these remaining memory allocations into
  high memory.  If you have such a requirement and are a customer with a
  valid support contract, please contact Golden Code Development (see section
  19 below).

- Right To Left (RTL) text processing is not functional at this time.

- DBCS support is partial.  The base J2SE processing in a DBCS environment
  is now complete, however DBCS support in graphical environments is not
  yet 100%. While Swing based applications will work well, including Input
  Method support (Chinese version was tested, other versions are only tested
  partially), the DBCS support in AWT heavyweight controls is only partial
  and is relatively untested.

- Robot does not support drag and drop (drag and drop is fully supported in
  Java applications, however the AWT Robot function cannot initiate a drag
  and drop event).

-----------------------------------------------------------------------------

13. Known Problems/Limitations in the GCD JVM and/or in OS/2

- AWT/Swing/Java2D

  - Some Java applications have a latent defect in which the printing code
    assumes that it is only called once per page or once per Swing component.
    Implementing printing in this manner is contrary to the defined Sun
    specification however it is a common issue since the JVM implementations
    on most platforms only call printing functions once per page. The current
    GCD JVM does not follow this model and thus exposes this latent issue in
    applications.  One known example of this is the Polarbar Mailer. Golden
    Code will work with software vendors to resolve this issue in
    applications where it is found.
  - On some video hardware, the drag and drop cursors are displayed
    incorrectly.
  - The JTextArea "caret" (the text mode insertion cursor) is not visible
    during a drag and drop operation.
  - The TextArea does not wrap text.
  - Some versions of the IBMPCL5 printer driver generate an extra line at the
    bottom margin of the last page of a print job. This is a defect in this
    driver, not in the JVM.  One can duplicate this result by printing any
    bitmap using applications such as PMView or Impos/2.  Golden Code will
    work with IBM via an IBM PMR to resolve this issue if necessary for a
    customer.  See section 18 for details on the process.
  - Some JDialogs containing at least one JTextArea component are laid out
    such that the dialog is too tall. The root cause of this problem has
    not yet been identified. This behavior occurs in Sun's Win32 J2SE
    implementation as well.
  - The direct manipulation APIs (i.e. drag and drop or DnD) in the OS/2
    Presentation Manager (PM) have undocumented dependencies upon the
    Workplace Shell (WPS). This means that some DnD functions that are 
    properly coded will fail when run on a system in which the WPS is not
    running.  This is a limitation of OS/2 itself and is not a problem in
    the JVM.  There is nothing that can feasibly be done to remove this
    limitation.

- Running IBM's TCP/IP configuration application (TCPCFG2.CMD) requires a JNI
  module called CFG2NATV.DLL. This module loads properly in the GCD JVM,
  however it has a flaw in which it successfully queries 3 paths to TCP/IP
  resources but does not properly return these paths to Java. Golden Code
  will work with IBM via an IBM PMR to resolve this issue if necessary for a
  customer.  See section 18 for details on the process.

- JDB command retrieval (using up/down arrow keys) is non-functional. The
  F3 and left/right arrow keys do provide command retrieval.

- Starting JAVA based child processes that use AWT/Swing can sometimes leave
  a "Completed" CMD.EXE window behind. German NLS customers will see a
  "Beendet wurde" instead of "Completed".

- Launching child processes that subsequently launch "grandchildren" of mixed
  session types (PM and VIO) can cause the original Java parent to fail to
  detect when the immediate child process has exited.  Specifically, the exit
  notification will not occur until all descendant processes have ended.

- Child processes launched will be killed by OS/2 if the parent JVM that
  launched them is ended first.

- OS/2 only supports passing up to 1024 bytes of argument data to child
  processes through the DosStartSession API. Certain OS/2 kernel levels have
  a defect that will trigger a system trap when this threshold is exceeded
  by some small amount (which is impossible to externally determine in
  advance).  The process launching mechanism in the JVM has been modified
  to artificially limit arguments to a 1024 byte maximum. However, there are
  instances in which more than this may be needed.  If both the parent and
  child processes are GCD JVMs, then this will be detected and they will
  employ an alternate mechanism to pass arguments which will allow arguments
  of unlimited length to be passed.  If the child process is not a GCD JVM
  and one requires a greater number of bytes to be passed, one can try the
  -XOS2argLengthWorkaround=<size> where <size> is a decimal integer specifying
  the number of bytes to which the internal JVM limit should be set.  This
  will allow a larger number of bytes to be passed through the DosStartSession
  API, however GCD IS NOT RESPONSIBLE IF THIS CAUSES PROBLEMS.  Based on
  our testing, this may trap the OS/2 kernel and there is no way to resolve
  this problem short of a PMR with IBM.

- Appletviewer does not honor the 'width' attribute in the <applet> tag
  for smaller widths (approx. <= 100 pixels) because this is the smallest
  width a frame window can have with working frame controls (e.g. Min/Max 
  buttons).  This is a design choice in the GCD AWT implementation.

- JSound - OS/2 Multimedia Presentation Manager (MMPM) Limitations

  - As of the GCD 1.4.1_07 release, the JSound implementation has been 
    completely rewritten.  This now provides a shared sound implementation
    which allows a Java applet to be a better citizen with the rest of the
    system in regards to its usage of the sound device.  On some sound cards,
    particularly those cards where only one sound device instance is available,
    the old exclusive approach caused problems because it would lock the device
    and never release it.  This problem has been eliminated, however the nature
    of the OS/2 sound architecture is that only one OS/2 application may use
    a sound device at a time, even in "shared" mode.  This means that when an
    applet uses sound, the sound device will be owned by the applet as long as
    that applet is actively using the sound device.  In addition, some applets
    can be written to hold onto the sound device (even if not actively playing)
    until the applet is disposed.  Switching the active browser "tab" away from
    the applet or closing the applet will release the sound device in these 
    cases.
  
  - Due to a problem in the OS/2 MMPM implementation, recording should not be 
    started if recording in another application is in progress. This may cause
    the application with the active recording to lose the input device. If this
    happens then the application which lost the input device will be unable to 
    operate the input device until the application has been restarted.

-----------------------------------------------------------------------------

14. Known Differences from the IBM JVM 1.3.1

This section documents the functional differences between the GCD JVM and the
IBM JVM. However, this deliberately ignores the differences that result from
the IBM JVM being frozen at the 1.3.1 functional level.  Specifically, these
differences are in functions that are common to both 1.3.1 and 1.4.1.

- Process Launching
  - The GCD JVM honors any specified working directory. This will be of value
    to applications such as ANT.
  - Starting multiple types of sessions (VIO, PM...) works properly in the
    GCD JVM.
  - Using waitfor() on multiple child processes does not cause a hang in the
    GCD JVM.
  - In the GCD JVM multiple child processes are started in different sessions
    rather than in the same session. This *really* helps when starting
    multiple text mode apps!
  - In a VIO java.exe, starting child processes with the same session type
    as the JVM doesn't cause conflict with video output (related to previous
    comment).

- The GCD JVM does not provide a replacement for the ICAT debugger. However,
  Sun's JDB is fully functional, as is the JVMDI (JVM Debugger Interface)
  native interface and the JDWP (Java Debugger Wire Protocol). Specifically,
  a sockets based JDWP (DTSOCK) is provided and has been tested.

- There is no feature installer in the GCD JVM. There is no need for one.

- The IBM custom fonts (e.g. Times New Roman MT 30) are not provided with the
  GCD JVM.

- Multiple threads interleave more smoothly in the GCD JVM than the IBM JVM.

- The GCD JVM maintains a directory structure that is identical to the Sun
  reference (duplicates executables between bin and jre\bin). The IBM JVM
  does not duplicate the runtime EXE modules in the bin directory which
  can break some scripts for common 3rd party/open source applications and
  servers.

- CTRL-BREAK or CTRL-C during the startup of the JVM will not cause a trap
  in the GCD JVM, where it will trap the IBM JVM.

- If you have JNI applications which are linked to JVM.LIB or JAWT.LIB, you
  must relink these modules using the .LIB files shipped in the
  \java141\include directory. The interfaces provided by the GCD JVM are
  nearly 100% compatible with those provided by the IBM JVM 1.3.1.  The
  IBM JDK does provide an additional interface to specific features of the
  IBM JVM. This interface consists of the following parts:

  1. Access to JVM extra threads and finalization status information (jni.h).
  2. Access to garbage collector information (jni.h).
  3. Additional JVMPI events (see jvmpi.h).

  These facilities in the IBM JVM are non-standard and thus are proprietary
  to IBM.  As a result those constants, APIs and structures that are specific
  to the IBM JDK are not available in the GCD JDK which is based on a HotSpot
  VM.

  If you have any questions regarding the differences, please contact GCD
  (see section 19 below).

- No int64_md.h/jniproto_md.h headers in the include directory. The
  JNI interface for the GCD JVM is much simpler because there is no
  requirement for compatibility between the Windows and OS/2 versions of
  VisualAge C++ as IBM had.  There is also no requirement for special
  functions that provide long long (64-bit integer) support in the GCD JVM.
  If a customer requires this support, please contact Golden Code
  Development.  In particular, this means that versions of VisualAge C++
  prior to 3.6.5 cannot be used for JNI modules due to the lack of long
  long support.  See section 17 for more details.

- IBM Compatibility Features

  - There is no LAN Server/UPM specific Java Authorization and Authentication
    (JAAS) module.

  - The product requires long filenames at this time.  IBM's JRE has been
    modified to only use short filenames so as to be compatible with a FAT
    file system.

-----------------------------------------------------------------------------

15. Known Differences from the Sun J2SE 1.4.1

- Where WIN32-specific functions exist for which there is no direct analog on
  OS/2, those functions do not exist in the GCD JVM.  Note that in all of
  these cases, there is no real functional loss, as these are non-essential
  areas of the Java runtime environment.  Sun had just provided these as
  extras for WIN32, but they are not provided on Solaris or Linux. The
  following is a list of some of these functions:

  - Native JAAS module for using the NT authentication services.
  - Since the OS/2 system itself has no concept of ODBC (Microsoft's Open
    Database Connectivity interface), no JDBCODBC bridge is provided.
    However, JDBC itself is completely functional.
  - Swing Windows "Look and Feel" is included in the RT.JAR but we are not
    allowed to make it functional.
  - Some (more unusual) DataFlavors for both images and text.

- The new user and system preferences features of the J2SE 1.4.1 are stored
  in the file system (see section 5 above) rather than in the OS2.INI,
  OS2SYS.INI or in the Registry as in Sun's WIN32 JVM.

-----------------------------------------------------------------------------

16. Performance Comparison

Significant performance tuning and optimization has been implemented for this
product. This effort comprises the first, rough optimizations that are
possible with the GCD JVM.  Substantial improvements have been made compared
to previous distributions. More importantly, runtime performance surpasses
other J2SE 1.4 implementations in virtually all cases.

The GCD JVM achieves this performance while remaining a "good citizen" with
regard to other users of system resources.  For instance, the GCD JVM does
not resort to the use of time critical threads, a shortcut which would
improve performance of the foreground JVM application at the expense of the
rest of the system.

All load-time performance testing was done using a Pentium II 600MHz CPU
with HPFS as the file system. This is considered a slow system and thus
the performance expectations are approaching the worst case scenario. On
faster hardware and/or with a faster file system, the results are
significantly improved.  The runtime performance tests were run on an Athlon
XP 2100+ system. In all cases the 3 JVMs were run using the same software and
hardware including filesystem, system software levels, memory and CPU.

However the important comparison is the relative difference between the JVMs,
All JVMs see benefits from faster hardware or a faster file system, thus the
specific environment is less important in this discussion.  All comparisons
in this document are done between the following JVMs:
  - GCD JVM 1.4.1_05 build 27 20031024
  - IBM JVM 1.3.1    co131-20020710
  - InnoTek 1.4.2_01 (latest available as of 2003-10-27)

Load Time Performance:

In comparison with IBM's 1.3.1 JVM: the "raw" load time of the IBM JVM is
on average 0.16 seconds and the GCD "raw" load time is 0.89 seconds. "Raw"
load time is the load time of a minimal JVM.  The load time of small AWT
applications may be slightly slower on the GCD JVM than in the IBM JVM.
Load time comparisons for large Swing applications vary, but the GCD JVM
generally loads this class of application comparably to the IBM JVM.  For
example, the Java2Demo application loads in 4.11 seconds in the GCD JVM
while it loads in 4.59 seconds in the IBM JVM. GCD JVM is faster despite
the fact that 1.4.1 must load 20% more classes than a 1.3 level JVM, to
perform even the most minor tasks.

Load time for both the IBM and GCD JVMs is improved notably when a matching
JVM is already loaded into memory, since DLLs and other shared resources
do not need to be loaded from disk for subsequent copies of the JVM.
So if load time is a concern, preloading a VM is going to make a difference,
at the expense of working set.  The raw JVM load time for the GCD JVM is
only 0.8 seconds (0.09 seconds improvement) in this case. For
larger Swing applications, the improvement is larger.  For example, the
loading of the Java2Demo application only takes 3.99 seconds in the GCD JVM
(0.12 seconds faster), when another GCD JVM instance is already loaded.

In comparison with the load time of InnoTek's JVM, the GCD JVM is quite close
but InnoTek's JVM does sometimes have a slight advantage.  Raw JVM load time
for InnoTek is about 0.33 seconds, just over 0.5 second faster than the GCD
JVM. Load time of larger Swing applications is a bit slower, for example
Java2Demo loads in 4.17 seconds (just over 0.06 seconds slower than
the GCD JVM). Interestingly enough, the InnoTek JVM does not obtain the same
improvements as the GCD JVM when there is another InnoTek JVM instance
already loaded. The difference in raw load time of the InnoTek JVM is
hardly notable for raw JVM (the same 0.33 seconds), the load time of larger
Swing applications is actually changed very slightly. For example, Java2Demo
still loads at 4.15 seconds (about 0.02 seconds improvement). With this
information in mind, the following point is important:

  InnoTek's claim of a 2X to 6X load time advantage over "traditional
  ports" is unfounded.  Assuming one is running both JVMs on the same
  hardware, same partition/file system, same software levels and with
  identical configuration, Golden Code has found no way to ever create
  more than a 0.6 second advantage for the InnoTek JVM and only in
  artificial test circumstances, when no actual application is loaded.

Runtime Performance:

Testing indicates that the GCD JVM is virtually always faster than the
InnoTek JVM and often faster than the IBM JVM in general purpose programs.
IBM provides a JIT compiler which does generate very good resulting native
instructions. In circumstances where code is run in tight loops, there can be
a break-even point at which the IBM JVM will start to be faster than the GCD
JVM.  This is due to the fact that IBM compiles everything in advance of
running it whereas the GCD JVM (being based on the Sun HotSpot compilers)
analyzes the interpreted Java code and determines the most important Java
methods to compile ("HotSpots") and then compiles only these.  This
compilation is dynamic and ongoing, but the bias is towards not compiling
anything that is seldom used.  In addition, the HotSpot compilers try to
reduce the amount of time spent compiling, which may lead to less optimized
native code. It seems that the IBM JVM takes much longer to compile
something, but once it is done, the resulting code is quite good.

As an example, the IBM JVM may take 0.56 seconds to run the first iteration
of a tight loop, but then subsequent runs will only take 2 milliseconds each.
So 10 runs are barely longer than 1 run, BUT the cost is significant.  Many
applications would not justify the "initial investment".  In the GCD JVM
(using Sun's HotSpot technology), all runs through the same tight loop take
from 33-41 milliseconds.  Thus, there appears to be a break-even point (in
this example) of somewhere around 16 runs of the tight loop.  Before this
point the GCD JVM will appear faster.  After this point the IBM JVM will
appear faster.  So the runtime story is very competitive and the GCD JVM will
win some performance comparisons, depending on the application.

In the following tests, each ImageJ was started in each JVM.  This
application can be found at the following URL:

   http://rsb.info.nih.gov/ij/

All 6 test runs were made in order, without unloading the application.  Each
image was loaded in turn using "File->Open Samples" and then "Image->
Benchmark->Run Benchmarks" was run twice for each image.

        ImageJ Benchmark Results (all results are in seconds):
-----------------------------------------------------------------------------
| Run                 | GCD C1 | GCD C2 | IBM JIT | InnoTek C1 | InnoTek C2 |
-----------------------------------------------------------------------------
| Embryos  - 1st pass |  5.299 |  5.822 |   6.746 |      5.310 |      6.930 |
|*Embryos  - 2nd pass |  5.029 |  4.836 |   3.410 |      5.040 |      4.600 |
| Bridge   - 1st pass |  1.806 |  2.145 |   3.700 |      2.070 |      3.250 |
| Bridge   - 2nd pass |  1.654 |  1.690 |   2.597 |      1.960 |      1.920 |
| Mandrill - 1st pass |  3.410 |  3.705 |   4.099 |      3.520 |      4.620 |
|*Mandrill - 2nd pass |  3.130 |  2.886 |   2.125 |      3.270 |      2.550 |
-----------------------------------------------------------------------------

The important points that can be summarized here:

  1. The GCD JVM (either C1 or C2) is always the fastest in the first pass
     while IBM is fastest in most subsequent passes.  This is a good example
     of the JIT versus HotSpot compiler differences.
  2. The InnoTek JVM is slower than the GCD JVM in all cases except two marked
     by asterisk. The GCD JVM in some cases outperforms the InnoTek JVM by more
     than 50%.
  3. The C2 compiler is usually slower than C1 on the first pass of any image
     but the subsequent pass is usually significantly faster. This reflects
     the better native code generation but shows the compilation cost that
     comes with it.

The server compiler *is* generally faster at runtime than the client
compiler.  The client compiler is optimized for a smaller working set and
faster load times.  The code generation of the server compiler is better than
the client compiler, though there is still a possible break-even point at
which the IBM compiler will perform better.  However with the server
compiler, the break-even point will be hit much later.  In other words, if 16
runs of the tight loop show the IBM JVM has equal performance to the GCD
client JVM, it might take 30 runs of the tight loop to show the same break-
even performance between the IBM JVM and the GCD server JVM.

Customers can take advantage of the choice that allows them to trade off
working set and load time with runtime performance.  This is a unique value
add of the GCD JVM compared to the IBM JVM.

Another example of the performance difference is in the Java2Demo application
that ships with the JVM. This application shows the performance of certain
Java2D operations in addition to the animation of the resulting images.  By
looking at the effective frame rates one can get some idea of the basic
Java2D performance of the JVM in question.  By default the animation delay is
set to 30 ms, when the application is started.  The same exact JAR file was
used for all of the JVMs.  This JAR file was the one shipping with the IBM
JVM since the IBM can't run the version of the JAR file that ships with the
1.4.x based JVMs.  On each page of the application, a pause was made to allow
the compiler to get the methods compiled. Once the frames per second
indicators became more stable, the range was captured.  Only pages with
animation were used for this test.  All values are in frames per second
(fps).

                           30 ms Animation Delay
-----------------------------------------------------------------------------
| Java2Demo Page      | GCD C1 | GCD C2 | IBM JIT | InnoTek C1 | InnoTek C2 |
-----------------------------------------------------------------------------
| Curves              | 26-27  | 25-27  | 15-16   | 14-29      | 14-25      |
| Clipping            | 25-27  | 25-27  | 15-16   | 14-26      | 24-30      |
| Colors              | 23-24  | 23-24  | 15-16   | 28-29      | 28-30      |
| Composite           | 22-24  | 23-24  | 14-15   | 27-29      | 28-30      |
| Images              | 27-28  | 27-28  | 15-16   | 28-29      | 28-30      |
| Lines               | 26-27  | 26-27  | 15-16   | 28-29      | 28-29      |
| Mix                 | 27-29  | 26-28  | 15-18   | 22-30      | 14-19      |
| Paint               | 26-28  | 26-27  | 15-16   | 22-30      | 25-29      |
| Transforms          | 22-23  | 22-23  | 15-17   | 14-23      | 14-29      |
-----------------------------------------------------------------------------

There is no significant difference between JVMs except that the IBM JVM
always shows smallest rates. Another interesting point is that the InnoTek
JVM almost always has a higher variability in its performance results.  While
it may sometimes get a higher maximum frame rate, it most often will have a
minimum rate that is significantly lower than the other two JVMs. In all
cases CPU usage is less than 100%, therefore difference in performance can be
caused by different implementation of the Thread::sleep() method in JVMs.

The next set of results shows a different situation, where JVM performance is
the cornerstone in the achievement of the best results.

                            0 ms Animation Delay
-----------------------------------------------------------------------------
| Java2Demo Page    |  GCD C1 | GCD C2  | IBM JIT | InnoTek C1 | InnoTek C2 |
-----------------------------------------------------------------------------
| Curves            |  35-72  |  38-78  |  55-72  |  38-40     |  37-39     |
| Clipping          |  65-81  |  65-82  |  94-156 |  56-62     |  56-60     |
| Colors            |  66-93  |  63-87  | 100-110 |  68-85     |  68-81     |
| Composite         |  78-102 |  88-102 |  65-79  |  76-85     |  75-83     |
| Images            | 157-168 | 180-192 | 192-232 | 125-130    | 125-130    |
| Lines             | 107-128 | 105-128 | 134-167 |  96-100    |  93-99     |
| Mix               | 106-115 | 105-122 | 125-138 |  61-65     |  60-63     |
| Paint             |  90-95  |  84-101 |  90-120 |  58-62     |  60-62     |
| Transforms        |  42-50  |  44-55  |  54-66  |  40-46     |  40-44     |
-----------------------------------------------------------------------------

IBM JVM has better results than the GCD JVM in the scenario where animation
delay is set to 0 ms (except Composite test).  In ALL cases the GCD JVM is
faster than the InnoTek JVM.

It should be noted that server JVMs achieve best performance after some time
of the execution of the application. Initial performance is usually worse than
performance of the appropriate client JVM.

An anomaly seen in the InnoTek JVM was a long pause (2-3 seconds) when trying
to switch away from the Java2Demo application while the animation delay was
set to 0 ms.  This can duplicated by trying to change applications to any
other application, such as EPM.

When trying to switch back to the InnoTek JVM from a native application, it
often painted in two steps: at first step animated windows are painted and
after some delay (usually 3-4 seconds) remaining parts of the application
are exposed. This only occurred when the 0 ms delay was set.

The InnoTek JVM relies upon the heavy handed manipulation of thread
priorities to achieve its results.  In particular, the highest Java priority
level (10) is set to the OS/2 time critical priority class.  This is a very
dangerous thing to do as it artificially steals CPU resources from the rest
of the applications.  This may make the foreground application look
responsive but it often has negative effects on both other applications and
even the other threads of the foreground application. It is this reliance
upon time critical threads that is probably a big part of the previously
mentioned performance anomalies in the InnoTek JVM.

Please note that the GCD results at 0 ms were very consistent, stable and no
strange behavior or anomalies were seen.  The reader is encouraged to recreate
these documented tests (ImageJ, Java2Demo...) and examine the results and
anomalies. The GCD JVM has very strong performance and this will be easily
demonstrated. Also, it should be noted that performance of the Sun JVM in the
release 1.4.2 is significantly improved but despite this fact GCD JVM performs
better in most cases. This proves the fact that native port has opportunity to
optimize any aspect of the environment as necessary in order to achieve best
performance.

-----------------------------------------------------------------------------

17. Developer Notes

- The Java language uses 64-bit integers as a basic feature. This means that
  native methods (written in C or C++) accessed via JNI, must be compiled 
  with an environment that properly supports 64-bit integers. The first
  IBM compiler to provide such features is VisualAge C++ 3.6.5.  This means
  that the VisualAge C++ 3.08 or prior compilers cannot be used to write
  JNI modules for the GCD JVM.  However, the VisualAge C++ 3.6.5 works quite
  well (it is in fact the compiler used to build the GCD JVM itself). Other
  compilers such as OpenWatcom should also work, as long as they provide
  "long long" support.

- Non-blocking mode considerations for NIO package

 - If you are a Java developer using SocketChannel or ServerSocketChannel in
   non-blocking mode, the following consideration must be taken into account:

   First, every TCPIP connection has unique timing parameters, speed and
   quality.  Since by Sun's design the non-blocking mode does not guarantee
   successful data delivery, some retry approach must be provided inside your
   program.

   Second, for multithreading programs the "optimal" delay time must be
   multiplied by the number of threads which are running simultaneously. As 
   an alternative, you can use the blocking call of (Selector).select() or 
   (Selector).select(0) for non-blocking mode channels rather than 
   (Selector).select(timeout).  It is also important to preserve the
   recommended algorithm while using the non-blocking channels facility. 
   It is likely that one can improve performance at the expense of
   flexibility. Please carefully review the J2SE SDK documentation for a
   description of using the advanced NIO features.

-----------------------------------------------------------------------------

18. Submitting Problem Reports

To submit a problem report, please send an e-mail to:

  techsupport@goldencode.com

The following information should always be included in a problem submission:

  * Your name.
  * Your organization's name (if applicable).
  * Your reply-to e-mail address.
  * The serial number of the product license. This can be obtained by running
    'java -Xlicenseverify' at the command line.
  * A detailed description of the problem, including steps on how to
    recreate the error condition.
  * If it is possible to isolate the problem with a small test case, the
    test case should be attached to the e-mail, or instructions on how to
    download the test case.
  * The hotspot log file that was created when the problem was encountered,
    if the problem ended in a crash of the product.

Some problems may be caused by underlying defects in the OS/2 operating
system or other related IBM software. If a defect is found to be so caused,
Golden Code has an arrangement with IBM in which the two companies can
effectively work together to resolve such issues. The customer must open an
IBM PMR and authorize the IBM personnel to work with Golden Code on this
issue.

PLEASE NOTE THAT UNLESS YOU MAKE ARRANGEMENTS TO EXCHANGE ENCRYPTED E-MAIL
WITH GOLDEN CODE DEVELOPMENT, ANY E-MAIL YOU SEND IS NOT SECURE AND MAY BE
VIEWED IN TRANSIT.

-----------------------------------------------------------------------------

19. Contacting Golden Code

E-mail   : info@goldencode.com (general), techsupport@goldencode.com
           (support)
Address  : 1455 Old Alabama Rd., Suite 135, Roswell, Georgia, U.S.A.
Phone    : +1 678-352-2301
Fax      : +1 678-352-2305

-----------------------------------------------------------------------------

20. Trademarks

'Golden Code' is a registered trademark of Golden Code Development
Corporation.

'IBM' and 'OS/2' are registered trademarks of International Business Machines
Corporation. 'WorkSpace On-Demand' is a trademark of International Business
Machines Corporations.

'Java', 'J2SE', and 'Java Compatible' are trademarks of Sun Microsystems,
Inc.

'Pentium' is a trademark of Intel Corporation.

Other names referenced in this document are the property of their respective
owners.

-----------------------------------------------------------------------------
       Copyright (c) 2002-2004, Golden Code Development Corporation.
                            ALL RIGHTS RESERVED.
-----------------------------------------------------------------------------
