RELEASE NOTES - Java(TM) 2, Standard Edition, v. 1.3.0_02 for Caldera(R) UNIX(R) Operating Systems

Release Notes

JavaTM 2, Standard Edition, v. 1.3.0_02
for Caldera® UNIX® Operating Systems


CONTENTS

GENERAL INFORMATION

License

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

Introduction

These are the release notes for the JavaTM 2 Standard Edition (J2SE), version 1.3.0_02 for Caldera® UNIX® Operating Systems.

The Java 2 Standard Edition contains both the Java 2 Runtime Environment, which allows Caldera UNIX end users to run Java applets and applications on Caldera UNIX operating systems, and the Java 2 Software Development Kit (J2SDK), which enables Caldera UNIX OEMs, ISVs, and end users to develop Java applets and applications that conform to the Java 2 Core API.

This product is hereafter referred to as either "J2SE 1.3 for Caldera UNIX" or "J2SDK 1.3 for Caldera UNIX", depending upon which context the reference occurs in.

J2SE 1.3 for Caldera UNIX is a full implementation of the Sun MicrosystemsTM Java 2 Platform - the technology and environment described in the SunTM specifications of the Java 2 Platform, Standard Edition, v. 1.3.0_02. (The _02 suffix indicates the patch level of the Sun J2SE that J2SE 1.3 for Caldera UNIX corresponds to.)

This product was previously known as the Java 2 Standard Edition for SCO Operating Systems. In May 2001, the operating systems business of SCO, Inc., was acquired by and made part of Caldera International, Inc.

These Release Notes refer to this product as being for "Caldera UNIX Operating Systems" to distinguish the operating systems supported by this Java implementation from the existing Caldera OpenLinux® operating system. There is a separate Java 2 Standard Edition implementation available for Caldera OpenLinux.

System Requirements and Supported Platforms

Software:
Supported Caldera UNIX platforms:
  • Open UNIX® 8 Release 8.0.0 operating system
    • requires package urwfonts [*]

  • UnixWare® 7 Release 7.1.1 operating system
    • requires package urwfonts or freefonts [*]
    • requires package set udkrtfs [**],
      OR packages libc, libC, and libm versions 8.0.0 or higher from the Open UNIX Development Kit
    • requires the latest libthread supplement (ptf7410h or higher)[***],
      OR package libthread version 8.0.0 or higher from the Open UNIX Development Kit
    • requires the latest libsocket supplement [***]
    • requires the latest libnsl supplement [***] if and only if NIS is enabled

  • SCO OpenServerTM Release 5.0.6 operating system
    • requires package urwfonts or freefonts [*]
    • requires package OSRcompat version 7.1.1b [**]
    • requires OSS643A for socket driver supplement [***]
    • Release Supplement 5.0.6A may be installed but is not required

  • SCO OpenServer Release 5.0.7 operating system
    • requires package urwfonts or freefonts [*]
    • requires package OSRcompat version 7.1.1b [**]
RAM: 64 MB
Disk Space: Minimum 40 MB

J2SE 1.3 for Caldera UNIX is NOT available for the SCO UnixWare® 2 operating system.

J2SE 1.3 for Caldera UNIX is not supported on older versions of the supported operating systems, such as SCO OpenServer Release 5.0.5 or UnixWare 7 Release 7.1.0.

J2SE 1.3 for Caldera UNIX cannot be used with the older OSRcompat packages that were released together with UnixWare 7 Release 7.0, UnixWare 7 Release 7.1.0, or UnixWare 7 Release 7.1.1.

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

[*] Package urwfonts is available as part of the Open UNIX 8 media kit and is automatically installed as part of Initial System Load. Package freefonts is available as part of "Caldera Open Source Software with Skunkware", formerly known as the SCO Open License Software Supplement or as SCO SkunkwareTM. It is available for free download from http://www.caldera.com/skunkware/ or on Skunkware CD-ROMs in the media kits for SCO OpenServer 5 or UnixWare 7, or in the Caldera Open Source Software with Skunkware OU8 CD-ROM in the media kit for Open UNIX 8. Package urwfonts is the (URW)++ subset of package freefonts.

[**] Package set udkrtfs, is available for free download from http://www.caldera.com/download/. Click on "UNIX", then choose "UnixWare and OpenServer Development Kit Feature Supplement 7.1.1b", then look for the downloadable file udkrtfs.image.Z. This set also includes package OSRcompat version 7.1.1b. (Which packages the set installs will depend upon which operating system you are on.)

[***] These are Support Level Supplements (SLS) that are provided to Caldera UNIX customers to fix problems reported in our products. These are available for free download via anonymous ftp from ftp://ftp.caldera.com/pub/openunix8, ftp://ftp.caldera.com/pub/unixware7, and ftp://ftp.caldera.com/pub/openserver5.

Individual supplements (also known as "ptfs") are routinely bundled into larger Maintenance Supplements. These ptfs are then considered obsolete (or superseded) and removed from the download site. Any superseded ptfs that have been replaced by a maintenance supplement, will be listed and described in the maintenance supplement documentation. Be sure to check the Caldera Support page at http://www.caldera.com/support/ftplists for the latest listings of all supplements that are available for each of Caldera's products.

However, an issue arises if UnixWare 7 NonStop® Clusters Release 7.1.1+IP (NSC 7.1.1+IP) is installed. This has the same requirements as are listed for UnixWare 7 Release 7.1.1. Installing the urwfonts or freefonts and udkrtfs packages on an NSC 7.1.1+IP system is not a problem. However you cannot generally install UnixWare 7 Release 7.1.1 ptfs on an NSC 7.1.1+IP system. Instead, package nsc1011x is installed, which bundles a number of UnixWare 7 Release 7.1.1 ptfs together in a form suitable for use on an NSC 7.1.1+IP system.

As of this writing, the current version of this package nsc1011g does not include the ptf7410h and libsocket supplement (previously ptf7631e) levels required by J2SE 1.3 for Caldera UNIX. To compensate for this, the java2sdk3 and java2jre3 packages do not check for the presence of these ptfs. However, libthread, which is the subject of ptf7410h, does not have any NSC 7.1.1+IP dependencies, and so you can update it by hand from a UnixWare 7 Release 7.1.1 system where ptf7410h is installed. But this cannot be done for libsocket, the subject of ptf7631e, because it does have NSC 7.1.1+IP dependencies. The consequence of not having the ptf7631e fix installed is that the jdb debugging tool may not operate properly.

Changes in This Release

J2SE 1.3 for Caldera UNIX includes improvements in performance, functionality, and reliability over the previous Java releases from SCO, Java 2 Software Development Kit, Standard Edition, version 1.2.2-001 and Java Development KitTM 1.1.8.

For a complete list of new Sun features in Java 2 Standard Edition version 1.3, visit http://java.sun.com/j2se/1.3/docs/relnotes/features.html. (Potential compatibility problems between this release and J2SDK 1.2.2 and earlier Java releases are described at http://java.sun.com/j2se/1.3/compatibility.html.)

The following changes specific to the Caldera UNIX implementation have been made, relative to JDK 1.1.8 for SCO (the most recent Java for SCO release prior to this one):

