RELEASE NOTES

Java Development Kit 1.1.3u for SCO Operating Systems


Contents

License
Introduction
Installation
Documentation
Using JDK 1.1.3u for SCO
Extensions to Sun JDK 1.1.3
The JIT Compiler
Native Methods
Debugging Native Methods
JDBC
Implementation Notes
Known Problems

License

Please read the license.txt file for the license terms of this SCO product.

Introduction

These are the release notes for the JavaTM Development Kit (JDK), Release 1.1.3u for SCO Operating Systems, hereafter referred to as "SCO JDK 1.1.3u".

SCO JDK 1.1.3u is a full update release to the earlier SCO JDK 1.1.3. The changes in it include:

This product is a full implementation of Sun Microsystems' Java Development Kit 1.1.3. It enables SCO OEMs, ISVs, and end users to develop and run applets and applications that conform to the Java 1.1 Core API.

Note that this release incorporates SunSoft's JDK 1.1.3A and 1.1.3D and subsequent fixes and enhancements to JavaSoft's JDK 1.1.3; this is done to support the Java WorkShop and Java Studio products found in the UnixWare/OpenServer Development Kit (UDK), as well as the JIT compiler.

This JDK product is being released on the most recent versions of all three SCO operating system platforms: UnixWare 7, OpenServer 5.0.4, and UnixWare 2.1.2.

This product is not supported on previous versions of these operating systems, such as OpenServer 5.0.2 or UnixWare 2.1.1.

For the most part the JDK is identical for all three platforms, and everything in these release notes applies to all three platforms unless otherwise noted.

SCO JDK 1.1.3u is distributed in the following packages:

Package jdk113 includes the essential execution engine of Java, that is, what you need to run Java applications:

Package jdk113 also includes some Java development tools:

Finally, package jdk113 also includes additional components to support distributed applications and database access:

Package jdk113pls includes:

Package jdk113jit includes:

In addition to Sun's documentation in the jdk113pls package, SCO JDK 1.1.3u provides UnixWare7 users with documentation integrated with SCOhelp in these packages:

Installation

The SCO JDK 1.1.3u binary distribution is built on and for UnixWare 7, but is able to run on OpenServer 5.0.4 by virtue of the UDK Compatibility Module for OpenServer, and likewise on UnixWare 2.1.2 by virtue of the UDK Compatibility Module for UnixWare. Because of this, there are a few differences in how the JDK is installed on each platform.

OpenServer 5.0.4

Begin by removing any existing Java packages in this order:
# pkgrm js10 # pkgrm jws20 # pkgrm jdk113pls # pkgrm jdk113 # pkgrm [any other existing Java packages]

If the UDK Compatibility Module for OpenServer (package name OSRcompat) is not already installed on your system, you need to mount the UDK CD-ROM and install the package OSRcompat:

# mount -r /dev/cd0 /mnt # pkgadd -d /mnt OSRcompat

When that installation is complete, install the core JDK (package name jdk113):

# pkgadd -d /mnt jdk113

Then you can install the JDK "Plus" (package name jdk113pls):

# pkgadd -d /mnt jdk113pls

NOTE:

Do not install the Just-In-Time (JIT) Compiler package (jdk113jit) included in this release on OpenServer systems.


UnixWare 2.1.2

If the UDK Compatibility Module for UnixWare (package name UW2compat) is not already installed on your system, you need to mount the UDK CD-ROM and install the package UW2compat:

# mount -F cdfs -r /dev/cdrom/* /mnt # pkgadd -d /mnt UW2compat

If your machine has more than one CD-ROM drive, specify the CD-ROM device exactly (e.g. /dev/cdrom/c0b0t6l0).

When that installation is complete, install the core JDK 113 (package name jdk113):

# pkgadd -d /mnt jdk113

Then you can install the JDK 113 Plus (package name jdk113pls):

# pkgadd -d /mnt jdk113pls

The JIT package can be installed as:

# pkgadd -d /mnt jdk113jit

Alternatively, the graphical desktop tool App_Installer may be used to install these packages.

Note that you may need to increase certain system memory limits; see Using JDK 1.1.3u for SCO below.

UnixWare 7

The jdk113 package is installed automatically during Initial System Load (ISL) of the UnixWare 7 Base OS. (The jdk113 package is part of the BaseWeb set, which is on the Base OS CD.) However, if you de-selected the jdk113 during ISL, you must install it from the UnixWare 7 CD before installing the JDK packages included in this release. To do so, mount the UnixWare 7 CD-ROM and install the JDK (package name jdk113):
# mount -F cdfs -r /dev/cdrom/* /mnt # pkgadd -d /mnt jdk113
If your machine has more than one CD-ROM drive, specify the CD-ROM device exactly (e.g. /dev/cdrom/c0b0t6l0).

