Release Notes

Java^TM 2 SDK, Standard Edition, v. 1.2.2-001
for SCO^® Operating Systems

• SPECIAL INSTALLATION UPDATE FOR UW 7.1.0
• GENERAL INFORMATION
  • License
    
  • Introduction
    
  • System Requirements and Supported Platforms
    
• PACKAGES
  • The JRE Package
    
• INSTALLATION
• DOCUMENTATION
• DEVELOPER NOTES
  
  • Using Java 2 SDK for SCO
    
  • The JIT Compiler
    
  • Threads: Green or Native
    
  • Native Methods
    
  • Debugging Native Methods
    
  • Additional Implementation Notes
    
  • Conformance
    
  • JDBC
    
  • Fonts
  • Color
  • Audio
• KNOWN PROBLEMS
• ADDITIONAL INFORMATION/LINKS

GENERAL INFORMATION

License

Introduction

J2SDK 1.2.2 is the first release from SCO based on Java^TM 2 technology. It 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.2.2-001. (The -001 suffix indicates the patch level of the Sun J2SDK that J2SDK 1.2.2 for SCO corresponds to; this particular patch contains several bug fixes from Sun, including some that are date-related.)

J2SDK 1.2.2 enables SCO OEMs, ISVs, and end users to develop and run applets and applications that conform to the Java 2 Core API. J2SDK 1.2.2 includes improvements in performance and functionality over the Java Development Kit 1.1.x. For a complete list of new features in Java 2 visit http://java.sun.com/products/jdk/1.2/docs/relnotes/features.html.

System Requirements and Supported Platforms

[*] ptfs are Support Level Supplements (SLS), that are provided to SCO customers to fix problems reported in our products. These are available for free download via anonymous ftp from ftp://ftp.sco.com/SLS

---

At this time, J2SDK 1.2.2 for SCO is NOT available for the SCO UnixWare^® 2.1.3 operating system.

---

NOTES: J2SDK 1.2.2 for SCO cannot be used with the older OSRcompat packages that were released together with UnixWare 7 Release 7.0 or UnixWare 7 Release 7.1.

J2SDK 1.2.2 for SCO is not supported on older versions of these operating systems, such as UnixWare 7 Release 7.0.1.

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

---

PACKAGES

Package Name	Approx. Size	Contains
Software Packages
java2sdk2	29 MB	Runtime Support: java, the Java virtual machine (JVM); the JIT compiler; appletviewer, the Java Applet Viewer; Java Foundation Classes (JFC) & Swing Package; and basic API libraries: language support, I/O, AWT, networking, utilities, images, media, math, compression, and security. Development Tools: javac, the Java Compiler; jdb, the command-line Java debugger; javah, the C Header and Stub File Generator for native methods; javap, the Java Class File Disassembler; javadoc, the JAVA API Documentation Generator; and jar, the Java Archive (JAR) tool. Distributed applications and database access: Remote Method Invocation (RMI); Java Beans (component object model); JDBC (database access); Internationalization tools; Security tools; Java IDL tools.
java2pls2	33 MB	Java 2 demo applets and applications; Demos of Swing set functionality; native method demos; and Debuggable versions (_g-suffixed) of many of the commands and libraries.
java2jre2	16 MB	Java Runtime Environment (see following section)
Documentation Packages
java2doc	92 MB	Java 2 API documentation; guides to new features; release notes from Sun; and links to other information. Documentation in this package is not integrated with SCOhelp.
java2man	380 KB	Manual pages for the J2SDK commands. Documentation in this package is integrated with SCOhelp.

The JRE Package

Not included with the Java 2 for SCO distribution material, but available separately from SCO if required, is the Java^TM 2 Runtime Environment, v. 1.2.2-001, for SCO Operating Systems, also known as the JRE 1.2.2 for SCO, in package java2jre2.

The Java 2 Runtime Environment contains the Java virtual machine, runtime class libraries, and Java application launcher that are necessary to run programs written in the Java programming language. It is not a development environment and does not contain development tools such as compilers or debuggers. For development tools, use the J2SDK 1.2.2 for SCO.

