Release Notes

Java^TM 2, Standard Edition, v. 1.3.1_22
for SCO^® UNIX^® Operating Systems

• GENERAL INFORMATION
  • License
    
  • Introduction
    
  • System Requirements and Supported Platforms
    
  • Changes in This Release
    
  • Distributed CA Certificates
    
• PACKAGES
  • The JRE Package
    
• INSTALLATION
• DOCUMENTATION
• DEVELOPER NOTES
  
  • Using Java 2 SDK for SCO UNIX
    
  • Java Classes as First-Class Executables
    
  • The JIT Compiler
    
  • Threads: Green or Native
    
  • Native Methods
    
  • Debugging Native Methods and the JVM
    
  • Profiling
    
  • Additional Implementation Notes
    
  • Conformance
    
  • JDBC^TM
    
  • Fonts
• JAVA PLUG-IN
• KNOWN PROBLEMS
• JAVA FOR LINUX KERNEL PERSONALITY (LKP)
• ADDITIONAL INFORMATION LINKS

GENERAL INFORMATION

License

Introduction

This release of Java 2 Standard Edition contains:

• the Java 2 Runtime Environment, which allows SCO UNIX end users to run Java applets and applications on SCO UNIX operating systems
• the Java 2 Software Development Kit (J2SDK), which enables SCO UNIX OEMs, ISVs, and end users to develop Java applets and applications that conform to the Java 2 Core API
• the Java 2 Plug-In for Netscape 4.x browsers on earlier SCO UNIX platforms and the Mozilla browsers available for UnixWare 7.1.3 and later and OpenServer 5.0.7.

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

J2SE 1.3.1 for SCO UNIX is a full implementation of the Sun Microsystems^TM Java 2 Platform - the technology and environment described in the Sun^TM specifications of the Java 2 Platform, Standard Edition, v. 1.3.1_22. (The _22 suffix indicates the patch level of the Sun J2SE that J2SE 1.3.1 for SCO UNIX corresponds to.)

This product was originally 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., and this product became known as the Java 2 Standard Edition for Caldera UNIX Operating Systems. In August 2002, Caldera International, Inc. announced that it would be changing its name to The SCO Group, Inc. (a change completed in May 2003), and this product is now known as the Java 2 Standard Edition for SCO UNIX Operating Systems.

These Release Notes refer to this product as being for "SCO UNIX Operating Systems" to distinguish this Java implementation and the operating systems it supports from any existing Linux J2SE that is available for the Linux Kernel Personality (LKP) on UnixWare. There are separate Java 2 Standard Edition implementations available for LKP.

System Requirements and Supported Platforms

J2SE 1.3.1 for SCO 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, nor is it available for older operating systems, such as the SCO UnixWare 2 operating system.

J2SE 1.3.1 for SCO 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.1 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 UnixWare 7.1.3, the Open UNIX 8.0.0 and the OpenServer 5.0.7 media kits and is automatically installed as part of Initial System Load if Java is installed. It is also available on the UnixWare and OpenServer Development Kit 7.1.3, the Open UNIX Development Kit Release 8.0.0 or downloadable from the J2SE 1.3.1 web download page http://www.sco.com/download/.

[**] The recommended runtime for UnixWare and Open UNIX is the various library packages version 8.0.1 that are part of the UnixWare 7.1.3 media kit, on the UnixWare and Open Server Development Kit version 7.1.3 CD-ROM, or the UnixWare 7.1.3 (UDK) Runtime Libraries available at the SCO download site, http://www.sco.com/download/. The required runtime on OpenServer 5 are the libraries contained in the package set OSRcompat version 8.0.1 available on the UnixWare and Open Server Development Kit 7.1.3 CD-ROM, the SCO OpenServer Release 5.0.7 media, or in the Binary Compatibility 7.1.3 for OpenServer on the SCO download site, http://www.sco.com/download/.

Package set udkrtfs, is available for free download from http://www.sco.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. Package set OSRcompat version 8.0.1 is available from the SCO OpenServer Release 5.0.7 media kit.

[***] Maintenance packs, maintenance supplements, release supplements, and support level supplements (SLS) that are provided to SCO UNIX customers to fix problems reported in our products, are available for free download via anonymous ftp from ftp://ftp.sco.com/pub/unixware7/713, ftp://ftp.sco.com/pub/openunix8, ftp://ftp.sco.com/pub/unixware7, and ftp://ftp.sco.com/pub/openserver5.

[****] After the release of UnixWare 7 Release 7.1.1, the UnixWare 7 product line was renamed to Open UNIX 8 with the release of Open UNIX 8 Release 8.0.0, and then was renamed back to UnixWare 7 with the release of UnixWare 7.1.3. In effect, then, Open UNIX 8 Release 8.0.0 is equivalent to what would have been UnixWare 7 Release 7.1.2.

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 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.1 for SCO UNIX. To compensate for this, the j2jre131 package does 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.1_22

