Contents

License

Introduction

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

• a number of fixes for reported and discovered problems;
• some miscellaneous performance improvements;
• a just-in-time (JIT) compiler (for UnixWare 2.1.2 and UnixWare 7 only);
• documentation integrated with SCOhelp (for UnixWare 7 only).

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

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

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

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

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

SCO JDK 1.1.3u is distributed in the following packages:

• jdk113
• jdk113pls
• jdk113jit (for UnixWare 7 and UnixWare 2.1.2 only)

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

• Java Virtual Machine, JVM (the java command)
• appletviewer, the Java Applet Viewer
• basic API libraries
  • language support
  • I/O
  • AWT
  • networking
  • utilities
  • images, media
  • math
  • compression
  • security

Package jdk113 also includes some Java 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
• jar, the Java Archive (JAR) tool

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

• Remote Method Invocation (RMI)
• Java Beans (component object model)
• JDBC (database access)

Package jdk113pls includes:

• The JavaSoft documentation which contains a full description of the different parts of the JDK (this documentation is in stand-alone format and is not integrated into documentation browsers);
• Many interesting Java demo applets and applications including some native method demos;
• Debugging versions of many of the commands and libraries.

Package jdk113jit includes:

• The JIT compiler.

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

• jdkdoc: Includes JDK API documentation, JDK guide to new features, Sun's release notes, and links to other information, all tailored to the UnixWare7 platform.

• jdkman: Includes manual pages for the JDK commands; these manual pages are available from the command line as well as SCOhelp.

Installation

OpenServer 5.0.4

# pkgrm js10
# pkgrm jws20
# pkgrm jdk113pls
# pkgrm jdk113
# pkgrm [any other existing Java packages]

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

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

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

# pkgadd -d /mnt  jdk113

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

# pkgadd -d /mnt  jdk113pls

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

UnixWare 2.1.2

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

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

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

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

# pkgadd -d /mnt  jdk113

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

# pkgadd -d /mnt  jdk113pls

The JIT package can be installed as:

# pkgadd -d /mnt  jdk113jit

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

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

UnixWare 7

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

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

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

Then add the Java packages from the UDK set:

# pkgadd -d /mnt  udk

When prompted, add the Java components in this order:

jdk113pls
jdk113jit
jdkdoc
jdkman

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

NOTE:

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

Documentation

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

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

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

Using JDK 1.1.3u for SCO

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

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

# /etc/conf/bin/idtune -m HVMMLIM 0x7FFFFFFF
# /etc/conf/bin/idtune -m HDATLIM 0x7FFFFFFF
# /etc/conf/bin/idtune -m SVMMLIM 0x7FFFFFFF
# /etc/conf/bin/idtune -m SDATLIM 0x7FFFFFFF
# /etc/conf/bin/idbuild

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

Extensions to Sun JDK 1.1.3

Java Classes as First-Class Executables

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

$ foo.class

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

$ ln -s foo.class foo

$ foo

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

$ java foo

The JIT Compiler

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

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

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

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

$ java hello			# JIT will run

$ JAVA_COMPILER= java hello	# JIT will not run

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

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

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

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

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

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

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

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

Native Methods

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

Some of the reasons for this requirement include:

• 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 X must reference X11R6 headers, since that is what the JDK AWT uses

• native methods must use the same calling conventions, header files, and libraries as the JVM, which has itself been built with the UDK

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

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

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

• Using JNI Invocation to start the JVM from within a C or C++ application may not work if the C or C++ application makes use of any of these system calls: write writev read readv getmsg putmsg poll open close pipe fcntl dup creat accept recv send recvfrom socket. This is because in green threads, these system calls are wrapped by the JVM in order to support non-blocking I/O. If they are called outside of a context in which the JVM expects, problems often result.

• Furthermore, using JNI Invocation from a C++ program will not work on OpenServer 5.0.4 or UnixWare 2.1.2, and will not work on UnixWare 7 unless libC is linked statically (use the options -Bstatic -lC at the end of the command line). Both of these restrictions are consequences of system calls made during libC initialization.

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

Debugging Native Methods

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

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

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

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

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

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

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

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

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

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

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

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

alias cnm create /usr/java/bin/x86at/green_threads/java_g ; run -u linker_md.c@207

JDBC

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

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

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

Implementation Notes

System Properties

java.home=/usr/java
java.vendor=SCO
java.vendor.url=http://www.sco.com/
java.class.version=45.3

while here are values that are specific to OpenServer 5.0.4:

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

UnixWare 2.1.2:

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

and UnixWare 7:

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

Abstract Windowing Toolkit

Threads

Performance

Conformance

Known Problems

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

2. On OpenServer 5.0.4 and UnixWare 2.1.2 when appletviewer or a java AWT application is invoked you may see the following messages
   

   current locale is not supported in X11, locale is set to C
   X locale modifiers are not supported, using default
   

   This indicates that you are in a locale other than the default C locale. The problem is that the UDK compatibility modules are lacking necessary X locale support. The JDK will continue to operate after this warning is given, but with the locale set to the C locale.

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

See also the restrictions and limitations on native methods.