The 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 java2jre2 package, unlike the other java2* packages, is installed as some_dir/opt/jre2-1.2.2/ anywhere within a directory structure, based on input given by the installer during the pkgadd command. This allows ISVs to govern where the JRE is placed. The default for some_dir/ will be /.

Note again that the JRE package is intended for use by ISVs; if you are an end user, you should simply use the regular java2sdk2 package (and java2pls2 package if desired) instead.

INSTALLATION

The J2SDK 1.2.2 for SCO binary distribution is built on and for UnixWare 7 Release 7.1.x, but is able to run on SCO OpenServer Release 5 by virtue of the UDK Compatibility Module for SCO OpenServer .

On all platforms, the freefonts package must be installed first. This package is available from the free SCO Open License Software Supplement (also known as SCO Skunkware^TM). The Supplement is distributed as a CD-ROM in the media kit for SCO operating systems, and the package is also available for free download from http://www.sco.com/skunkware/ (look in the Graphics/Viewers section).

---

NOTE: J2SDK 1.2.2 packages can be installed on your system even if you have JDK^TM 1.1.x for SCO packages. Installation of J2SDK 1.2.2 will not automatically remove your previous JDK 1.1.x from the system.

JDK 1.1.x is installed at /opt/jdk-1.1.x and is accessed via /usr/java/bin. J2SDK 1.2.2 is installed at /opt/java2-1.2.2 and is accessed via /usr/java2/bin. (You need to include /usr/java2/bin in your PATH environment variable.)

If you have JDK 1.1.x for SCO on your system and would like to continue to use it as the default java (or Java Virtual Machine), then make sure that /usr/java/bin comes before /usr/java2/bin in your PATH. On the other hand, if you want to use the JVM from Java 2 SDK, then /usr/java2/bin must precede /usr/java/bin in your PATH. In any case, you can access whichever JVM you choose by supplying the full pathname.

---

There are a few differences in how the J2SDK is installed on each platform:

SCO OpenServer Release 5

If the UDK Compatibility Module for SCO 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 Java 2 SDK (package name java2sdk2):

# pkgadd -d /mnt  java2sdk2

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

# pkgadd -d /mnt  java2pls2

UnixWare 7 Release 7.1.x

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

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

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

Similarly for the other packages:

# pkgadd -d /mnt  java2pls2
# pkgadd -d /mnt  java2doc
# pkgadd -d /mnt  java2man

DOCUMENTATION

Documentation for the Java 2 SDK is contained in the java2doc (full Sun Java 2 SDK documentation including APIs) and java2man (just the manual pages for the J2SDK commands) packages.

Due to the large size of the Java 2 SDK API documentation, only Java command manual pages are integrated with SCOhelp on the UnixWare 7 platform. Java 2 SDK manual pages are not available using SCOhelp on SCO OpenServer Release 5; we recommend that you consult the Java 2 SDK commands documentation from online SCO Product Documentation Library http://uw7doc.sco.com .

Full Java 2 SDK documentation (including APIs) is available at http://www.sco.com/java/j2sdk122-001/docs/index.html where it can be viewed with a Netscape^® Navigator^® browser (version 3.0 or higher).

Document	File/Link Name
these release notes	ReleaseNotes.html
Sun documentation for Java 2 SDK	/usr/java2/docs/
Sun and SCO demos for Java 2 SDK	/usr/java2/demo/
documentation on the SCO JDBC implementation and the SCO SQL-RetrieverTM product	see JDBC section

Customers working in a Japanese locale can obtain localized Java 2 documentation from the Sun Java download site at http://java.sun.com/products/jdk/1.2/download-ja-docs.html

---

NOTE: If you have both JDK 1.1.7 for SCO and J2SDK 1.2.2 for SCO installed on your UnixWare 7 Release 7.1 system, you might want to have both corresponding documentation packages installed as well:

• jdkdoc and jdkman packages for JDK 1.1.7 for SCO, and
• java2doc and java2man for J2SDK 1.2.2 for SCO.