Relative to J2SDK 1.2.2 for SCO, these additional changes have been made:

Finally, this release contains fixes for a number of SCO-specific problems found in prior releases.

Note that there was an earlier release of J2SE 1.3.0_02 for Caldera UNIX before this one. It was documented as a final release for Open UNIX 8 and UnixWare 7, but as only a beta release for SCO OpenServer 5. Its build version string, as shown by the java -version command, was *FCS-OU8*FCS-UW7*BETA-OSR5*:010602-10:46. This newer release is a final release for SCO OpenServer 5, and also contains fixes for Caldera-specific problems on Open UNIX 8 and UnixWare 7 discovered since the earlier release went out. This newer release has a build version string of *fixes-OU8*fixes-UW7*FCS-OSR5*:<later-date-and-time>.

PACKAGES

Package Name
Approx. Size
Contains
   
    java2sdk3
36 MB Runtime Support:
java, the Java virtual machine (JVM); the JIT compiler; appletviewer, the Java Applet Viewer; Java Foundation Classes (JFC) & Swing Package; and basic API libraries: language support, I/O, AWT, networking, utilities, images, media, math, compression, and security.

Development Tools:
javac, the Java Compiler; jdb, the command-line Java debugger; javah, the C Header and Stub File Generator for native methods; javap, the Java Class File Disassembler; javadoc, the JAVA API Documentation Generator; and jar, the Java Archive (JAR) tool.

Distributed applications and database access:
Remote Method Invocation (RMI); JavaBeansTM (component object model); JDBCTM (database access); Internationalization tools; Security tools; Java IDL tools.

    java2pls3
39 MB Java 2 demo applets and applications; Demos of Swing set functionality; native method demos; Debuggable versions (_g-suffixed) of many of the commands and libraries.
    java2jre3
25 MB Java Runtime Environment (see following section)

The JRE Package

Not included with the Java 2 for Caldera UNIX distribution material, but available separately by download from http://www.caldera.com/download/, is the JavaTM 2 Runtime Environment, v. 1.3.0_02, for Caldera UNIX Operating Systems, also known as the JRE 1.3 for Caldera UNIX, in package java2jre3.

This package matches the Sun product configuration of the Java Runtime Environment (JRE). The JRE 1.3 for Caldera UNIX is the minimum standard Java platform for running Java programs. It contains the Java virtual machine, JIT compiler, Java core classes and supporting files, and Java application launcher. The JRE does not contain any of the development tools (such as appletviewer or javac) or classes that pertain only to a development environment. For such tools, use the J2SDK 1.3 for Caldera UNIX.

One particular purpose of the JRE package is so that licensed independent software vendors (ISVs) can bundle it with their Java application, if desired. That way, the application and the Java version it has been tested on can be installed together on customer machines, rather than relying on whatever Java version is currently installed on those machines.

The java2jre3 package is by default installed in /usr/jre2/, with that actually being a symbolic link to /opt/jre2-1.3/. Unlike the java2sdk3 and java2pls3 packages, however, it is possible for an ISV or system administrator to change where the JRE is installed.

ISVs wanting to do this would change the value of BASEDIR in the pkginfo file and then repackage the java2jre3 package. The JRE would then install into BASEDIR/opt/jre2-1.3/. System administrators wanting to do this would change the value of basedir in the /var/sadm/install/admin/default file, and then the JRE would install into basedir/opt/jre2-1.3/. Or, they could copy /var/sadm/install/admin/default somewhere else, modify the value of basedir there, and then tell pkgadd to use that alternate file with the -a option. Finally, if basedir=ask is set in that file, then the pkgadd command will prompt the installer for the desired package base directory.

INSTALLATION

SCO OpenServer Release 5

First you must obtain and install any necessary prerequisite packages, as explained in System Requirements and Supported Platforms.

When those installations are complete, install the core Java 2 SDK (package name java2sdk3):

# pkgadd -d /mnt  java2sdk3

Then you can install the Java 2 SDK additional materials, if desired (package name java2pls3):

# pkgadd -d /mnt  java2pls3

UnixWare 7 Release 7.1.1

First you must obtain and install any necessary prerequisite packages, as explained in System Requirements and Supported Platforms.

When those installations are complete, install the core Java 2 SDK (package name java2sdk3):

# pkgadd -d /mnt  java2sdk3

Then you can install the Java 2 SDK additional materials, if desired (package name java2pls3):

# pkgadd -d /mnt  java2pls3

Open UNIX 8 Release 8.0.0

The java2sdk3 package is installed automatically during Initial System Load (ISL) of the Open UNIX 8 Release 8.0.0 Base OS. (The java2sdk3 package is on one of the Base OS CDs). The prerequisite urwfonts package is also installed automatically during this time.

However, if you de-selected the java2sdk3 during ISL, you can install it from the Open UNIX Development Kit CD in the following way:

Mount the CD-ROM and install the Java 2 SDK (package name java2sdk3):

# mount -F cdfs -r /dev/cdrom/* /mnt
# pkgadd -d /mnt  urwfonts
# pkgadd -d /mnt  java2sdk3
If your machine has more than one CD-ROM drive, specify the CD-ROM device exactly (e.g. /dev/cdrom/c0b0t6l0).

Similarly for the other package:

# pkgadd -d /mnt  java2pls3

Installation Location and Multiple Java Versions

While the J2SE is accessed through the /usr/java2 pathname, installation actually places its contents into /opt/java2-1.3/. Then a symbolic link is made from /usr/java2 to /opt/java2-1.3/.

You can have multiple versions of Java installed on your system at the same time. Installation of J2SE 1.3 will not automatically remove any previous versions of Java from your system.

If you already have J2SDK 1.2.2 for SCO on your system, all that installation of J2SE 1.3 will do is change the /usr/java2 symbolic link from /opt/java2-1.2.2 (the actual installation point of J2SDK 1.2.2) to /opt/java2-1.3/. You may still access J2SDK 1.2.2 directly by naming its actual installation point. For example, the command /opt/java2-1.2.2/bin/java will start up the J2SDK 1.2.2 virtual machine.

If you do not already have JDKTM 1.1.8 for SCO, or an earlier version of JDK 1.1.x for SCO, on your system, then installation of J2SE 1.3 for Caldera UNIX will also create /usr/java as a symbolic link to /opt/java2-1.3/ in addition to /usr/java2. Thus, you can access the J2SE 1.3 for Caldera UNIX virtual machine by either /usr/java/bin/java or /usr/java2/bin/java, and similarly for other Java commands.

Being able to use /usr/java has several advantages: It is the place where Java is accessed on many other systems, including on Caldera OpenLinux, and thus is often the place third-party scripts will look for Java. It is the place where Java first-class executable support on Open UNIX 8 will look for Java. And it is the place that is by default added to your PATH environment variable when login accounts are created on UnixWare 7 or Open UNIX 8.

However, if you do already have a JDK 1.1.8 or earlier 1.1.x for SCO version installed on your system, then you may not want the /usr/java symbolic link changed to point to J2SE 1.3 for Caldera UNIX. For example, you may have applications that do not run correctly under Java 2, whose scripts are expecting Java 1.1.x to be in /usr/java. In this case, the install will notify you of the potential conflict, and give you a choice of whether you want /usr/java to be changed to point to J2SE 1.3 for Caldera UNIX or whether you want it left alone.

