Release Notes

JavaTM Communications API Implementation
for SCO® UNIX® Operating Systems,
Version 2.0

Introduction

These are the Release Notes for an implementation of the JavaTM Communications API (also known as javax.comm) for SCO® UNIX® Operating Systems. This API allows Java applications to communicate with serial and parallel devices.

The Java Communications API is described at http://java.sun.com/products/javacomm/.

This implementation is available for the following SCO UNIX operating systems:

A prerequisite is that Java 2 Standard Edition v. 1.3 or greater for SCO UNIX Operating Systems must already have been installed. This requirement may be met by any of the following Java for SCO UNIX releases:

This implementation is a port of the open source RXTX implementation of the Java Communications API. Information about RXTX may be found at http://www.rxtx.org. This port has been done off of RXTX version 1.4-8.

RXTX includes part of the Sun MicrosystemsTM Java Communications API implementation for Solaris/x86, version 2.0. This part (the comm.jar file) is included in this distribution; you do not need to download it from the SunTM web page.

Installation

To install this beta implementation, place the javaxcomm.ds package file somewhere. Go there, become root, and then do: 

# pkgadd -d 'pwd`/javaxcomm.ds

This will install package javaxcomm, which places the following substantive files into the J2SE for SCO UNIX directory structure: 

/usr/java/jre/lib/ext/comm.jar 
/usr/java/jre/lib/ext/jcl.jar
/usr/java/jre/lib/ext/gnu.io.rxtx.properties
/usr/java/jre/lib/x86at/libSerial.so
/usr/java/jre/lib/x86at/libParallel.so
/usr/java/jre/lib/javax.comm.properties
/usr/java/javax.comm-ReleaseNotes.html
/usr/java/javax.comm-ReleaseNotes.txt

This also places a couple of license files in /usr/java/, and a number of demonstration and example files under /usr/java/demo/comm/.

The installed binaries of the Java Communications API package are used for all SCO UNIX platforms. (On SCO OpenServer, the native code libraries are executed via the OSRcompat binary compatibility module, just as the native code layers of J2SE are.)

Note that if you install a new version of J2SE for SCO UNIX (for example, if you go from J2SE 1.3.1 to J2SE 1.4.2), you will have to re-install the javaxcomm package. This is because the previously installed javaxcomm files actually reside within (for example) /opt/java2-1.3.1/ (with /usr/java having been a symbolic link to that), and thus are not visible to the new J2SE within /opt/java2-1.4.2/ (with /usr/java now being a symbolic link to this). Do not pkgrm the javaxcomm package first; just pkgadd it a second time, and then it will be available for use with both J2SE 1.3.1 and J2SE 1.4.2 for SCO UNIX.

Initial Testing and Use

To use this implementation of Java Communications API, just compile and run Java as you normally would. Because the above files are installed into the standard extension space of J2SE for SCO UNIX, there is no need to set the CLASSPATH or LD_LIBRARY_PATH environment variables in order to access the Java Communications API.

A simple test of the serial I/O part of this implementation can be done as follows. Set up a null modem RS-232 cable between two machines. Become root. Run the open source minicom tool on each machine and verify that the connection is working, by typing characters back and forth between the two machines.

