

IBM OS/2 Java Developer's Kit 1.0 beta 1 Release Notes 25th January 1995
========================================================================

(c) Copyright Sun Microsystems Inc, 1992-1995. All rights reserved.
(c) Copyright IBM Corporation, 1996. All rights reserved.

This port is based in part on the work of the Independent JPEG group.

US Govt Users Restricted Rights - Use duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.

Java and the Java compatibility logo are trademarks of Sun Microsystems, Inc.

Mike Cowlishaw & Matthew Vaughton, IBM Hursley, United Kingdom.


Introduction
------------

The current Java for OS/2 distribution is (deliberately) a copy of the beta
distribution for Windows NT except, of course, for the platform-dependent
binaries. You will see Sun copyright notices, etc.; these will be updated
later.

The current beta inevitably has some problems and restrictions. In particular
AWT image support has yet to be implemented and the JDB debugger break points
do not work reliably.

There is not yet a beta version of the Hotjava browser available.


Installation instructions
-------------------------

--- You need ---

  OS/2 2.x or Warp  -- Warp is recommended, and is required for audio
                       [we have not tested on 2.x recently, but it
                       should work]
  an HPFS disk      -- with at least 15MB free space
                       [Long name support is currently *required* for Java]
  JAVAOS2.ZIP       -- the Java for OS/2 package
  UNZIP.EXE         -- Infozip's version 5.12, August 1994, or later or an
                       equivalent unzip tool
  TCP/IP            -- either Warp IAK or TCP/IP 2.0+
  Hardware          -- a 486-class machine with 12MB+ RAM is recommended