The only exception to this is if you are upgrading your system from UnixWare 7 Release 7.1.1 to Open UNIX 8 Release 8.0.0; the update is non-interactive and thus will always change the symbolic link. You can manually restore the symbolic link afterwards if you so desire.

Note however that even if /usr/java is changed, the actual installation point of /opt/jdk-1.1.x of any JDK 1.1.x for SCO will be unchanged, and you can access its commands by using a full pathname. For example /opt/jdk-1.1.8/bin/java will start up the JDK 1.1.8 for SCO virtual machine.

Similar considerations apply to the JRE 1.3 for Caldera UNIX and previous JRE versions.

DOCUMENTATION

Unlike with previous Java releases for SCO platforms, this J2SE 1.3 for Caldera UNIX release contains no bundled Java documentation beyond these Release Notes.

Instead, you may browse Sun's complete documentation for Java 2 SDK, Standard Edition Version 1.3 at http://java.sun.com/j2se/1.3/docs/index.html. This contains the very latest and most accurate documentation for J2SE 1.3.

The Japanese version of the documentation may be found at http://java.sun.com/j2se/1.3/ja/docs/ja/index.html.

Both the English and Japanese versions of the documentation may be downloaded as a large HTML bundle at http://java.sun.com/j2se/1.3/docs.html.

Where the documentation differs depending upon the underlying operating system (such as with the SDK tool documentation), follow the "SolarisTM" version (not the "LinuxTM" or "Win32" versions).

Note that there are also useful Sun and Caldera UNIX demonstration uses of J2SE 1.3 and J2SDK 1.3 at /usr/java2/demo/ when the java2pls3 package has been installed.

DEVELOPER NOTES

Using Java 2 SE for Caldera UNIX

In general, use of the Java 2 SE for Caldera UNIX follows that which is described in the Sun documentation.

After the Java 2 SE packages are installed, we recommend that you set PATH in your .profile startup file (or whatever startup file is used in your shell) to include the directory where the Java 2 commands are installed, /usr/java2/bin or /usr/java/bin (if J2SE 1.3 for Caldera UNIX has been installed there as well). In the later case, modifying your startup file may not be necessary, as UnixWare 7 and Open UNIX 8 login accounts are usually created with /usr/java/bin as part of the PATH.

Java Classes as First-Class Executables

Caldera has provided a functional extension to the Sun Java 2 SE for use on the Open UNIX 8 platform: Java classes as first-class executables. This extension does not affect the Java 2 APIs; it just affects how Java can be invoked.

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 Caldera UNIX platforms.)

Then, on Open UNIX 8 only, you can execute a Java application simply by giving the name of the main class:

$ foo.class
Open UNIX 8 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.

(This extension also exists on the UnixWare 7 platform, but it will attempt to invoke JDK 1.1.x for SCO, not J2SE 1.3 for Caldera UNIX. As a work-around, if you copy the file /usr/bin/javaexec from an Open UNIX 8 system to a UnixWare 7 system, then J2SE 1.3 for Caldera UNIX will be invoked.)

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
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

A just-in-time (JIT) compiler improves Java performance by, as the program is executing (hence the name), compiling Java method bytecode to native Intel® IA-32 machine code. On subsequent executions of the method the machine code is executed instead of the bytecode being re-interpreted. Thus, a JIT compiler is a run-time component, not a development component (as conventional language compilers are).

A JIT compiler is part of the base J2SE 1.3 for Caldera UNIX product and package java2sdk3 (or java2jre3 if the JRE package is being used). It is a transparent component: it is always there and is always executing unless it is explicitly turned off by the user. It does not have to be separately licensed or installed.

You do not have read or use any of the information in the rest of this section in order to gain the benefit of the JIT; the information is here only for those wanting a better understanding of what the JIT does, or for those wanting to exercise further control over the JIT.

The JIT compiler in J2SE 1.3 for Caldera UNIX is named sunwjit and is based upon the JIT compiler of the same name from Sun, but it has been significantly enhanced by Caldera.

The JIT compiler in J2SE 1.3 for Caldera UNIX has the ability to compile or inline 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), although it may choose to defer compilation for a given method. Methods of dynamically loaded classes may be compiled after the class is loaded. Class initializers are never compiled. If for some reason a method cannot be compiled (such as an internal error in the JIT, or invalid bytecode contents), 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.

Controlling the JIT

The JIT compiler runs by default. It can be explicitly requested via its sunwjit name, but this is not necessary.

Normally there is no reason to suppress running of the JIT, but you might want to do it in the following situations:

You can turn off the JIT 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=sunwjit java hello	# JIT will run
$ java -Djava.compiler=sunwjit 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 space-separated 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 for these methods
bco=on|offalways run/don't run the bytecode optimizer part of the JIT

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()
In particular, JIT_ARGS=trace is useful in verifying that the JIT is installed correctly and is actually executing.

The bytecode optimizer is a particular part of the JIT, which by default only runs when a method is being jitted during the first time it is called (for internal reasons this optimizer is usually ineffective when used for a method for which compilation has been deferred). The bco= option may be used to force the bytecode optimizer to either always or never run when a method is compiled, which may be useful for pinpointing the source of performance problems or other JIT problems.

JIT Heuristics for Selective Compilation

All JIT compilers come with a trade-off: the cost of the time it takes to pause execution of a method and do the compilation to machine code (once per method per program) versus the benefit of the time saved by subsequent invocations of that method running as machine code rather than being interpreted. For example, for a short method that is only called once, this trade-off is obviously a loss, while for a long method called many times, this trade-off is clearly a win.

By default, the JIT compiler in J2SE 1.3 for Caldera UNIX attempts to maximize this trade-off for each individual method, by using two heuristics. One is the size of the method in bytecodes: it is assumed that shorter methods take less time to compile and less time to execute (although measurements have shown that the correlation is rather weak for the latter, especially for smaller-sized methods). The other is the number of times the method has already executed during the program's run: it is posited that those methods that have already been called a lot, will be the ones that will tend to be called a lot for the rest of the program's lifetime.

(This is a Caldera enhancement; in the base Sun version of sunwjit, methods are always compiled the first time they are called.)

Two environment variables are used to control these heuristics: JIT_MIN_TIMES and JIT_MIN_SIZE, both of which can be set to non-negative integer values. JIT_MIN_TIMES=n tells the JIT to compile a method after it has been executed n many times, no matter what the size of the method. JIT_MIN_SIZE=m tells the JIT to compile a method that is greater than or equal to m bytes in bytecode size, no matter how many times it has been executed.

The default values used by the JIT are JIT_MIN_TIMES=40 and JIT_MIN_SIZE=150; you do not need to set these environment variables unless you want to change these values for your application.

In between the points given by these limits, the JIT interpolates the heuristic; so, for example, a method of 75 bytes in size might be compiled once it has executed 30 times.

Example of the use of these environment variables might be:

$ JIT_MIN_TIMES=0 java my_app   # methods will be jitted after 0th time called

$ JIT_MIN_TIMES=100 JIT_MIN_SIZE=500 java my_app   # only jit the really "heavy hitters"

