Java Development Kit 1.1.7A for SCO Operating Systems
This product is a full implementation of Sun Microsystems' Java Development Kit 1.1.7A. It enables SCO OEMs, ISVs, and end users to develop and run applets and applications that conform to the Java 1.1 Core API.
SCO JDK 1.1.7A is a full update release to the earlier SCO JDK 1.1.3, 1.1.3u, and 1.1.3w releases. It has the same functionality as SCO JDK 1.1.3w, except that it is derived from the Sun JDK 1.1.7A base and contains the fixes and improvements that Sun added between JDK 1.1.3 and 1.1.7A. In addition, SCO JDK 1.1.7A contains additional fixes and internal enhancements due to Sun's Solaris-based JDK 1.1.3A and 1.1.3D releases. Finally, this release incorporates elements of native threads support found in Sun's JDK 1.2.
NOTE: SCO Edition of Sun's Java WorkShop and Java Studio and the accompanying just-in-time (JIT) compiler are no longer available due to licensing changes.
The SCO JDK 1.1.7A product will run on the following versions of SCO's operating system platforms, with the indicated provisos:
libc
libthread
SCO JDK 1.1.7A is not supported on older versions of these operating systems, such as OpenServer 5.0.0, UnixWare 2.1.2, or UnixWare 7.0.0.
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.7A is distributed in the following packages:
jdk117 (size: about 13MB)
jdk117pls (size: about 34MB)
Package jdk117 includes the essential execution engine of Java,
that is, what you need to run Java applications:
java, the Java virtual machine (JVM)
appletviewer, the Java Applet Viewer
Package jdk117 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 jdk117 also includes additional components to
support distributed applications and database access:
Package jdk117pls is an optional supplement to jdk117
that includes several kinds of additional materials useful in Java
development work:
_g-suffixed)
of many of the commands and libraries.
In addition to Sun's documentation in the jdk117pls package, SCO
JDK 1.1.7A provides UnixWare 7 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 UnixWare 7 platform.
jdkman: Includes manual pages for the JDK commands; these manual
pages are available from the command line as well as SCOhelp.
/usr/java link.
By default, /usr/java will always point to the latest JDK.
After JDK 1.1.7A is installed, and if you had a previous version
of the JDK, for example JDK-1.1.3, the link of /usr/java
to JDK-1.1.3 will
be removed. /usr/java will point to JDK 1.1.7A.
If you remove JDK 1.1.7A from the system, and if you have another verion
of JDK on your system, for example JDK 1.1.3, the /usr/java
link will be restored to JDK 1.1.3.
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 jdk117):
# pkgadd -d /mnt jdk117
Then you can install the JDK additional materials, if desired
(package name jdk117pls):
# pkgadd -d /mnt jdk117pls
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 117A
(package name
Then you can install the JDK 117A additional materials, if desired
(package name
The graphical desktop tool
Note that you may need to increase certain system memory limits;
see Using JDK 1.1.7A for SCO below.
Mount the CD-ROM and install the JDK
(package name
Similarly for the other packages:
Note that the documentation included in the
Also note that much of this documentation is from Sun, but should be read
in an SCO context. For instance, for "Solaris" read any of the three SCO
platforms (UnixWare 7, OpenServer, or UnixWare 2).
For customer support, any of
the normal SCO support mechanisms should be used, rather than contacting Sun.
After the JDK packages are installed, you probably want to
set
On UnixWare 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:
Then, on UnixWare 7 only, you can execute a Java application
simply by giving the name of the main class:
Furthermore, by making a hard link or symbolic link such as
Of course, you can always use the traditional way
of executing a Java application:
"Green threads" refers to a model where 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 model where the Java virtual machine creates and
manages Java threads using the operating system threads library - named
In SCO JDK releases prior to JDK 1.1.3w only the green threads model was
supported. As of SCO JDK 1.1.3w, and in this release,
both models are supported (except on
OpenServer), and it is up
to you to decide which to use for your application. Green threads
is the default. To specify the threads model, set the
One reason to use green threads is that it is the more mature implementation.
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. Since most applications up to this point
have been written under green threads (that was the first model
available on most platforms, including SCO), chances are that the native
threads model would be more likely to expose incorrect application dependencies.
For both of the above reasons, green threads is the default implementation,
at least for this release of the SCO JDK.
Finally, on a uniprocessor machine, green threads sometimes has performance
advantages over native threads, although the difference tends to be
relatively minor.
There are two major potential advantages to using native threads, in addition
to it intuitively being the "right way" to implement Java threads.
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 has no ability to distribute 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 threads library multiplexed thread,
and the threads library will indeed map those threads to different LWPs
as they are available. Furthermore under native threads the Java virtual
machine will expand the number of LWPs available to the threads library,
one for each additional processor in the MP configuration.
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 3x 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
A final advantage of native threads is that is sometimes gives a clearer
picture of a program's activities when debugging at the native methods
level with the UDK debugger.
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 software development kit on OpenServer or UnixWare 2.
Some of the reasons for this requirement include:
Another important limitation with native methods is upon the kinds
of system operations that a native method can do when "green threads"
is being used as the Java threads implementation model (see the
Threads: Green or Native section above).
Under green threads the following restrictions are in place:
None of these limitations exist with the "native threads" implementation
model, so if you are coding native methods and
that model is available to you, it is strongly recommended
that you use it.
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.7A distribution
(when
Debugging of Java applications is done with the JDK-provided
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 to note first is that after-the-fact core dumps from the JVM
(which might be caused by a native methods bug) 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:
The actual point of failure is at frame level [4] in this case. Note also
that when the JIT is in use, you don't see the rest of the stack. 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
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
If you invoke
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
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.7A the appropriate breakpoint is
If you do a lot of this kind of debugging it can be useful to set up
an alias in your
This technique of using an alias can allow you to define a whole series
of convenience commands to set up a typical native methods debugging session.
An example of a full
The setting of the
For debugging when the JVM is using native threads, simply change the
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.7A 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
while here are values that are specific to OpenServer 5.0.5:
UnixWare 2.1.3:
and UnixWare 7.1.0:
SCO is committed to maintaining Java application compatibility across
all platforms. SCO does not superset or subset the Java APIs as
defined by Sun.
See also the restrictions and limitations on native methods.
# pkgadd -d /mnt jdk117
jdk117pls):
# pkgadd -d /mnt jdk117pls
App_Installer
may also be used to install these packages.
UnixWare 7
jdk117):
If your machine has more than one CD-ROM drive, specify the CD-ROM
device exactly (e.g.
# mount -F cdfs -r /dev/cdrom/* /mnt
# pkgadd -d /mnt jdk117
/dev/cdrom/c0b0t6l0).
# pkgadd -d /mnt jdk117pls
# pkgadd -d /mnt jdkdoc
# pkgadd -d /mnt jdkman
Documentation
Documentation for the JDK 1.1.7A is contained in the jdk117pls
package and, for UnixWare 7 only, also in the
jdkdoc and jdkman packages.
All of the documentation is in HTML format and
may be viewed with any browser you have installed on your system.
Document File/Link Name these release notes ReleaseNotes.htmlSun documentation for JDK 1.1.7A docs/index.htmlSun and SCO demos for JDK 1.1.7A demo/documentation on SCO's JDBC implementation
and SCO's SQL-Retriever productsee JDBC sectionjdk117pls 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.
Using JDK 1.1.7A for SCO
In general, use of SCO JDK 1.1.7A follows that which is described
in the Sun documentation.
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.
and then reboot to rebuild the kernel.
# /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
Extensions to Sun JDK 1.1.7A
SCO has provided only one functional extension to Sun's JDK 1.1.7A,
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.)
UnixWare 7 will look for
$ foo.class
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.
you will be able to execute the application simply by saying
$ ln -s foo.class 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
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.)
In this case,
$ java foo
java must be in the PATH,
and foo.class must be in the CLASSPATH.
Threads: Green or Native
Threads are an essential part of the Java language and API set, and every Java
implementation must decide how to implement Java threads. The SCO JDK 1.1.7A,
like many other implementations, supports two alternate internal threads models:
"green threads" and "native threads". Note that Java application code
does not change at all from one model to the other; the threads model
is an internal,
"under the covers" difference, although one that can have an important impact
on the behavior and performance of a Java application.
libthread
on UnixWare - and each Java thread is mapped to one threads library thread.
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; but for
other commands, the environment variable must be used. Some examples:
$ java my_app # green 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 -native my_app # native threads will be used
$ THREADS_FLAG=native appletviewer my_applet.html # only way to set native threads
Advantages of Green Threads
Advantages of Native Threads
-Kthread.
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.
All of these items are satisfied by the UDK but not by the existing
software development kit on OpenServer or UnixWare 2.
The UDK can be used either on OpenServer 5 or
UnixWare 2 itself,
or native method dynamic libraries can be built with the UDK on
UnixWare 7 Gemini and then moved to OpenServer or UnixWare 2.
long long data type,
to match the Java 64-bit long data type
libC.so) rather than an archive (libC.a)
libthread threads library
from UnixWare 2 or UnixWare 7.
write writev read readv getmsg putmsg poll open close pipe fcntl
dup creat accept recv send recvfrom socket,
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.
jdk117pls package is installed), in the directory
/usr/java/demo/,under the subdirectories
native_c_demo,
jni_c_demo,
native_c++_demo, and
jni_c++_demo.
In addition, the subdirectory jni_invoc_demo gives an example
for C and C++ of the JNI Invocation API. It is highly recommended that
you follow the command invocations given in these examples, for unless
the native code is built correctly, it will not work as intended.
Debugging Native Methods
jdb
debugger, as described in the relevant Sun documentation.
$ debug -c core.993 /usr/java/bin/x86at/green_threads/java_g
Core image of java_g (process p1) created
CORE FILE [__lwp_kill]
Signal: sigabrt
0xbffc8a72 (__lwp_kill+12:) ret
debug> stack
Stack Trace for p1, Program java_g
*[0] __lwp_kill(0x1, 0x6) [0xbffc8a72]
[1] sysAbort(presumed: 0xbfffdbb4, 0xbf753ca0, 0) [../../../../src/unixwar
e/java/runtime/system_md.c@283]
[2] signalHandlerPanic(sig=8, info=0x8046f00, uc=0x8046d00) [../../../../src
/unixware/java/green_threads/src/interrupt_md.c@491]
[3] _sigacthandler(presumed: 0x8, 0x8046f00, 0x8046d00) [0xbffb6831]
[4] nfib_fib(s=0xbf708bc8, n=0, presumed: 0) [fib.C@27]
[5] JIT_CALLBACK1_MARKER() [0xbf4c8fa8]
debug>
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.
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.
/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>
dlopen call, and until this happens, symbols in
the native methods won't be visible to the debugger.
linker_md.c@199.
Here is an example demonstrating both the problem and the solution:
You can debug normally from that point on.
$ 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@199
EVENT [1] assigned
debug> run
STOP EVENT TRIGGERED: linker_md.c@199 in p1 [sysAddDLSegment in ../../../../src/unixware/java/runtime/linker_md.c]
199: 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>
~/.debugrc
file:
Then just giving the
alias cnm create /usr/java/bin/x86at/green_threads/java_g $1 ; run -u linker_md.c@199
cnm some_class
command to the debugger will bring you
to the point where you can set breakpoints in your native method code.
.debugrc alias for JVM green threads
debugging might be look something like:
alias cjvm set $CLASSPATH=".:/home/whatever/java:/usr/java/lib/classes.zip" ; export $CLASSPATH ;
set $LD_LIBRARY_PATH="/usr/java/lib/x86at/green_threads:/usr/lib:/usr/X/lib" ; export $LD_LIBRARY_PATH ;
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 SIGUSR1 ;
set $JAVA_HOME="/usr/java" ; export $JAVA_HOME ;
run -u linker_md.c@199
CLASSPATH 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 Windows 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.
green to native in the above paths. You will
probably also want to add a
statement as well, depending upon what you are trying to debug.
set %thread_change=ignore ;
JDBC
jdk117 installation.
It is necessary to separately install the SQL-Retriever
product if you are interested in using JDBC.
Additional Implementation Notes
In general one of the important
characteristics of Java is that it behaves in exactly
the same fashion on all platforms.
However there are a few areas where it
may be useful to know how the JDK has been implemented on SCO platforms.
Some of these have already been discussed above; others are described here.
System Properties
If it is necessary for application code to determine which of the 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.version=1.1.7A
java.class.version=45.3
os.arch=IA32
os.name=OpenServer
os.version=5.0.5
os.arch=IA32
os.name=UnixWare
os.version=2.1.3
os.arch=IA32
os.name=UnixWare
os.version=7.1.0
Abstract Windowing Toolkit
This implementation uses the X Windows System, version X11R6.1,
to implement the Java Abstract Windowing Toolkit.
java -debug
This implementation changes any use of the java -debug
command into java_g -debug.
Performance
This implementation uses an assembly-coded main interpreter loop for
faster bytecode execution (however, the debug version
java_g uses a C language interpreter), and a just-in-time
compiler to further improve performance.
Conformance
This release of SCO JDK 1.1.7A has passed Sun's Java Compatibility
Kit (JCK) 1.1.6a test suite, which is the most recent version of
JCK that is applicable to the Sun JDK 1.1.7A baseline.
Known Problems
This section contains known problems or limitations
with SCO's port of JDK 1.1.7A to
SCO platforms. For known problems with Sun's JDK 1.1.x releases themselves,
see the list at
Sun's website.
xhost +your_machine_name command.
java.io package, or anywhere else in the JDK.
jdb debugger does not always successfully bring up
a debugging session in native threads mode. As an alternative,
use jdb in green threads mode. If the program being
tested needs to be run in native threads mode, run it as a separate
process and then grab it with a green threads jdb.
DISPLAY environment variable, .gif
or other image elements may be missing.
/etc/resolv.conf file is present and
DISPLAY is set to a name not registered in DNS, Java graphical
applications will fail to connect to the X server, even if
this name is registered in the /etc/hosts file.
Copyright © 1999 The Santa Cruz Operation, Inc. All Rights Reserved.