When the jdk113 package is installed, or if it was already installed as part of the BaseWeb set, mount the UDK CD-ROM and use the pkgadd command to update the installed package to the current version:

# mount -F cdfs -r /dev/cdrom/* /mnt # pkgadd -d /mnt jdk113

Then add the Java packages from the UDK set:

# pkgadd -d /mnt udk

When prompted, add the Java components in this order:

jdk113pls jdk113jit jdkdoc jdkman

We recommend that you only add packages from the UDK set (using pkgadd udk) rather than adding individual packages (for example, pkgadd jdk113jit). Doing so will make it easier to manage later release updates.


NOTE:

You must license Java Studio or Workshop to run the JIT Compiler.


Documentation

Documentation for the JDK 1.1.3u is contained in the jdk113pls package and, for UnixWare 7 only, also in the jdkdoc and jdkman packages. All of the documentation is in HTML format and may be viewed with any browser you have installed on your system.

DocumentFile/Link Name
these release notesReleaseNotes.html
JavaSoft documentation for JDK 1.1.3 (same as for 1.1.4)docs/index.html
JavaSoft demos for JDK 1.1.3demo/
documentation on SCO's JDBC implementation
and SCO's SQL-Retriever product
see JDBC section

Note that the documentation included in the jdk113pls package is not integrated into OpenServer SCOhelp or UnixWare 2 Dynatext Library graphical help systems. However, the documentation included in the jdkdoc and jdkman packages is integrated with SCOhelp on the UnixWare 7 platform.

Also note that much of this documentation is from JavaSoft, but should be read in an SCO context. For instance, for "Solaris" read any of the three SCO platforms (UnixWare 7, OpenServer 5.0.4, UnixWare 2.1.2). For customer support, any of the normal SCO support mechanisms should be used, rather than contacting Sun.

Using JDK 1.1.3u for SCO

In general, use of SCO JDK 1.1.3u follows that which is described in the JavaSoft documentation.

After the JDK packages are installed, you probably want to set PATH in your .profile to include the directory where the JDK commands are installed, /usr/java/bin. On UnixWare 7 systems, this will usually have been done for you already when your account was created.

On UnixWare 2.1.2, applications of significant size are likely to get "out of memory" errors with the default memory limits provided by the operating system. To fix this, do the following as root:

# /etc/conf/bin/idtune -m HVMMLIM 0x7FFFFFFF
# /etc/conf/bin/idtune -m HDATLIM 0x7FFFFFFF
# /etc/conf/bin/idtune -m SVMMLIM 0x7FFFFFFF
# /etc/conf/bin/idtune -m SDATLIM 0x7FFFFFFF
# /etc/conf/bin/idbuild
and then reboot to rebuild the kernel.

On all three platforms, you need to give an xhost command for your machine if you are using appletviewer (see Known Problems below).

Extensions to Sun JDK 1.1.3

SCO has provided only one functional extension to Sun's JDK 1.1.3, and it is useful only on the UnixWare 7 platform.

Java Classes as First-Class Executables

When javac is used to compile one or more classes, it will set the execute permissions bit on for the .class file if the class contains a main method. (This happens on all three platforms.)

Then, on UnixWare 7 only, you can execute a Java application simply by giving the name of the main class:

$ foo.class
UnixWare 7 will look for foo.class by use of the PATH environment variable, just as it would for any other executable. foo.class must also be in the CLASSPATH, as in normal execution.

Furthermore, by making a hard link or symbolic link such as

$ ln -s foo.class foo
you will be able to execute the application simply by saying
$ foo
For instance, this gives you the ability let users invoke utilities without knowing the utilities are written in Java. For this to work you must keep the name prefix intact and the class file intact. That is, you have to keep foo.class somewhere, and then you can make a hard or soft link of foo to it. foo can be in another directory, but you can't change the name; i.e., you can't link bar to it. That's because once the system invokes the JVM, it expects to find a foo.class file there. For this same reason you also can't just rename foo.class to foo, because the JVM will still need a foo.class. (You could copy foo.class to foo, but that will of course waste disk space compared to a link.)

Of course, you can always use the traditional way of executing a Java application:

$ java foo
In this case, java must be in the PATH, and foo.class must be in the CLASSPATH.

The JIT Compiler

The Just-in-time (JIT) Compiler is new with SCO JDK 1.1.3u. It is installed as part of package jdk113jit. However it can only be run if the Java WorkShop or Java Studio product is licensed. If the JIT is installed but does not detect a WorkShop or Studio license, a warning will be issued and the JVM will proceed with interpreted execution without the JIT.

Currently the JIT compiler is only supported on UnixWare 7 and UnixWare 2.1.2; it is not available for OpenServer 5.0.4.