Only JDK 1.1.7 Guide material will be found under "Software Development": Java development tools.

Similarly, Java manual pages (the Sun "tooldocs") are available from the man command and SCOhelp in release-specific manual page sections:

• man sections 1Mrtjava and 1dkjava (JDK 1.1.7)
• man section 1java2 (J2SDK 1.2.2)

Note that documentation for existing technologies will be included in both sets with varying degrees of modification. For example, if both documentation sets are installed and you search a topic such as "RMI", you will get search hits for JDK 1.1.7 only, as the J2SDK 1.1.2 guide material is not integrated with SCOhelp. However, for manual page searches two hits will be displayed for the javac manual page, javac(1dkjava) for JDK 1.1.7 and javac(1java2) for J2SDK 1.2.2.

Note also that some Java 2 SDK manual pages are included in the UnixWare 7 base operating system documentation set: java(1), appletviewer(1) and classpath(5). These manual pages are duplicated in the J2SDK 1.2.2 java2man package; depending on the documentation packages installed, you may have multiple versions of these pages on your system.

---

DEVELOPER NOTES

Using Java 2 SDK for SCO

In general, use of the Java 2 SDK for SCO follows that which is described in the Sun documentation.

After the Java 2 SDK packages are installed, we recommend that you set PATH in your .profile to include the directory where the Java 2 SDK commands are installed, /usr/java2/bin.

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 x86 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 J2SDK 1.2.2 for SCO product and package java2sdk2. 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. The JIT compiler runs on UnixWare 7 Release 7.1.1 and Release 7.1, and SCO OpenServer Release 5.0.5. On SCO OpenServer Release 5.0.2 or 5.0.4, the JIT compiler cannot execute, and conventional bytecode interpretation will take place instead.

By default, the JIT compiler in J2SDK 1.2.2 for SCO 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.

Controlling the JIT

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 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
bco=off	suppress the bytecode optimizer part of the JIT

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

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

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

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

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

In particular, JIT_ARGS=trace is useful in verifying that the JIT is installed correctly and is actually executing.

The bytecode optimizer is a particular part of the JIT; suppressing it may be useful for pinpointing the source of performance problems or other JIT problems.

JIT Heuristics

All JIT compilers come with a trade-off: the cost of the time it takes to stop 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.

As stated in The JIT Compiler above, by default the JIT compiles every method the first time it sees it. The environment variable JIT_MIN_TIMES can be set to a non-negative integer n to indicate a different approach: a method will not be jitted until the method has already executed at least n times. In other words, this is a heuristic that posits that those methods that have already been executed a lot, will be the ones that will tend to execute a lot for the rest of program execution. An example of its use would be:

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

For some short- or medium-lived applications, use of JIT_MIN_TIMES may improve the performance of the JIT. One example is the javac Java language translator, which has now been set up to use the JIT heuristics mechanism. The only way to find out for your application is to experiment with it, using different minimum count values. However for long-running, server-oriented applications, the default strategy of always jitting when a method is first called is likely to be the best.

Threads: Green or Native

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

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

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

J2SDK 1.2.2 for SCO supports both models (except on SCO OpenServer Release 5), 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 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

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 J2SDK 1.2.2 for SCO.

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 has 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 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 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 they sometimes give a clearer picture of a program's activities when debugging at the native methods level with the UDK debugger.

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 (sometimes known as NMI) are supported in J2SDK 1.2.2 for SCO. However, it is strongly recommended that you use newer JNI-style native methods, since they are the only ones that will be supported by Sun in the future; the older native method interface is deprecated and has already been eliminated in some Java implementations from Sun.

C and C++ native methods must be compiled and linked with the UnixWare and OpenServer Development Kit (UDK) from SCO. 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 X must reference X11R6 headers, since that is what the J2SDK 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.

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

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

• A native method cannot make use of the libthread threads library from UnixWare 7 Release 7.1.x.

• 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, close, pipe, fcntl, dup, creat, accept, recv, send, recvfrom, sendto, socket, connect, select, ioctl - 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.

