United States-English

» Contact HP

Release Notes

Software Development Kit (SDK) v 1.3.1-7
for the OpenVMS Alpha Operating System
for the Java™ Platform

» Introduction
» New Features
» Fixed Problems
» Compatibility
» Installation
» Contents of the SDK
» Using the SDK on OpenVMS Alpha Systems
» Documentation and Other Information
- » Documentation
- » More Information
» Problem Reporting

Introduction

Thank you for downloading the Software Development Kit (SDK) v 1.3.1-7 for the OpenVMS Alpha Operating System for the Java™ Platform (hereafter called the SDK). These release notes contain installation instructions, new features, known issues, fixed problems, usage documentation, and other information specific to the OpenVMS Alpha port of Sun Microsystems' Java™ 2 SDK, Standard Edition (J2SDK). This kit can be used to develop and run Java applets and programs on OpenVMS Alpha systems, Version 7.2-2 and higher.

Based on Sun’s J2SDK 1.3.1_10 Solaris Reference Release, the SDK v 1.3.1-7 kit implements J2SDK v 1.3.1 and passes all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). Use the java -version command to check the version of the SDK that you are using.

This kit contains two virtual machines:

The classic virtual machine (classic VM, the virtual machine shipped with prior releases) is based on Sun's reference implementation. The classic VM contains Just-In-Time (JIT) compiler technology, but does not have the performance of the Fast Virtual Machine (Fast VM). However, it provides additional debugging support not currently available in the Fast VM.
The Fast Virtual Machine, included in this kit, is no longer provided as a separate kit. Refer to Fast Virtual Machine (Fast VM) v 1.3.1 is Included with the SDK for more information. To learn more about the Fast VM, refer to Using the Fast VM.

You select which VM to use when you set up your Java environment. To set up your environment, use one of the following two commands, as described in Setting Up the Java Environment:

$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP FAST ! Use the Fast 
            VM

            $ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP ! Use the Classic VM

IMPORTANT: Please make sure you understand the Copyright (copyright.html, installed file) and License (license.html, installed file) information before using this release.

New Features

The following sections briefly describe the new features HP has included in SDK v 1.3.1. HP recommends that you read Sun's Java 2 SDK, Standard Edition, version 1.3 Summary of New Features and Enhancements for a thorough description of all new features and enhancements available in the J2SDK v 1.3.

SDK v 1.3.1-7 New Features

This kit installs SDK v 1.3.1-7, which is a maintenance with the following new features from HP.

File Permissions with `DECC$FILE_PERMISSION_UNIX` Enabled

The DECC$FILE_PERMISSION_UNIX logical name is now supported; for more information, refer to Enabling UNIX-Style Behavior in Certain File-Manipulation Commands.

Expiring Certificates Replaced

Expiring certificates in the SYS$COMMON:[JAVA$131.JRE.LIB.SECURITY]CACERTS.;1 file have been replaced with the latest updates.

SDK v 1.3.1-6 New Features

SDK v 1.3.1-6 was a maintenance release with the following new features from HP.

New Command Procedures

This release includes two new command procedures that may help you begin using the Java programming language on OpenVMS:

$ @SYS$COMMON:[JAVA$131.COM]JAVA$CONFIG_WIZARD.COM $ @SYS$COMMON:[JAVA$131.COM]JAVA$CHECK_ENVIRONMENT.COM

For more information, refer to Getting Started With the Java Programming Language on OpenVMS. HP would appreciate your opinion on whether you find these command procedures useful and how they could be improved in future iterations. Please use the Support page to provide feedback.

New Logical to Enhance Performance Tuning

Because some Web applications spend considerable time using Socket Streams with timeout values, the virtual machine makes use of C Runtime Library's select() function in a multi-thread nature. If the logical JAVA$TIMED_READ_USE_QIO is enabled, the virtual machine will use QIO(s) and AST(s) to implement the same functionality as select(). The result can be a reduction of overall kernel mode CPU usage, giving the application more available user mode CPU power. For more information, refer to Using JAVA$TIMED_READ_USE_QIO.

SDK v 1.3.1-5 New Features

SDK v 1.3.1-5 was a maintenance release with the following new feature from HP.

Additional Caching Available When `JAVA$CACHING_INTERVAL` is Enabled

A new logical name, JAVA$CACHING_DIRECTORY, is available to enhance the caching provided by JAVA$CACHING_INTERVAL. If JAVA$CACHING_INTERVAL is enabled and JAVA$CACHING_DIRECTORY is defined, the caching algorithm will attempt to find out the reason a file is "not found". If it is because a directory tree does not exist, the caching algorithm will be optimized to recognize that future attempts to this tree will also fail (until the directory has been created). This improves application startup for an application that has several directories defined in JAVA$CLASSPATH (or CLASSPATH). For more information, refer to Using JAVA$CACHING_INTERVAL in Application Performance Tuning.

SDK v 1.3.1-4 New Features

SDK v 1.3.1-4 was a maintenance release with the following new features from HP.

New Logicals

This release includes the following new logicals:

UNIX-like Behavior: The following logicals enable UNIX-style behavior for certain file-manipulation commands:

JAVA$DELETE_ALL_VERSIONS JAVA$RENAME_ALL_VERSIONS JAVA$CREATE_DIR_WITH_OWNER_DELETE

For more information, refer to Enabling UNIX-Style Behavior in Certain File-Manipulation Commands.

Debugging Tools: The following logicals can assist in debugging:

JAVA$PRINT_COMMAND_ARGS JAVA$ENABLE_SIGQUIT_CTRLC JAVA$ENABLE_SIGQUIT_MAILBOX
JAVA$FSYNC_INTERVAL

For more information, refer to Debugging Tools.

Performance Enhancement: The following logicals can improve performance for some applications:

JAVA$DAEMONIZE_MAIN_THREAD JAVA$READDIR_CASE_DISABLE

For more information, refer to the Using JAVA$DAEMONIZE_MAIN_THREAD and Using JAVA$READDIR_CASE_DISABLE in Application Performance Tuning.