(Binary versions of minicom are installed into /usr/java/demo/comm/minicom/ as minicom-uw7 and minicom-osr5. Note that you need to first do minicom -s to tell it about the names and speeds of your serial ports. When you then run minicom, use the ctrl-A E and ctrl-A A commands to turn on local echo and linefeed add. See http://minicom.alioth.debian.org/ for more information on minicom.)

Once working serial communication has been verified, shut down minicom on the machine that Java Communications API is installed on. Then access the Sun SerialDemo demo program, which installed at /usr/java/demo/comm/SerialDemo/. Change into that SerialDemo directory, and run 

# /usr/java/bin/java SerialDemo

This should bring up a GUI. Change the serial device port name and speed in the GUI if necessary, then click "Open Port". Type into the top pane and text should appear in the minicom window on the other machine. Type into the minicom window on the other machine and text should appear in the middle pane of the SerialDemo GUI. Click "Close Port" to finish.

If you do not have access to a graphical environment, you can run the even simpler Sun demo programs installed at /usr/java/demo/comm/Simple/, which work at the command-line level.

Additional sample programs using the Java Communications API are available as part of the Sun Solaris/x86 implementation and can be downloaded from http://java.sun.com/products/javacomm/.

A simple test of parallel I/O part of this implementation can be done as follows. Connect a parallel printer and define it to the system in the usual fashion as a local printer. Then obtain the Sun ParallelBlackBox demo program, which is available from Sun as one of the sample programs just mentioned above. Run it as 

# /usr/java/bin/java ParallelBlackBox

This should bring up a GUI, and it will usually find the correct parallel port. Type into the top pane and text will start printing out at the printer. You may need to eject the page yourself depending upon the printer.

Ports and Locks

On SCO OpenServer, there are several kinds of serial ports. This implementation supports both modem control (e.g. /dev/tta1A) and standard control (e.g. /dev/tty1a) operations on serial ports, as well as use of USB-serial ports (e.g. /dev/ttyu1A or /dev/ttyu1a).

On all SCO UNIX platforms, certain serial ports are predefined and are known to the implementation. These are:

These ports are scanned when javax.comm is started up, and those that represent working serial ports on the system will be included in the list returned by the javax.comm.CommPortIdentifier.getPortIdentifiers() method.

This predefined list may be overridden by specifying the property gnu.io.rxtx.SerialPorts. Set the property to a colon-separated list of ports that should be scanned for inclusion. This may be done via the command line when Java is invoked: 

# /usr/java/bin/java -Dgnu.io.rxtx.SerialPorts=/dev/ttya01a:/dev/ttya02a SerialDemo
To do it on a more global basis, modify the file /usr/java/jre/lib/ext/gnu.io.rxtx.properties, and uncomment and change the definition of the property there.

Note that the gnu.io.rxtx.SerialPorts property, if used, replaces the predefined list of ports; it does not augment it. Thus, if your system has four serial ports on the predefined list and four extra ones not on the list, you need to name all eight when specifying the property.

During the scanning of ports, this implementation will put out trace messages to the standard output indicating its progress. These will help you troubleshoot any difficulties in this area.

This implementation uses the standard UNIX "lock file" protocols to protect serial ports from concurrent access. This means that javax.comm will not be able to access the port if it is already locked by another serial application (whether javax.comm, a non-Java application such as minicom, or a system command such as cu), and vice versa.

In particular, on SCO OpenServer, the lock files are of the form /usr/spool/uucp/LCK..tty?a, where the device name portion is folded to lowercase. On UnixWare 7 the lock files are of the form /var/spool/locks/LK.x.y.z, where x, y, and z are the major device number of the device directory, the major device number of the device, and the minor device number of the device. For all operating systems, the lock file is created to hold the process-id, application name (javax.comm), and username.

On all SCO UNIX platforms, certain parallel ports are also predefined and are known to the implementation. These are:

This predefined list may be overridden by specifying the property gnu.io.rxtx.ParallelPorts, similarly to the serial case described above.

Known Limitations

  1. When a serial port is locked out by another application, javax.comm will throw a PortInUseException exception object. If you call the getMessage method for that object, you will get a message containing the phrase "Port currently owned by unknown Solaris Application". (This message comes out of the Sun comm.jar binary implementation code and by license cannot be modified by SCO.) You may want to intercept this message in your application and change the text; see for example the change made to SerialConnection.java in the installed SerialDemo application.

  2. Because of the way serial I/O is implemented in the SCO OpenServer operating system, it is theoretically possible that javax.comm serial I/O will not perform satisfactorily if all of the other threads in the Java application in question are all CPU-bound. This would be a rare circumstance, but if it happens, either change some of the other threads to do any kind of Java I/O while the serial processing is taking place, or more simply, use the Java "green threads" time slicing option (e.g., java -Xts10 ...).

  3. The parallel I/O part of this implementation has been successfully tested for sending text to parallel local printers on both SCO OpenServer and UnixWare 7. However, there are a number of javax.comm methods in the ParallelPort class that are not supported in this implementation. These are: getOutputBufferFree isPaperOut isPrinterBusy isPrinterError isPrinterSelected isPrinterTimedOut notifyOnBuffer notifyOnError restart suspend setInputBufferSize getInputBufferSize setOutputBufferSize getOutputBufferSize . In addition sending events based on the parallel port device status is not implemented yet. For all of these methods, a dummy version is in place which will issue a diagnostic to the terminal when they are called (for some frequently-called methods, this message will only appear once) and then execution will proceed. The dummy is* methods will return false, and the get* methods will return a low value such as zero or one.

License and Open Source Considerations

The license for the part of the Sun Microsystems Java Communications API implementation for Solaris/x86, version 2.0 used in this implementation is available here. It provides for binary redistribution of the implementation; no source is provided by Sun or SCO.

The license for the open source RXTX project that is used as the base for this implementation is the GNU Library General Public License (LGPL), available here. Source for the version of RXTX used and for the modifications that SCO made to it is not included in the javaxcomm package, but is available from the SCO ftp site at ftp://ftp.sco.com/pub/unixware7/713/opensrc/rxtx-1.4-8.src.tar.gz.

The RXTX source base has advanced beyond the 1.4-8 version that this product is derived from. The SCO UNIX-specific changes there were made for this product have been given back to the RXTX project and have been incorporated into the more recent source versions. However at this time none of those more recent versions is operational on SCO UNIX platforms.

Last Updated: 2004-04-07

Copyright © 2004 The SCO Group, Inc. All Rights Reserved.

SCO, SCO OpenServer, and UnixWare are trademarks or registered trademarks of The SCO Group, Inc. in the U.S.A. and other countries.

Sun, Sun Microsystems, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries, and are used under license. UNIX is a registered trademark of The Open Group in the United States and other countries.

The SCO Group, Inc. reserves the right to change or modify any of the product or service specifications or features described herein without notice. This document is for information only. No express or implied representations or warranties are made in this document.