|
|
United States-English | |
|
|
 |
|
Release NotesSoftware Development Kit (SDK) v 1.3.1-7for the OpenVMS Alpha Operating System for the Java™ Platform
|
|
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| UAF Fillm | 4096 |
| Channelcnt | 4096 |
| Wsdef | 2048 |
| Wsquo | 4096 |
| Wsextent and Wsmax | 16384 |
| Pgflquo | 2097152* |
| bytlm | 400000 |
| biolm | 150 |
| diolm | 150 |
| tqelm | 100 |
*A good number for Pgflquo is (2 x heap-size), for example, 128 MB (2*128*1024*1024)/512 = 524288. Recall that the recommended minimum Pgflquo is 96 MB when using the RTE. When you increase the Pgflquo parameter, you should always increase the system's page file size to accommodate the new Pgflquo parameter, if needed.
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:
$ @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
To set up the Java environment with the
Fast VM your as virtual machine, use the FAST parameter
on the following command:
$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP FASTVerify your Java environment by typing the
java -versioncommand. The screen displays the following message:$ java -version java version "1.3.1" Java(TM) 2 Runtime Environment, Standard Edition Fast VM (build 1.3.1-n ...)where n identifies the specific SDK v 1.3.1 that is installed, and
Fast VMidentifies the virtual machine.
To set up the Java environment with the classic VM as your virtual machine, type the following.
$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COMVerify your Java environment version by using the
java -versioncommand. The screen displays the following message:$ java -version java version "1.3.1" Java(TM) 2 Runtime Environment, Standard Edition Classic VM (build 1.3.1-n ...)where n identifies the specific SDK v 1.3.1 that is installed, and
Classic VMidentifies the virtual machine.Note: To revert to the Fast VM, type the following command:
$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP FAST
After setting up the Java environment, you invoke the SDK with
the Java command:
Java Usage: Java [-options] classname [args]
Any arguments that appear after classname on the
command line are passed to the main method of the class.
For information on switching versions in separate processes, or in the same process, refer to Switching Versions.
As noted in the Introduction, this kit contains two virtual machines. 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. The following sections describe how to control the Fast VM.
You select which VM to use when you set up your Java environment. To set up the Java environment using the Fast VM, refer to Setting Up the Java Environment.
The Fast VM supports the following standard options:
| Option | Function |
|---|---|
|
|
Specify a list of directories,
JAR archives, and ZIP archives to search for user class files.
Class path entries are separated by colons (:).
Specifying If |
|
|
Initializes the Fast VM with a maximum heap size of 64 MB, a maximum global region size of 128 MB and the compacting collector. Refer to Reducing Fast VM Memory Requirements for Workstations and Client-side Applications for more information. |
|
|
Set a system property value. |
|
|
Display usage information and exit. |
|
|
Execute a program encapsulated in a JAR file. The first argument is the name of a JAR file instead of a startup class name. In order for this option to work, the manifest of the JAR file must contain a line of the form Main-Class: classname. Here, classname identifies the class having the
When you use this option, the JAR file is the source of all user classes, and other user class path settings are ignored. |
|
|
Display information about each class loaded. |
|
|
Report on each garbage collection event. |
|
|
Report information about use of native methods and other Java Native Interface activity (JNI). (This option can be specified but it has no effect.) |
|
|
Display version information and exit. |
|
|
Display usage information for non-standard options and exit. |
This version of the Fast VM also includes support for the following
Java nonstandard options.
| Option | Function |
|---|---|
|
|
Specify a colon-separated list of directories, JAR archives, and ZIP archives to search for boot class files. These are used in place of the boot class files included in the SDK software. |
|
|
Enable strictest checks, anticipating future default. |
|
|
Specifies the global region maximum allocation
size. The global region contains class definitions, string
constants, and other data internal to the VM. |
|
|
Specify the initial size of the memory allocation
pool. This value must be greater than 1000. To multiply the
value by 1000, append the letter |
|
|
Specify the maximum size of the memory allocation
pool. This value must be greater than 1000. To multiply the
value by 1000, append the letter |
|
|
Set the maximum stack size for any thread. |
|
|
Do not generate stack trace information for exceptions. |
| Instructs the Fast VM to use the compacting garbage collector. (See also Dynamic Heap Settings.) |
|
| Instructs the Fast VM to use the default "copying" garbage collector. |
|
|
|
When used with the compacting garbage collector,
this specifies the minimum percentage of heap space that the
collector should try to free for new objects. Thus, it dictates
when a full compaction must occur, rather than a sweep or
minor compaction. Values from 0 to 100 may be specified in
the form |
Once the Fast VM is set up as your virtual machine, it is automatically
used when you invoke any of the Java development tools (for example,
javac, javadoc, javap, jar,
appletviewer).
Rather than use fixed values for the default settings for the
memory allocation pool (Java heap), the Fast VM determines the defaults
for the initial heap size (-Xms) and the maximum heap
size (-Xmx) dynamically based on the environment in
which it is executing as shown below:
max_memory = min (physical memory on machine, total memory available to the process) default initial heap size = 10% of max_memory default maximum heap size = 60% of max_memory
By setting heap size defaults automatically, the Fast VM adjusts
the heap size based on the amount of memory that is available. This
generally produces better results than specifying fixed -Xmx
and -Xms values, especially for an application that
is executed on different systems with varying amounts of memory.
It is sometimes possible to obtain better results by specifying
-Xmx and -Xms rather than letting the
Fast VM pick the defaults. To determine what values to use you should
use the -verbose:gc command line option to monitor
your application's heap activity. If you notice that a large number
of garbage collections are occurring, increase the heap size as
much as possible without causing excessive page faults. Also see
Memory Usage for additional information.
The Fast VM has been tuned for large memory systems and, in addition, a number of trade-offs have been made that favor speed of execution over memory usage. As a result, the Fast VM uses more physical and virtual memory for the same application, often as much as 50 percent more. This can lead to excessive paging and degraded performance if the system is not tuned correctly or if there is insufficient physical memory on the system.
If you notice that your application runs more slowly with the Fast VM than the classic SDK JIT, you should do the following:
-Xmx and -Xms
values rather than letting the Fast VM pick the defaults. (See
Dynamic Heap Settings.)
Note that you are better off with a smaller heap that results in more garbage collections than allowing your application to page fault too often due to a large heap size.
For more information on system tuning and resource limits, see the OpenVMS Performance Management manual.
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 addresses these
needs.
The client configuration significantly reduces the Fast VM memory footprint.
The -client switch is a convenience switch, analogous
to setting the following switches on a command line:
java -Xmx64m -Xglobal128m -Xgc:compacting
The individual switch settings that make up the -client
switch can be overridden; for example:
java -client -Xmx256m
will initialize the Fast VM with a maximum heap size of 256 MB, with a maximum global region size of 128 MB, and with the compacting collector.
This release supports the ability to create and invoke the Fast VM in C/C++ programs using the Invocation API.
The Invocation API is an integral part of the Java Native Interface (JNI) that allows you to initialize virtual machine arguments, create and load a virtual machine into your application, and then unload or destroy the virtual machine. For additional information about the Invocation API and how to use it, refer to Sun's Java Native Interface Specification.
In order to take advantage of the Invocation API functionality, your C/C++ program (new and existing programs) must first create the virtual machine so that the Java code can be executed. Once the virtual machine is embedded into the program, the program can then load Java classes and execute Java methods.
Let us assume that you have a C++ program called invokejvm.cxx.
This program creates a virtual machine and then calls a Java method.
The following example shows how to compile and link a C++ program
that invokes the Fast VM:
JAVA$JVM_SHR/SHAREABLE
$ CXX INVOKEJVM.CXX /INCLUDE=SYS$COMMON:[JAVA$131.INCLUDE...] - /NAMES=AS_IS/FLOAT=IEEE $ LINK INVOKEJVM, EXAMPLE/OPTIONS
The /NAME=AS_IS qualifier is required to preserve the original case of external name strings. If your C/C++ code shares floating-point data with the RTE, the /FLOAT=IEEE qualifier is required because the RTE uses IEEE format floating-point, while C/C++ uses G-floating by default.
After you link the example, the program will use either the classic virtual machine or the Fast VM, depending on your Java environment setup, because it was linked with just JAVA$JVM_SHR, not the specific file that the logical name translates to.
Native methods used with the Fast VM must conform to the Java Native Interface (JNI) specification on the Sun site. The Fast VM does not support native method conventions older than the JNI specification.
Plug-in v 1.3.1 enables users to run Java applets and JavaBeans™ components on web pages using the RTE as an alternative to using the default virtual machine for Java 2 that comes with the web browser. It is based on the Java Plug-in 1.3.1 provided by Sun Microsystems and contains similar functionality.
For additional information on topics such as Java Plug-in Security, using signed applets, JNI and Java Plug-in, Using Java Plug-in in Intranet Environments, and How Proxy Configuration Works in Java Plug-in, see the Sun Microsystems Java Plug-in 1.3 Documentation web page; the documentation is the same for the Java Plug-in 1.3.1.
Note: You must be running Mozilla® 0.9.6 or higher.
To install Mozilla 0.9.6:
To run Mozilla:
$ @sys$common:[mozilla]mozilla
Note: We strongly recommend that you run Mozilla as an interactive job as indicated above.
If you spawn it off as a subprocess
$ spawn/nowait @sys$common:[mozilla]mozillayou will likely exhaust some resources if you attempt to use the plug-ins for anything non-trivial.
To enable the RTE within your browser:
Edit->PreferencesAdvanced.Enable Java.$ copy /prot=W:RE SYS$COMMON:[JAVA$131.JRE.PLUGIN.ALPHA.NS600]LIBJAVAPLUGIN_OJI.SO
SYS$COMMON:[MOZILLA.PLUGINS]
Thereafter, you can set up for Java operation:$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM
$ @sys$common:[mozilla]mozillaTo verify that Mozilla has found the plug-ins refer to:
Help->About Plug-ins
Mozilla will display the plug-ins it has initialized.
As of Mozilla 0.9.9 and Secure Web Browser (SWB) 1.0, you can choose where to place plug-ins.
For system-wide usage, use the respective location in the Mozilla/SWB installation tree:
$ copy /PROT=W:RE -
SYS$COMMON:[JAVA$131.JRE.PLUGIN.ALPHA.NS600]LIBJAVAPLUGIN_OJI.SO -
SYS$COMMON:[MOZILLA.PLUGINS]
$ copy /PROT=W:RE -
SYS$COMMON:[JAVA$131.JRE.PLUGIN.ALPHA.NS600]LIBJAVAPLUGIN_OJI.SO -
SYS$COMMON:[CSWB.PLUGINS]
You can also use "private" plug-ins by creating a [.PLUGINS]
directory in your _MOZILLA directory (which resides
in SYS$LOGIN). For example:
USERS:[FLINTSTONE._MOZILLA.PLUGINS]
To use this "private" plug-ins area:
$ copy /PROT=W:RE -
SYS$COMMON:[JAVA$131.JRE.PLUGIN.ALPHA.NS600]LIBJAVAPLUGIN_OJI.SO -
USERS:[FLINTSTONE._MOZILLA.PLUGINS]
Note that the public plugin areas are distinct:
SYS$COMMON:[MOZILLA.PLUGINS]
SYS$COMMON:[CSWB.PLUGINS]
and affect only the indicated product.
However, the user-private area, e.g.,
USERS:[FLINTSTONE._MOZILLA.PLUGINS]
is shared by Mozilla and SWB.
Essentially, if you place a LIBJAVAPLUGIN_OJI.SO into
USERS:[FLINTSTONE._MOZILLA.PLUGINS], it will be used
by both Mozilla and SWB and override what is in both SYS$COMMON:[MOZILLA.PLUGINS]
and SYS$COMMON:[CSWB.PLUGINS].
A Plug-in Control Panel lets you change Plug-in options such as proxies and enabling of the Java console window. It also allows you to switch the RTE version you want to run with your Plug-in. To run the Control Panel, enter the following command:
$ ControlPanel
Or you can use the Mozilla browser to visit the Control Panel applet page that was installed as
SYS$COMMON:[JAVA$131.JRE]ControlPanel.html
For example:
@sys$common:[mozilla]mozilla -
file:///SYS$COMMON:[JAVA$131.JRE]ControlPanel.html
Some of the Control Panel features are discussed below. Refer to Sun's Java Plug-In Control Panel web page for information about additional features and uses of the Java Plug-in Control Panel.
You can view a moderate amount of Java Plug-in tracing information
in Mozilla's Java Console by setting the JAVA_PLUGIN_TRACE
environment variable:
$ DEFINE
JAVA_PLUGIN_TRACE trueTo see Java error messages:
With the console window enabled, when you next visit a Plug-in enabled page, a separate window will come up to display error messages.
With SDK v 1.3.1, you can have multiple SDK versions installed on your OpenVMS system, and you can change from one to the other. The following sections describe how to do this.
To use different SDK versions in separate processes, you must first run a command procedure to set up the Java environment definitions for the version of the SDK you want to use in the given process. The command procedures to perform the Java environment setup are version-specific, and are as follows:
| SDK Version |
Command Procedure |
| SDK v 1.3.1 |
|
| SDK v 1.3.0 |
|
| SDK v 1.2.2 |
|
| SDK v 1.1.8 |
|
You can select either the classic VM or Fast VM as your virtual machine using this command file. Refer to Setting Up the Java Environment to set up the Java environment.
Note: To run Fast VM with SDK v 1.3.0 or SDK v 1.2.2, you must install the appropriate version of Fast VM separately. Fast VM is not available for SDK v 1.1.8. Refer to our Software Download page for product listing.
For example, to run SDK v 1.3.1, first run the following command file in your process:
$ @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM
To use different SDK versions in the same process, you must first run a command procedure to cancel the Java environment definitions of one version of the SDK before setting up the environment of another version of the SDK. The command procedures to accomplish the Java environment cleanup are version-specific, and are as follows:
| SDK Version |
Command Procedure |
| SDK v 1.3.1 |
|
| SDK v 1.3.0 |
|
| SDK v 1.2.2 |
|
| SDK v 1.1.8 |
|
Once you have cancelled the Java environment, you must then run a command procedure to set up the Java environment definitions for the version of the SDK you want to use. For a list of these command procedures, see In Separate Processes.
For example, to switch from using SDK v 1.2.2 to using SDK v 1.3.1 in the same process, run the following command procedures:
@SYS$COMMON:[JAVA$131.COM]JAVA$122_CANCEL_SETUP.COM ! Clean up 1.2.2 environment @SYS$COMMON:[JAVA$131.COM]JAVA$131_SETUP.COM ! Set up 1.3.1 environment
Running @SYS$COMMON:[JAVA$131.COM]JAVA$122_CANCEL_SETUP.COM
cancels the setup of the SDK v 1.2.2 environment.
All Java files that are to be read by any of the Java tools or that serve as input class libraries (listed in CLASSPATH) must be in Stream_LF format. Stream_LF format is required for all data files read or written by Java programs.
To determine the record format of your file, do the following:
$ DIR/FULL MyFile.java
And observe the line:
Record format
By default, a file initially created on an OpenVMS system, with a text editor for example, will have 'Variable length' record format.
Although a *.java file with 'Variable length' record format compiles correctly if it is error-free, the compiler does not produce proper diagnostic outputs if a compilation error occurs.
To get an ASCII file into Stream_LF record format, do the following:
$ CONVERT/FDL=SYS$COMMON:[JAVA$131.COM]STREAM_LF.FDL input_filename -
output_filename
Where STREAM_LF.FDL is:
FILE
ALLOCATION 4
BEST_TRY_CONTIGUOUS yes
EXTENSION 0
ORGANIZATION sequential
RECORD
BLOCK_SPAN yes
FORMAT stream_LF
SIZE 0
If the file is in the proper format (STMLF), you will see the source error line printed out, with a carat (^) indicating the point of error:
$ javac "Bounce.java"
Bounce.java:11: Superclass smith.java.applet.Applet of class Bounce not found.
public class Bounce extends smith.java.applet.Applet implements Runnable
^
1 error
If the file is not in STMLF format, a blank line is printed instead of the source error line, and the carat position is not useful:
$ javac "Bounce.java"
Bounce.java:10: Superclass smith.java.applet.Applet of class Bounce not found.
^
1 error
Binary .class files need to be Stream_LF as well. If they are not Stream_LF you will get error messages like the following, even though your CLASSPATH is correct and the correct .class file is on the path:
Can't find class Test.HelloWorld
If you import .class files from a non-OpenVMS computer, be sure to convert them to Stream_LF.
To get a binary file (.class, .jar, .zip) into Stream_LF record format, do the following to give the file the right record format attributes:
$ SET FILE/ATTR=(RFM:STMLF,RAT:CR) filespec
There are a number of issues trying to represent UNIX directory and file specifications on an OpenVMS Alpha system. If you try to run a Java application developed elsewhere on an OpenVMS Alpha system, you might encounter problems with file and directory names.
The RTE provides a number of mapping algorithms that try to make a UNIX-style name usable under an OpenVMS Alpha file system.
These algorithms can be used in combinations. You can enable the use of each algorithm by turning on a particular bit in the following logical name:
JAVA$FILENAME_CONTROLS
To change the JAVA$FILENAME_CONTROLS default values, edit the file:
SYS$COMMON:[JAVA$131.COM]JAVA$FILENAME_CONTROLS.COM
This file is called by JAVA$131_SETUP.COM to establish these and other defaults.
We suggest that you start off using this file as-is to enable all algorithms.
Different users may want to read/edit this file to enable/disable different algorithms to avoid selected problems.
The algorithms and the bit values to set them are summarized below. A more detailed explanation of each option follows the table.
Current Filename Mapping Table Option name Value Support UNIX and VMS filename %x00000008 Support Dir in the filename %x00000200 Support Valid characters in filename %x00001000 Support Hidden Filename (replace with _) %x00004000 Support Hidden Filename (remove the .) %x00008000 Support Multi dot in directory (replace with _) %x00020000 Support Multi dot in directory (remove dots) %x00040000 Support Multi dot in file, keeping last %x00100000 Support Multi dot in file, keeping first %x00200000 Support more than 39 characters by truncation %x04000000 Support more than 39 characters by moving the dot %x08000000 Support Directory remapping %x20000000
To see individual filename mappings as they occur, define the logical JAVA$SHOW_FILENAME_MAPPING:
$ DEFINE JAVA$SHOW_FILENAME_MAPPING 1
This is useful if you are experiencing problems with the way filenames are being mapped, perhaps resulting in unexpected "File not found" messages.
To enable "UNIX and VMS" and "Multi dot first" you must issue the following DEFINE:
$ FILE_MASK = %x00000008 + %x00200000 $ DEFINE JAVA$FILENAME_CONTROLS 'file_mask'
The options are processed at runtime in order from smallest to largest values.
Therefore, in this example, first "UNIX and VMS" would be processed, and then "Multi dot first".
To enable all the options:
$ define JAVA$FILENAME_CONTROLS -1
If JAVA$FILENAME_CONTROLS is not defined or is equal to zero, then no mappings are attempted.
The following sections further describe the available mapping options.
Use this to map a mix of UNIX and OpenVMS filenames into UNIX-style names.
For example,
this: $disk1:[smith]/test.jtjtj/test.jtjtj
maps into this: /$disk1/smith/test.jtjtj/test.jtjtj
Change names of the form xxx.dir to their UNIX directory counterpart.
For example,
a name like: /dkb500/smith.dir/testing.dat
maps into: /dkb500/smith/testing.dat
Characters that can occur in UNIX-style names but are prohibited in OpenVMS-style names are replaced by underscores. [ "_" ] unless these characters have special meaning in the UNIX-style name. In that case, we attempt to map the special meaning.
For example, "~" refers to SYS$LOGIN.
The list of characters contains characters like "+".
No uppercasing is done. C will create/open the correct file.
Some Java applications expect to be able to create a hidden file or directory. The hidden character "." will be replaced by the "_" character.
For example:
A name like: .hotjava
maps into: _hotjava
Or,
A name Like: test/.hotjava/appletviewer.dat
maps into: test/_hotjava/appletviewer.dat
Some Java applications expect to be able to create a hidden file or directory. The hidden character "." will be removed from the filename.
For example:
A name like: .hotjava
maps into: hotjava
Or,
A name Like: test/.hotjava/appletviewer.dat
maps into: test/hotjava/appletviewer.dat
A name like:
/dkb500/smith/version1.1.4.3/testing_dat.dat
Maps into:
/dkb500/smith/version1_1_4_3/testing_dat.dat
A name like:
/dkb500/smith/version1.1.4.3/testing_dat.dat
Maps into:
/dkb500/smith/version1143/testing_dat.dat
Multiple dots in the filename are turned into underscores, but the LAST dot is retained:
For example:
A name like: SDKDOC_1.3.1
maps into: SDKDOC_1_3.1 Multiple dots in the filename are turned into underscores, but the FIRST dot is retained:
For example:
A name like: SDKDOC_1.3.1
maps into: SDKDOC_1.3_1 For filenames greater than 39 characters either to the left of the single dot or the right of the single dot, that portion of the name is truncated on the right.
For example:
A name like:
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz.extension
Maps into:
abcdefghijklmnopqrstuvwxyzabcdefghijklm.extension
Similarly,
A name like:
somename.abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
Maps into:
somename.abcdefghijklmnopqrstuvwxyzabcdefghijklm
For filenames that have more than 39 characters either to the left or to the right of the single dot in the filename, AND the total number of characters is less than [39+39 =] 78, the algorithm tries to shift the single dot so that there are no more than 39 characters to the left of the dot.
For example:
A name like:
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz.extension
Maps into:
abcdefghijklmnopqrstuvwxyzabcdefghijklm.nopqrstuvwxyzextension
There is support for representing a directory structure that is more than 8 levels deep on an ODS-2 format disk.
If your application will use more than the OpenVMS maximum of 8 nested directories, then define the following logicals to work around this restriction:
JAVA$DIRECTORY_MAPPING_COUNT nn : How many directory mappings exist?
JAVA$DIRECTORY_MAPPING_nn : Directory mapping value
where nn is an integer from 01 to 99.
For example, the following filename previously failed with SDK v 1.1 for OpenVMS because the directory has too many levels for RMS:
/test1/test2/test3/test4/test5/test6/test7/test8/test9/test10
Using the directory mapping logic, you can redirect deep directory names to either a concealed logical or another directory.
Using the example above:
$ DEF JAVA$DIRECTORY_MAPPING_COUNT 1 ! how many directory mappings.
$ DEF JAVA$DIRECTORY_MAPPING_01 -
_$ "/test1/test2/test3/test4/test5/test6/test7=/test7_relevel"
All files/directories created with a prefix
of the following will now be created in the directory /test7_relevel:
/test1/test2/test3/test4/test5/test6/test7
So, the filename
/test1/test2/test3/test4/test5/test6/test7/test8/test9/test10/foo.bar
would actually be created as:
/test7_relevel/test8/test9/test10/foo.bar
Note: Define the JAVA$DIRECTORY_MAPPING_nn logical only from the first character on. You cannot map directories from the middle of a directory tree. Note the limit of 99 remappings.
Historically, at users' request, the RTE has performed filename mapping to map file names that are not directly representable on an OpenVMS file system into ones that are representable. This filename mapping requires several (potentially large) buffers on the stack. As the number of requested mappings increases, an increasingly larger number of such buffers are required. See Description of Mapping Options in UNIX-Style Filenames on OpenVMS Systems for a full discussion of these filename mappings.
Now available for OpenVMS Alpha V7.2-2 and V7.3 is a C RTL ECO that enriches the kinds of filenames you can directly specify on an ODS-5 volume under OpenVMS Alpha. This functionality is included with higher versions of OpenVMS Alpha without the need for an ECO. See the product page on the Web site for more information.
To summarize, if your application is intended to run only on an OpenVMS system that has this C RTL functionality, and your files are restricted to an ODS-5 volume, then you can probably reduce the number of filename mappings that you request.
Whenever you eliminate a filename mapping option, you reduce the
number of internal buffers that need to be allocated—leading to
a smaller memory footprint for your application. When no filename
mapping is needed (JAVA$FILENAME_CONTROLS defined to 0), you can
lower the -ss (stack size) value. The gains will be
in memory usage and thread creation.
JAVA$CLASSPATHThe JAVA$CLASSPATH logical is an alternative way of
specifying the class path. Defining this logical overrides the CLASSPATH
logical, if set.
JAVA$CLASSPATH lets you define a class path using
OpenVMS file specification syntax. Therein lies its advantage: with
JAVA$CLASSPATH, you specify multiple paths with a comma-separated
expression; with CLASSPATH, you use a single, quoted
string comprised of colon-separated pathnames. JAVA$CLASSPATH,
therefore, avoids the OpenVMS 255-character length restriction that
you can encounter with CLASSPATH.
The following two sample statements accomplish the same result:
$ DEF JAVA$CLASSPATH USER1$:[SMITH.KIT]MY_CLASSES.ZIP,[] $ DEF CLASSPATH "/user1$/smith/kit/my_classes.zip:."
Note that:
CLASSPATH is a colon-separated list enclosed in
quotes.
JAVA$CLASSPATH is a comma-separated list not enclosed
in quotes.
JAVA$CLASSPATH overrides CLASSPATH,
if JAVA$CLASSPATH is defined.
-classpath option on a Java tool overrides
both JAVA$CLASSPATH and CLASSPATH. For further information, see Setting the Classpath on Sun's site.
JAVA$ENABLE_ENVIRONMENT_EXPANSIONYou can use the JAVA$ENABLE_ENVIRONMENT_EXPANSION
logical to bypass the 255-character DCL command-line limit:
$ define/job JAVA$ENABLE_ENVIRONMENT_EXPANSION TRUE
When this logical is defined, the RTE will attempt to expand any
logical or symbol that is preceded by "$"
on the Java command line. To bypass the 255-character DCL command
line limit, you can define lengthy command-line operands as more
compact symbols or logical names and specify them on the Java command
line, each preceded by a "$". They will be
passed by DCL to the RTE for expansion. Also, if the logical is
a multi-valued logical, this feature will attempt to convert the
list into a UNIX list with a ":" as a delimiter.
For example:
$ define java$classpath [], dka200:[apache.jakarta.tomcat.lib]servlet.jar
$ extra_option = "-Dfoobar=value1 -Dfoobar1=value2"
$ java -cp $java$classpath $extra_option javaprogram
With the logical defined, the RTE would expand the command line to the following:
$ java -cp .:/dka200/apache/jakarta/tomcat/lib/servlet.jar -
"-Dfoobar=value1" "-Dfoobar1=value2" javaprogram
Note: This feature does not expand operands provided
via the "-V" method.
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.
There is a relaxation in the way shareable image names are used.
Before SDK v 1.1.8, the JNI example provided for OpenVMS systems suggests you put your native code into a shareable image named JAVA$foo_SHR.EXE, where you choose the foo portion of the image name. In your Java code, you would have the following statement to load your shareable image so you can call its native methods:
System.loadLibrary("foo");
This has the disadvantage of requiring users to create shareable images using our reserved name prefix of JAVA$.
As of SDK v 1.1.8, you are allowed and encouraged to create shareable image names that do not collide with our namespace:
As a workaround to support old SDKs, we recommend you define two logical names: "JAVA$foo_SHR" and "foo", both pointing to your foo.exe shareable image:
$ DEFINE/JOB JAVA$foo_SHR USER_DISK:[FOO]FOO.EXE $ DEFINE/JOB foo USER_DISK:[FOO]FOO.EXE
The corresponding statement in your Java code would be:
System.loadLibrary("foo");
When you no longer support SDKs prior to SDK v 1.1.8, you could stop defining the JAVA$foo_SHR logical. The foo logical would then continue to get you to your shareable image.
System.loadLibrary("foo");
The RTE supports limited file-sharing and has several user-selectable modes of file sharing. To enable RTE file-sharing modes, define the logical JAVA$FILE_OPEN_MODE to any of the following values:
| 0 or not defined |
no file sharing
|
| 2 |
sync writes, every write to a file, the file is sync with the disk. Note: A sync for every write gives you file sharing close to what the SDK expects. However, things that normally took seconds to run, can take minutes or longer. |
| 3 |
A table of all open file descriptors is kept by the SDK. The SDK then monitors when an application writes to a file, and sets a write_pending flag. Before every read operation the SDK scans the list of open file descriptors. If a match is found with a write pending, the pending write is flushed to the disk before the read. Limitations: only one process can share the file reliably. |
We are working with HP C engineering to enhance the file-sharing features in the C RTL and the SDK.
The SDK for OpenVMS Alpha has the capability to shorten long procedure names (more than 31 characters) using the same translation algorithm used by the C/C++ compilers. (This capability was first included with SDK v 1.1.8-5.) To make use of this feature, compile your C/C++ code with the /NAMES=(SHORTENED, AS_IS) qualifier.
The old name-shortening method using SCAN_FOR_31_CHARS.COM is still
supported. You can choose either method. (For information on using
SCAN_FOR_31_CHARS.COM, included in the JNI_EXAMPLE.BCK saveset,
follow the instructions at How
do I handle procedure names over 31 characters? on our FAQ
page , and then read the files JNI_README.TXT, JNI_EXAMPLE.COM,
and SCAN_FOR_31_CHARS.COM. You run SCAN_FOR_31_CHARS.COM manually
to produce .H files that redefine the oversized name
to be 31 characters.) The names produced in this way are different
from those produced by the C/C++ compilers.
When the RTE is confronted with an oversized name, it first tries to find a match using the new compiler-based name compression algorithm -- the same one used by running the C or C++ compiler with the /NAMES=(AS_IS,SHORTENED) qualifier.
If the RTE fails to find such a match, it then tries to create a short name using the algorithm used by SCAN_FOR_31_CHARS.COM.
Although the old manual name-shortening method will continue to work, we encourage you to take advantage of the new, more automatic method.
OpenVMS Version 7.2 introduces support for Extended File Specifications, which consists of two parts: deep directory nesting and extended file names. See the OpenVMS Guide to Extended File Specifications for more information. The RTE can take advantage of both of these capabilities, particularly the extended file names on an ODS-5 disk, which allow much longer file names and mixed-case file names.
To activate this support:
SET PROCESS/PARSE_STYLE=EXTENDED
This command preserves the case of the arguments on the command line, and must be enabled to take advantage of C RTL changes.
$ DEFINE DECC$ARGV_PARSE_STYLE ENABLE
$ DEFINE DECC$EFS_CASE_PRESERVE ENABLE
With this support enabled, the file "Foo.java" compiles to "Foo.class" instead of "FOO.CLASS".
To disable this feature, issue any one of the following commands:
$ SET PROCESS/PARSE_STYLE=TRADITIONAL $ DEFINE/SYSTEM DECC$ARGV_PARSE_STYLE DISABLE $ DEASSIGN DECC$ARGV_PARSE_STYLE $ DEFINE DECC$EFS_CASE_PRESERVE DISABLE
The values for the DECC$ARGV_PARSE_STYLE and DECC$EFS_CASE_PRESERVE logicals are case-insensitive.
Previously, HP had added the capability for JAVAC and JAR to accept wild-carded file specifications and would automatically determine the right case of the name. This allowed you to say:
$ JAVAC *.java
and
$ JAR cvf test.jar *.class
SDK v 1.3.1 extends this capability in these two tools for any .java and .class file operand, so you can say, e.g.,
$ JAR cvf test.jar TESTPLOT.CLASS
and not worry whether it really should be:
$ JAR cvf test.jar "TestPlot.class"
$ JAR cvf test.jar "TESTPLOT.CLASS"or
$ JAR cvf test.jar "testplot.class"
This can be particularly helpful to those using DCL to automatically generate operands, because DCL will uppercase them. In general, this reduces the number of situations where you need to present the exact-cased name and quote it.
Note: This works only for JAVAC and JAR. You still need to use the right case for verbs like JAVA itself.
This feature is enabled by default; if it causes troubles with existing command procedures, it can be entirely disabled by setting:
$ define JAVA$OMIT_CASE_CHECK true
The following logical names enable UNIX-style behavior for certain file-manipulation commands:
$ define JAVA$DELETE_ALL_VERSIONS true(on delete, delete all versions)
$ define JAVA$RENAME_ALL_VERSIONS true(on rename, rename all versions)
$ define JAVA$CREATE_DIR_WITH_OWNER_DELETE true
(on directory creation, establishO:REWDprotection as default)
The DECC$FILE_PERMISSION_UNIX logical name supercedes
the effects of JAVA$CREATE_DIR_WITH_OWNER_DELETE.
On OpenVMS, if you type:
mkdir("a/b/c", mode)
and later:
chmod("a/b/c", mode)
only the directory 'c' gets the new mode.
By turning on the DECC$FILE_PERMISSION_UNIX logical
name, the directories 'a' and 'b' are
affected by the new mode as well.
For more information, refer to Enabling Compaq C RTL Features Using Feature Logical Names in the Compaq C Run-Time Library Reference Manual for OpenVMS Systems.
You can optimize the performance of your application on OpenVMS Alpha in several ways, without changing your application code. The RTE is sensitive to the existence of a certain logicals that will alter its behavior. The following descriptions offer several techniques you can use to optimize performance:
JAVA$FORK_MAILBOX_MESSAGES,
JAVA$EXEC_USE_PIPES, and JAVA$FORK_PIPE_STYLEApplications can be tuned for performance using the logical JAVA$FORK_MAILBOX_MESSAGES
and JAVA$EXEC_USE_PIPES.
On OpenVMS Alpha systems, Java process creation and parent-child relationships are managed by native threads. If they pass data between them it is done by mailboxes. For example, a typical scenario is where a child process produces a stream of output, and the parent process consumes this stream as input.
Schematically,
Child Writes
|
V
Mailbox
|
V
Parent Reads
Some applications are written such that the parent starts off the child and then waits for the child to finish before starting to read its stream of data. In others applications, the parent starts reading as soon as it can, but cannot keep up with the child. Both of these approaches can get into trouble.
The trouble arises because the mailboxes are of a finite size.
If the mailbox fills up, the child is blocked from doing further work and never gets done. Meanwhile, the parent is waiting for the child to finish, and also cannot proceed. This state is known as a Read-Write MailBoX (RWMBX) wait state (or RWINS), and the process running this application is blocked.
To try to avoid this situation, the RTE does buffering between the mailbox and the consumer. One thread reads data from the mailbox and stores it in heap storage. Another thread reads buffered data from this heap and delivers it to the parent when it asks for it.
Schematically:
Child Writes
|
V
Mailbox
|
V
PutToHeap
|
V
GetFrom Heap
|
V
Mailbox
|
V
(Java Application)Parent Reads
In the case where the parent is waiting for the child to finish, this buffering may empty the mailbox enough so that the child can continue to run and finish, thereby freeing the parent to continue as well. In the case where the parent is continually reading but is temporarily being overwhelmed, the buffering smooths the production-consumption data flow.
If the parent is really waiting for the child to complete before consuming any of the information stream, this buffering mechanism itself starts to fail when the volume of output exceeds the amount of heap storage available. When no more heap is available, PutToHeap cannot empty the Mailbox, and again you face (RWMBX or RWINS) wait state. The blocked state persists unless some asynchronous agent comes along and changes the resources involved; for example, releasing some heap storage.
In most cases, however, the added capacity of heap storage is enough for the child to complete and the parent to continue.
As a further enhancement to control this data flow, we monitor the pipeline for how many messages are outstanding.
Schematically:
+--------->Child Writes
| |
| V
| Mailbox
count |
messages |
outstanding V
| PutToHeap
| |
| V
+---------->GetFrom Heap
|
V
Mailbox
|
V
(Java Application)Parent Reads When the number of messages written exceeds
the number read by an amount equal to the lesser of 1024 and the
value of the logical JAVA$FORK_MAILBOX_MESSAGES, then we stop the
writes to prevent the RWMBX condition. JAVA$FORK_MAILBOX_MESSAGES
is assumed to be 8 if not defined.
This temporary curtailment of production allows the parent thread to catch up (get within the exceeded message threshold), and the overall application continues.
As mentioned above, if JAVA$FORK_MAILBOX_MESSAGES
is not defined, it is assumed to be 8. With this value in control,
any time the writer gets 8 records ahead of the consumer, the writer
is temporarily suspended. For applications that produce many small
records, you might want to set a value of JAVA$FORK_MAILBOX_MESSAGES
to a larger value -- something on the order of 1024 divided by your
typical mailbox record size. The bigger you can make it -- think
of it as a blocking factor -- the more efficient the operation becomes
because you are minimizing the start-stop time of the producer thread.
If you make it too large, you might induce the RWMBX state. If you
see the Java application in RWMBX state for a period of time without
having explicitly used JAVA$FORK_MAILBOX_MESSAGES,
try setting it to a value less than the default value of 8.
You can revert to unbuffered behavior for exec and pipes by defining
the logical JAVA$EXEC_USE_PIPES.
$ DEFINE JAVA$EXEC_USE_PIPES 1 ! use unbuffered behavior
Starting with SDK v 1.3.1-2, the logical name JAVA$FORK_PIPE_STYLE
is available to augment the features offered by JAVA$EXEC_USE_PIPES.
You can choose among three styles of data flow management:
| Value for JAVA$FORK_PIPE_STYLE | Behavior | Same as… |
| 0 | Use unbuffered behavior | JAVA$EXEC_USE_PIPES = 1 |
| 1 | Default behavior | JAVA$EXEC_USE_PIPES undefined |
| 2 | Default behavior, except uses a socket rather than a mailbox for buffering data between the heap and the Java application Parent Reads (requires a TCP/IP stack) | JAVA$EXEC_USE_PIPES undefined, except
uses a socket rather than a mailbox for buffering data between
the heap and the Java application Parent Reads (requires a TCP/IP
stack) |
Defining JAVA$FORK_PIPE_STYLE with the value 0 is the
same as defining JAVA$EXEC_USE_PIPES with the value
1. The result is that the unbuffered behavior is used.
Defining JAVA$FORK_PIPE_STYLE with the value 1 is
the same as NOT defining JAVA$EXEC_USE_PIPES. The result
is the buffered behavior described in the previous paragraphs.
Defining JAVA$FORK_PIPE_STYLE with the value of 2
is similar to NOT defining JAVA$EXEC_USE_PIPES, but
will result in the use of a socket rather than a mailbox for buffering
data between the heap and the Java application Parent Reads. Note:
This style requires a TCP/IP stack.
Schematically:
Child Writes
|
V
Mailbox
|
V
PutToHeap
|
V
GetFrom Heap
|
V
Socket
|
V
(Java Application)
Parent Reads
Because the Java application is reading from a socket device, it can use nonbuffered IO, ioctl features, cancel IO operations, etc. It is the closest to simulating true UNIX pipe functionality. Processing data from the child using this style results in a performance improvement.
JAVA$DISABLE_MULTIDOT_DIRECTORY_STAT stat()
call Because of the way File Name Mapping works, and the way in which
directories that contain dots are handled on OpenVMS Alpha, the
RTE may need to do an extra stat() call whenever you
seek a class file that is not found on the initial stat()
call.
Consider this example: Suppose you import an application from
another platform that has within its overall directory structure
a directory named project-4.1-A.
During operation you may need to verify that the directory exists.
On OpenVMS Alpha you cannot yet represent a directory named project-4.1-A.
As a result, if the application attempts to see if the directory
exists, the RTE will first try to access via stat(): projects/project-4.1-A.
When that fails, it will do another stat() wherein
the path has been modified to remove all dots from directory names:
projects/project-4_1-A.
Because this second attempt is needed to support remapping of
directories that contain "dot(s)," any failed stat()
will result in a second call to stat() to attempt to
see if it is a directory containing a "dot(s)."
In general, whenever a stat() call fails, the RTE
attempts another stat() call with a potentially modified
path name.
stat()
call?Modern Java applications are typically constructed by drawing together class files (libraries) provided by a number of vendors. In order to tie this together at runtime, you must specifiy long Classpath strings that can contain hundreds of individual path names.
For example, for projects/classes/MyApp.class, the
RTE would try to stat() "projects/classes/MyApp.class"
first; if that fails, it would try "projects/classes/MyApp_class"
to see if it is a directory that contains any "dot(s)."
If you are looking from a particular class file, you will generally
need to look through approximately 50 percent of the paths to find
the one you need; this means that the RTE will do two stat()s
for every class file lookup failure.
Each time you look on a path that does not contain the sought
class, the failure of the stat() causes a secondary
stat() to be issued. If you multiply these secondary
stat() calls by the several hundred classes that are loaded during
a typical application you can see that the total number of secondary
stat() calls can account for a significant amount of
application start up.
However, if you know that your application never deals
with directories that have dots in their names, you can now tell
the RTE not to do the secondary stat() call because
it will have no value to your application.
This is accomplished by setting:
$ define/nolog JAVA$DISABLE_MULTIDOT_DIRECTORY_STAT true
This will disable the secondary stat() call.
Realize, however, that if you turn on this logical and your application
does attempt to find something in a directory that originally had
dots in it, your application will fail, probably by throwing a java.lang.NoClassDefFoundError
or Directory error.
JAVA$CACHING_INTERVALSome applications spend considerable time creating files, monitoring directories for the existence of files, and testing properties of files using file methods such as
File file = new File(name);
file.exists()
file.isDirectory()
file.isAbsolute()
These methods indirectly use the underlying C Runtime Library
stat() function.
A typical sequence might appear as:
if (file.exists()) { // ends up calling stat()
if (file.isDirectory()) { // ends up calling stat() again
...
}
}
If your application does these kinds of operations--continuous polling for changes in a monitored set of files--you might benefit from this optimization.
If you define a logical,
$ DEFINE/JOB JAVA$CACHING_INTERVAL <caching interval in seconds>
e.g.,
$ DEFINE/JOB JAVA$CACHING_INTERVAL 60
then the information gathered by the stat() function
is cached for the interval indicated before it is deemed stale and
the cache is invalidated.
Hence, in the code fragment above, the question file.isDirectory()is
answered from cached information and no I/O is actually performed.
This represents a considerable difference in time. Some web servers
have been observed making hundreds of calls per second to monitor
the status of the same group of files. The overall speed-up in such
cases can be dramatic.
Additional caching occurs when JAVA$CACHING_INTERVAL
is enabled and JAVA$CACHING_DIRECTORY defined; the
caching algorithm will attempt to discover 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).
The cache is invalidated and a real call to stat()
is made the first time after:
Runtime.exec()
or completes.The main drawback to this caching is that if another application, without the cooperation of this application (e.g., FTP), copies a file into the monitored set, the RTE might not see it until the cache is invalidated for one of the reasons above.
By default, this optimization is not enabled. You can enable it
only by setting the logical JAVA$CACHING_INTERVAL to
a positive non-zero value.
JAVA$DAEMONIZE_MAIN_THREADWith applications that make heavy use of ASTs, the main Java thread could be starved for CPU time.
As described in section B.12.5, Delivery of ASTs, in the Guide to the POSIX Threads Library:
In addition to per-thread ASTs, there are also user mode ASTs that are directed to the process as a whole, or to no thread in particular, or to a thread that has since terminated. These "process" ASTs are queued to the initial thread, making the thread runnable in a fashion similar to per-thread ASTs. They are executed in the context of the initial thread ....
Later, the same section describes how, among the implications that must be considered for application development:
If an application makes heavy use of ASTs, it can starve the initial thread to a degree, because only that thread executes the ASTs that are directed to the entire process.
In other words, "process" ASTs are executed first, and the Java thread running in the main thread only gets the CPU if there are not any ASTs. If you define a logical,
$ define JAVA$DAEMONIZE_MAIN_THREAD true
a new thread is created to run the main Java thread. In applications that make heavy use of ASTs, this allows ASTs to use a CPU without starving the main Java thread.
Without JAVA$DAEMONIZE_MAIN_THREAD defined, the main
Java thread shares a CPU with ASTs. With JAVA$DAEMONIZE_MAIN_THREAD
defined, the main Java thread is an empty thread allowing it to
handle only ASTs. The real main Java thread is moved to another
thread. On a multi-CPU system, the main Java thread could be running
on a new thread and the ASTs could be running on the initial thread.
JAVA$READDIR_CASE_DISABLEThis logical name allows the user to turn off the case-sensitive filename extraction feature (ODS-2 “auto case” correction for “readdir” entries) if it is not needed:
$ define JAVA$READDIR_CASE_DISABLE true
If you use the Java method File.list() and JAVA$READDIR_CASE_DISABLE
is not defined (by default it is not defined), the RTE will ensure
that all directory lookups for .java or .class
filename entries will have the correct case. For example,
if the properly cased filename is “Foobar.class,” on an ODS-2 disk
structure, the filename will be stored as “FOOBAR.CLASS”. By default,
the RTE will ensure the internal view of the filename is “Foobar.class”.
If you can restrict all your files to an ODS-5 disk structure and
ensure the filenames are created/named with the correct case, defining
JAVA$READDIR_CASE_DISABLE will increase the performance
of scanning directories that contain “*.java” and “*.class”
filenames.
JAVA$TIMED_READ_USE_QIOSome Web applications spend considerable time using Socket Streams
with timeout values. Because of this, 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 major result has
been a reduction of overall kernel mode CPU usage, giving the application
more available user mode CPU power.
If you are running TCP/IP Services for OpenVMS, you can use the
command tcpip show comm/mem to determine if your application
might benefit from using this logical.
Capture a baseline for the number TCPIP Timer and Select structures before starting the application.
$ tcpip show comm/mem
...
8 mbufs allocated to OpenVMS TCPIP Timer structure
3 mbufs allocated to OpenVMS LAN VCI VCIB structure
1 mbufs allocated to OpenVMS LAN MCAST_REQ structure
2 mbufs allocated to OpenVMS SELECT structure
...
Continue to monitor these values as the application is stressed.
$ tcpip show comm/mem
...
30 mbufs allocated to OpenVMS TCPIP Timer structure
3 mbufs allocated to OpenVMS LAN VCI VCIB structure
1 mbufs allocated to OpenVMS LAN MCAST_REQ structure
24 mbufs allocated to OpenVMS SELECT structure
...
If the mbuf "Select" structure count is double digits,
your application could benefit from this logical.
You can monitor the overall system performance improvement. The
system will use less Kernel and Executive Mode CPU.
Before:
$ monitor system/all
SYSTEM STATISTICS
on node SECURE
12-MAY-2003 15:22:19.28
CUR AVE MIN MAX
Interrupt State 16.33 15.80 14.83 16.33
MP Synchronization 5.33 5.19 4.16 5.66
Kernel Mode 80.83 80.73 77.66 84.66
Executive Mode 20.50 20.16 18.83 20.66
Supervisor Mode 0.00 0.00 0.00 0.00
User Mode 94.16 95.03 90.83 99.00
Compatibility Mode 0.00 0.00 0.00 0.00
Idle Time 183.16 183.03 175.50 191.83
After:
SYSTEM STATISTICS
on node SECURE
12-MAY-2003 15:38:44.41
CUR AVE MIN MAX
Interrupt State 16.50 17.95 16.50 20.16
MP Synchronization 4.00 4.25 4.00 4.83
Kernel Mode 32.83 35.87 32.83 41.33
Executive Mode 1.00 0.50 0.00 1.00
Supervisor Mode 0.00 0.00 0.00 0.00
User Mode 75.00 77.95 72.83 87.00
Compatibility Mode 0.00 0.00 0.00 0.00
Idle Time 270.83 263.62 246.83 270.83
Note: The major benefit was a decrease in CPU usage. This test case also handled 33% more transactions than the "Before" test.
Before SDK v 1.3.1-2, if you did not specify a classpath directory path, RTE would search only in the default directory. Beginning with SDK v 1.3.1-2, you can use VAXC$PATH as an OpenVMS search path for locating .EXEs or .COMs files outside the default directory. For example,
$ define VAXC$PATH GNU:[bin],[],sys$common:[java$131.bin] ! open source GNU files
br = new BufferedReader(new InputStreamReader(
rt.exec("chmod").getInputStream()));
The above will now search the three directories defined in VAXC$PATH
for chmod., chmod.exe, or chmod.com. Also,
br = new BufferedReader(new InputStreamReader(
rt.exec("javac").getInputStream()));
The above will search for javac., javac.exe, or javac.com.
fname) When fname is a Logical or
a Disk NameNOTE: This is an incompatible change to behavior in SDK v 1.3.1-1.
SDK v 1.3.1-1 fixed a problem that occurred when you tried to open a file using rooted logicals such as:
File f = new File ("/sys$sysroot");
A problem would occur if you attempted to get a directory listing
of rooted logicals, (e.g., sys$sysroot) or of disk
names (e.g., "/sys$sysdevice" or "/node$dka200").
With the current C RTL the RTE must internally add a "/000000"
to these names to make this directory listing operation work correctly.
This workaround created problems with nonrooted logicals like "/sys$errorlog".
HP expects that newer C RTLs will handle these special cases internally
and the RTE will no longer need to use this workaround. Anticipating
this transition, we have removed the automatic addition of "/000000"
as the default behavior. If you still need this capability in your
application with the current C RTL you must explicitly request it
by defining a logical:
$ define/job JAVA$ENABLE_ROOT_WITH_000000 TRUE
Printing has been enabled on OpenVMS. The classes PSPrinterJob
and PSPrintControl will create input dialogs. You may
enter your printer queue name in the Printer text input field. Please
see Sun's documentation for examples of using these classes.
Runtime.exec() 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:
java.io.IOException: function not implemented
This would protect the Java application from changing its own
current working directory. While we are waiting for a C RTL enhancement,
if JAVA$FORK_SUPPORT_CHDIR is defined, as in:
$ define/job JAVA$FORK_SUPPORT_CHDIR TRUE
The RTE will do the following (where CWD is the current working directory):
vfork()execv*()Note: Between steps 2 and 5 another thread could
attempt to open a relative filename (e.g., foobar.dat).
If this happens you might see random errors reporting files not
found.
The SDK release includes the following font support.
Starting with J2SDK v 1.2.1, Java applications require a font property
file to properly display the application's AWT windowing and Java2D
components. This file contains mappings of Java logical font names
to physical fonts on the X server and is installed by this kit in
SYS$COMMON:[JAVA$131.JRE.LIB]FONT.PROPERTIES. It identifies
fonts that should be available on your X server. This version is
different from previous versions of the Java Development Kit (JDK)
1.1.n, where a font property file was not required. Instead of using
Java default fonts, which were resolved at run-time by the X server
to physical fonts on the display side, the font.properties
file provides a mapping of the Java logical font names to fonts
on the system. This allows for greater consistency across Java applications
using the same J2SDK. Therefore, you might notice some differences
in your window displays because of the fonts now being used. You
might also see a noticeable difference in the size of the text displayed
when using the J2SDK compared with using JDK 1.1.n; text will now
be displayed larger. This is because JDK 1.1.n as implemented by
Sun for Solaris incorrectly implements font point sizes, causing
text to appear smaller on the screen. This was fixed in J2SDK v
1.2.1 and the correct point sizes for fonts are now used. If your
GUI display does not appear as expected, you may need to make some
adjustments in your application for a component's size and placement.
If you prefer to use fonts other than those that have been predefined
by the property file for your use, copy the file installed by this
kit from [.JRE.LIB]FONT.PROPERTIES to your SYS$LOGIN
directory and modify it. When you run a Java application, it will
use your local font property file instead of the one installed by
this kit.
It is difficult to supply a font.properties file that
is ideal for use in all environments -- to enable the use of many
fonts in environments that have them, yet work properly in font-poor
environments.
As a result, this kit contains two font.properties files:
font.properties
This default font.properties file is optimized
for use if you plan on displaying your application only to OpenVMS
and Tru64 UNIX workstations.
font_properties.excursion
This alternate font.properties file is optimized
for use if you plan on displaying your application only to PCs
running the DIGITAL eXcursion™ window manager. It takes
advantage of the rich font environment.
Both of these files reside in [.JRE.LIB], and the
one actually named font.properties is the one that
will be used. This file is a system-wide file and is used for the
display of all Java programs that are run on that system. The SDK
supports local customizations of the font property file which can
take affect on a user or system-wide basis. When the RTE needs to
find a font.properties file, it starts its search in
SYS$LOGIN. A local version of the font.properties file
takes precedence over a system-wide version. Therefore, you can
make either of these two files your user local font.properties
by copying the font property file of your choice to a file named
font.properties in SYS$LOGIN.
If you prefer to use fonts other than those that have been predefined
by the font properties file for your use, copy the file installed
by this kit from [.JRE.LIB]FONT.PROPERTIES to your
SYS$LOGIN directory and modify it. When you run a Java application,
it will use your local font property file instead of the one installed
by this kit. The following example makes the eXcursion version of
the file the one that is used, on a user-local basis only.
$ COPY SYS$COMMON:[JAVA$131.JRE.LIB]font_properties.excursion -
SYS$LOGIN:font.properties
Alternatively, if you want to use the font_properties.excursion
file as a system-wide file for use by all users on the system (thus
overriding the system-wide default font.properties
file), perform the following steps:
$ COPY SYS$COMMON:[JAVA$131.JRE.LIB]font.properties -
SYS$COMMON:[JAVA$131.JRE.LIB]font_properties.orig$ COPY SYS$COMMON:[JAVA$131.JRE.LIB]font_properties.excursion - SYS$COMMON:[JAVA$131.JRE.LIB]font.properties
If later you wish to revert to the original file that shipped
with the SDK kit, you would copy font_properties.orig
to font.properties.
If you encounter one of the following warnings, you are probably
referencing a font in your font.properties file that
is not available on your system. Check your font path by issuing
the OpenVMS command:$ mcr decw$utils:xset.exe -q. If
your font path setting is not what you expect, you might need to
change the search order. Also, make sure that the font property
file references fonts that are installed on your system; you may
be attempting to use a font that is not available.
"Font specified in font.properties not found [-*-helvetica-bold-r-normal...]"
If you are having problems with fonts when you display remotely to a PC using eXcursion™, you might need to upgrade to a newer version of the eXcursion software and install additional fonts. Also, make sure that the font property file references fonts that are installed on your PC.
You can define the following logical names to assist in debugging.
JAVA$PRINT_COMMAND_ARGS
$ define JAVA$PRINT_COMMAND_ARGS true
When defined, this prints out the parsed argument list before the
RTE sees it and tabulates the argument list before the RTE can add
default parameters like "-Djava.class.path=."
For example:
$ type x.x
-Xms64m
$ java "-V" x.x decus wait_time
will produce as output:
0: sys$common:[java$131.bin]java$java.exe
1: -Xms64m
2: decus
3: wait_time
_JAVA_LAUNCHER_DEBUG
$ define _JAVA_LAUNCHER_DEBUG 1
This will show the arguments in effect at the time the Java Virtual Machine starts up.
$ java -mx32m TestArgs “< = 1” 2 3
----_JAVA_LAUNCHER_DEBUG----
JRE path is /JSTABLE/build/OpenVMS-alpha
jvm.cfg[0] = ->-classic<-
1 micro seconds to parse jvm.cfg
Does ‘java$jvm_shr’ exist ... yes.
JVM path is java$jvm_shr
JavaVM args:
version 0x00010002, ignoreUnrecognized is JNI_FALSE, nOptions is 2
option[ 0] = ‘-Djava.class.path=.’
option[ 1] = ‘-Xmx32m’
1 micro seconds to InitializeJVM
Main-Class is ‘TestArgs’
Apps’ argc is 3
argv[ 0] = ‘< = 1’
argv[ 1] = ‘2’
argv[ 2] = ‘3’
1 micro seconds to load main class
----_JAVA_LAUNCHER_DEBUG----
$
JAVA$EXEC_TRACE
$ define/job JAVA$EXEC_TRACE true
You can use the logical name JAVA$EXEC_TRACE to help
debug Runtime.exec() calls on OpenVMS. When this logical
is defined, a printout displays the C Runtime Library exec
variant and its list of arguments.
JAVA$ENABLE_SIGQUIT_CTRLC
$ define JAVA$ENABLE_SIGQUIT_CTRLC true
This replaces the ^] feature in UNIX.
When defined, a CRTL-C handler will be established that
will raise the SIGQUIT signal. Then, if you type ^C,
the RTE dumps out all the Java thread information.
This logical will only work for terminal devices, when the RTE
is running interactively from a terminal process. See JAVA$ENABLE_SIGQUIT_MAILBOX
for information on how to communicate with batch jobs or detached
jobs.
JAVA$ENABLE_SIGQUIT_MAILBOX
$ define JAVA$ENABLE_SIGQUIT_MAILBOX true
Use this logical to force a Java application to dump threads, if no terminal is involved, e.g., a batch job or a detached job. Use it to dump out where the subprocess is stuck. This mimics UNIX sending a SIGQUIT to a Java process. When this logical is defined, the RTE creates a temporary mailbox you can ping from another process, allowing you to ping stuck batch jobs.
To use this, perform the following steps:
Before starting the Java application, define the following logical:
$ define JAVA$ENABLE_SIGQUIT_MAILBOX true
This creates a logical with a mailbox name. After starting your Java application, scan the job logicals tables to determine the correct mailbox. Run the following command from another terminal:
$ pipe show log/table=* *signal* | search sys$input: signal
Sample output:
"JAVA$SIGNAL_MAILBOX_20200234" = "MBA90:"
For the process pid 20200234 you have a mailbox MBA90:
Issue the following command, substituting your mailbox name for MBA90:
$ copy tt: MBA90:
You will not see any output, but whenever you press RETURN,
the subprocess will print a thread dump.
When done, type ^Y to exit the COPY command.
JAVA$FSYNC_INTERVAL RMS buffers are not usually flushed to disk until the buffer is
full or the program exits. If you want to view the contents of the
file before the buffer is full (e.g., monitoring a logfile for output),
the JAVA$FSYNC_INTERVAL logical allows you to define
an interval after which all pending output is flushed to the disk
with the command:
$ define/job JAVA$FSYNC_INTERVAL<number_of_seconds>
For example,
$ define/job JAVA$FSYNC_INTERVAL 60 ! flush any pending output to disk every 60 seconds.
Note: Defining the logical to a very low value could cause performance degradation.
The following scenarios suggest resolutions to problems you might encounter on OpenVMS Alpha systems when using the RTE.
Problem:
You wrote a Java program in a file called SERTEST.JAVA. The public class definition starts off with:
public class SerTest {
...
You've tried to compile it with the following:
$ javac SERTEST.JAVA
and also with:
$ javac sertest.java
In both cases the compilation fails with the error message:
sertest.java:7:
Public class SerTest must be defined in a
file called "SerTest.java".
public class SerTest {
^
1 error
What's wrong?
The Java runtime environment insists in a one-to-one relationship between class names and file names. You must express the file name in the same case-sensitive manner as your public class declaration, namely "SerTest.java".
So, in this example, you need to type the command as:
$ javac "SerTest.java"
If the file name is not in quotation marks,
DCL automatically uppercases the string. So by the time javac
sees it, the file name is SERTEST.JAVA, which does not match the
class name.
Problem:
You copied some Java source files from another computer and/or
have created some new .java files from scratch. Some
files compile just fine on your OpenVMS Alpha system. But if an
error occurs, the error message tells you what the error is but
the indicator "^" showing where the error occurs on the line, does
not point to anything.
What's wrong?
Java source files on OpenVMS systems must be in Stream_LF record format, although other record formats will work if the compilation is error-free. However, if an error occurs, the program cannot show you where it is on the line. To do this, the file must be in Stream_LF record format. Enter the command:
$ DIR/FULL mysource.java
Then note the line that starts with the string:
Record format:
If the Record Format is not shown as Stream_LF, you must convert it to Stream_LF. Text files can be converted to Stream_LF format with the following command:
$ CONVERT/FDL=STREAM_LF.FDL input_file.JAVA output_file.JAVA
An example of a valid STREAM_LF.FDL is shipped on the kit and can be found in:
SYS$COMMON:[JAVA$131.COM]STREAM_LF.FDL
Problem:
You copied a .ZIP file from another computer and added a reference to this .ZIP file to your CLASSPATH. You still get error messages indicating that the system is not seeing the classes defined in your new .ZIP file.
What's wrong?
Make sure that the new .ZIP file is in Stream LF format. Enter the following command:
$ DIR/FULL MY.ZIP
Note the line that starts with the string:
Record format:
If the Record Format is not shown as Stream_LF, you must convert it to Stream_LF. Binary files like .ZIP files can be converted to Stream_LF format with the following command:
$ SET FILE MY.ZIP /ATTR=(RFM:STMLF,RAT:CR)
For more details, see Stream_LF File Format Required.
Problem:
You get error messages like the following:
%IMGACT-F-SYMVECMIS, shareable image's symbol vector table mismatch -IMGACT-F-FIXUPERR, error when JAVA$JAVA_SHR referenced DECC$SHR
What's wrong?
The SDK for OpenVMS Alpha has been linked against a specific set of OpenVMS shareable images assumed to be on the user's system at runtime. These images contain enhanced functionality required by the RTE. This specific set of images is packaged into one or more ECOs (Engineering Change Orders). These ECOs are specified on the product page from which you obtained the pointers for the SDK. You must download and install these ECOs for the RTE to operate correctly.
For a list of ECOs required for your version of OpenVMS Alpha, see Prerequisites.
Problem
Your Java application displays its output to an AlphaStation without a problem. But when you try to redirect the display to a VAXstation, you get no window at all, or you see DECWindows error messages like the following:
X error event received from server: BadValue (integer parameter out of range for operation)
What's wrong?
You need to add the following line:
$DEFINE/TABLE=DECW$SERVER0_TABLE DECW$CARD16_VALIDATE TRUE
to the following file controlling your VAXStation:
SYS$MANAGER:DECW$PRIVATE_SERVER_SETUP.COM
Then restart DECWindows.
For more details, see Problem displaying to a VAXstation.
Problem
The javadoc tool produces .html files that contain
references to files that have been given different names.
What's wrong?
javadoc attempts to create .html files for each module
in the system being documented. These files are given a name that
matches its packaging hierarchy. Therefore, a package named alpha.beta.gamma
will go into a file named alpha.beta.gamma.html.
In the course of writing this file, the filename mapping algorithms
enabled by JAVA$FILENAME_CONTROLS are
applied, and in the default case (JAVA$FILENAME_CONTROLS = -1),
the file is automatically written to a file named alpha_beta_gamma.html
so that it can be represented on an OpenVMS Alpha file system.
However, references to this file, both within the file itself and
in other .html files produced by javadoc, still refer
to it by its alpha.beta.gamma.html name.
A utility program to solve this problem can be downloaded from the Frequently Asked Questions area of our web site. The utility searches through directory trees of .html files and rewrites these files so that their internal references match the names that the files were actually given.
For example, if a file contains the following reference:
<img src="javautil.doc.anc2.gif">
That reference is rewritten as:
<img src="javautil_doc_anc2.gif">
Similarly, an anchor reference like the following:
<a href="8.doc.html#40898">
Is rewritten as:
<a href="8_doc.html#40898">
To use this utility:
$ RUN PARSE_ANCHOR_IMAGE.BCK_DCX_AXPEXE
This unpacks itself into a save set called PARSE_ANCHOR_IMAGE.BCK;1.
$ BACKUP PARSE_ANCHOR_IMAGE.BCK/SAVE *.*
This gives you the following individual files:
README.HTML (This note) REWRITE_HTML_TREE.COM PARSE_ANCHOR_IMAGE.EXE
The SDK v 1.3.1 documentation tree begins at the following location on the system where the SDK is installed:
SYS$COMMON:[JAVA$131.DOCS]INDEX.HTML
The installed documentation is in HTML format and includes this release notes file and additional documentation.
Note: The documentation in the above directory does not include the API reference documentation. If you want to use the API reference documentation locally, download the separate API documentation file (DEC-AXPVMS-JAVAAPIDOC131-V0103-11-1.PCSI_SFX_AXPEXE), and install it as described in the Installing the API Reference Documentation section.
You can also browse the SDK documentation we provide with our kit on our web site.
There is also a Java entry in the OpenVMS Help facility that describes the Java command and points to the installed documentation. The Java Help file ships with the operating system and describes the version of the SDK that was shipped with the operating system; the Help file is not updated by this kit.
For more information on this release, refer to the Release Notes for the J2SDK v 1.3.1 software from Sun Microsystems, and to the Frequently Asked Questions (FAQ) web page.
If you are new to the Java programming language, you can browse or download the Java Tutorial on Sun's site.
To report problems, refer to the Support web page.
© 2001, 2004 Hewlett-Packard Development Company, L.P. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Hewlett-Packard shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is subject to change without notice. INFORMATION PROVIDED HEREWITH IS PROVIDED “AS IS” “WHERE IS” WITHOUT ANY WARRANTY WHATSOEVER. THE ENTIRE RISK ASSOCIATED WITH THE USE OF MATERIALS RESIDES WITH LICENSEE. ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, ARE DISCLAIMED, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, ACCURACY, CONDITION, OWNERSHIP, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT OF THIRD PARTY INTELLECTUAL PROPERTY RIGHTS. |
|
|||||||||||||||
|
|||||||||||||||