Automatic update of the /usr/java and /usr/java2 symbolic links to the installation of this J2SE release has changed. Please see the "Installations Location and Multiple Java Versions" subsection of these J2SE 1.3.1_22 Release Notes for complete details.

J2SE 1.3.1_22 for SCO UNIX is the latest and cumulative update to J2SE 1.3.1. It contains the latest set of fixes from Sun including the following security issue announced by Sun:

Sun Alert ID	Description
200040 (formerly 103112)	A vulnerability in the Virtual Machine of the Java Runtime Environment may allow an untrusted applet to elevate its privileges. For example, an applet may grant itself permissions to read and write local files or execute local applications that are accessible to the user running the untrusted applet.
201519 (formerly 103079)	A vulnerability in the Java Runtime Environment (JRE) with applet caching may allow an untrusted applet that is downloaded from a malicious website to make network connections to network services on machines other than the one that the applet was downloaded from. This may allow network resources (such as web pages) and vulnerabilities (that exist on these network services) which are not otherwise normally accessible to be accessed or exploited.
200041 (formerly 103078)	A vulnerability in the Java Runtime Environment (JRE) may allow malicious Javascript code that is downloaded by a browser from a malicious website to make network connections, through Java APIs, to network services on machines other than the one that the Javascript code was downloaded from. This may allow network resources (such as web pages) and vulnerabilities (that exist on these network services) which are not otherwise normally accessible to be accessed or exploited. A second vulnerability in the JRE may allow an untrusted applet that is downloaded from a malicious website through a web proxy to make network connections to network services on machines other than the one that the applet was downloaded from. This may allow network resources (such as web pages) and vulnerabilities (that exist on these network services) which are not otherwise normally accessible to be accessed or exploited.
200162 (formerly 103072)	A vulnerability in the Java Runtime Environment may allow an untrusted Java Web Start application or Java applet to move or copy arbitrary files on the system that the application or applet runs on, by requesting the user of the application or applet to drag a file from the application or applet window to a desktop application that has permissions to accept and write files on the system. To exploit this vulnerability, the application or applet has to successfully persuade the user to drag and drop the file.
200837 (formerly 103071)	When an untrusted applet or application displays a window, the Java Runtime Environment includes a warning banner inside the window to indicate that the applet or application is untrusted. A defect in the Java Runtime Environment may allow an untrusted applet or application that is downloaded from a malicious website to display a window that exceeds the size of a user's screen so that the warning banner is not visible to the user.
200856 (formerly 102934)	A buffer overflow vulnerability in the image parsing code in the Java Runtime Environment may allow an untrusted applet or application to elevate its privileges. For example, an applet may grant itself permissions to read and write local files or execute local applications that are accessible to the user running the untrusted applet.
233324	A vulnerability in the Java Plug-in may an untrusted applet to bypass same origin policy and leverage this flaw to execute local applications that are accessible to the user running the untrusted applet.

This release supercedes the previous J2SE 1.3.1_20 web-release for UnixWare 7.1.x and OpenServer 5.0.[67] and is available for download from the OS specific section of the SCO support web site at http://www.sco.com/support/download.html/.

J2SE 1.3.1_20

J2SE 1.3.1_20 for SCO UNIX, previously available from the SCO Support download site, contained the then latest set of fixes from Sun including:

• Additional updates to TimeZone.java that correspond to Olson's public zone information in tzdata2007a.
• The following security issue announced by Sun.

Sun Alert ID

Description

102686

The Java Runtime Environemnt and the Java Secure Socket Extension may verify incorrect RSA PKCS #1 v1.5 signatures if the RSA public key exponent is 3. This may allow applets or applications that are signed by forged signing certificates and web sites with forged web server certificates to be verified as valid. For more information see: http://www.imc.org/ietf-openpgp/mail-archive/msg14307.html http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2006-4339

This release supercedes the previous J2SE 1.3.1_19 web-release for UnixWare 7.1.x and OpenServer 5.0.[67] and is available for download from the OS specific section of the SCO support web site at http://www.sco.com/support/download.html/.

J2SE 1.3.1_19

J2SE 1.3.1_19 for SCO UNIX, previously available from the SCO Support download site, contained the then latest set of fixes from Sun including:

• Additions or corrections to the US DST timezone changes that go into effect in 2007.
• Western Australia (Perth) timezone changes for the recently enacted (Nov. 21, 2006) summer time phase shift that went into effect on Dec. 3, 2006.
• The CA Root Certificates file (cacerts) has additional root certificates that we have recieved permission to distribute; see section "Distributed CA Certificates" for details
• Fixes for the following previously unannounced security issues.