--- Installation procedure ---

  1. Copy the file you downloaded to the root directory of your chosen
     disk, using the name JAVAOS2.ZIP

  2. Unzip the ZIP file, using InfoZip's UNZIP program, for example:

       unzip javaos2

     Warning: if you are not using Infozip, you may need to specify a -d
              flag for subdirectories to be created.  Check your UNZIP
              program's documentation.]

     This should create a JAVAOS2 directory, with the following subdirectory
     trees, containing the Java interpreter, compiler & tools:

       applet   -- Applet viewer output directory
       bin      -- Java .EXE files
       classes  -- Tree with compiled Java programs (.CLASS files).  Note
                   that Java requires that this directory be a sibling of
                   the BIN directory.
       demo     -- Demonstration applets, images, audio clips, etc
       dll      -- .DLL files for the Java interpreter and native classes
       include  -- Include files for building native classes
       lib      -- .LIB files and Java property files
       src      -- Java source code for a subset of the classes
       .hotjava -- Directory for network property files

  3. Edit your CONFIG.SYS file:

       o Add the DLL [eg, E:\javaos2\dll] directory to LIBPATH [required]

       o Add the BIN [eg, E:\javaos2\bin] directory to SET PATH [recommended]

     Reboot (if you had to do either of these).

  4. To check installation, change directory to javaos2\demo\hello, then:

       o  Enter the command

            java hello

          This runs (interprets bytecodes from) the 'hello.class' file.

       o  Enter the command

            javac hello.java

          This runs (interprets bytecodes for) the Java Compiler, to compile
          the file 'hello.java' to make 'hello.class'.  Note that many Java
          commands have case-sensitive arguments.

          You can then issue the command

            java hello

          again to check the hello.class file you just built.

     Note: As with the other Java packages, you must specify '.java' on
           the filename on JAVAC, and must *not* specify '.class' on JAVA
           (since it looks for a class, not specifically a file).

     If you added the JAVAOS2\BIN directory to your path, the JAVA and JAVAC
     commands should work in any directory.

     Note: Java will use the JAVAOS2 directory as its home directory.  To
           use a different one, set the HOME environment variable (for
           example, SET HOME=C:\home  [note no trailing '\']).  The home
           directory must be on an HPFS disk.

  5. In the beta distribution, the HotJava browser is replaced by an
     applet viewer; to run one of the demo applets, change directory
     to one of the javaos2\demo subdirectories, then:

       o  Enter the command:

            start applet example1.html

          [This processes the HTML file specified, and runs the applet
           referenced in that document.]

     Note: The applet viewer needs a "Home directory" (represented in
           some path names by the character '~') to save properties and
           a log of standard out messages.  You can specify the home
           directory with an environment variable set using the command
           such as SET JAVA_HOME=C:\home  [no trailing '\']. If this has
           not been specified when the viewer starts, it will attempt to
           use the javaos2\applet directory.  The home directory must be
           on an HPFS disk.

General Notes
-------------

  1. This package is a copy of the Sun Java release for Windows NT
     (1beta1), with the exception of the BIN, DLL, INCLUDE\OS2, and LIB
     directories, this file, and certain network defaults.  We have not
     attempted to update the documentation or notices for OS/2 yet.

  2. With the exception of the windowing (AWT) classes, which are still
     under development, the package is functionally complete or superior
     to the Sun 1b1 level (but see restrictions, below).

     The package includes the Java interpreter, compiler, debugger, and
     other tools, and the network, windowing, applet, agent, and audio
     classes.

     Audio supports AudioStreams to either 8-bit or 16-bit sound cards,
     at either 8000 or 11025 samples per second.

  3. The entire package should be considered 'untested'.

  4. This package is for evaluation and testing; we are not formally
     supporting it, yet, though we would like to hear of any problems
     that seem OS/2-related.

  5. All the binaries come in two forms.  Those with suffix '_g' on the
     name are compiled and linked with debugging information. DLL names
     must match the .EXE names in use (that is, JAVA_G.EXE links to
     JAVA_G.DLL and NET_G.DLL but would not link to NET.DLL).

  6. Although LIB and INCLUDE files are provided for building native
     classes, it is likely that there is insufficient information
     available to do this (and some headers may be missing) -- see Sun
     documentation and mailing lists.  We have noticed some errors in
     the Sun documentation in this area.

  7. If you see problems, try running the interpreter with the -diag
     (for OS/2-specific), -verbose, and -verbosegc options. The
     diagnostic information produced may be helpful.

  8. We've added some new environment variable settings that let you
     adjust some Java defaults (note that if you issue these commands
     from an OS/2 command prompt, you must not have any spaces before
     the '='):

     SET JAVA_CONNECT_TIMEOUT=n

      o adjusts the time that Java will wait for a network connection
        before it reports a timeout.  'n' is in seconds, from 1 through
        a million (default=30).

     SET JAVA_AUDIO_VOLUME=v

      o adjusts audio volume from Java as a percentage of the maximum.
        'v' may take the values 0 through 100 (default=50).

     SET JAVA_AUDIO_RATE=n

      o sets the preferred playback sample rate for audio.  Use a value
        of 8 for 8000 samples per second, or 11 for 11025 samples per
        second.  Java for OS/2 will normally try 8000 first (to match the
        incoming data stream) and then 11025; some drivers (notably some
        Thinkpad 701C early drivers prior to October 1995) appear to
        support 8000 but then fail: they can be made to work by forcing
        the rate to 11.


Known restrictions and problems
-------------------------------

  1. OS/2 machine-dependent layer:

      o Not all floating point operations are handled correctly yet.

      o Garbage collection will fail if an I/O operation (for example,
        disk I/O, but not TCP/IP, AWT, or audio I/O) prevents a thread
        from suspending for more than 5 seconds.  A message 'thread X
        failed to suspend' may be followed by unpredictable behaviour.
        This will only be seen if garbage collection is attempted.

        An alternative Garbage collection environment is being
        investigated.

  2. Windowing classes (AWT):

      o All functions except for image are complete.

  3. Audio (MMEDIA) native class:

      o Audio support requires Warp (the device will not open under 2.x).
        This is a permanent restriction.  Audio sharing may be unreliable
        with some older sound cards and drivers.

      o Java audio is streaming .. that is, it can be played as it arrives
        across a network.  Performance, bandwidth, or latency problems may
        therefore cause breakup and affect sound quality.

  4. Sun code:

      o Sun have documented a number of problems in the shared code;
        these will still be present.  We have not attempted to debug or
        upgrade the 'shared' code except where essential to build the
        package.

      o Audio support is internally monaural 8-bit U-law only.  There is
        no recording capability at present.

  5. JDB (debugger) does not work reliably at the moment.

  6. Temporarily only one instance of Java may be run at a time.

  7. Colour rendition is currently minimal.


IBM Java mailing lists
----------------------

IBM would like to hear about all problems and learn form your experiences with
this beta. Mailing lists have been set up to discuss Java for OS/2 and more
general Java issues.

In order to download this package you were required to register with IBM's
java beta development programme. This means that you have been automatically
subscribed to the following mailing lists:

     ibm-java@hursley.ibm.com

        General information and discussion relating to the IBM versions of Java

     ibm-java-announce@hursley.ibm.com

        Announcements & latest news from IBM's Java team

     ibm-java-os2@hursley.ibm.com

        Technical discussions relating specifically to the OS/2 version of the
        IBM Java distribution

--------------------------------- End of file ---------------------------------