Bypassing the 255-character DCL Command-Line Limit: With the following logical, the Run Time Environment (the RTE) expands any logical or symbol that begins with a "$":

JAVA$ENABLE_ENVIRONMENT_EXPANSION

For more information, refer to Using JAVA$ENABLE_ENVIRONMENT_EXPANSION.

Placement of Plug-Ins

As of Mozilla 0.9.9, the user can choose where to place plug-ins, depending on system-wide or individual components. For more information, refer to Placing Plug-Ins.

Installing Plug-ins for SWB

Information on installing plug-ins for the Secure Web Browser (SWB) has been added. For more information, refer to Placing Plug-Ins.

SDK v 1.3.1-3 New Features

SDK v 1.3.1-3 was a maintenance release with the following new features from HP.

Optional Optimization for Select Applications

Some applications spend considerable time creating files, monitoring directories for the existence of files, and testing properties of files using file methods. This continuous polling for changes in a monitored set of files can result in hundreds of unnecessary calls per second to the stat() function. If your application does these kinds of operation, you may benefit from the logical JAVA$CACHING_INTERVAL, which caches the information gathered by stat(). For more information, refer to Using JAVA$CACHING_INTERVAL in Application Performance Tuning.

New Logical to Help Debug `Runtime.exec()` Calls

The logical name JAVA$EXEC_TRACE is available to help debug Runtime.exec() calls on OpenVMS. When this logical is defined,

$ define/job JAVA$EXEC_TRACE true

a printout displays the C Runtime Library exec variant and its list of arguments. Refer to JAVA$EXEC_TRACE in Debugging Tools for more information on this and other diagnostic tools.

Improved Memory Utilization

Improvements have been incorporated that will lower the amount of program stack space needed under certain circumstances. Note, however, that for these improvements to be used, a new C Run Time Library (C RTL) is needed. For more information refer to Improving Memory Utilization By Reducing Filename Mapping.

Reduced Fast VM Memory Requirements

The Fast VM is optimized for large, long-running programs running on server systems. Many users would like to use the Fast VM on their workstations for client-side applications; however, some of these systems do not have the resources to start up the Fast VM with its default configuration. A -client switch has been added to address these needs. For more information, refer to Reducing Fast VM Memory Requirements for Workstations and Client-side Applications.

SDK v 1.3.1-2 New Features

SDK v 1.3.1-2 was a maintenance release with the following new features from HP.

Fast Virtual Machine (Fast VM) is Included with the SDK

The Fast VM is Just-In-Time (JIT) compiler technology designed to provide optimal Java runtime performance on OpenVMS Alpha systems. The Fast VM offers significant performance advantages over the Classic JIT provided with the SDK.

Starting with SDK v 1.3.1-2, the Fast VM is included with the SDK v 1.3.1 kit. The Fast VM was previously a separate download.

To learn more about the Fast VM, refer to Using the Fast VM.

Java `fork/exec` now supports C's VAXC$PATH

Before SDK v 1.3.1-2, if you didn't specify a classpath directory path, the Run Time Environment ( RTE) would search only in the default directory. Now, you can use VAXC$PATH as an OpenVMS search path for locating .EXEs or .COMs outside the default directory. For more information, see Supporting VAXC$PATH.

The logical name `JAVA$FORK_PIPE_STYLE` is available to augment the features offered by `JAVA$EXEC_USE_PIPES`

You can now choose among three styles of data flow management from a child process to its parent Java application using the JAVA$FORK_PIPE_STYLE. Included are the ability to more closely simulate a true UNIX pipe and improved performance. Refer to the section Using JAVA$FORK_MAILBOX_MESSAGES, JAVA$EXEC_USE_PIPES, and JAVA$FORK_PIPE_STYLE in Application Performance Tuning.

SDK v 1.3.1-1 New Features

SDK v 1.3.1-1 contained the following new features from HP.

Plug-in for the OpenVMS Operating System

SDK v 1.3.1 includes the Plug-in for the OpenVMS Operating System (hereafter called the Plug-in) that enables users to run Java applets and JavaBeans™ components on web pages using the RTE for the OpenVMS Operating System as an alternative to using the default virtual machine for Java 2 that comes with the Web browser. Based on the Java Plug-in 1.3.1 provided by Sun Microsystems, the Plug-in contains similar functionality. The Open JVM Interface (OJI) Plug-in is now supported. For more information, refer to Using the Plug-In.

Mozilla® 0.9.6 Browser Support

SDK v 1.3.1 includes support for Java plug-ins to the Mozilla® 0.9.6 browser. See Using the Plug-in to enable this support on your system.

Extended Capability for JAVAC and JAR

The capability of JAVAC and JAR commands to accept wild-carded file specifications and automatically determine the right case of the name has been extended to include any .java and .class operands for JAVAC and JAR. This capability is no longer limited to wild-carded file operands. For more information, refer to Case of JAVAC and JAR File Operands is Determined Automatically.

Optimization to Speed Up Class Loading in Some Instances

With this release, you can disable certain costly operations when you know they will not be needed because of how your application is organized. See Avoiding Secondary stat() call in Application Performance Tuning for a full explanation of this capability.

Choice of Keyboard Style

By default, the RTE responds to keystrokes, assuming they came from a PC-style keyboard with the "NumLock", "/", "*" and "-" (NUM_LOCK, DIVIDE, MULTIPLY, and SUBTRACT) on the top row of the numeric keypad.

When you are using a DIGITAL-style keyboard, which has different keys at the top of the keypad (PF1, PF2, PF3, and PF4), this interpretation will not be correct for certain keys.

If you define the JAVA$KEYBOARD_TYPE_DEC logical name as shown:

$ define/log JAVA$KEYBOARD_TYPE_DEC true

then the keys will be interpreted correctly for the DIGITAL-style keyboard. In addition to the keys mentioned, the "Find" and "Select" keys will behave as expected for a DIGITAL-style keyboard.

Fast VM v 1.3.1-1 New Features