Examples specific to SCO 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.2.2 for SCO distribution (when java2pls2 package is installed), in the directory /usr/java2/demo/native,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

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

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.

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

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

$ . setup_java	# your script to set LD_LIBRARY_PATH and _JVM_THREADS_TYPE
$ debug -ic	# or can use graphical version
debug> create /usr/java2/bin/x86at/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 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.2.2 for SCO the appropriate breakpoint is linker_md.c@127. You then have to stop the JVM there as many times as necessary until the library you are interested in has been loaded. Here is an example demonstrating both the problem and the solution:

$ debug -ic
debug> create /usr/java2/bin/x86at/green_threads/java_g nfib
New program java_g (process p1) created
HALTED p1 [main in ../../../../../src/share/bin/java.c]
81:     
debug> stop Java_nfib_fib
Error: No entry "Java_nfib_fib" exists
debug> stop linker_md.c@127
EVENT [1] assigned
debug> r
STOP EVENT TRIGGERED: linker_md.c@123  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> r
STOP EVENT TRIGGERED: linker_md.c@123  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> r
STOP EVENT TRIGGERED: linker_md.c@123  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@123  in p1 [sysLoadLibrary in ../../../../../src/unixware/hpi/src/linker_md.c]
123:    
debug> stop Java_nfib_fib
EVENT [2] assigned
debug> run
STOP EVENT TRIGGERED: Java_nfib_fib  in p1 [Java_nfib_fib in fib.c]
8:              if (n == 12)
debug> 

You can debug normally from that point on. (How many times to stop it depends upon how many J2SDK native libraries are loaded, which depends upon what your application is doing. The above shows the correct number for a command-line application with the JIT compiler running.)

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

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

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

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

	set %thread_change=ignore ;

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 J2SDK 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 SCO platforms it is running on, the Java class System.Properties can be queried. Here are some of the values that will be returned by default on all SCO platforms:

java.home=/opt/java2-1.2.2/jre
java.vendor=SCO, Inc.
java.vendor.url=http://www.sco.com/
java.version=1.2.2
java.vm.info=build SCO-JDK-1.2.2-001, green threads, sunwjit
java.class.version=46.0

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

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

and UnixWare 7 Release 7.1:

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

Abstract Windowing Toolkit

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

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

Conformance

This release of J2SDK 1.2.2 for SCO has passed the Sun Java Compatibility Kit (JCK) 1.2.2 test suite, which is the most recent version of the JCK that is applicable to the Sun J2SDK 1.2.2.

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.2.2 for SCO contains the SCO implementation of JDBC and includes the SCO JDBC driver. The SCO JDBC implementation is built upon the SCO 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 java2sdk2 installation. It is necessary to separately install the SQL-Retriever product if you are interested in using JDBC. The SCO JDBC implementation is included in the /usr/java2/jre/lib directory as sqlr.jar. To use it, include the appropriate path to this jar file in your CLASSPATH.

The SCO JDBC implementation included in J2SDK 1.2.2 is compliant with the Sun JDBC 1.2 specification. It is not compliant with the Sun JDBC 2.0 specification.

Fonts

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

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

The consequences of missing fonts in Java 2 can be severe. For example, without freefonts the individual benchmark scores do not appear above their graph bars in the 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 freefonts package has been required for J2SDK 1.2.2 for SCO and JRE 1.2.2 for SCO.

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

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

Color

If the user encounters errors such as "unsupported 4-bit depth" (color depth) when running Java graphical applications, the video configuration of the machine may need to be reconfigured to a higher level, such as 1024x768 256 colors.

Audio

In this release of J2SDK 1.2.2 for SCO, the implementation of the audio engine is based on the Sun JDK 1.1.8 audio engine implementation. As a result, this implementation supports only one sound format: 8 bit, µlaw, 8000 Hz, one-channel .au files, just as the Sun JDK 1.1.8 does. In contrast, full Java 2 audio implementation would support playback for MIDI files and the full range of .wav, aiff and .au files. Note that only the underlying audio engine is based on JDK 1.1.8. J2SDK 1.2.2 for SCO, which fully conforms to the Java 2 APIs as defined by Sun, allows applications to create AudioClips without requiring an AppletContext, just as the Sun J2SDK 1.2.2 does.

