RELEASE NOTES

Java Development Kit 1.1.3 for SCO Operating Systems


Contents

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

License

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

Introduction

These are the release notes for the JavaTM Development Kit (JDK), Release 1.1.3 for SCO Operating Systems.

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 in fact this release incorporates SunSoft's JDK 1.1.3A and 1.1.3D fixes and enhancements to JavaSoft's JDK 1.1.3; this is done to support the Java Workshop, Java Studio, and JIT compiler products found in the UnixWare/OpenServer Development Kit (UDK).

This JDK product is being released on all three SCO operating system platforms: UnixWare 7, OpenServer (5.0.4), and UnixWare 2 (2.1.2).

(The JDK should also work on OpenServer 5.0.0 and 5.0.2, but is not conformance tested on those platforms.)

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.

The SCO JDK-1.1.3 is packaged in two separate packages:

The jdk113 includes the essential runtime engine of Java, that is, the equivalent of an OS's kernel and libraries:

The jdk113 also includes Java development tools:

The jdk113 also includes additional components to support distributed applications and database access:

The jdk113pls includes

Installation

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

OpenServer 5.0.4

If the UDK Compatibility Module for OpenServer (package name OSRcompat) is not already installed on our 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-1.1.3 (package name jdk113):

# pkgadd -d /mnt jdk113

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

# pkgadd -d /mnt jdk113pls

UnixWare 2.1.2

If the UDK Compatibility Module for UnixWare (package name UW2compat) is not already installed on our 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

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 for SCO below.

UnixWare 7

The jdk113 package is installed automatically during Initial System Load (ISL) of the UnixWare 7 Base OS. (The jdk113 package is part of the BaseWeb set which is on the Base OS CD).

However, if you de-selected the jdk113 during ISL, you can install it from UnixWare 7 CD in the following way:

Mount the CD-ROM and install the JDK (package name jdk113):

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

Documentation

Documentation for the JDK 1.1.3 is contained in the jdk113pls package. All of the documentation is in HTML format and may be viewed with any browser you have installed on your system.

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

Note that these documents are not integrated into the graphical help system on your platform (e.g. the ScoHelp).

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.3 for SCO

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

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

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

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

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

Extensions to Sun JDK 1.1.3

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

Java Classes as First-Class Executables

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

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

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

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

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

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

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

Native Methods

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

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

Some of the reasons for this requirement include:

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

Another important limitation with native methods is upon the kinds of system operations that a native method can do. In particular:

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.3 (in the jdk113pls package), under the subdirectories native_c_demo, jni_c_demo, native_c++_demo, and jni_c++_demo.

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 JDK 1.1.3 the appropriate breakpoint is linker_md.c@207. Here is an example demonstrating both the problem and the solution:

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

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

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

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

JDBC

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

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

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

Implementation Notes

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

System Properties

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

while here are values that are specific to OpenServer 5.0.4:

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

UnixWare 2.1.2:

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

and UnixWare 7:

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

Abstract Windowing Toolkit

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

Threads

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

Performance

This implementation uses an assembly-coded main interpreter loop for faster bytecode execution. [However, the debug version java_g uses the C-language interpreter.]

Conformance

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

Known Problems

This section contains known problems with SCO's port of JDK 1.1.3 to SCO platforms. For known problems with Sun's JDK 1.1.x releases themselves, see the list at JavaSoft's website.
  1. On all three platforms, the X11R6 implementation is currently built to only use TCP/IP as a connection mechanism. This means that even when working locally, you need to issue an xhost +your_machine_name command.

  2. On OpenServer (5.0.4) and UnixWare (2.1.2) when appletviewer or java are invoked you may see the following message which may be ignored:
    current locale is not supported in X11, locale is set to CX locale modifiers are not supported, using default

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

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