Sun Alert ID	Description
102760	A buffer overflow vulnerability in processing GIF images in the Java Runtime Environment may allow an untrusted applet to elevate its privileges. (Fix from J2SE 5.0, update 10 released in SCO's J2SE 5.0, update 09 release.)
102732	Two vulnerabilities in the Java Runtime Environment may allow an untrusted applet to access data in other applets.
102729	Two buffer overflow vulneribilities in the JRE may independently allow an untrusted applet to elevate its previleges. For example, an applet may grant itself permissions to read and write a local file or execute local applications that are accessible to the user running the untrusted applet.

J2SE 1.3.1_18

J2SE 1.3.1_18 for SCO UNIX, previously available from the SCO Support download site, contained the then latest set of fixes from Sun including the Austrailian timezone (DST shift) fix.

It supercedes the previous J2SE 1.3.1_17 web-release for UnixWare 7.1.x and OpenServer 5.0.[67].

J2SE 1.3.1_17

J2SE 1.3.1_17 for SCO UNIX, previously available at this download site, was the then latest and cumulative update to J2SE 1.3.1. It contained the latest set of fixes from Sun.

It supercedes the previous J2SE 1.3.1_16 web-release for UnixWare 7.1.x and OpenServer 5.0.[67].

J2SE 1.3.1_16

J2SE 1.3.1_16 for SCO UNIX, previously available at this download site, was the then latest and cumulative update to J2SE 1.3.1. It contained the latest set of fixes from Sun at that time including the following security fix.

Sun Alert ID	Description
102003	A security vulnerability with the use of "reflection" APIs in the Java Runtime Environment (JRE) may (independently) allow an untrusted applet to elevate its privileges. For example, an untrusted applet may grant itself permissions to read and write local files or execute local applications that are accessible to the user running the untrusted applet.

It superceded the previous J2SE 1.3.1_13 web-release for UnixWare 7.1.x and OpenServer 5.0.[67].

J2SE 1.3.1_13

J2SE 1.3.1_13 for SCO UNIX, previously available at this download site, is the previous and cumulative update to J2SE 1.3.1. It contains the latest set of fixes from Sun including the following recently announced Java Plug-in security fixes.

Sun Alert ID	Description
57591	A vulnerability in the Java Plug-in may allow an untrusted applet to escalate priveleges through JavaScript to Java communication.
?????	A vulnerability in the Java Plug-in may allow an untrusted applet to inappropriately interfere with another applet in the same web-page including causing it to incorrectly load non-code resources such as files and web pages.

It supercedes the previous J2SE 1.3.1_12 web-release for UnixWare 7.1.x and OpenServer 5.0.[67].

J2SE 1.3.1_12

J2SE 1.3.1_12 for SCO UNIX, previously available at this download site, was the latest and cumulative update to J2SE 1.3.1. It contains the latest set of fixes from Sun. It supercedes the J2SE 1.3.1_10 release in UnixWare 7.1.3 Update Pack 4, UnixWare 7.1.4 and OpenServer 5.0.7 MP3.

J2SE 1.3.1_10

J2SE 1.3.1_10, released in the UnixWare 7.1.3 Update Pack 4 and with OpenServer 5.0.7 Maintenance Pack 3, has the following security fixes from Sun:

Sun Alert ID	Description
57436	Verisign Class 3 and Class 2 PCA Root Certificate Expiration
57221	A Vulnerability in JRE May Allow an Untrusted Applet to Escalate Privileges

J2SE 1.3.1_08

J2SE 1.3.1_08 for SCO UNIX has a Java plug-in for the Mozilla browsers released with OpenServer 5.0.7 and UnixWare 7.1.3 Update Pack 2. In addition, it has fixes for problems reported by users of J2SE 1.3.1 including the following security fix from Sun:

Sun Alert ID	Description
55101	Java VM / Plug-in May Allow An Untrusted Applet to Access User Authentication Info

J2SE 1.3.1_06

J2SE 1.3.1_06 for SCO UNIX, still available on this download site for BEA WebLogic users, has fixes for problems reported by users of J2SE 1.3.1 including the following security fixes from Sun:

Sun Alert ID	Description
49304	Java VM Allows Constructors not to Call Other Constructors
50081	Incorrect Certificate Validation in Java Secure Socket Extension (JSSE), Java Plug-In and Java Web Start
50083	Java Virtual Machine May Allow Illegal Access to Protected Fields or Methods

J2SE 1.3.1_04

J2SE 1.3.1_04 for SCO UNIX includes improvements in performance, functionality, and reliability over the previous Java release for SCO UNIX, the Java 2 Standard Edition, version 1.3.0_02 and is available on the UnixWare 7.1.3 and on the OpenServer Release 5.0.7 media kits.

Distributed CA Certificates

Prior to the J2SE 1.3.1_19 release, the system-wide keystore certificates file named "cacerts" in the release contained a limited number of root CA certificates. It was the responsibility of users to add the specific root CA certificates of interest to their Java installation.

Beginning with the release of J2SE 1.3.1_19, the "cacerts" file contains root CA certificates from several public Certificate Authorities. As permission to distribute other root CA certificates is obtained, they will added in subsequent updates. As before, users may add to or maintain their keystore with the Java keytool command. See the "keytool - Key and Certificate Management Tool" documentation for usage and the default password.

PACKAGES

The JRE Package

All J2SE 1.3.1 for SCO UNIX users must install the JRE package. It is the base package which other J2SE 1.3.1 for SCO UNIX packages depend upon. (This is different from previous Caldera UNIX and SCO UNIX releases, wherein the SDK package was the base and contained the JRE and the SDK, and the JRE package was a separate, parallel special purpose package. Now, the JRE package is the base, and the SDK package contains only the SDK pieces that are not in the JRE.)

One additional 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 j2jre131 package is by default installed in /usr/java/, with that actually being a symbolic link to /opt/java2-1.3.1/.

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 j2jre131 package with a different name. The JRE would then install into BASEDIR. System administrators wanting to do this would 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.

Note that the other J2SE 1.3.1 packages require that the j2jre131 package be installed in /opt/java2-1.3.1.

INSTALLATION

SCO OpenServer Release 5.0.7

The j2jre131 and j2sdk131 packages, and the prerequisite OSRcompat and urwfonts packages, are installed by default during initial load of the OpenServer Release 5.0.7 Base OS.

However, if you de-selected those packages during initial load, you can later install them from the UnixWare and OpenServer Development Kit 7.1.3 CD in the OpenServer Release 5.0.7 media kit as follows.

You need to mount the UDK CD-ROM from the OpenServer 5.0.7 media kit and install urwfonts and the version 8.0.1 package set OSRcompat:

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

When those installations are complete, install the core Java 2 runtime (package name j2jre131), and if desired, the Java 2 SDK:

# pkgadd -d /mnt  j2jre131
# pkgadd -d /mnt  j2sdk131

Including the case where the above packages were installed by default on system load, you can now install the Java 2 SDK demos/debugging package and/or the Java 2 Plug-in package, if so desired (package names j2pls131 and j2plg131):

# pkgadd -d /mnt  j2pls131
# pkgadd -d /mnt  j2plg131

Note that if you are installing these packages after having downloaded them from the SCO web site or an SCO ftp site, they will be in datastream format (a single file with a suffix of .ds) rather than in file system format. Assuming you downloaded the file to the directory /some/dir/, the installation commands would look like this (giving the full pathname is necessary):

# pkgadd -d /some/dir/j2jre131.ds

Finally, the UDK 7.1.3 CD-ROM contains versions of the J2SE for SCO UNIX packages that are in custom format, which is the standard packaging format for OpenServer. An advantage of installing them via custom is that they will appear together with all the other software packages on the system when doing system maintenance.

To install this way, insert the UDK CD-ROM from the OpenServer 5.0.7 media kit, then bring up the Software Manager, either by double-clicking the desktop icon or by running the custom command from the command line. Then use the Software | Install New menu choices to get to the list of software packages available from the CD-ROM. Choose the ones you want to install and click on the Install button. Note that the entry "Java 2 Software Development Kit" in Software Manager includes both the j2sdk131 and j2pls131 packages within it.

SCO OpenServer Release 5.0.6

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

You need to mount the UDK CD-ROM from the OpenServer 5.0.7 media kit and install the version 8.0.1 package set OSRcompat, and, if not already installed, package urwfonts:

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

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

# pkgadd -d /mnt  j2jre131

Then you can install one or both of the Java 2 SDK additional materials or Java 2 Plug-in, if desired (package names j2sdk131, j2pls131 and j2plg131):

# pkgadd -d /mnt  j2sdk131
# pkgadd -d /mnt  j2pls131
# pkgadd -d /mnt  j2plg131

Note that, in the more likely case that you are installing these packages after having downloaded them from the SCO web site or an SCO ftp site, the packages will be in datastream format (a single file with a suffix of .ds) rather than in file system format. Assuming you downloaded the file to the directory /some/dir/, the installation commands would look like this (giving the full pathname is necessary):

# pkgadd -d /some/dir/j2jre131.ds

Finally, the UDK 7.1.3 CD-ROM contains versions of the J2SE for SCO UNIX packages that are in custom format, which is the standard packaging format for OpenServer. An advantage of installing them via custom is that they will appear together with all the other software packages on the system when doing system maintenance.

To install this way, insert the UDK CD-ROM from the SCO OpenServer Release 5.0.7 media kit, then bring up the Software Manager, either by double-clicking the desktop icon or by running the custom command from the command line. Then use the Software | Install New menu choices to get to the list of software packages available from the CD-ROM. Choose the ones you want to install and click on the Install button. Note that the entry "Java 2 Software Development Kit" in Software Manager includes both the j2sdk131 and j2pls131 packages within it.

UnixWare 7.1.3

However, if you de-selected these packages during ISL, you can install them from the UnixWare and OpenServer Development Kit 7.1.3 CD in the following way:

Mount the CD-ROM and install the Java 2 SDK

# mount -F cdfs -r /dev/cdrom/* /mnt
# pkgadd -d /mnt  urwfonts
# pkgadd -d /mnt  j2jre131
# pkgadd -d /mnt  j2sdk131
# pkgadd -d /mnt  j2plg131

Including the case where the above packages were installed by default on ISL, you can now install the Java 2 SDK demos/debugging package if so desired (package name j2pls131):

# pkgadd -d /mnt  j2pls131

If you are performing an upgrade installation of UnixWare 7 Release 7.1.3 from Open UNIX Release 8.0.0 and had the previous Java 2 SDK, version 1.3.0_02 installed, the J2SE 1.3.1_04 JRE and SDK will automatically be selected for installation. All or the remaining packages that you desire must be added following the upgrade.

Open UNIX 8 Release 8.0.0

Mount the UDK CD-ROM from a UnixWare 7.1.3 media kit and install the Java 2 core Java 2 runtime (package name j2jre131):

# mount -F cdfs -r /dev/cdrom/* /mnt
# pkgadd -d /mnt  urwfonts		# if needed
# pkgadd -d /mnt  j2jre131

Then you can install one or both of the Java 2 SDK additional materials or Java 2 Plug-in, if desired (package names j2sdk131, j2pls131 and j2plg131):

# pkgadd -d /mnt  j2sdk131
# pkgadd -d /mnt  j2pls131
# pkgadd -d /mnt  j2plg131

Note that, in the more likely case that you are installing these packages after after having downloaded them from the SCO web site or an SCO ftp site, the packages will be in datastream format (a single file with a suffix of .ds) rather than in file system format. Assuming you downloaded the file to the directory /some/dir/, the installation commands would look like this (giving the full pathname is necessary):

# pkgadd -d /some/dir/j2jre131.ds

UnixWare 7 Release 7.1.1

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

Mount the UDK CD-ROM from a UnixWare 7.1.3 media kit and install the Java 2 core Java 2 runtime (package name j2jre131):

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

Then you can install one or both of the Java 2 SDK additional materials or Java 2 Plug-in, if desired (package names j2sdk131, j2pls131 and j2plg131):

# pkgadd -d /mnt  j2sdk131
# pkgadd -d /mnt  j2pls131
# pkgadd -d /mnt  j2plg131

Note that, in the more likely case that you are installing these packages after having downloaded them from the SCO web site or an SCO ftp site, the packages will be in datastream format (a single file with a suffix of .ds) rather than in file system format. Assuming you downloaded the file to the directory /some/dir/, the installation commands would look like this (giving the full pathname is necessary):

# pkgadd -d /some/dir/j2jre131.ds

Installation Location and Multiple Java Versions

The symbolic links will not be altered if they currently point to a later release of Java such as J2SE 1.4.2.

Previous Behavior

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

For compatibility with older J2SE for SCO releases, a symbolic link is also made from /usr/java2 to /opt/java2-1.3.1/. Thus, for example, you may invoke the Java virtual machine with either the command /usr/java/bin/java or the command /usr/java2/bin/java.

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

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

However, if you happen to 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.1 for SCO 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.1 for SCO UNIX or whether you want it left alone. In the latter case, you would access J2SE 1.3.1 for SCO UNIX via /usr/java2 rather than /usr/java.

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

Being able to use /usr/java has several advantages: It is the place where Java is accessed on many other systems, including on Linux operating systems, 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 and UnixWare 7.1.3 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.

Note however that even if /usr/java is changed to point to J2SE 1.3.1 for SCO UNIX, 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.

DOCUMENTATION

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

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 "Solaris^TM" version (not the "Linux^TM" or "Win32" versions).

Note that there are also useful Sun and SCO UNIX demonstration uses of J2SE 1.3.1 and J2SDK 1.3.1 at /usr/java/demo/ when the j2pls131 package has been installed.

DEVELOPER NOTES

Using Java 2 SE for SCO UNIX

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/java/bin (or /usr/java2/bin, if the /usr/java link was not changed).

However, on UnixWare 7 and Open UNIX 8 modifying your startup file may not be necessary, as login accounts are usually created with /usr/java/bin as part of the PATH.

Java Classes as First-Class Executables

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.1 for SCO UNIX product and package j2jre131. 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.1 for SCO UNIX is named sunwjit and is based upon the JIT compiler of the same name from Sun, but it has been significantly enhanced by SCO.

The JIT compiler in J2SE 1.3.1 for SCO 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:

• to do performance analysis of the JIT's effectiveness
• because you suspect the JIT may be causing a problem
• to see source line numbers in Java exception stack traces

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

trace	show 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|off	always 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()

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.1 for SCO 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 an SCO 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

"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.1 for SCO 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 some 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

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

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   

Native Methods

C and C++ native methods must be compiled and linked with the UnixWare and OpenServer Development Kit (UDK) from SCO, 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:

• native methods need the C/C++ 64-bit long long data type, to match the Java 64-bit long data type

• C++ native methods need for the C++ standard library to be a dynamic library (libC.so) rather than an archive (libC.a)

• native methods using the X Window System must reference X11R6 headers, since that is what the J2SE 1.3.1 for SCO UNIX AWT uses

• native methods must use the same calling conventions, header files, and libraries as the JVM, which has itself been built on UnixWare 7 Release 7.1.1 with the UDK 7.1.1b Feature Supplement.

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:

• A native method cannot make use of the libthread threads library from UnixWare 7 or Open UNIX 8.

• Direct native methods access to commercial database systems is potentially hazardous due to inappropriate system-level usages by the DBMSes conflicting with the JVM; use JDBC instead.

• In general, if native methods use any of these system calls - write, writev, read, readv, getmsg, putmsg, poll, open, open64, close, pipe, fcntl, dup, creat, creat64, accept, recv, send, recvfrom, sendto, socket, connect, select, ioctl (including their UnixWare 7 or Open UNIX 8 versioned names with _x prefixes) - you may run into trouble because of green threads wrappers. However it is safe to make these system calls from JNI Invocation C or C++ code before the Java virtual machine is started up, because at that point the green threads wrappers are not yet activated.

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.

SCO 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.1 for SCO UNIX distribution (when j2pls131 package is installed), in the directory /usr/java/demo/native,under the subdirectories

• native_c_demo
• jni_c_demo
• native_c++_demo
• jni_c++_demo
• jni_invoc_demo.

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 UnixWare 7.1.3 and Open UNIX 8, this is the GNUgcc package within the open source OSTools product set that SCO builds and ships as part of the UDK/OUDK CD-ROM. This same package may also be installed on UnixWare 7 Release 7.1.1. 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/java/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 an SCO 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 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/java/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/java/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/java/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/java/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.1 for SCO UNIX the appropriate breakpoint is linker_md.c@167. 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/java/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@167
EVENT [1] assigned
debug> r
STOP EVENT TRIGGERED: linker_md.c@167  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> r
STOP EVENT TRIGGERED: linker_md.c@167  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> r
STOP EVENT TRIGGERED: linker_md.c@167  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@167  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> 

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/java/bin/./../jre/lib/x86at/green_threads:/usr/java/bin/./../jre/lib/x86at/classic:/usr/java/bin/./../jre/lib/x86at:" ;  export $LD_LIBRARY_PATH ; 
	set $_JVM_THREADS_TYPE="green_threads" ; export $_JVM_THREADS_TYPE ; 
	create -f none /usr/java/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/java" ; 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

On SCO OpenServer Release 5.0.6 and later this is not a 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.1 for SCO UNIX on UnixWare 7 Release 7.1.x 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/java/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.

Additional Implementation Notes

System Properties

java.home=/opt/java2-1.3.1/jre
java.vendor=The SCO Group, Inc.
java.vendor.url=http://www.sco.com/
java.vendor.url.bug=http://www.sco.com/support/
java.version=1.3.1_10
java.vm.vendor=The SCO Group, Inc.
java.vm.version=SCO-UNIX-J2SE-1.3.1_10:*FCS*:...
java.class.version=47.0
java.compiler=sunwjit

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

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

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.1.3:

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

Open UNIX 8 Release 8.0.0:

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

and UnixWare 7 Release 7.1.1:

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

Abstract Windowing Toolkit

Signals

This implementation interprets SIGQUIT as a request for a Java threads dump. JNI code should not attempt to use SIGQUIT.

In some contexts this implementation intentionally raises SIGSEGV signals in order to implement null reference checking and stack overflow checking. JNI code that accidentally or intentionally raises SIGSEGV will function properly (the JVM will handle the signal, issue a Java threads dump, and shut down). However you should not send a random SIGSEGV signal to a Java process (as is sometimes done in QA testing) because if the JVM is in one of the contexts where SIGSEGV is intentionally used, it will get confused and undefined behavior will result.

Finally, this implementation will handle any "fatal error" signals such as SIGBUS, SIGILL, etc., and proceed to issue a Java threads dump and shut down the JVM. This processing will function properly even if the signal is sent randomly to the Java process.

Performance

J2SE 1.3.1 for SCO UNIX contains an implementation of Sun's "classic VM" virtual machine, together with a JIT compiler. The more recent (and generally better performing) Sun HotSpot^TM 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 Linux Kernel Personality (LKP) for an alternative way to gain access to an implementation of the HotSpot virtual machine on some SCO UNIX platforms.

Conformance

SCO is committed to maintaining Java application compatibility across all platforms. SCO 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.1 for SCO UNIX contains the SCO UNIX implementation of JDBC and includes the SCO UNIX JDBC driver. The SCO UNIX JDBC implementation was built upon the SCO, Inc. SQL-Retriever^TM product.

There is no need to separately install the SCO UNIX JDBC implementation, since it is part of the j2sdk131 installation. It is necessary to separately install the SQL-Retriever product if you are interested in using JDBC. The SCO UNIX JDBC implementation is included in the /usr/java/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 SCO UNIX JDBC implementation included in J2SDK 1.3.1 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.1 for SCO UNIX.

Fonts

Support for fonts in the Japanese locale, including for Java, has been greatly improved in UnixWare 7.1.3. For support and use of fonts for Java in the Japanese locale on the previous releases Open UNIX 8 and UnixWare 7 Release 7.1.1, read the notes and directions in the comments at the beginning of the file /usr/java/jre/lib/font.properties.ja.

Even for European languages, only a limited number of scalable fonts is available on SCO 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.

If using the default /usr/java/jre/lib/font.properties, it is necessary that the Java logical font sansserif.0 or sansserif.plain.0 be specified and be installed as a font on the X server platform displaying the graphical user interface of the Java application. If using any of the other font properties files, it is necessary that Java logical fonts serif.0 or serif.plain.0 and serif.1 or serif.plain.1 are defined in the /usr/java/jre/lib/font.properties[.locale] file and that they be installed as a font on the X server platform displaying the graphical user interface of the Java application.

The consequences of missing fonts in Java 2 can be severe. For example, without package urwfonts 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 the urwfonts package is required for J2SE 1.3.1 for SCO UNIX and JRE 1.3.1 for SCO 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/j2se/1.3/docs/guide/intl/addingfonts.html.

JAVA PLUG-IN

Java Plug-in is a mechanism whereby Java applets being executed in a browser may be run using the external Java virtual machine from the underlying operating system, rather than the internal Java virtual machine included with the browser.

This is important because the Mozilla browser does not have an internal Java virtual machine and the internal Java virtual machines included in the Netscape 4.x browsers available on SCO UNIX operating systems are old, implementing Java Development Kit 1.1.x versions of the Java language and libraries. Thus the Netscape internal JVMs cannot run Java applets that use any Java 2 features or APIs (such as Swing) that have been added to the language since then. Using Java Plug-in allows such applets to run.

Additional general information about Java Plug-in may be found at http://java.sun.com/products/plugin/.

Java Plug-in 1.3.1 for Netscape 4.x and Mozilla 1.2.1 is installed by adding the package j2plg131, as described in the Installation section above. This will install Java Plug-in for all users on the system (unlike previous Java Plug-in 1.2.2 and 1.3.0 alpha releases from SCO and Caldera, which installed Plug-in only for the user doing the installation). Plug-in files are installed in /usr/local/lib/netscape. Netscape 4.x will look in this directory for available plugins. For Mozilla, a link to the appropriate dynamic library is installed in the plugins directory of the Mozilla release. Note that these files do not include the Java virtual machine implementation itself; the one on the system already installed via package j2jre131 is used (this is different from previous Java Plug-in 1.2.2 and 1.3.0 alpha releases from SCO and Caldera, in which a separate JVM was included with the Plug-in distribution).

If you already have a Java Plug-in 1.2.2 or 1.3.0 alpha Plug-in installed, you should remove it by deleting the file $HOME/.netscape/plugins/javaplugin.so and the entire directory $HOME/.netscape/java/. Otherwise, Netscape will use the older Plug-in for any applets that are permitted to run with that older version, since Netscape looks for plug-ins in $HOME/.netscape/plugins/ before it looks for plug-ins in /usr/local/lib/netscape/plugins/.

An important aspect of Java Plug-in 1.3.1 for Netscape 4.x browsers is that for the Plug-in to actually be used, the HTML invoking the Java applet must be changed to use an <embed> tag rather than the usual <applet> tag. This is usually done by hand editing, although an automated conversion tool may also be used. This tool is found at /usr/local/lib/netscape/ojiplugin/bin/HtmlConverter and its use is described at http://java.sun.com/products/plugin/1.3/docs/html_converter.html.

To verify that installation of Java Plug-in 1.3.1 is working correctly, you may run the simple Plug-in demo applet file:/usr/java/demo/plug-in/applet_id/applet_id.html (the j2pls131 package, which contains all Java demos, must have been installed). This applet will display what Java virtual machine implementation and version it is running with.

A more complex Plug-in demo applet to test is found at file:/usr/java/demo/jfc/SwingSet2/SwingSet2Plugin.html. You may also run the applet demos found underneath /usr/java/demo/applets/, but you will have to modify their HTML files as described above for use with Netscape 4.x.

In some versions of the Netscape 4.x and Mozilla browsers, you can also find out what plug-ins are installed by selecting "About Plug-ins" from the top-level "Help" menu.

The Java Plug-in Control Panel allows you to change the default settings used by Java Plug-in at startup. This tool is found at /usr/local/lib/netscape/ojiplugin/bin/ControlPanel and its use is described at http://java.sun.com/products/plugin/1.3/docs/controlpanel.html. You may also invoke this tool from within the Netscape browser by using the URL file:/usr/local/lib/netscape/ojiplugin/ControlPanel.html. Unlike on some other systems, this URL is not added to the Netscape browser bookmarks list automatically when Java Plug-in is installed; you may do this addition by hand if you wish.

Environment variables that modify the behavior of the Java virtual machine may still be used in the Java Plug-in context if desired. For example, to run Java Plug-in on Open UNIX 8 in green threads mode rather than native threads mode, do $ THREADS_FLAG=green /usr/bin/X11/netscape & .

Java Plug-in 1.3.1 may be removed from the system by doing a pkgrm j2plg131 command. The next time the browser is brought up, it will realize that the plug-in is no longer there.

KNOWN PROBLEMS

1. On some SCO 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 -ljvm -lhpi 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 -ljvm -lhpi itself. (See /usr/java/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.1 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.1 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 SCO OpenServer Release 5 only, the locale setting that J2SE 1.3.1 for SCO 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 language 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.1 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.1 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 set.)

See also the restrictions and limitations on native methods.

JAVA FOR LINUX KERNEL PERSONALITY (LKP)

In addition, there is a separate and distinct Java 2 Standard Edition, v. 1.3.1, for Linux implementation available for the Linux Kernel Personality on UnixWare. 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 Linux implementation uses by default the Sun HotSpot virtual machine, while the SCO 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 and UnixWare 7.1.3, when the Linux Kernel Personality feature is installed, it is possible to run the Java implementation for Linux while in UNIX mode. To do this, access the J2SE 1.3.1 for Linux implementation through the /linux filesystem, as in this example:

$ /linux/opt/java-1.3.1/bin/java -version
java version "1.3.1"
Java(TM) 2 Runtime Environment, Standard Edition (build Caldera-1.3.1-02aFCS)
Java HotSpot(TM) Client VM (build Caldera-1.3.1_02a-FCS, 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 mode, after which you can access Java using /usr/java/bin/java.)

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

$ /usr/java/bin/java -version
java version "SCO-UNIX-J2SE-1.3.1_10"
Java(TM) 2 Runtime Environment, Standard Edition (build SCO-UNIX-J2SE-1.3.1_10:**FCS*:20yymmdd)
Classic VM (build SCO-UNIX-J2SE-1.3.1_10:*FCS*:20yymmdd, native threads, sunwjit)

Options can be given to the J2SE 1.3.1 for Linux 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.1 for Linux.

If native methods are used in conjunction with J2SE 1.3.1 for Linux, they must be built with the GNU GCC compilers present in the Linux distribution. They cannot be built with the UnixWare 7/Open UNIX 8 GCC compilers or with the UDK/OUDK compilers.

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

ADDITIONAL INFORMATION LINKS

• SCO and Caldera http://www.sco.com
• SCO Server Solutions http://www.sco.com/products/
• Java Technologies on SCO Systems http://www.sco.com/developers/java/
• SCO Product Documentation Library http://www.sco.com/support/docs/
• SCO FTP Download Site ftp://ftp.sco.com/pub/
• Tarantella http://www.tarantella.com

• The Java Language Specification, Second Edition
• The Java Virtual Machine Specification, Second Edition
• The Java Community Process^SM Program, which governs the evolution of Java

• Sun http://java.sun.com
• Java 2 SE Page http://java.sun.com/j2se/1.3
• Java 2 SE SDK version 1.3.1 New Features http://java.sun.com/j2se/1.3/docs/relnotes/features.html
• Java 2 Platform Compatibility with Previous Releases http://java.sun.com/j2se/1.3/compatibility.html
• Java 2 SE SDK version 1.3.1 Documentation
  • English http://java.sun.com/j2se/1.3/docs/index.html
  • Japanese http://java.sun.com/j2se/1.3/ja/docs/ja/index.html
• Java Plug-in Home Page http://java.sun.com/products/plugin/

The SCO Group, 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.