KNOWN PROBLEMS

This section contains known problems or limitations with the SCO port of J2SDK 1.2.2 to SCO platforms. For known problems with the Sun J2SDK 1.2.2 reference implementation itself, see the Sun Developer Connection website ( http://developer.java.sun.com).

1. On some SCO 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. Audio support in J2SDK 1.2.2 for Sun is based on that in Sun JDK 1.1.8.
3. Large file support (for files > 2GB in size) is not yet present in the java.io package, nor anywhere else in the J2SDK.
4. The "first-class executable" support found in JDK 1.1.x for UnixWare 7 is not available for J2SDK 1.2.2 for UnixWare 7. That is, when UnixWare 7 sees a Java class file named at the command line without reference to a java command, it will invoke JDK 1.1.x rather than J2SDK 1.2.2. Since the first-class executable feature is typically used by smallish utility programs that do not make use of Java 2 advanced features, this is unlikely to be a significant limitation.
5. Support for multicast routing is not available on SCO OpenServer Release 5. This is not problem with J2SDK 1.2.2 per se, just that SCO OpenServer Release 5 doesn't support it.
6. There are some limitations regarding fonts for both European and for non-European languages (see previous section).
7. The JDBC driver is JDBC 1.2 compliant but not JDBC 2.0 compliant.
8. Some multiple-level executable/library structures that use JNI Invocation will not work correctly. In particular, an a.out that does a dlopen of a libuser.so that in turn invokes the Java virtual machine, will not work. An a.out that is linked with -luser but not -ljava that calls a libuser.so that in turn invokes the Java virtual machine, will also not work. Such an a.out must always be linked against -ljava itself. (See /usr/java2/demo/jni_invoc_demo for the full set of system libraries to link against.)
9. 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 J2SDK itself.) The solution is to free up space in /tmp; only a little is required.
10. 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.
11. 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.
12. 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 Release 7.1.x (both green threads and native threads) this input is non-blocking and other threads will continue to execute.
13. On SCO OpenServer Release 5 only, the java profiling options -Xrunhprof:cpu=times and -Xrunhprof:cpu=old cause core dumps, as does the JDK 1.1.x -prof option, which now equates to -Xrunhprof:cpu=old. These profiling options work correctly on UnixWare 7 Release 7.1.x .
14. On SCO OpenServer Release 5.0.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.
15. jdb does not work when trying to debug a program running with native threads. This is true whether jdb runs the program directly or whether it grabs a running running JVM process. As a work-around use green threads when running programs under or for jdb.
16. Using native threads, and under a heavy stress load of rapidly created, short-lived threads, a problem has been occasionally seen that results in an assertion failure or core dump in the java.io.UnixFileSystem.list native method.
17. Using native threads, a problem has been occasionally seen that results in the java.awt.Container.getComponent method returning an incorrect value or throwing a NullPointerException exception.

See also the restrictions and limitations on native methods.

ADDITIONAL INFORMATION/LINKS

• SCO http://www.sco.com
• SCO Java Technologies http://www.sco.com/java
• SCO Product Documentation Library http://sco.doc.com
• SCO FTP Download Site ftp://ftp.sco.com
• Java 2 SDK New Features http://java.sun.com/products/jdk/1.2/docs/relnotes/features.html
• Java 2 SDK Page http://java.sun.com/products/jdk/1.2
• Japanese Java 2 SDK Documentation http://java.sun.com/products/jdk/1.2/download-ja-docs.html

[TOP]

---

Last Updated: 2/16/2000

Copyright © 2000 The Santa Cruz Operation, Inc. All Rights Reserved.

SCO, SCO OpenServer, and UnixWare are registered trademarks of The Santa Cruz Operation, Inc. in the U.S.A. and other countries. Sun, Sun Microsystems, Java, and JDK are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries, and are used under license. Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries. X Window System is a trademark of the Massachusetts Institute of Technology.

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

The Santa Cruz Operation, 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.