(The first example above reproduces the default behavior in previous releases of Java for SCO platforms, where every method was compiled the first time it was called.)

This heuristics strategy significantly increases the performance of some short- or medium-lived applications, such as the javac Java language translator.

Even for long-lived applications, this strategy often improve the start-up time of the application, especially when Swing or AWT is involved, with no subsequent performance degradation compared to the older strategy of always jitting methods the first time they are seen.

However, for some long-lived applications where the start-up time is not of importance, it might be better to set JIT_MIN_TIMES=0 to compile everything the first time it is called. This also has the benefit of running the bytecode optimizer part of the JIT for every method, which will result in the best generated code being produced. In running long-lived server-oriented benchmarks, however, the default settings have proved best over the life of the program.

In conclusion, the only way to find out for sure whether adjusting any of these JIT-related environment variables will benefit your application is to experiment with it, using different values.

Threads: Green or Native

Threads are an essential part of the Java language and API set, and every Java implementation must decide how to implement Java threads. The J2SE 1.3 for Caldera UNIX, like some other implementations, supports two alternate internal threads models: "green threads" and "native threads". Note that Java application code does not change at all from one model to the other; the threads model is an internal, "under the covers" difference, although one that can have an important impact on the behavior and performance of a Java application.

"Green threads" refers to a model in which the Java virtual machine itself creates, manages, and context switches all Java threads within one operating system process. No operating system threads library is used.

"Native threads" refers to a in which the Java virtual machine creates and manages Java threads using the operating system threads library - named libthread on UnixWare 7 and Open UNIX 8 - and each Java thread is mapped to one threads library thread.

J2SE 1.3 for Caldera UNIX supports both models (except on SCO OpenServer Release 5), and it is up to you to decide which to use for your application. Native threads is the default on UnixWare 7 and Open UNIX 8 (this is a change from previous releases of Java on UnixWare 7, when green threads was the default), while only green threads is available on SCO OpenServer Release 5.

To specify the threads model, set the THREADS_FLAG environment variable to either green or native. For convenience, the java command also has an option, -green or -native, that can be used if it is the first option specified; but for other commands, the environment variable must be used. Some examples:

$ java my_app				# native threads will be used

$ THREADS_FLAG=green java my_app	# green threads will be used

$ THREADS_FLAG=native java my_app	# native threads will be used

$ java -green my_app			# green threads will be used

$ THREADS_FLAG=green appletviewer my_applet.html   # only way to set green threads

Advantages of Green Threads

One reason to use green threads had been that it was the more mature implementation, but by now this is no longer true.

Another reason to use it is that switching the threads model may change the behavior of the Java application. The Java language specification does not give a lot of precise details about how Java threads are scheduled, so there is some room for implementation dependencies in this area (unlike the rest of the Java specification). Java applications that (incorrectly) make assumptions about how threads will be scheduled may work under one threads model but not under the other. Older Java applications were written under green threads (that was the first model available on most platforms, including SCO), and for them the chances are that the native threads model would be more likely to expose incorrect application dependencies. However, in recent years many system vendors have been providing Java implementations that only implement native threads, or that default to native threads, and so newer Java applications are less likely to have these dependencies.

Finally, on a uniprocessor machine, green threads sometimes has performance advantages over native threads, although the difference tends to be relatively minor.

Advantages of Native Threads

There are two major potential advantages to using native threads, in addition to it intuitively being the "right way" to implement Java threads - it uses the threads capability of the underlying operating system.

The first advantage is performance on multiprocessor (MP) machines. In green threads all Java threads execute within one operating system lightweight process (LWP), and thus UnixWare 7 or Open UNIX 8 have no ability to distribute the execution of Java threads among the extra processors in an MP machine. But in the native threads model, each Java thread is mapped to a UnixWare 7 or Open UNIX 8 threads library multiplexed thread, and the threads library will indeed map those threads to different LWPs as they are available.

The performance benefit from using native threads on an MP machine can be dramatic. For example, using an artificial benchmark where Java threads are doing processing independent of each other, there can be a three-fold overall speed improvement on a 4-CPU MP machine.

The second major advantage of native threads is when native methods are being used. In order for the green threads implementation to perform non-blocking I/O, a number of system calls are "wrapped" by the JVM to use green threads synchronization primitives and the like. If native methods make system calls in some way that the green threads JVM doesn't expect, these wrappers often cause severe problems. As a consequence, there are a number of restrictions placed upon native methods in green threads mode, as listed in the section Native Methods below.

In comparison, in native threads mode there is no need for I/O system call wrappers, and there are no restrictions upon what native methods may do, as long as they are coded to be thread-safe and are built with -Kthread.

A final advantage of native threads is that it usually gives a clearer picture of a program's activities when debugging at the native methods level with a debugger.

Controlling Pre-emption in Green Threads

By default, scheduling in green threads mode is not pre-emptive. This means that if one thread has control of the processor and is not giving it up (by doing an I/O operation or making a Thread.yield call), other higher- or equal-priority threads may never get a chance to run.

This behavior can be changed by using Sun's formerly-documented green threads time slicing option -Xtsnn. This will force the JVM green threads scheduler to interrupt threads every nn milliseconds and give control to other threads that eligible to run.

For example, this command:

$ THREADS_FLAG=green java -Xts10 my_app
will force time slicing every 10 milliseconds.

Controlling Concurrency Level in Native Threads

When using multiplexed threads in the UnixWare 7 or Open UNIX 8 threads library, as the Java virtual machine does in native threads mode, the key to how much real concurrency is achieved is how many LWPs are active within the process. J2SE for Caldera UNIX uses the threads library's thr_setconcurrency() interface to guide this, and there are three different schemes for controlling the number of LWPs.

By default, the number of LWPs is set dynamically as the Java application executes. The base level is one LWP for each processor in the machine. Then, additional LWPs are requested as threads are blocked in certain system calls, these being recv accept send waitid read poll, all of which tend to block their threads for a long time within the JVM. The request level is decremented once these calls return. This default behavior is a reasonable heuristic that on the one hand tries to maximize useful concurrency and reduce scheduling stress on the threads library, but on the other hand tries to conserve a dear system resource. For compatibility with some previous Java for SCO releases, this scheme is also used if the THR_INCR_CONC environment variable is set to nothing or to the empty string.

Alternatively, if the THR_INCR_CONC environment variable is set to zero:

$ THR_INCR_CONC=0 java my_app
the number of LWPs created by the JVM is specified to be equal to the number of active processors in the machine. This is the minimum allocation that will take advantage of real parallelism in multiprocessor machines. (This was previously the default in some Java for SCO releases.)

Finally, you can specify your own concurrency level, by setting the THR_INCR_CONC environment variable to a positive integer. An example would be:

$ THR_INCR_CONC=20 java my_app   
In both of these alternatives, the specified number of LWPs will be requested at the beginning of execution, and the requested level will be fixed for the rest of execution; in particular, the level will not vary based on threads blocking in system calls.

Native Methods

Both the JNI-style native methods added as of Sun JDK 1.1 and the old-style, lower-level native methods from Sun JDK 1.0.2 (sometimes known as NMI) are supported in this release. However, it is strongly recommended that you use newer JNI-style native methods, since they are the only ones that will be supported by Sun in the future; the older native method interface is deprecated and has already been eliminated in some Java implementations from Sun.