Memory allocation and garbage collection algorithms have been improved for better performance and scaling on symmetrical multiprocessing (SMP) systems.
Compacting garbage collector: This version of the Fast VM supports an alternative compacting garbage collector, which compacts live data in-place, rather than copying it as the default collector does. This collector is a hybrid mark-sweep/mark-compact collector, which will avoid moving data when it is not necessary. This collection scheme can have better performance characteristics and lower heap size requirements for applications in which the heap contains a high percentage of long-lived data. This collector can also perform minor collections, rather than collecting the entire heap, when the percentage of live data is moderate. It can also perform sweeps, which free space without moving any data at all. Thus, it may also provide performance advantages for certain applications with a moderate amount of long-lived data, but a high rate of short-lived object turnover.

To use the compacting collector, specify the -Xgc:compacting option on the command line. The -Xgc:copying option causes the Fast VM to use the default "copying" collector.

Increased heap size: The maximum heap allocation has been increased from 512 MB to 900 MB. This increase benefits applications that use large amounts of memory and can increase performance in certain cases by decreasing garabage collections while running an application. Use the -Xmx and/or -Xms switches documented later in these release notes to control the amount of heap that is allocated.

Fixed Problems

This kit installs SDK v 1.3.1-7. The following sections provide important information about problems that HP has fixed in SDK v 1.3.1. HP recommends that you also review Sun's Java 2 SDK and Runtime Environment Important Bug Fixes and Changes documentation for information concerning bug fixes that Sun has made for this release.

Problems Fixed in SDK v 1.3.1-7

The SDK v 1.3.1-7 kit is based on Sun Microsystems' J2SDK 1.3.1_10 Solaris Reference Release and passes all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-7 contains the following HP-specific fixes:

Previously, when using the the Fast VM, if an object in the Java heap spanned more than a page of memory, and the compacting garbage collector performed a sweep operation, in rare cases a SEGV exception could occur on the subsequent collection. This has been corrected.
The Fast VM has been modified to always use P1 space for heap storage. This leaves more P0 space for application libraries and allows more threads to operate.

Both the Fast VM and the classic VM now support the debugging assistance provided by the JAVA$ENABLE_SIGQUIT_CTRLC and JAVA$ENABLE_SIGQUIT_MAILBOX logical names. Previously, only the classic VM supported those debugging assistance logical names.

Fast VM now supports the -Xrs option, as described on Sun's site.

Problems Fixed in SDK v 1.3.1-6

The SDK v 1.3.1-6 kit was based on Sun Microsystems' J2SDK 1.3.1_08 Solaris Reference Release and passed all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-6 contained the following HP-specific fixes:

Invoking java "-Xrunhprof:cpu=times" no longer access violates.
When running the JIT, an IncompatibleClassChangeError exception might occur. This has been corrected.

Invoking java "-Xrunhprof" <class_name> now works correctly instead of running out of memory.

This release fixes some access violation and IllegalAccessError errors that previously occurred when using the Fast VM.

Previously, an infinite loop occurred when running rmiregistry using the Fast VM. This problem has been fixed in this release.

Previously, if a Java application that used the System.currentTimeMillis() method was running and the Fast VM was the virtual machine in use, HP recommended not setting the system time back to a value that was earlier than the time the Java application was started. This restriction has been lifted.

Problems Fixed in SDK v 1.3.1-5

The SDK v 1.3.1-5 kit was based on Sun Microsystems' J2SDK 1.3.1_04 Solaris Reference Release and passed all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-5 contained the following HP-specific fixes:

Close() I/O issue in multithreaded environment: Previously, in a multithreaded environment, if one thread was doing a read and a second thread proceeded to close the file descriptor, a memory corruption could occur. (The former thread would continue to access a file descriptor that had already been freed.) Eventually, this would lead to a random access violation. Now available is a C RTL ECO that corrects this problem. See the product page on the Web site for more information.

SDK v 1.3.1-4 for OpenVMS Alpha introduced a regression in command-line option switch processing. In SDK v 1.3.1-4, only in the case of the Fast VM, a defined CLASSPATH or JAVA$CLASSPATH logical would incorrectly override the -classpath option of the command line. This has been corrected so that if the -classpath option is on the command line, it will override the value of the logicals CLASSPATH and JAVA$CLASSPATH.

Fixed a problem that could have resulted in a hang condition with JAVA$CACHING_INTERVAL.

Problems Fixed in SDK v 1.3.1-4

The SDK v 1.3.1-4 kit was based on Sun Microsystems' J2SDK 1.3.1_04 Solaris Reference Release and passed all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-4 contained the following HP-specific fixes:

SDK v 1.3.1-3 for OpenVMS Alpha introduced a regression in the processing of some command-line parameters when using the Fast VM. If you have a program that obtains and prints out the value of properties that are specified on the command line, and the specification of the property occurs more than once, the last such specification is what should determine its value.
For example, if you have a command that contains:

$ java "-DMyArg=First" "-DMyArg=Second" "test_arg_interp"

the value assigned to MyArg should be the last one, that is, the value "Second".

In SDK v 1.3.1-3 the first value ("First") was erroneously assigned.

This error has been corrected in SDK v 1.3.1-4.
Major set-up files have been modified to reduce the output displayed when running them more than once. Also, because the SDK no longer supports the DCL-style command-line interface (DCL /qualifiers versus UNIX -switches) the message, "Setting up symbols for foreign command-line usage...." has been removed.

Fixed problem with NoClassDefFoundError exception not being correctly thrown in compiled code.

Under SDK v 1.3.1-3 or earlier, when an application used the change directory feature of Runtime.exec(), the Java Virtual Machine would throw a "function not implemented" exception. This release provides a temporary workaround, as described in Changing the Working Directory Within Runtime.exec().

This release provides a fix to the "-V" method of bypassing the 255-character command-line length limitation. In earlier releases, if, within the data file, used as input to "-V" processing, an operand had white space, it would not be parsed correctly. For more information on the new logical that addresses this issue, refer to the JAVA$DISABLE_CMDFILE_WHITESPACE_PARSING logical description in Known Issues.