A JIT compiler improves Java performance by, as the program is executing (hence the name), compiling Java method bytecode to native x86 machine code. On subsequent executions of the method the machine code is executed instead of the bytecode being re-interpreted. By default, this JIT compiler compiles or inlines every method in the program, the first time the method is invoked (except for a few primordial methods which cannot be compiled until the JIT compiler itself is loaded). Dynamically loaded classes are compiled after they are loaded. Class initializers are not compiled. If for some reason a method cannot be compiled, it is interpreted. Jitted code is not saved across sessions of the JVM.

How much the JIT improves performance depends greatly upon the nature of the application being run. Applications that are compute-intensive benefit the most, while those that are dominated by object creation/garbage collection, graphics, or networking tend to benefit less. The only way to know the benefit for your application is to measure it.

If installed, the JIT compiler runs by default. If you want to suppress running of the JIT (either to do performance analysis or because you suspect it may be causing a problem), you can turn it off in two ways: by setting the JAVA_COMPILER environment variable to the empty value, or by setting the java.compiler property to the empty value. Examples:

$ java hello			# JIT will run

$ JAVA_COMPILER= java hello	# JIT will not run

$ java -Djava.compiler= hello	# JIT will not run

The environment variable JIT_ARGS provides further control over execution of the JIT. You can define JIT_ARGS as a string containing one or more of these options:

traceshow which methods are compiled or inlined
compile(method-list)compile just these methods
exclude(method-list)do not compile just these methods
dump(method-list)dump the generated assembly code

The method-list is a comma-separated list of method names, possibly qualified by class names. The class name part is separated by slashes. If only a class name is given, all methods of that class are selected. If no method-list is given, the option applies to all methods. Examples:

$ JIT_ARGS=trace java hello	# show what the JIT does

$ JIT_ARGS="dump(hello)" java hello	# show how the JIT does it (lots of output!)

$ JIT_ARGS="trace compile(myclass.)" java myclass	# only jit myclass's methods

$ JIT_ARGS="trace exclude(java/lang/System.exit)" java myclass	# jit everything except java.lang.System.exit()

Native Methods

Both the JNI-style native methods added as of JDK 1.1 and the old-style, lower-level native methods from JDK 1.0.2 are supported in this release.

C and C++ native methods must be compiled and linked with the SCO UnixWare/OpenServer Development Kit (UDK). This means that native methods cannot be built with the existing development kit on OpenServer or UnixWare 2.

Some of the reasons for this requirement include:

All of these items are in the UDK but not in the existing development kit on OpenServer 5.0.4 and UnixWare 2.1.2. The UDK can be used either on OpenServer 5.0.4 or UnixWare 2.1.2 itself, or native method dynamic libraries can be built with the UDK on UnixWare 7 Gemini then moved to OpenServer 5.0.4 or UnixWare 2.1.2.

Another important limitation with native methods is upon the kinds of system operations that a native method can do. Because of the current user-space "green threads" implementation of Java threads, the following restrictions are in place:

SCO-specific examples of the commands needed to build old- and new-style native methods with C and C++ are included in the demos part of the JDK 1.1.3u distribution (in the jdk113pls package), under the subdirectories native_c_demo, jni_c_demo, native_c++_demo, and jni_c++_demo. In addition, the directory jni_invoc_demo gives an example for C and C++ of the JNI Invocation API.

Debugging Native Methods

Debugging of Java applications is done with the JDK-provided jdb debugger, as described in the relevant JavaSoft documentation.

Debugging of C or C++ native methods, however, must be done with the UDK debugger. This section describes how to go about this.

One thing you'll notice is that after-the-fact core dumps from the JVM (which might be caused by a native method bug) are pretty useless, because the traceback comes from a JVM signal handler rather than from the real point of failure.

The solution to this is to run the application, i.e., the JVM, from within the debugger. Then when a segmentation violation occurs, for instance, the debugger will stop right there and the stack trace will be from the real point of failure.

In order to run the JVM from within the debugger, you need to invoke the JVM executable directly. First, you should run the java_g version of the JVM, since that contains debugging information. Second, if you look at /usr/java/bin/java_g, you'll see that it's a link to a script called .java_wrapper, that sets up the LD_LIBRARY_PATH and CLASSPATH environment variables before calling the actual JVM executable in /usr/java/bin/x86at/green_threads/java_g.

If you invoke /usr/java/bin/java_g through ksh -x you'll see the values LD_LIBRARY_PATH and CLASSPATH are set to; you can set those manually at the command line (store in a script that you "dot" if you debug frequently), then invoke the debugger:

$ . setup_java	# your script to set LD_LIBRARY_PATH and CLASSPATH
$ debug -ic	# or can use graphical version
debug> create /usr/java/bin/x86at/green_threads/java_g my_app
debug> run
debug>