C and C++ native methods must be compiled and linked with the UnixWare and OpenServer Development Kit (UDK) from Caldera, version 7.1.1 or later (unless the JNI Invocation API is being used, in which case the version 7.1.1b Feature Supplement or later is required), or with the Open UNIX Development Kit (OUDK).

This means that native methods cannot be built with the SCO OpenServer Release 5 Development System.

Some of the reasons for this requirement include:

All of these items are satisfied by the UDK or OUDK. The UDK can be used on SCO OpenServer Release 5 itself, or native method dynamic libraries can be built with the UDK on UnixWare 7 Release 7.1.1 or OUDK on Open UNIX 8 Release 8.0.0 and then moved to SCO OpenServer Release 5.

Another important limitation with native methods is upon the kinds of system operations that a native method can do when "green threads" is being used as the Java threads implementation model (see the Threads: Green or Native section above). Under green threads the following restrictions are in place:

None of these limitations exist with the "native threads" implementation model, so if you are coding native methods and that model is available to you, it is strongly recommended that you use it.

Caldera UNIX-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 J2SDK 1.3 for Caldera UNIX distribution (when java2pls3 package is installed), in the directory /usr/java2/demo/native,under the subdirectories

Some of these subdirectories have further subdirectories. The last directory gives examples for C and C++ of the JNI Invocation API. In all cases execute the mk script to run the example. It is highly recommended that you follow the command invocations given in all these examples, for unless the native code is built correctly, it will not work as intended.

Native methods using GCC

Another compiler system that can be used for building native methods is the GNU GCC compiler, described in general at http://gcc.gnu.org.

If native method or JNI invocation code is written in C, the GNU gcc compiler that generates code for the UDK/OUDK environment may be used.

On Open UNIX 8, this is the GNUgcc package within the open source OSTools product set that Caldera builds and ships as part of the OUDK CD-ROM. This same package may also be installed on UnixWare 7. Alternatively on UnixWare 7, the Skunkware gcc from http://www.caldera.com/skunkware/ may be used. On SCO OpenServer Release 5, the regular gcc for OpenServer cannot be used; instead, you must build the OpenServer-hosted, UDK-targeted gcc described at http://gcc.gnu.org/install/specific.html#ix86-*-udk.

If native method code code is written in C++, the GNU g++ compiler that generates code for the UDK/OUDK environment may be used, with the same guidelines as for C. Note that g++ version 2.95.3 or higher (as is found in package GNUgcc within OSTools) must be used, since the previous g++ version 2.95.2 had several problems building C++ code with the -shared option, which made it very difficult to use for Java native methods.