This release contains a performance enhancement for BEA WebLogic™.

This release contains enhancements to the RandomAccessFile class. The RTE now correctly shares random-access files within the same Java process. In previous versions of the RTE, the Java process did not correctly handle shared read and write operations to the same file. This condition usually happened only if the file was opened for "Read" and then opened for "Read/Write" later in the same process.

Problems Fixed in SDK v 1.3.1-3

The SDK v 1.3.1-3 kit was based on Sun Microsystems' J2SDK 1.3.1_02 Solaris Reference Release and passed all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-3 contained the following HP-specific fix:

This release serializes (synchronizes) access to the RTE's native exec() code to avoid possible data corruptions when spawning a child process via Runtime.exec() methods. Previously there was a small window where such corruption could occur with unpredictable results.

Problems Fixed in SDK v 1.3.1-2

The SDK v 1.3.1-2 kit was based on Sun Microsystems' J2SDK 1.3.1_02 Solaris Reference Release and passed all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-2 contained the following HP-specific fix:

Enabled correct operation of File (fname) when fname is a logical or a disk name: In SDK v 1.3.1-1 a fix was added to correct a problem that occurred when you tried to open a file using certain rooted logicals; however, this workaround created problems with nonrooted logicals. For SDK v 1.3.1-2, the errant fix has been removed. However, if you did not experience problems and did benefit from the SDK v 1.3.1-1 fix, you can explicitly select this behavior by defining a logical name. Refer to Enabling Correct Operation of File (fname) When fname is a Logical or a Disk Name.

Problems Fixed in SDK v 1.3.1-1

The SDK v 1.3.1-1 kit was based on Sun Microsystems' J2SDK 1.3.1_01 Solaris Reference Release and passed all the tests in Sun's Java Compatibility Kit test suite (JCK V1.3a). SDK v 1.3.1-1 contained the following HP-specific fixes:

The Fast VM v 1.3.1-1 includes the following fixes:
- Certain applications require a large number of open files at one time. The default value of allowed open file descriptors has been increased to 32K. This change fixes a potential memory corruption problem for these applications.
- A socket close operation would sometimes hang. This problem has been fixed in this release.
Fixed erroneous destruction of mutex and condition variables belonging to main thread: All threads except the main thread need synchronization during thread creation. This involves creating and initializing a special mutex and condition variable. Because the main thread does not need the extra mutex/condition variables, the RTE does not initialize these variables; however, in prior versions of SDK v 1.3.*, the RTE, during thread rundown, always destroyed all the mutex/condition variables, even those for the main thread.

This did not cause any real harm, but caused programs like Visual Threads that monitor thread operation to report mutex.destroy and condition.destroy "Rule Violations." In this release, this has been changed so that the special mutex and condition variables are destroyed only if the threat is not the main thread.

Fixed a problem passing environment variables via java.lang.Runtime.exec() call: In earlier versions of SDK v 1.3.*, the user would experience an Access Violation exception when passing environment variables to processes that were created using the java.lang.Runtime.exec()call.