Another complication sets in when you want to use symbols (to set breakpoints on, for instance) that are outside of the JVM, such as in native methods. The dynamic libraries that contain native methods are loaded by the JVM via the dlopen call, and until this happens, symbols in the native methods won't be visible to the debugger.

The solution to this is to set a breakpoint inside the JVM at the point where the dynamic library has been loaded, but before code in the libraries is called. For SCO JDK 1.1.3u the appropriate breakpoint is linker_md.c@207. Here is an example demonstrating both the problem and the solution:

$ debug -ic
debug> create /usr/java/bin/x86at/green_threads/java_g my_app
debug> stop my_nativemethod_function
Error: No entry "my_nativemethod_function" exists

debug> stop linker_md.c@207
EVENT [1] assigned
debug> run
STOP EVENT TRIGGERED: linker_md.c@207  in p1 [sysAddDLSegment in ../../../../src/unixware/java/runtime/linker_md.c]
207:        dlsegment[useddlsegments].fname = strdup(fn);
debug> stop my_nativemethod_function
EVENT [2] assigned
debug> run
STOP EVENT TRIGGERED: my_nativemethod_function in p1 [my_nativemethod_function in myfile.C]
68:         bool finished = false;
debug>
You can debug normally from that point on.

If you do a lot of this kind of debugging it can be useful to set up an alias in your ~/.debugrc file:

alias cnm create /usr/java/bin/x86at/green_threads/java_g ; run -u linker_md.c@207
Then just giving the cnm command to the debugger will bring you to the point where you can set breakpoints in your native method code.

JDBC

Java Database Connectivity is a standard SQL database access interface for Java, providing uniform access for Java applications to a wide range of relational databases.

SCO JDK 1.1.3 contains SCO's implementation of JDBC and includes the SCO JDBC driver. SCO's JDBC implementation is built upon SCO's SQL-Retriever product. For more information on SCO SQL-Retriever, please visit www.vision.sco.com .

There is no need to separately install the SCO JDBC implementation, since it is part of the jdk113 installation. It is necessary to separately install the SQL-Retriever product if you are interested in using JDBC.

Implementation Notes

In general one of the important characteristics of Java is that it behaves in exactly the same fashion on all platforms. However there are a few areas where it may be useful to know how the JDK has been implemented on SCO platforms.

System Properties

If it is necessary for application code to determine which of the three SCO platforms it is running on, the Java class System.Properties can be queried. Here are some of the values that will be returned on all SCO platforms:
java.home=/usr/java
java.vendor=SCO
java.vendor.url=http://www.sco.com/
java.class.version=45.3

while here are values that are specific to OpenServer 5.0.4:

os.arch=IA32
os.name=OpenServer
os.version=5.0.4

UnixWare 2.1.2:

os.arch=IA32
os.name=UnixWare
os.version=2.1.2

and UnixWare 7:

os.arch=IA32
os.name=UnixWare
os.version=7

Abstract Windowing Toolkit

This implementation uses the X Windows System, version X11R6.1, to implement the Java Abstract Windowing Toolkit.

Threads

As noted previously, this implementation uses Sun's "green threads" implementation of Java threads rather than "native threads" implementation. This means the Java VM controls the scheduling and context switching of Java threads. In a native threads implementation, Java threads would be mapped onto an operating system library and the scheduling and context switching would be done by the operating system.

Performance

This implementation uses an assembly-coded main interpreter loop for faster bytecode execution (however, the debug version java_g uses a C language interpreter), and a just-in-time compiler to further improve performance.

Conformance

This release of SCO JDK 1.1.3u has passed Sun's Java Compatibility Kit (JCK) 1.1.2a test suite.

Known Problems

This section contains known problems or limitations with SCO's port of JDK 1.1.3 to SCO platforms. For known problems with Sun's JDK 1.1.x releases themselves, see the list at JavaSoft's website.

  1. On all three platforms, the X11R6 implementation is currently built to only use TCP/IP as a connection mechanism. This means that even when working locally, you need to issue an xhost +your_machine_name command.

  2. On OpenServer 5.0.4 and UnixWare 2.1.2 when appletviewer or a java AWT application is invoked you may see the following messages
    current locale is not supported in X11, locale is set to C
    X locale modifiers are not supported, using default
    
    This indicates that you are in a locale other than the default C locale. The problem is that the UDK compatibility modules are lacking necessary X locale support. The JDK will continue to operate after this warning is given, but with the locale set to the C locale.

  3. Large file support (for files > 2GB in size) is not yet present in the java.io package, or anywhere else in the JDK.

See also the restrictions and limitations on native methods.


Copyright 1998 The Santa Cruz Operation, Inc. All Rights Reserved.