If JNI invocation code is written in C++, the GNU g++ compiler can only be used if the C++ program is very simple and does not use many C++ language or library features. This is because part of the JDK itself is built with the UDK/OUDK C++ compiler, and in the JNI invocation context, the UDK/OUDK and GNU C++ runtime systems usually cannot coexist together. (This problem does not occur in the native method context because there the C++ runtime usages are isolated to dlopen'd native code libraries that do not have any visibility to each other. This is not the case in JNI invocation where the JVM is visibly linked against the C or C++ main program.)

The /usr/java2/demo/native directories described above may also be used to run native methods examples with the GNU compilers. Pass the option gcc or g++ into the mk scripts.

All three examples in the jni_invoc_demo directory will run under gcc, but only the hello example will run under g++.

Debugging Native Methods and the JVM

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

Debugging of C or C++ native methods, however, must be done with the UDK or OUDK debugger; this section describes how to go about this. This discussion is also applicable to isolating or troubleshooting potential problems within the JVM itself, since the lower layers of the JVM are in effect C native methods.

Core dumps should never occur within Java. If they do, then either there is an application bug in a native method, or there is an internal bug within the JVM, or there is an internal bug within a Caldera UNIX operating system library. Java core dumps tend to be large; you may need to set ulimit -c unlimited to avoid having the core file be truncated (typically to 16 MB) and thus be unreadable by the UDK/OUDK debugger.

Core dumps from the JVM will usually have a few levels of signal handlers on the stack subsequent to the actual point of failure. This is true in both green threads and native threads modes. An example would be:

kauai: debug -c core.22890 /usr/java2/bin/x86at/green_threads/java_g
Core image of java_g (process p1) created
CORE FILE [_kill]
Signal: sigabrt
        0xbffa45b3 (_kill+12:)           jb       +0x5ce  [ _cerror ]
debug> stack
Stack Trace for p1, Program java_g
*[0] _kill(0x596a, 0x6) [0xbffa45b3]
 [1] abort(presumed: 0xbff69ea0, 0x8046d74, 0x8046d74)  [0xbffd835a]
 [2] Abort(presumed: 0xbff84458, 0x8055e7c, 0x804c378)  [../../../../src/share/javavm/runtime/interpreter.c@1441]
 [3] panicHandler(sig=8, siginfo=0x8047018, uc=0x8046e18)       [../../../../src/unixware/javavm/runtime/signals_md.c@324]
 [4] userSignalHandler(sig=8, info=0x8047018, uc=0x8046e18, arg=0xbff58de0)     [../../../../../src/unixware/hpi/src/interrupt.c@120]
 [5] intrDispatch(interrupt=8, siginfo=0x8047018, context=0x8046e18)    [../../../../../src/unixware/hpi/src/interrupt.c@106]
 [6] intrDispatchMD(sig=8, info=0x8047018, uc=0x8046e18)        [../../../../../src/unixware/hpi/green_threads/src/interrupt_md.c@131]
 [7] _sigacthandler(presumed: 0x8, 0x8047018, 0x8046e18)        [0xbffb5fd1]
 [8] Java_nfib_fib(env=0x804c2fc, cls=0x8047118, n=2)   [fib.c@13]
 [9] args_done()        [0xbff59a05]
debug> 

The actual point of failure is at frame level [8] in this case. Note also that when the JIT is in use, you don't see the rest of the stack; it usually ends as shown, or in a function named something like JIT_CALLBACK1_MARKER. If you turn off the JIT, then you can see it, but it will just be a bunch of internal routines inside the JVM (with names like do_execute_java_method ) that won't tell you much. In other words, there is no debugging tool available that will show you both the Java stack and the native methods stack at the same time.

However, when using native threads, you can make use of the JVM's Java thread dumps for this purpose. These are what you see when a Java process aborts; you can also get one by doing ^\ (control-backslash) at the command line as a Java application is running (this is especially useful if a JVM process is hung, frozen, or looping) or equivalently by sending a SIGQUIT signal to the process, such as with the kill -3 command. (You can also get some of the same information by grabbing with or running under jdb.)

You'll see entries in the Java threads dump like

    "Thread-464" (TID:0xbf0a1cc8, sys_thread_t:0x8472010, state:R, thread_t: t@4
66, sp:0xbaee3498 threadID:0x0, stack_base:0xbaee3c64, stack_size:0x20000) prio=
5
        java.io.PrintStream.println(Compiled Code)
        T.run(Compiled Code)
In native threads, the "thread_t: t@466" contains the thread number (466 in this case), and is your link between this dump and what the UDK/OUDK debugger produces. When you use the UDK/OUDK debugger ps command, the number in the "Thread" column is the same as this thread number. (This is different from the "ID" column, which has the p1.nn identification used in debugger commands, but you can use the ps output to correlate the two.)

In some cases, an abort() call can completely obscure the actual place of failure, especially if the JVM runs into further trouble while trying to print the Java thread dumps. In this case, when using native threads, you can define the environment variable JVM_NOT_HANDLE_SIGABRT; this will cause an immediate core dump and exit from the point of the abort, without the JVM getting involved. Then bringing up the debugger on the core file and doing a stack trace on the current thread will show you to the exact location of failure.

Java threads dump can also be produced when using green threads, but there is no good way to associate the Java thread stacks with native method thread stacks, since the latter are not visible to the debugger. The JVM_NOT_HANDLE_SIGABRT environment variable has no effect in green threads.

Of course, to do real native methods debugging you'll want to run the JVM from within the debugger. To do this you'll need to invoke the JVM executable directly. First, you should use the java_g version of the JVM, since that contains debugging information. Second, if you look at /usr/java2/bin/java_g, you'll see that it's a link to a script called .java_wrapper in that same directory, that sets up and exports the LD_LIBRARY_PATH and _JVM_THREADS_TYPE environment variables before calling the actual JVM executable in /usr/java2/bin/x86at/green_threads/java_g. (Note that unlike in JDK 1.1.x, the wrapper script does not set the CLASSPATH environment variable.)

If you invoke /usr/java2/bin/java_g through ksh -x you'll see the values LD_LIBRARY_PATH and _JVM_THREADS_TYPE 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 _JVM_THREADS_TYPE
$ debug -ic	# or can use graphical version
debug> create /usr/java2/bin/x86at/native_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 a 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 J2SDK 1.3 for Caldera UNIX the appropriate breakpoint is linker_md.c@143. You then have to stop the JVM there as many times as necessary until the library you are interested in has been loaded. Here is an example demonstrating both the problem and the solution:

$ debug -ic
debug> create /usr/java2/bin/x86at/green_threads/java_g nfib
New program java_g (process p1) created
HALTED p1 [main in ../../../../../src/share/bin/java.c]
81:     
debug> stop Java_nfib_fib
Error: No entry "Java_nfib_fib" exists
debug> stop linker_md.c@143
EVENT [1] assigned
debug> r
STOP EVENT TRIGGERED: linker_md.c@143  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> r
STOP EVENT TRIGGERED: linker_md.c@143  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> r
STOP EVENT TRIGGERED: linker_md.c@143  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> stop Java_nfib_fib
Error: No entry "Java_nfib_fib" exists
debug> r
STOP EVENT TRIGGERED: linker_md.c@143  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> stop Java_nfib_fib
EVENT [2] assigned
debug> run
STOP EVENT TRIGGERED: Java_nfib_fib  in p1 [Java_nfib_fib in fib.c]
8:              if (n == 12)
debug> 
You can debug normally from that point on. (How many times to stop it depends upon how many J2SDK native libraries are loaded, which depends upon what your application is doing. The above shows the correct number for a command-line application with the JIT compiler running.)

If you do a lot of this kind of debugging it can be useful to set up an alias in your ~/.debugrc file, which allows you to define a whole series of convenience commands to set up a typical native methods debugging session. An example of a full .debugrc alias for JVM green threads debugging might be look something like:

alias cj13 set $LD_LIBRARY_PATH=".:/usr/java2/bin/./../jre/lib/x86at/green_threads:/usr/java2/bin/./../jre/lib/x86at/classic:/usr/java2/bin/./../jre/lib/x86at:" ;  export $LD_LIBRARY_PATH ; 
	set $_JVM_THREADS_TYPE="green_threads" ; export $_JVM_THREADS_TYPE ; 
	create -f none /usr/java2/bin/x86at/green_threads/java_g $1 $2 $3 $4 $5 $6 $7 $8 ; 
	set %stack_bounds=no ; signal -i cld poll alrm ; 
	set $JAVA_HOME="/usr/java2" ; export $JAVA_HOME 

The setting of the _JVM_THREADS_TYPE and LD_LIBRARY_PATH environment variables follows the discussion above. The create -f none command tells the debugger to ignore child processes caused by forks done within the X Window System libraries. The stack_bounds setting avoids spurious warnings due to jitted code being executed. The signal -i command keeps the debugger from stopping on innocuous signals that the JVM handles. Setting JAVA_HOME is necessary when debugging within the appletviewer.

For debugging when the JVM is using native threads, simply change the green to native in the above paths. Depending on what you are trying to debug, you probably want to add a statement such as:

	set %thread_change=ignore ;

Profiling

J2SDK 1.3 for Caldera UNIX implements Sun's hprof profiler, as described in Sun's Java 1.3 documentation. However, the CPU time usage profiling that hprof does is only as good as the resolution of the underlying operating system timer.

On SCO OpenServer Release 5.0.6 and later, this is no problem, since as of that release the standard UNIX APIs (such as gettimeofday()) have a resolution of one microsecond, which is adequate for the task. However, on UnixWare 7 and Open UNIX 8 the normal resolution of UNIX APIs is typically much worse, on the order of ten milliseconds or so, and as a result profiling data suffers in terms of usefulness.

Better profiled timings can be obtained with J2SDK 1.3 for Caldera UNIX on UnixWare 7 Release 7.1.1 or Open UNIX 8 by doing the following:

  1. Using the SCOadmin system administration tool, go into Hardware, then System Tuner. Under the category of Miscellaneous Parameters, change the setting of USER_RDTSC from 0 to 1. This enables a high resolution clock counter. The system will then rebuild the kernel and reboot.

  2. Before starting the Java Virtual Machine, define the environment variable JVM_USE_RDTSC. Ideally, it should be set to the speed of the processor you are running on, in MHz. Thus, for example:
    $ JVM_USE_RDTSC=400 /usr/java2/bin/java -Xrunhprof:cpu=times MyApp
    
    If the value specified for the environment variable is missing or invalid, 266 MHz is used as a default. It is not vital to get the processor speed correct, though, since most profiling data is expressed in terms of percentages.
While this method of timing has resolution at the nanosecond level, it lacks accuracy at times due to a thread counting the work of other threads. However, over the course of an application run these errors will tend to cancel each other out and the profiling data will still be representative of the application's performance behavior.

Additional 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 J2SE has been implemented on Caldera UNIX platforms. Some of these have already been discussed above; others are described here.

System Properties

If it is necessary for application code to determine which of the Caldera UNIX platforms it is running on, the Java class System.Properties can be queried. Here are some of the values that will be returned by default on all Caldera UNIX platforms:
java.home=/opt/java2-1.3/jre
java.vendor=Caldera International, Inc.
java.vendor.url=http://www.caldera.com/
java.vendor.url.bug=http://www.caldera.com/support/
java.version=1.3.0_02
java.vm.vendor=Caldera International, Inc.
java.vm.version=Caldera-UNIX-J2SE-1.3.0_02:*fixes-OU8*fixes-UW7*FCS-OSR5*:[build-date-and-time]
java.class.version=47.0
java.compiler=sunwjit

while here are values that are specific to SCO OpenServer Release 5.0.6:

os.arch=IA32
os.name=OpenServer
os.version=5.0.6
java.vm.info=green threads, sunwjit

UnixWare 7 Release 7.1.1:

os.arch=IA32
os.name=UnixWare
os.version=7.1.1
java.vm.info=native threads, sunwjit

and Open UNIX 8 Release 8.0.0:

os.arch=IA32
os.name=OpenUNIX
os.version=8.0.0
java.vm.info=native threads, sunwjit

Abstract Windowing Toolkit

This implementation uses the X Window System, version X11R6.1, and Motif® version 1.2, to implement the Java 2 Abstract Windowing Toolkit.

Performance

When the JIT is suppressed or is not being used for a method for some reason, this implementation uses an assembly-coded main interpreter loop for faster bytecode execution. However, the alternate debug command java_g uses a C language interpreter when the JIT is not on.

J2SE 1.3 for Caldera UNIX contains an implementation of Sun's "classic VM" virtual machine, together with a JIT compiler. The more recent (and generally better performing) Sun HotSpotTM virtual machine is not available in the implementation described here. Attempts to use the HotSpot-specific JVM options -hotspot, -client, or -server will result in a warning diagnostic, with the classic VM being invoked anyway.

However see the section on Java for Caldera OpenLinux and LKP for an alternative way to gain access to an implementation of the HotSpot virtual machine on some Caldera UNIX platforms.

Conformance

This release of J2SE 1.3 for Caldera UNIX has passed the Sun Java Compatibility Kit (JCK) 1.3a test suite, which is the most recent version of the JCK that is applicable to the Sun J2SE 1.3.

Caldera is committed to maintaining Java application compatibility across all platforms. Caldera does not superset or subset the Java 2 APIs as defined by Sun.

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.

J2SDK 1.3 for Caldera UNIX contains the Caldera UNIX implementation of JDBC and includes the Caldera UNIX JDBC driver. The Caldera UNIX JDBC implementation was built upon the SCO, Inc. SQL-RetrieverTM product.

There is no need to separately install the Caldera UNIX JDBC implementation, since it is part of the java2sdk3 installation. It is necessary to separately install the SQL-Retriever product if you are interested in using JDBC. The Caldera UNIX JDBC implementation is included in the /usr/java2/jre/lib directory as sqlr.jar. To use it, include the appropriate path to this jar file in your CLASSPATH.

The part of SCO that made SQL-Retriever is now known as Tarantella, Inc. As of April 2001, the SQL-Retriever product has been withdrawn from the market. However a license for residual contractual requirements may still be available, and in any case, if you already have it installed you can continue to use it.

The Caldera UNIX JDBC implementation included in J2SDK 1.3 is compliant with the Sun JDBC 1.2 specification. It is not compliant with the Sun JDBC 2.0 specification.

Third-party database vendors and other ISVs may also provide JDBC implementations that work with J2SE 1.3 for Caldera UNIX.

Fonts

Java 2 looks for scalable fonts in TrueType, Type 1 or F3 formats. However, on Caldera UNIX platforms, fonts for most non-European languages, particularly those scalable fonts in TrueType, Type 1 or F3 formats, are not available. Consequently this release of J2SE 1.3 for Caldera UNIX will have difficulty displaying the characters of those languages. For the time being, users of those foreign languages are advised to find the needed fonts (as applicable to Caldera UNIX platforms) themselves, install them and add them to the /usr/java2/jre/lib/font.properties file of this release of J2SE 1.3 for Caldera UNIX.

Even for European languages, only a limited number of scalable fonts is available on Caldera UNIX platforms. However, the SCO Open License Software Supplement has a collection of freely available X11 fonts in package freefonts which helps alleviate this problem.

The consequences of missing fonts in Java 2 can be severe. For example, without packages urwfonts or freefonts the individual benchmark scores do not appear above their graph bars in the once-commonly used CaffeineMark benchmark GUI harness. As another example, the Java2D demo program gets spurious out of memory exceptions, security exceptions, and illegal argument exceptions, as well as not displaying its fonts properly. For these reasons installation of either the urwfonts or freefonts package has been required for J2SE 1.3 for Caldera UNIX and JRE 1.3 for Caldera UNIX.

When a Java program requests a particular font of a particular size, Java 2 looks for scalable fonts first. If nothing could match, then Java 2 will try to find the fonts whose sizes and types are as close as possible, including trying the fixed-size fonts if their size is close enough. This, sometimes, could cause the font displayed to look not as you wanted, if no appropriate fonts could be found on the system the Java program is running on.

You may find useful information on these and other font issues from Sun at http://java.sun.com/products/jdk/1.2/docs/guide/internat/fontprop.html.

KNOWN PROBLEMS

This section contains known problems or limitations with the Caldera port of J2SE 1.3 to Caldera UNIX platforms. For known problems with the Sun J2SE 1.3 reference implementation itself, see the Sun Developer ConnectionSM website ( http://developer.java.sun.com).

  1. On some Caldera UNIX platforms, the X11R6 implementation is currently built to only use TCP/IP as a connection mechanism. This means that even when working locally, you may need to issue an xhost +your_machine_name command.
  2. There are some limitations regarding fonts for both European and for non-European languages (see Fonts section).
  3. If you encounter an error such as "unsupported 4-bit depth" (color depth) when running Java graphical applications, the video configuration of your desktop may need to be reconfigured to a higher level, such as 1024x768 resolution with 256 colors.
  4. The JDBC driver is JDBC 1.2 compliant but not JDBC 2.0 compliant.
  5. Some multiple-level executable/library structures that use JNI Invocation will not work correctly, due to the semantics of dynamic libraries. In particular, an a.out that does a dlopen of a libuser.so that in turn invokes the Java virtual machine, will not work. An a.out that is linked with -luser but not -ljava that calls a libuser.so that in turn invokes the Java virtual machine, will also not work. Such an a.out must always be linked against -ljava itself. (See /usr/java2/demo/jni_invoc_demo for the full set of system libraries to link against.)
  6. When the /tmp filesystem is completely full, Java commands will fail with apparently mysterious errors such as Error: can't find libjava.so. or UX:test (java): ERROR: Argument expected. (This is due to Korn shell behavior rather than the J2SE itself.) The solution is to free up space in /tmp; only a little is required.
  7. When the JIT is running and old-style JDK 1.0.2 native methods (NMI) are being used, the first argument to a static native method (which represents the this reference) will not be NULL as it should be. The impact of this is negligible, though, since it is very unlikely that NMI native methods would dynamically test against this argument to know whether they are static or not.
  8. When the JIT is running, Java frames are allocated on the "native" thread stack (the size of which is governed by the java -Xss option), while when the JIT is not running, Java frames are allocated on the "Java" thread stack (the size of which is governed by the java -Xoss option). Since these stacks have different default sizes (128k and 400k respectively), it is possible for an application to experience a StackOverflowError exception when the JIT is running but not otherwise. If this happens, adjust the native thread stack size accordingly. Note however that "legitimate" stack overflows in Java are rare, since most objects are allocated on the heap; stack overflows are usually due to application bugs (recursive loops) or Java implementation bugs.
  9. On UnixWare 7 and Open UNIX 8 only, the file(1) command does not correctly recognize Java .class files. This is not problem with J2SE 1.3 per se, but with the two underlying operating systems. If you want to have file correctly identify these files, add the following line to the /etc/magic file:
    0       long    0xbebafeca      uxcore:999      Java Class File
    
    (The fields in this line must be tab-separated.) On SCO OpenServer Release 5 the file command does recognize Java .class files, and no modification is necessary.
  10. Support for multicast routing is not available on SCO OpenServer Release 5. This is not problem with J2SE 1.3 per se, just that SCO OpenServer Release 5 doesn't support it.
  11. On SCO OpenServer Release 5 (green threads) only, reading from standard input at a terminal will block all other threads from executing. On UnixWare 7 and Open UNIX 8 (both green threads and native threads) this input is non-blocking and other threads will continue to execute.
  12. On SCO OpenServer Release 5 only, after a comprehensive multicast Java application is run, the MulticastSocket.leaveGroup method may not relinquish the socket's membership in the group due to some unknown operating system or hardware related problem. Rebooting the machine will resolve this behavior.
  13. On SCO OpenServer Release 5 only, giving the jdb "run" command does not result in the program under test starting to run. In this case, issue a "threads" command, and then a "run" command.
  14. When using the KDE desktop, some graphical Java applications will appear with the top border of the window moved off the upper left corner of the screen. A work-around is to right-click along the bottom border of the window, and then do a "move" operation to pull the whole window into the visible part of the screen.
  15. On UnixWare 7 the Tarantella Enterprise 3 server (which is a Java application) will infrequently get a core dump. The Enterprise 3 server may also experience a slow memory leak during its execution.
  16. On UnixWare 7 or Open UNIX 8 applications that are making numerous networking socket connections, may experience excessive blocking delays or even a hung state. This is due to an operating system problem with the connect() system call and certain signals used by the threads library. It is corrected in the upcoming uw711pk1 and ou800pk3 maintenance packs.
  17. On SCO OpenServer Release 5 only, the locale setting that J2SE 1.3 for Caldera UNIX needs may be different than the locale setting that OpenServer selects as part of system configuration. For example, setting the locale to the French langauge in the SCO desktop internationalization dialog will have the effect of setting the environment variable LANG=fr_FR.ISO8859-1. However, in order for J2SE 1.3 to change its default locale to the French one, it needs for LANG=fr_FR to be set; the fr_FR.ISO8859-1 value will not work. Thus, you should do something like:
    $ LANG=fr_FR /usr/java/bin/java my_app
    
    when invoking the JVM, to change the LANG value for the JVM (but not for any other OpenServer applications). (This is not a problem with J2SE 1.3 per se, but rather with the different locale setting conventions between UnixWare 7 and SCO OpenServer Release 5, and how those differences are reflected through the OSRcompat package.)

See also the restrictions and limitations on native methods.

JAVA FOR CALDERA OPENLINUX AND LKP

These Release Notes describe the Java 2 Standard Edition implementation for the SCO OpenServer 5, UnixWare 7, and Open UNIX 8 operating systems. This is a "native" implementation that has been built on UnixWare 7 for execution on all of these three platforms.

In addition, there is a separate and distinct Java 2 Standard Edition, v. 1.3.0, implementation available for, and distributed with, the Caldera OpenLinux Workstation 3.1 and OpenLinux Server 3.1 operating system products. It too is a full implementation of the Sun Microsystems Java 2 Platform. The major internal difference between that Java implementation and this one is that the OpenLinux implementation uses by default the Sun HotSpot virtual machine, while the Caldera UNIX operating systems implementation uses the Sun "classic VM" virtual machine together with a JIT compiler. For most applications, the HotSpot virtual machine will show better performance than the classic VM/JIT combination.

On Open UNIX 8 when the Linux Kernel Personality feature is installed, it is possible to run the Java implementation for OpenLinux while in the UNIX environment. To do this, access the J2SE 1.3 for OpenLinux implementation through the /linux filesystem, as in this example:

$ /linux/opt/java-1.3/bin/java -version
java version "1.3.0"
Java(TM) 2 Runtime Environment, Standard Edition, root-09Mar2001-22:12
Java HotSpot(TM) Client VM, Caldera Systems, mixed mode

(You cannot currently use the more natural /linux/usr/java/bin/java because of a symbolic link not working across the filesystem divide. Of course, you can also use the linux command to go into Linux shell mode, after which you can access Java using /usr/java/bin/java.)

The J2SE 1.3 for Caldera UNIX implementation described in these Release Notes may be still accessed as well, in the normal manner:

$ /usr/java/bin/java -version
java version "1.3.0_02"
Java(TM) 2 Runtime Environment, Standard Edition (build SCO-JDK-1.3.0_02:-010416-03:42)
Classic VM (build SCO-JDK-1.3.0_02:-010416-03:42, native threads, sunwjit)

Options can be given to the J2SE 1.3 for OpenLinux implementation to select the HotSpot client compiler, the HotSpot server compiler, the HotSpot interpreter, or the classic VM interpreter (native threads or green threads). No JIT compiler is available for the classic VM in J2SE 1.3 for OpenLinux.

If native methods are used in conjunction with J2SE 1.3 for OpenLinux, they must be built with the GNU GCC compilers present in the OpenLinux distribution. They cannot be built with the Open UNIX 8 GCC compilers or with the OUDK compilers.

The J2SE 1.3 for OpenLinux implementation cannot be used on the SCO OpenServer 5 platform; the J2SE 1.3 for Caldera UNIX implementation described in these Release Notes is the only Java implementation available for SCO OpenServer 5.

ADDITIONAL INFORMATION LINKS

[TOP]


Last Updated: 3/5/2002

Copyright © 2002 Caldera International, Inc. All Rights Reserved.

Caldera, OpenLinux, SCO, SCO OpenServer, UnixWare, and Open UNIX are trademarks or registered trademarks of Caldera International, Inc. in the U.S.A. and other countries.

The Santa Cruz Operation, Inc., SQL-Retriever, Tarantella, and Tarantella Enterprise 3 are trademarks or registered trademarks of Tarantella, Inc. in the U.S.A. and other countries.

Sun, Sun Microsystems, Java, Java Development Kit, JDK, JavaBeans, JDBC, and HotSpot are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries, and are used under license.

UNIX and Motif are registered trademarks of The Open Group in the United States and other countries. Intel is a registered trademark of Intel Corporation. NonStop is a registered trademark of Compaq Computer Corporation. X Window System is a trademark of the Massachusetts Institute of Technology. Linux is a registered trademark of Linus Torvalds.

The Santa Cruz Operation, Inc. and SCO Skunkware are not related to, affiliated with or licensed by the famous Lockheed Martin Skunk Works®, the creator of the F-117 Stealth Fighter, SR-71, U-2, VenturestarTM, DarkstarTM, and other pioneering air and spacecraft.

Caldera International, Inc. reserves the right to change or modify any of the product or service specifications or features described herein without notice. This document is for information only. No express or implied representations or warranties are made in this document.