Fixed a problem with thread cancellation point: In prior versions of SDK v 1.3.*, the RTE could not close a socket when there was a read pending on the socket. If one thread were trying to read from a socket, and another thread attempted to close the socket, the thread doing the close would hang. Similarly, attempts to cancel a thread with outstanding I/O would not be possible. These have been fixed so that they are now possible. This allows the orderly rundown of I/O on the channel being used by the thread being cancelled. (Note that cancelling an I/O operation in midoperation can result in a loss of data and the user's application bears the responsibility of dealing with this loss.)

Fixed error in parsing of Locale string: In prior versions of SDK v 1.3.* and SDK v 1.2.2 an error was introduced in the computation of the string returned by:
Locale.getDefault().toString()

For example, it would return:

ja_JP.eucJP instead of ja_JP

and

fr_FR.ISO8859-1 instead of fr_FR.

This has been corrected in this release.
Increased the size of strings that can be supplied via the files specified by the "-V" switch: Specifically, this allows users to use much larger Classpath strings.

Added new font converters to support new encoding:

jisx0208.1983-1 encoding
dec.cns11643.1986-2 encoding
gb2312.1980-1

This allows a greater variety of fonts to be specified in some foreign-language font.properties, e.g., Japanese font.properties.ja files.

Keyboard enhancements/fixes include several new key definitions that make it possible to use older-style DIGITAL keyboards and eXcursion mappings. Also, revised handling of <ALT> key allows menus and buttons to be activated from the keyboard via accelerator keys.

Certain numeric keypad keys did not work when using the eXcursion window manager or DIGITAL keyboards. Keys "/", "*", "-", "+", "Home", and "End" now work correctly. These keyboard problems did not exist for PC keyboards when using CDE or Motif.

Memory leaks in code that deals with reading directories have been cleaned up; these leaks were exposed in servers that run for long periods.

In some situations users might have encountered a java.security.AccessControlException: access denied (java.net.NetPermission setDefaultAuthenticator), because of a problem parsing and correctly interpreting a "-" character in a net permissions .policy file. This error has been corrected.

An error attempting to obtain the the local timezone in GMT format from class Date has been corrected in this release.

In the 1.3.1-beta release, when operating with eXcursion, attempts to highlight text and copy to the clipboard in an application would hang the application. This now functions properly.

We also recommend that you review Sun's J2SDK 1.3.1 Important Bug Fixes and Changes documentation for information concerning bug fixes Sun has made for this release.

Compatibility

SDK v 1.3.1 is compatible with previous versions of the SDK. Most existing programs will run on SDK v 1.3.1 platform. However, some important incompatibilities do exist and are thoroughly discussed in Sun's Java 2 Platform Compatibility with Previous Releases document. For specific incompatibilities, refer to the section, Incompatibilities in the Java 2 Platform, Standard Edition, v1.3, on the Sun site.

Installation

The following sections describe how to install the SDK kit on your OpenVMS Alpha system.

Prerequisites

The prerequisites for installing this kit are:

OpenVMS Alpha Version 7.2-2 or higher. See Mandatory Patches below.
Compaq TCP/IP Services for OpenVMS Alpha V5.0A or higher (and required patches).
DECWindows Motif V1.2-4, if you plan on AWT use.
Mandatory Patches: To successfully install and run SDK v 1.3.1 for OpenVMS Alpha, mandatory prerequisite patches must be installed. For more information, refer to the product page on the Web site.

Installing the Kit

To install the SDK v 1.3.1-7 kit:

Download and install the prerequisite ECOs.

Download the file DEC-AXPVMS-JAVA131-V0103-17-1.PCSI_SFX_AXPEXE (~63,000 blocks) from our Software Download page and execute it to unpack it and obtain the original DEC-AXPVMS-JAVA131-V0103-17-1.PCSI file (~180,000 blocks):
$ RUN DEC-AXPVMS-JAVA131-V0103-17-1.PCSI_SFX_AXPEXE

Note: When you are downloading the file to an ODS-5 disk on OpenVMS Version 7.2-2 or higher, the unpacking operation might convert the filename into lower case. Convert it to upper case before proceeding; for example:

$ RENAME dec-axpvms-java131-v0103-17-1.pcsi - DEC-AXPVMS-JAVA131-V0103-17-1.PCSI
Extract the Release Notes for this kit:
$ PRODUCT EXTRACT FILE JAVA131 - /SOURCE=[directory_where_you_put_the_PCSI_file]- /SELECT=RELEASE_NOTES.HTML- /DEST=[] - /BASE_SYSTEM=AXPVMS
Install the SDK v 1.3.1-7 kit from the .PCSI file obtained, using the PCSI (POLYCENTER Software Installation) utility PRODUCT command:

$ PRODUCT INSTALL JAVA131- /SOURCE=[directory_where_you_put_the_PCSI_file]- /BASE_SYSTEM=AXPVMS
The SDK gets installed in root directory SYS$COMMON:[JAVA$131].

Also, the following files are installed by the PCSI utility with file attribute of ARCHIVE:

SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM SYS$COMMON:[JAVA$131.JRE.LIB]FONT.PROPERTIES SYS$COMMON:[JAVA$131.JRE.LIB]FONT_PROPERTIES.JA

If a file having any of these names already exists on the system, the installation process renames it to a new name with a filetype ending in _OLD, before loading the new copy from the kit. Only the latest version of the existing file is preserved (by being renamed to file.type_old) before PCSI deletes all remaining versions.

For example, an existing SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM is renamed to SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM_OLD before the new copy is copied from the kit.

If you have previously personalized any of these files, you might need to merge your personalizations with the new copies.

Notes:

The PCSI PRODUCT tool for OpenVMS Alpha installs different versions of the SDK using unique product names. For example:

SDK v 1.1.8-n and SDK v 1.1.6-n are installed as product JAVA

SDK v 1.2.2-n is installed as product JAVA122

SDK v 1.3.0-n is installed as product JAVA130

SDK v 1.3.1-n is installed as product JAVA131

Therefore, if you decide to update to an earlier or later version of the SDK within the same product, you should not use the PCSI PRODUCT REMOVE command. Instead, use the PRODUCT INSTALL of the desired kit. By following these instructions you avoid potential shared-file conflicts.

Installing in the SYS$COMMON area requires privileges. The SYS$COMMON:[JAVA$131] directory is the supported location for the installation of this kit.

To use SDK v 1.3.1-7, you must first set up the Java environment. You can select either the classic VM or the Fast VM as your virtual machine.

Because you can have multiple SDK versions installed on your OpenVMS system, and because you can change from one version to the other, you need to follow specific steps to set up your Java environment properly. To run the command procedure to do this, refer to Setting Up the Java Environment.
Refer to Using the SDK on OpenVMS Alpha Systems for additional information on how to use this product in an OpenVMS environment. A local copy of these Release Notes is installed at SYS$COMMON:[JAVA$131.DOCS]RELEASE_NOTES.HTML.

Installing the API Reference Documentation

You can also download and install the API reference documentation for SDK v 1.3.1, to provide you with a local copy. Allow 201,000 blocks of permanent disk space for the installed API reference files.

Note: If you previously installed both the SDK and API documentation for earlier versions of SDK v 1.3.1, you do not need to repeat the installation of the API reference documentation for the SDK v 1.3.1-7 kit. The API reference documentation is the same; however, if you did not install the API reference documentation for an earlier version of SDK v 1.3.1, please note the installation instructions that follow.

Install the API documentation in the same way you installed the kit:

Copy the API documentation file DEC-AXPVMS-JAVAAPIDOC131-V0103-11-1.PCSI_SFX_AXPEXE (18,000 blocks) by viewing the Software Download page and clicking on the software kit and following the path to download the kit. Next, execute the file to unpack it and obtain the original DEC-AXPVMS-JAVAAPIDOC131-V0103-11-1.PCSI file:
```
$ RUN DEC-AXPVMS-JAVAAPIDOC131-V0103-11-1.PCSI_SFX_AXPEXE
```

When you are downloading the file to an ODS-5 disk on OpenVMS Version 7.2-2 or higher, the unpacking operation might lowercase the filename. Make sure to convert it to upper case before proceeding. For example:
```
$ RENAME dec-axpvms-javaapidoc131-v0103-11-1.pcsi -
     DEC-AXPVMS-JAVAAPIDOC131-V0103-11-1.PCSI
```
Install the API documentation from the .PCSI file obtained, using the PCSI (POLYCENTER Software Installation) utility PRODUCT command:
```
$ PRODUCT INSTALL JAVAAPIDOC131-
     /SOURCE=[directory_where_you_put_the_PCSI_file]-
     /BASE_SYSTEM=AXPVMS
```
The API documentation files are installed in the following directories:
```
SYS$COMMON:[JAVA$131.DOCS.API]INDEX.HTML (frames)
SYS$COMMON:[JAVA$131.DOCS.API]OVERVIEW-SUMMARY.HTML (no frames)
```

Determining Your Installed Version

After downloading, installing, and running the command procedure to set up the Java environment, use the java -fullversion command to display the version. For example:

$ java -fullversion
  java full version "1.3.1-7"

To switch from one version to another, see Switching Versions.

Contents of the SDK

This section provides a general summary of the files and directories contained in the SDK once it has been installed on your system.

Development Tools

In SYS$COMMON:[JAVA$131.BIN]

This area contains programs that will help you develop, execute, debug, and document programs written in the Java programming language. For further information, see Sun's Tools and Utilities page.

Important: Review the information in the Interpreting Commands and OpenVMS Operating System Differences table to fully understand the nuances and differences in the SDK on OpenVMS Alpha.

Though Sun's Tools and Utilities documentation specifies all the details about operating various tools, you must interpret the literal examples of commands with an eye to OpenVMS Alpha differences.

Note: It is imperative that you understand these differences if you want to operate these tools successfully on OpenVMS Alpha.

Getting Started with the Java Programming Language on OpenVMS

The following two command procedures may assist you in getting started using the Java programming language on OpenVMS Alpha. The files help you determine whether you are set up to run the Java programming language (quota-wise) and to generate a configuration file of $ DEFINE commands that you could invoke after running JAVA$131_SETUP.COM.These command procedures are independent of JAVA$131_SETUP.COM.

The first command procedure can be found in:

SYS$COMMON:[JAVA$131.COM]JAVA$CONFIG_WIZARD.COM

When you execute the following procedure:

$ @SYS$COMMON:[JAVA$131.COM]JAVA$CONFIG_WIZARD.COM

you are asked several questions about your environment and the Java application you intend to run.

Based on your answers, it generates a command procedure file (called JAVA$CONFIG_SETUP.COM) which, when executed, sets up the logical names that are appropriate for your intended usage.

The second command procedure can be found in:

SYS$COMMON:[JAVA$131.COM]JAVA$CHECK_ENVIRONMENT.COM

When you execute the following procedure:

$ @SYS$COMMON:[JAVA$131.COM]JAVA$CHECK_ENVIRONMENT.COM

it tests the process quotas in the current process and warns you if some of your account and sysgen quotas are not up to recommended level for running Java programs.

The following example illustrates a typical pattern for using these command procedures:

$ @SYS$COMMON:[JAVA$131.COM]JAVA$CHECK_ENVIRONMENT.COM !One time-Am I set up quota-wise to run Java? $ @SYS$COMMON:[JAVA$131.COM]JAVA$CONFIG_WIZARD.COM !One time-Build me a JAVA$CONFIG_SETUP.COM for my intended usage

$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM {FAST} !Set up the Java environment, select VM $ @JAVA$CONFIG_SETUP.COM !Define my tailored set of logical names

Note: If you choose to run JAVA$CONFIG_SETUP.COM, be sure to run it after running JAVA$131_SETUP.COM.

Interpreting Commands and OpenVMS Operating System Differences
OpenVMS Usage	Explanation
`Stream_LF`	All files read by Java code (`.java`, `.class`, `.jar`, etc.) must have a `Stream_LF` record format. To learn how to check whether files are `Stream_LF` and how to convert them if they are not, see `Stream_LF` File Format Required. Files created by Java tools will automatically be `Stream_LF`.
Role of `JAVA$CLASSPATH`	A number of tools rely on either a -classpath argument on the command line, or rely on the setting of a logical `CLASSPATH`--a colon-separated search list of directories in UNIX-style filename syntax. Sometimes it is easier to fabricate a comma-separated search list of directories in OpenVMS-style file syntax. This is done with a logical named `JAVA$CLASSPATH`. See Setting `JAVA$CLASSPATH` for details on `JAVA$CLASSPATH` and its interaction with `CLASSPATH` and `-classpath`.
Quoting Operand	Certain operands need to be quoted; Java tools are case-sensitive throughout their operation. Command-line operands are automatically lower-cased as they are acquired from the command line. In order to preserve the case so that these operands are acceptable to Java commands, you must quote them. The most common instances of this are: Need to quote upper-case switches Memory allocation on Java command. `$ java "-Xmx64m" mytest` Need to quote class names and package names Class name specification `$ java "MyPackage/MyTest"` Need to quote upper-case keywords Encoding type keyword `$ native2ascii -encoding "ISO8859_1" data.txt data.txt` See Known Issues for further discussion and examples of where quoting is needed.
Combating limitations on DCL command line length	DCL command-line length is limited to 255 characters. Constructing longer command lines is frequently convenient (and sometimes necessary). To work around this limitation on the OpenVMS Operating System, the RTE has been customized to allow you to place operands into a data file and then simply point to the data file on the command line. For example, you can type: `$ javac "-V" FILES_TO_COMPILE.DAT` where `FILES_TO_COMPILE.DAT` contains (the potentially long) list of files to compile. See Command lines on OpenVMS Alpha cannot exceed 255 characters for further discussion of this capability. Note that the `-V` is quoted for reason cited above.
Dealing with UNIX-style filenames that cannot be represented on OpenVMS Alpha	The OpenVMS file system on ODS-2 formatted disks cannot represent certain legitimate UNIX-style file names; for example, a file named font.properties.ja cannot be created. On OpenVMS Alpha, the RTE supports a filename remapping strategy that allows you to represent otherwise-unrepresentable filenames via a filename-mapping capability. This allows you to specify, for example, that all filenames presented with mulitple dots in their names should be stored and retrieved as if all of the dots, except the last, have been replaced by underscores; hence the file above would be methodically read and written as if it were named `font_properties.ja`. To learn more about other possible filename mappings, see UNIX-Style Filenames on OpenVMS Systems.
Getting around limitation of directory depth of 8 on ODS-2 disks	The OpenVMS file structure on ODS-2 formatted disks limits you to only eight levels of directories. It is not uncommon for Java programs imported from elsewhere to have a package structure that is more than eight levels deep. To circumvent these limitations on OpenVMS Alpha, the RTE supports a filename remapping strategy that allows you to represent the deeper structure in a more shallow directory. Refer to Description of Mapping Options to see how this is accomplished.
See Known Issues for more descriptions of how the OpenVMS Operating System differs from the UNIX environment in which the Java platform originated.

Run Time Environment (RTE)

In SYS$COMMON:[JAVA$131.JRE]

An implementation of the Run Time Environment (RTE) for use by the SDK. The runtime environment includes a virtual machine for Java 2, class libraries, and other files that support the execution of programs written in the Java programming language. (Note: The RTE included in the SDK is separate from the RTE kit.)

Additional Libraries

In SYS$COMMON:[JAVA$131.LIB]

Additional class libraries and support files required by the development tools.

Demo Applets and Applications

In SYS$COMMON:[JAVA$131.DEMO]

Examples, with source code, of programming for the Java platform. These include examples that use Swing and other Java Foundation Classes.

C Header Files

In SYS$COMMON:[JAVA$131.INCLUDE]

Header files that support native-code programming using the Java Native Interface and the Java Virtual Machine Debugger Interface, as described on the Sun site.

Source Code

In SYS$COMMON:[JAVA$131]SRC.JAR

Java programming language source files for all classes that make up the Java 2 core API (that is, source files for the java.*, javax.* and org.omg.* packages, but not for com.sun.* packages). This source code is provided for informational purposes only, to help developers learn and use the Java programming language. These files do not include platform-specific implementation code and cannot be used to rebuild the class libraries. To extract these files, use this command:

   jar xvf src.jar

Do not modify core API source files. To extend the behavior of the core API, write subclasses of the core API classes.

For core API documentation, refer to the following sources:

The Java Platform API Specification:
- Installed, as described in Installing the API Reference Documentation.
- On Sun's Java 2 Platform, Standard Edition, v 1.3.1 API Specification
The API documentation provides brief descriptions of the API with an emphasis on specifications, not on examples.

The Java Class Libraries, Second Edition, published by Addison-Wesley Longman as part of The Java Series, as described on Sun's site. These volumes include much more elaborate descriptions, with definitions of terminology and examples for practically every class, interface, and member.

Known Issues

This section provides descriptions of the known issues and limitations that exist in the SDK v 1.3.1 kit for OpenVMS Alpha; these issues include the following:

The java.awt.Robot class: MOTIF 1.2, the latest version available on OpenVMS Alpha, does not provide adequate support.
Correspondence between directory info in _java.policy and default directory: You must have a direct correspondence between the way you specify a directory in a _java.policy file and your current directory when used as part of the CLASSPATH. (Your current default directory is always part of your implied classpath.)
For example, if your policy files say:

grant codeBase "file:${rootdir}/-" { permission java.security.AllPermission; };

and you invoke your application (in part) as:
$ java -Drootdir=/DISK1$/directory/subdirectory/

you must get to that directory via:
$ SET DEF DISK1$:[directory.subdirectory]

You cannot use an alias such as:
$ SET DEF USER1$:[directory.subdirectory]

even if USER1$ is the same disk as DISK1$, because the entire permission process (to determine allowable access) is based on the comparison of file specification strings. From a string-comparison standpoint (even case-blind), USER1$:[directory.subdirectory]is not the same path as DISK1:[directory.subdirectory],and access will be denied.
Javadoc fails to distinguish class and package names that reside in the same directory and differ only in case. An example is the package java.awt.event and the class java.awt.Event.
Javald has not been ported to the SDK v 1.3.1 for OpenVMS.
Starting with SDK v 1.3.0-1, the SDK contains better graphic performance than previous SDK v 1.2.2 releases. However, some graphics operations remain slower in the releases beginning with SDK v 1.3.0-1 than they do in SDK v 1.1.n releases.
With Java 2, Sun changed the underlying architecture of the graphics subsystem. In Sun's Java Development Kit (JDK) V1.1.n, more of the graphics operations were done using native code. For example, the drawLine() method would result in a call to XDrawLine. With Java 2, the rendering of graphics has been moved to Java code, which computes the image and sends the pixels out to the display. As a result, the performance of graphical operations can be slower with J2SDK v 1.3.1, particularly when displaying to a remote machine.

Consequently, the slow performance that you see with some graphics operations is not specific to the SDK, but is inherent in the architecture of Java 2.

Sun has received a number of bug reports on this performance problem. For example, see the following list of bug reports in the Bug Database at Sun's Developer Services web site: 4204845, 4185726, 4217446, and 4210230. Once you have logged in (you have to register, but it is free), just follow the link to the Bug Database.
Java Sound is not supported. The following error is reported if you attempt to use Java Sound:
```
Java Sound support not currently available
```
The presence of a file named .; on the classpath (a file with no name or extension) will result in a failure to find the class file specified on the command line. Note the following example:
```
$ java helloworld 
Hello world.


$ create . 
EXIT 
$ java helloworld 
Exception in thread main java.lang.NoClassDefFoundError: helloworld
```
The VolanoMark™ benchmark requires a large buffered I/O byte count quota. If you plan to try out the VolanoMark benchmark, increase the byte count quota to around 3 million. Otherwise, Volano will exhaust all buffer I/O resources and hang the system.
When seeking beyond the end of a file, the default behavior of the C RTL is to physically extend the file. Depending on the offset specified in the seek operation, this can take a long time. This behavior differs from most UNIX. systems, where the file is only extended if you write to it after the seek operation.
Workaround: To enable the UNIX behavior on OpenVMS systems, uncomment the definition of the DECC$POSIX_SEEK_STREAM_FILE logical in the JAVA$131_SETUP.COM file.
Multiple listeners can bind to the same socket — a nonportable behavior.
On OpenVMS systems, TCP/IP allows multiple listeners to bind to the same socket. This behavior is different from that exhibited on some other operating systems, where this phenomenon is detected and the following exception is thrown:
```
  "java.net.BindException: Address already in use"
```
This is not a behavior specific to the RTE, but the way that TCP/IP Services works on OpenVMS systems. This difference is noted to caution you from relying on this exception if you intend to write portable Java applications.
Command lines on OpenVMS Alpha cannot exceed 255 characters.
This means you cannot build command lines like the following:
```
 	 $ javac "MyClass001.java" -
                  "MyClass002.java" -
                  "MyClass003.java" -
                   ...
                  "MyClass127.java" -
                  "MyClass128.java" 
```
To circumvent this shortcoming, use the @files feature of the SDK that allows you to put command operands in another file and simply name that operand file prefixed with an @ sign.

For example, you can write the following:
```
        $ javac @CLASS_LIST_FILE.DAT
```
where CLASS_LIST_FILE.DAT contains:
```
                MyClass001.java
                MyClass002.java
                MyClass003.java
                ...
                MyClass127.java
                MyClass128.java
```
Another usage is:
```
        $ javac @sys$input:
                MyClass001.java
                MyClass002.java
                MyClass003.java
                ...
                MyClass127.java
                MyClass128.java
```
Note that operands on the command line need to be in quotation marks to keep DCL from uppercasing the arguments, but the same arguments in a file do not need to be in quotes because they are not directly interpreted by DCL. File names appearing in the input file specified by @ should be in UNIX format rather than OpenVMS format and should not be in quotation marks. Also note that on OpenVMS, you can use "-V" in place of @files to achieve the same behavior. You can use "-V" with other Java commands in addition to javac; for example, you can write the following:
```
        $ java "-V" name_of_file_containing_operands.dat
```
Note: The existence or accessibility of the file specified by -V is not tested. If the file does not exist or cannot be opened, then no additional data is added to the command line being built; no error is reported.

If, within the data file used as input to "-V" processing, an operand has white space, it will not be parsed correctly.

For example, the quoted argument on the following command line

$ java xargs "< = 1" 2 3

will work. The arguments will be interpreted as:
< = 1 2 3

If you put the parameters into a data file called datafile1.txt, e.g.,
< = 1 2 3and then access them via:$ java xargs "-V" datafile1.txtthey will be interpreted as:
< = 1 2 3

The white space breaks up the processing of the line.

Even if you enclose the operand in quotes, as in a data file called datafile2.txt,
"< = 1" 2 3

and then access them via:

$ java xargs "-V" datafile2.txt

they will be interpreted as:
"< = 1" 2 3The white space still breaks up the processing of the line. Note that the quotation marks are retained.

The JAVA$DISABLE_CMDFILE_WHITESPACE_PARSING logical name enables you to provide operands that contain white space within the data file.

$ define/job JAVA$DISABLE_CMDFILE_WHITESPACE_PARSING TRUE

When this logical is defined, spaces and tabs are no longer treated as delimiters in "-V" files. Each line in the file is treated as a single command-line argument.

Note: If the line contains a space, this space will be included as part of the command argument.

For example, in:

$ create java_input.dat param1 param2 ^Z

$ java "-V" java_input.dat

Without the logical JAVA$DISABLE_CMDFILE_WHITESPACE_PARSING defined, the RTE sees two command line arguments: param1 and param2.

With the logical JAVA$DISABLE_CMDFILE_WHITESPACE_PARSING defined, the RTE sees only one command-line argument, param1 param2.

You can use the _JAVA_LAUNCHER_DEBUG logical name as a diagnostic tool, to see the arguments as they are passed to the Java Virtual Machine.

Alternatively, you can provide these parameters on the command line itself.
Approximating functionality that does not exist:
OpenVMS systems do not have a dlopen, dlsym, and/or dlclose runtime routine. To be able to support dynamically loaded runtime libraries, we have created dlopen, dlsym, and dlclose routines using LIB$FIND_IMAGE_SYMBOL (FIS).

FIS does not support pure dynamically linked library in the same manner as dlopen does. FIS does NOT resolve global symbols from other shareable libraries at runtime. Under OpenVMS, this must be done at link time, and not at run time.

Example:

The Java Zip RTL library needs java_lang_String_intern, which is declared in the main Java library (JAVA.SO). On UNIX systems, dlopen resolves this external global at runtime.

On OpenVMS systems, because FIS does NOT resolve any external globals at runtime that were not found at link time, the Java Zip library must be linked against the main Java library to allow java_lang_String_intern to be found at runtime.

Problem displaying to a VAXstation

You may see the following message when trying to display to a VAXstation:

     X error event received from server:  BadValue (integer parameter out of 
                                                     range for operation)
     Major opcode of failed request:  61 (X_ClearArea)
     Value in failed request:  0xffff****
     Serial number of failed request:  ###

     Current serial number in output stream:  ###
     %XLIB-E-ERROREVENT, error event received from server
     %TRACE-E-TRACEBACK, symbolic stack dump follows

     (* indicates a variance in the occurrence of the width & height)
       This is a problem with (width, height).

The OpenVMS server implements these parameters (width, height) as a signed word as opposed to CARD16 (unsigned word) as specified by the X Windows System Protocol. Hence, anything over 32767, (hex 7fff) is unacceptable to an OpenVMS server.

To fix this, in file SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.COM, specify:

$DEFINE/TABLE=DECW$SERVER0_TABLE   DECW$CARD16_VALIDATE  TRUE

Some images do not exit on ^Y when another image is started.
A small number of Java utilities (javap, javah, and verify), do not exit cleanly if they are aborted with a ^Y.

When you then type another command, or even $ EXIT, you might find that you have to do a second ^Y and another $ EXIT in order to stop all the threads that are running on your behalf.

If the application is deadlocked, holding a resource required by one of the exit handler's routines, the application will continue to hang, even after typing ^Y and EXIT. In these cases, type a second ^Y and STOP to terminate the application without running exit handlers. This behavior is not unique to Java applications but is characteristic of DECthreads operating in a multithreaded environment. See the Guide to DECthreads for a fuller discussion of this issue.
Japanese text fonts
When using Japanese Motif, you should use the following font specification sizes 8, 10, 12, 14, 18, or 24. When other sizes are specified by an application, Ja