IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4.1 User Guide
Note: Before using this information and the product
it supports, be sure to read the general information under Notices.
This edition of the User Guide applies to the IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 1.4.1,
Service Refresh 1, and to all subsequent
releases and modifications until otherwise indicated in new editions.
(c) Copyright Sun Microsystems, Inc. 1997, 2002, 901 San Antonio Rd., Palo
Alto, CA 94303 USA. All rights reserved.
(c) Copyright International Business Machines Corporation, 1999, 2003.
All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corp.
Read this User Guide if you want to use the SDK to write Java(TM) applications
and applets or if you want to use the Runtime Environment to run them.
Read this User Guide in conjunction with the more extensive documentation
on the Sun Web site, http://java.sun.com, and the
AIX download site, http://www.ibm.com/developerworks/java/jdk/aix.
The software that is contained in this release can be used only on AIX(R)
Version 5.1 or later. It is not supported, and does not work, on earlier versions
of the AIX operating system. See AIX Environment for
further details of requirements on the AIX operating system for this release.
This User Guide is part of a release and is applicable only to that particular
release. Ensure that you have the User Guide appropriate to the release you
are using.
Useful Web sites include:
The terms "Runtime Environment" and "Java Virtual Machine" are used interchangeably
throughout this User Guide.
Technical changes for this User Guide are indicated in red.
The SDK is a development environment for writing applets and applications
that conform to the Java 1.4 Core Application Program Interface (API).
An applet or application that ran with earlier versions of
the SDK should run with this version, except for the incompatibilities
listed in:
http://java.sun.com/j2se/1.4/compatibility.html
http://java.sun.com/j2se/1.3/compatibility.html
http://java.sun.com/products/jdk/1.2/compatibility.html
There is no guarantee that 1.4.1-compiled classes work on pre-1.4.0
SDK releases.
Applets that depend on the Java 1.4 (or later) APIs will
not work with browsers that do not support these APIs unless you install the
Java Plug-in.
The IBM 32-bit SDK for AIX, v1.4.1 has the following features:
- Fully compatible with the Java 2 version 1.4.1 language, enabling "Write
Once Run Anywhere"
- A comprehensive Diagnostics Guide for Java 1.4.1
at http://www.ibm.com/developerworks/java/jdk/diagnosis/index.html.
- Performance enhancements to make Java programs run faster
- The latest version of the IBM optimizing Just In Time (JIT) compiler version 5.0 with Mixed Mode Interpreter (MMI -
for selective compilation of frequently executed code)
- Concurrent garbage collection option, which can significantly reduce maximum
application pause times
- Incremental compaction, which significantly decreases the chance of a
full heap compaction (important for multi-gigabyte heaps)
- Support of AIX Large Pages
- Support of AIX's Very Large Address Space Model
- Java 3D version 1.3
- JavaHelp version 1.1.2
- A new Reliability, Accessibility, and Serviceability interface, to help
the IBM Service team debug any problems
- Efficient exploitation of AIX native threads
- "Handle-less" object model
- Fast, lightweight monitors
- Efficient management of large Java heaps through optimized object allocation
and efficient garbage collection with JVM runtime parameters for specifying
garbage collection policy
- Thread-local heap
- Support for the European Union currency, the Euro
- Robust networking supporting a large number of concurrent connections
- Better scaling support for large numbers of threads and large numbers
of file handles
- Java Communications API version 2.0
- IBM Big Decimal Extension
The IBM 32-bit SDK for AIX, v1.4.1, runs on AIX 5.1 (Recommended Maintenance Package AIX
5100-04 plus APAR IY46667), AIX 5.2 (Recommended Maintenance Package AIX 5200-01
plus APAR IY46668) and any later compatible level.
To test whether this Java 1.4.1 SDK is supported on a specific
pSeries system, at the system prompt type:
lscfg -p | fgrep Architecture
You should receive the reply:
Model Architecture: chrp
Only "Common Hardware Reference Platform" (chrp) systems are supported
by this SDK.
If you are using one of the supported non-UTF8 CKJ locales, you must install
one of the following filesets (the install images are available on AIX 5.1/5.2
base CDs; updates are available from the AIX fix distribution Web site, https://techsupport.services.ibm.com/server/fixes):
X11.fnt.ucs.ttf (for ja_JP or Ja_JP)
X11.fnt.ucs.ttf_CN (for zh_CN or Zh_CN)
X11.fnt.ucs.ttf_KR (for ko_KR)
X11.fnt.ucs.ttf_TW (for zh_TW or Zh_TW)
The SDK contains a Java Runtime Environment (JRE). This section describes
the contents of the Runtime Environment and other SDK tools.
Applications written entirely in Java should have no dependencies
on the IBM SDK's directory structure (or files in those directories). Any
dependency on the SDK's directory structure (or the files in those directories)
could result in application portability problems.
- Core Classes -- These are the compiled class files for the platform
and must remain zipped for the compiler and interpreter to access them. Do
not modify these classes; instead, create subclasses and override where you
need to.
- JRE tools -- The following tools are part of the Runtime Environment and are in
the /usr/java14/jre/bin directory.
- Java Interpreter (java)
- Executes Java bytecodes. The Java Interpreter runs programs that are written
in the Java programming language.
- Java Interpreter (javaw)
- Executes Java bytecodes in the same way as the java command
does, but does not use a console window.
- Key and Certificate Management Tool (keytool)
- Manages a keystore (database) of private keys and their associated X.509
certificate chains that authenticate the corresponding public keys.
- Policy File Creation and Management Tool (policytool)
- Creates and modifies the external policy configuration files that define
your installation's Java security policy.
- RMI activation system daemon (rmid)
- Starts the activation system daemon so that objects can be registered
and activated in a Java virtual machine (JVM).
- Common Object Request Broker Architecture (CORBA) Naming Service (tnameserv)
- Starts the CORBA transient naming service.
- Java Remote Object Registry (rmiregistry)
- Creates and starts a remote object registry on the specified port of the
current host.
- iKeyman GUI utility.
- Dump extractor (jextract)
- The following tools are part of the SDK and are located in the /usr/java14/bin
directory:
- Java Compiler (javac)
- Compiles programs that are written in the Java programming language into
bytecodes (compiled Java code).
- Java Applet Viewer (appletviewer)
- Tests and runs applets outside a Web browser.
- Java Debugger (jdb)
- Helps debug your Java programs.
- Class File Disassembler (javap)
- Disassembles compiled files and can print a representation of the bytecodes.
- Java Documentation Generator (javadoc)
- Generates HTML pages of API documentation from Java source files.
- Java Plug-in HTML Converter (HtmlConverter)
- Converts an HTML page that contains applets to a format that can use the
Java Plug-in.
- C Header and Stub File Generator (javah)
- Enables you to associate native methods with code written in the Java
programming language.
- Java Archive Tool (jar)
- Combines multiple files into a single Java Archive (JAR) file.
- JAR Signing and Verification Tool (jarsigner)
- Generates signatures for JAR files, and verifies the signatures of signed
JAR files.
- Native-To-ASCII Converter (native2ascii)
- Converts a native encoding file to an ASCII file that contains characters
encoded in either Latin-1 or Unicode, or both.
- Java Remote Method Invocation (RMI) Stub Converter (rmic)
- Generates stubs, skeletons, and ties for remote objects. Includes RMI
over Internet Inter-ORB Protocol (RMI-IIOP) support.
- IDL to Java Compiler (idlj)
- Generates Java bindings from a given IDL file.
- Serial Version Command (serialver)
- Returns the serialVersionUID for one or more classes in a format that
is suitable for copying into an evolving class.
- Extcheck utility (extcheck)
- Detects version conflicts between a target jar file and currently-installed
extension jar files.
- Cross-platform dump formatter (jformat)
- Java Web Start (webstart_install_sdk.sh)
- Enables the deployment and automatic maintenance
of Java applications. For more information, see Installing Web Start.
- INCLUDE FILES
- C headers for JNI programs.
- USER GUIDE
- COPYRIGHT
- Copyright notice for the SDK for AIX software.
- LICENSE
- The LICENSE file, /usr/swlag/<locale>/Java14.la, contains
the license agreement for the SDK for AIX software (where <locale> is the name of your locale, for example En_US). To
view or print the license agreement, open the file in a Web browser.
- FIXES.LST
- A text file that describes any defects that are fixed after the initial
release of this version.
Note:
See the documentation directory (/usr/java14/docs) for additional information
about this SDK. You might also be interested in downloading Sun's documentation
package from this Web site: http://java.sun.com/products/jdk/1.4/.
The documentation package is designed to be extracted into the SDK software
installation directory. If you download the ZIP file archive version, be sure
to preserve the path names when you extract the files from the archive.
The following tools are not included in the IBM SDK:
- MIF doclet
- orbd
- servertool
The IBM 32-bit SDK for AIX, v1.4.1 complete release consists of several installp image
files (packages). Each installp image file or package contains one or more
related filesets. You can install the packages using the smit or smitty system management tools. Alternatively,
you can use the installp command.
These packages are required:
- Java14.license (license)
- Java14.sdk (base SDK, WebStart, and dt.jar)
These packages are optional:
- Java14.debug (_g version of files such as java_g and libjvm_g.a)
- Java14.ext (Comm API, Java 3D, and JavaHelp)
- Java14.samples (demos)
- Java14.source (src.jar)
- Java14.msg.$LANG
$LANG is one of the following locales. These packages do not ship any files
but pull in required Unicode TrueType fonts, if not already installed, for
these locales:
- Zh_CN
- zh_CN
- ko_KR
- Ja_JP
- ja_JP
- Zh_TW
- zh_TW
The SDK is installed in the directory:
/usr/java14/
Set up your PATH environment variable to refer
to the new installation:
export PATH=/usr/java14/jre/bin:/usr/java14/bin:$PATH
Note: These elements of PATH changed, at Version
1.3.0, from the previous SDK releases. The V1.4.1 SDK does not use
a java wrapper as Version 1.1.x and 1.2.2 did. When you install the V1.4.1 SDK in
the /usr/java14/ directory, if you have symbolic links created by the v1.1.8 SDK and
you don't set up the PATH environment variable,
the v1.1.8 SDK is picked up as the default. You are not recommended to remove
the old links in case you have applications that require the v1.1.8 SDK.
To help ensure that the verification process behaves consistently, first:
*JAVA_HOME is
used in 1.1.x releases. It is not required to set JAVA_HOME in this release.
If you issue the command:
you should see:
When verification is complete, log on again and review any values that
you might have assigned to these variables with the new installation for possible
conflicts. Unless .hotjava already existed, executing
the applet viewer creates a directory called .hotjava in your home directory. Issuing the command:
should confirm this.
The IBM JIT compiler (libjitc.a) dynamically generates machine code for
frequently-used bytecode sequences in a Java application or applet during
execution. The JIT v5.0 compiler delivers dynamic compiler technology, including:
- Improvements to optimizations that were implemented in previous versions
of the JIT
- Optimizations that were added to JIT v5.0
- Stack allocation of objects
- Improved hardware exploitation
All SDK tools use the JIT by default. After installation, you can specify
whether or not the JIT will be used. You can disable the JIT to help in the
isolation of a problem with a Java application, an applet, or the compiler
itself.
There are two ways to disable the JIT:
- Type the following at a command prompt:
- For the Korn shell:
- For the Bourne shell:
-
JAVA_COMPILER=NONE
-
export JAVA_COMPILER
- For the C shell:
To enable the JIT, set the JAVA_COMPILER environment
variable to "jitc" or switch on the JIT compiler through the command line:
java -Djava.compiler=jitc <myapp>
To determine whether the JIT is enabled, type the following at a command
prompt:
java -version
If the JIT is not in use, a message is displayed that includes the following:
JIT disabled
If the JIT is in use, a message is displayed that includes the following:
JIT enabled: jitc
Note:
If JAVA_COMPILER="" or -Djava.compiler="" , the JIT compiler is disabled. If JAVA_COMPILER is unset, as in:
unset JAVA_COMPILER
the default JIT compiler is enabled. The default JIT compiler is always
the latest version.
The following sections provide information about using the SDK.
To obtain the IBM build and version number, at a command prompt type:
java -version
The main SDK tools are programs that are run from a command prompt.
After installing the SDK software, you run a tool by typing its name at
a command prompt with a filename as an argument.
You can specify the path to a tool by typing the path in front of the tool
each time. For example, if the javac compiler is in /usr/java14/bin, you can
compile a file named myfile.java by typing the following at a command prompt:
/usr/java14/bin/javac myfile.java Alternatively, you can add the
string /usr/java14/bin to your PATH environment variable.
Then you can compile the myfile.java file by typing the following at a command
prompt:
javac myfile.java The PATH environment
variable enables AIX to find the executable files (such as javac, java,
and javadoc) from any directory. To find the current value of your PATH, at a command prompt type:
echo $PATH
Note:
Like the 1.3.0 and 1.3.1 versions, the IBM 32-bit SDK for AIX, v1.4.1 ships the java
tools as binary executables instead of the shell scripts that were shipped
in previous versions up to Version 1.2.2. The PATH environment variable must point to the bin directories
instead of sh directories as follows:
export PATH=/usr/java14/bin:/usr/java14/jre/bin:$PATH
The java tool launches a Java application.
It does this by starting a Java Runtime Environment, loading
a specified class, and invoking that class's main method. The method declaration
must have the signature:
public static void main(String args[]) The
method must be declared public and static, it must not return any value, and
it must accept a String array as a parameter. By default, the first non-option
argument is the name of the class to be invoked. Use a fully-qualified class
name.
The JVM searches for the startup class, and other classes that are used,
in three sets of locations: the bootstrap classpath, the installed extensions,
and the user classpath. Arguments after the class name or JAR file name
are passed to the main function.
The javaw command is identical to java, except that javaw has no associated console
window. Use javaw when you do not want a command prompt
window to appear. The javaw launcher displays a dialog
box with error information if a launch fails.
The java and javaw command
have the following syntax:
java [ options ] class [ arguments ... ]
java [ options ] -jar file.jar [ arguments ... ]
javaw [ options ] class [ arguments ... ]
javaw [ options ] -jar file.jar [ arguments ... ]
Items that are within brackets are optional.
- options
- Command-line options.
- class
- Name of the class to invoke.
- file.jar
- Name of the jar file to invoke. It is used only with -jar.
- argument
- Argument passed to the main function.
If the -jar option is specified, the named JAR file
contains class and resource files for the application, with the startup class
indicated by the Main-Class manifest header.
The launcher has a set of standard options that are supported on the current
runtime environment and will be supported in future releases. In addition,
there is a set of non-standard options.
Standard options
-
-D<property_name>=<value>
- -assert
- Prints help on assert-related options.
- -cp or -classpath <directories and zip or jar files separated by :>
- Set search path for application classes and resources. If -classpath and -cp are not used, and CLASSPATH is not set, the user classpath is, by default, the current
directory (.). Also see Working with classpaths.
- -help or -?
- -showversion
- Prints product version and continues.
- -verbose:[class | gc | jni]
- -version
- -X
- Prints help on non-standard options.
Non-standard options
The -X options listed below are a subset of the available
ones. They are nonstandard and subject to change without notice.
- -Xargencoding
- Allows the options on the java command to use Unicode escape sequences
to represent characters that are not in the character set of the locale. Unicode
escape sequences are of the form \u#### where # is a hexadecimal digit.
- -Xbootclasspath:<directories
and zip or jar files separated by ;>
- Sets search path for bootstrap classes and resources. There are other
ways of setting the bootclasspath. See Working with the bootclasspath. Do not deploy applications that use this option to override a class in core.jar,
graphics.jar, server.jar, security.jar, xml.jar, tools.jar, or charsets.jar,
because such a deployment would contravene the Java 2 Runtime Environment
binary code license.
Note:
The rt.jar of earlier releases
has been split up into various jar files in Version 1.4.1: core.jar, graphics.jar,
security.jar, server.jar, and xml.jar.
- -Xbootclasspath/a:<directories
and zip or jar files separated by ;>
- Appends to end of bootstrap class path.
- -Xbootclasspath/p:<directories
and zip or jar files separated by ;>
- Puts on the front of bootstrap class path. Do not deploy applications
that use this option to override a class in core.jar, graphics.jar, server.jar,
security.jar, xml.jar, tools.jar, or charsets.jar, because such a deployment
would contravene the Java 2 Runtime Environment binary code license.
- -Xcheck:jni
- Performs additional checks for JNI functions.
- -Xcheck:nabounds
- Performs additional checks for JNI array operations.
- -Xdebug
- Starts the JVM with the debugger enabled.
- -Xdisableexplicitgc
- Changes calls to System.gc() into no-ops.
- -Xdisablejavadump
- Disables the java dump facility for abnormal process termination. When
the java dump is disabled, the system process termination dump is run. The
java dump is useful when the problem occurs within the java code.
- -Xgcpolicy:{optthruput
| optavgpause | subpool}
- -Xlp
- Requests the SDK to allocate the Java heap (the heap from which Java objects
get allocated) with 16 MB large pages. If large pages are not available,
the Java heap will be allocated with AIX's standard 4 KB pages. AIX requires
special configuration to enable large pages. For more information on configuring
AIX support for large pages, see http://www.ibm.com/servers/aix/whitepapers/large_page.html. The SDK supports the use of large pages only to back the Java heap's
share memory segments (the SDK uses shmget() with the SHM_LGPG and SHM_PIN
flags to allocate large pages). The use of the LDR_CNTRL=LARGE_PAGE_DATA environment variable is not supported. The -Xlp option
replaces the environment variable IBM_JAVA_LARGE_PAGE_SIZE, which is now ignored if set.
- -Xms<size>
- Sets initial Java heap size. The default is 4 MB.
- -Xmx<size>
- Sets maximum Java heap size. The default is 64 MB.
- -Xnoclassgc
- Disables class garbage collection.
- -Xoss<size>
- Sets maximum Java stack size for any thread. The default
is 400 KB.
- -Xquickstart
- Improves the startup time of applications . If you do not specify this
option, the initial compilation of methods is done at high optmization (that
is, the JIT does not recompile "hot" methods because the methods are initially
compiled with high optimization).
- -Xrs
- Reduces the use of operating system signals.
- -Xrunlibrary_name[:options]
- Loads helper libraries. To load multiple libraries, specify it more than
once on the command line. Examples of these libraries are:
- -Xrunhprof[:help] | [:<option>=<value>, ...]
- Performs heap, CPU, or monitor profiling.
- -Xrunjdwp[:help] | [:<option>=<value>, ...]
- Loads debugging libraries to support the remote debugging of applications.
- -Xss<size>
- Sets maximum native stack size for any thread. The default
is 512 KB.
- -Xverbosegclog:<path to file><filename>[X, Y]
- -Xverify
- Enables strictest checks, anticipating future default.
The java command and other java launcher commands
(such as javaw) allow a class name to be specified as
any Unicode character that is in the character set of the current locale.
You can specify any Unicode character in the class name and arguments by
using java escape sequences. To do this, you must specify -Xargencoding. To specify a Unicode character, use escape sequences in
the form \u####, where # is a hexadecimal digit
(0 through 9, A through F).
To specify that the class name and command arguments are in UTF8 or ISO8859_1
encoding, use -Xargencoding:utf8 and -Xargencoding:latin.
In the Runtime Environment, if you are using a non-English locale, the java and javaw commands give translated output
messages. These messages are different from those that are in the 1.3.1 version
and also differ based on the locale in which Java is running. The detailed
error descriptions and other debug information that is returned by java is in English. Debug information that is returned during initialization
is shown in brackets.
In the Runtime Environment, you can specify a class name as a complete file name including
a full path and the .class extension. In previous versions of the SDK, you
could specify only the class that was relative to the CLASSPATH, and the .class extension was not allowed. Use of the complete file
name permits you to launch a java application from your desktop or file launcher.
If you specify a .class file with path and extension, the specified path is
put into the CLASSPATH. For example, the command java ~/myapp/thisapp.class is equivalent to specifying java -classpath ~/myapp thisapp.
The environment variable LIBPATH tells AIX applications,
such as the JVM, where to find shared libraries when they are located in a
different directory from the directory that is specified in the header section
of the executable. For example, the header section of the java command is.
>dump -H /usr/java14/jre/bin/java
/usr/java14/jre/bin/java:
***Loader Section***
Loader Header Information
VERSION# #SYMtableENT #RELOCent LENidSTR
0x00000001 0x0000003f 0x0000006d 0x00000090
#IMPfilID OFFidSTR LENstrTBL OFFstrTBL
0x00000006 0x00000b24 0x00000099 0x00000bb4
***Import File Strings***
INDEX PATH BASE MEMBER
0 /usr/lib:/lib
1 libc.a shr.o
2 libC.a shr.o
3 libpthreads.a shr_comm.o
4 libpthreads.a shr_xpg5.o
5 libbsd.a shr.o
Index 0 (in bold above) contains the list of directories that are searched
for shared objects if LIBPATH is not specified. If LIBPATH is set, the specified directories are searched for
shared objects before those listed in Index 0 of the header.
The shared libraries for the SDK are located in /usr/java14/jre/bin and/usr/java14/jre/bin/classic.
These directories are automatically searched by the SDK's java launcher programs
(for example, java, javac, jar). If Java is installed as an AIX fileset, the
parent directory is /usr/java14/, but packages that bundle Java might use different
directories. This path is already set by the Java launcher programs such as java, javac, or jar.
Set the LIBPATH if:
- You are using other shared libraries (including JNI native libraries you
use or develop). Set the LIBPATH to include the directory
or directories that contain your libraries.
- You are using the JNI Invocation API to call Java code from you C/C++
application. Set the LIBPATH to include the directories
that contain the JVM libraries in addition to those that contain your own
libraries.
The LD_LIBRARY_PATH environment variable
is not used by Java. If your application needs to search specific directories
when looking for shared libraries, the only variable to set is LIBPATH.
You can set the system property ibm.jvm.bootclasspath by using the -D option that is described in Launching a Java application. The value of this property is used as an additional search
path, which is inserted between any value that is defined by -Xbootclasspath/p: and the bootstrap classpath. The bootstrap
classpath is either the default, or that that is defined using the -Xbootclasspath: option.
The -Xgcpolicy JVM runtime option specifies garbage
collection policy.
-Xgcpolicy takes the values optthruput
(the default), optavgpause, or subpool.
The option controls garbage collector behavior, making tradeoffs between throughput of the application and overall
system and the pause times that are caused by garbage collection.
The format of the option and its values is: -Xgcpolicy:optthruput
-Xgcpolicy:optavgpause
-Xgcpolicy:subpool
Pause time
When an application's attempt to create an object cannot be satisfied immediately
from the available space in the heap, the garbage collector is responsible
for identifying unreferenced objects (garbage), deleting them, and returning
the heap to a state in which the immediate and subsequent allocation requests
can be satisfied quickly. Such garbage collection cycles introduce occasional
unexpected pauses in the execution of application code. Because applications
grow in size and complexity, and heaps become correspondingly larger, this
garbage collection pause time tends to grow in size and significance. The
default garbage collection value, optthruput, delivers
very high throughput to applications, but at the cost of these occasional
pauses, which can vary from a few milliseconds to many seconds, depending
on the size of the heap and the quantity of garbage.
The subpool option of -Xgcpolicy provides additional throughput optimization for large SMP
systems (24- to 32-way).
Pause time reduction
The optavgpause option substantially reduces the
time that is spent in these garbage collection pauses, in addition to limiting
the effect of increasing heap size on the length of the garbage collection
pause. This option is particularly relevant to configurations that have large
heaps. (Consider a heap as large when it is at least 1 GB.) The pause
times are reduced by performing some garbage collection activities that are
concurrent with normal program execution. With the reduced pause time, you
might experience some reduction of application throughput, which varies from
application to application.
Environments with very full heaps
If the Java heap becomes nearly full, and very little garbage is to be
reclaimed, requests for new objects might not be satisfied quickly because
no space is immediately available. If the heap is operated at near-full capacity,
application performance might suffer regardless of which of the above options
is used; and, if requests for more heap space continue to be made, the application
receives an OutofMemory exception, which results in JVM termination if the
exception is not caught and handled. At this point the JVM will produce two diagnostic files: a Heapdump and a Javadump. These are detailed in the
Diagnostics Guide for Java 1.4.1
and can be used to determine what caused the high occupancy of the Java heap. In these conditions, you are recommended
either to increase the heap size by using the -Xmx option,
or to reduce the number of application objects in use.
Further information about garbage collection
For more detailed information about garbage collection, see:
http://www.ibm.com/developerworks/ibm/library/i-garbage1/
http://www.ibm.com/developerworks/ibm/library/i-garbage2/
http://www.ibm.com/developerworks/ibm/library/i-garbage3/
For information about handling memory leaks in your Java application, see: http://www.ibm.com/developerworks/library/j-leaks/index.html.
For information about tuning the heap size see:http://www-106.ibm.com/developerworks/library/j-tip-heap-size.html.
When the SDK runs in an AIX 5.2 logical partition (LPAR), you can move
partition resources from one AIX 5.2 partition to another without requiring
a reboot of the system of the affected partitions. Note that if you decrease
the number of CPUs or real memory allocated to an LPAR, the performance of
SDK applications might degrade.
If you run SDK applications on a single CPU LPAR and never dynamically
add a CPU to that LPAR while those SDK applications are running, you can improve
the performance (results vary depending on the execution characteristics of
your application) by exporting the following environment variable: export
NO_LPAR_RECONFIGURATION=1. Do not export this environment variable unless
you can guarantee all of the following:
- You are running in a LPAR
- The LPAR has 1 CPU
- The LPAR will never be dynamically reconfigured to add more CPUs while
SDK applications are running.
For more information, see http://www.ibm.com/servers/eserver/pseries/hardware/whitepapers/dlpar.html and the article: Dynamic reconfiguration: Basic building
blocks for autonomic computing on IBM pSeries servers in the following
IBM Systems Journal issue: http://www.research.ibm.com/journal/sj42-1.html.
With the Applet Viewer, you can run one or more applets that are called
by reference in a Web page (HTML file) by using the APPLET tag. The Applet
Viewer finds the APPLET tags in the HTML file and runs the applets, in separate
windows, as specified by the tags.
Because the Applet Viewer is for viewing applets, it cannot display a whole
Web page that contains many HTML tags. It parses only the APPLET tags and
no other HTML on the Web page.
To run an applet with the Applet Viewer, type the following at a command prompt:
appletviewer name
where name is one of the following:
- The file name of an HTML file that calls an applet
- The URL of a Web page that calls an applet
For example, to invoke the Applet Viewer on an HTML file that calls an
applet, type at a command prompt:
appletviewer $HOME/filename.html where filename is the
name of the HTML file.
For example, http://java.sun.com/applets/NervousText/example1.html is the URL of a Web page that calls an applet. To invoke the Applet
Viewer on this Web page, type at a shell prompt:
appletviewer http://java.sun.com/applets/NervousText/example1.html
The Applet Viewer does not recognize the charset option
of the <META> tag. If the file that appletviewer loads is not encoded as
the system default, an I/O exception might occur. To avoid the exception,
use the -encoding option when you run appletviewer.
For example:
appletviewer -encoding JISAutoDetect sample.html
You can debug applets by using the -debug option
of Applet Viewer. When debugging applets, you are advised to invoke the Applet
Viewer from the directory that contains the HTML file that calls the applet.
For example:
cd demo/applets/TicTacToe
../../bin/appletviewer -debug example1.html
You can find documentation about the debugger and its API at the Sun Web
site: http://java.sun.com/products/jdk/1.3/debugging/
See http://java.sun.com for any legal statements
regarding this information.
The Java Plug-in HTML converter allows you to convert any HTML page that
contains applets to a format that will use the Java Plug-in. The tool is in
the /usr/java14/bin directory with a jar file in the /usr/java14/lib directory.
For more information about the Java Plug-in HTML Converter, see the Sun
Web site: http://java.sun.com/products/plugin/1.3/features.html
Consider the following string of tokens:
opcode:attributeName:attributeValue\t
In Version 1.2.2, you set the delimiter to ":", and through the nextToken()
method of StringTokenizer obtain the token's "opcode" and "attributeName".
Then the delimiter is changed to "\t", and token "attributeValue" is returned
with StringTokenizer.nextToken().
In Version 1.3 and 1.4, if the delimiter is changed midway through tokenizing,
the next token starts with the old delimiter. The token returned is ":attributeValue".
Your application must check to see whether the next token is prepended with
the previous delimiter when the delimiter has been changed, and remove it
if it is.
The IBM 32-bit SDK for AIX, v1.4.1 uses the IPv6 extensions to the TCP/IP protocol by
default.
On AIX v5.2, if your application uses multicast sockets or your application
explicitly uses IPv6 format address, you must enable the network interfaces
on your machine to handle IPv6 addresses. The network interfaces can be configured
for IPv6 with smitty or by using the autoconf6 or ifconfig commands. Alternatively,
if you do not want to use IPv6 protocols, you can set the property java.net.preferIPv4Stack
to force the use of IPv4 protocols.
However, all levels of AIX v5.1 currently do not support IPv4-mapped Multicast
addresses. If you are using an IPv4 Multicast address, you cannot join a Multicast
group whether or not you are switching your application to IPv6. You must
change the default of your application by setting the java.net.preferIPv4Stack to true:
java -Djava.net.preferIPv4Stack=true <classname> where <classname> is the file name of
your .class file.
The Java 2 Platform, Service Edition (J2SE) supports, at a minimum, the
specifications that are defined in the Official Specifications for CORBA support
in J2SE 1.4 at http://java.sun.com/j2se/1.4.1/docs/api/org/omg/CORBA/doc-files/compliance.html. In some cases, the IBM J2SE ORB supports more-recent versions of the
specifications.
This SDK supports all versions of GIOP, as defined by chapters 13 and
15 of the CORBA 2.3.1 specification, OMG document formal/99-10-07, which you can obtain from:
http://www.omg.org/cgi-bin/doc?formal/99-10-07
Bidirectional GIOP is not supported.
This SDK supports Portable Interceptors, as defined by the OMG in the
document ptc/01-03-04, which you can obtain
from:
http://www.omg.org/cgi-bin/doc?ptc/01-03-04
Portable Interceptors are hooks into the ORB through which ORB services
can intercept the normal flow of execution of the ORB.
This SDK supports the Interoperable Naming Service, as defined by the
OMG in the document ptc/00-08-07, which you can obtain
from:
http://www.omg.org/cgi-bin/doc?ptc/00-08-07
The default port that is used by the Transient Name Server (the tnameserv command), when no ORBInitialPort parameter
is given, has changed from 900 to 2809, which is the port number that is registered with the IANA (Internet
Assigned Number Authority) for a CORBA Naming Service. Programs that depend
on this default might have to be updated to work with this version.
The initial context that is returned from the Transient Name Server is
now an org.omg.CosNaming.NamingContextExt. Existing
programs that narrow the reference to a context org.omg.CosNaming.NamingContext still work, and do not need to be recompiled.
The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters that are defined by the Interoperable Naming
Service specification, and the ORB::string_to_object operation now supports
the ObjectURL string formats (corbaloc: and corbaname:) that are defined by
the Interoperable Naming Service specification.
The OMG specifies a method ORB::register_initial_reference to register
a service with the Interoperable Naming Service. However, this method is not
available in the Sun Java Core API at Version 1.4.1. Programs that need to register
a service in the current version must invoke this method on the IBM internal
ORB implementation class. For example, to register a service "MyService":
((com.ibm.CORBA.iiop.ORB)orb).register_initial_reference ("MyService", serviceRef);
where orb is an instance of org.omg.CORBA.ORB, which is returned from ORB.init(), and serviceRef is a CORBA Object, which
is connected to the ORB.This mechanism is an interim one, and is not compatible
with future versions or portable to non-IBM ORBs.
A runtime debug feature provides improved serviceability. You might find
it useful for problem diagnosis or it might be requested by IBM service personnel.
Tracing is controlled by three system properties.
- To turn on tracing, set com.ibm.CORBA.Debug=true .
- To format and add to the trace GIOP messages sent and received, set com.ibm.CORBA.CommTrace=true.
By default, ORB tracing goes to files that have names of the form orbtrc.DDMMYYYY.HHmm.SS.txt.
- To send it to a different file, set com.ibm.CORBA.Debug.Output=<filename>.
For example, to trace events and formatted GIOP messages, type:
java -Dcom.ibm.CORBA.Debug=true
-Dcom.ibm.CORBA.CommTrace=true myapp
Do not turn on tracing for normal operation, because it might cause performance
degradation. Even if you have switched off tracing, FFDC (First Failure
Data Capture) is still working, so that only serious errors are reported.
If a debug output file is generated, examine it to check on the problem. For
example, the server might have stopped without performing an ORB.shutdown().
The content and format of the trace output might vary from version to version.
The following properties help you to tune the ORB:
- To control GIOP 1.2 fragmentation, set the system property com.ibm.CORBA.FragmentSize.
For example, to set the fragment size to
4096 bytes:
java -Dcom.ibm.CORBA.FragmentSize=4096 myapp
The default fragment size is 1024 bytes. You can turn off fragmentation
by setting the fragment size to 0.
- In a heterogeneous network, the response to a CORBA Request might be delayed
or lost. You can set the maximum time to wait by using the system property com.ibm.CORBA.RequestTimeout. Also, you can use com.ibm.CORBA.LocateRequestTimeout to control the timeout for LocateRequests.
For example, to restrict both delays to 30 seconds, type:
java -Dcom.ibm.CORBA.RequestTimeout=30
-Dcom.ibm.CORBA.LocateRequestTimeout=30 myapp
By default, the
ORB waits indefinitely for a response. Do not set the timeout too low, or
connections might be ended unnecessarily.
- If your program is providing a service in the network, you might have
to set, to a well-known value, the number of the port from which the ORB reads
incoming requests. You can control this by using the system property com.ibm.CORBA.ListenerPort.
For example, to make the ORB use port
1050, type:
java -Dcom.ibm.CORBA.ListenerPort=1050 myapp
If this property is set, the ORB starts listening as soon as it is initialized.
Otherwise, it starts listening only when required.
The following properties may be necessary to enable non-standard behaviour for some vendor ORBs:
- To use the POA ImplicitActivation policy with, for example, older Visibroker ORBs, it may be necessary to set the system property
com.ibm.CORBA.POACompatibilityMode=true
This property causes non-standard system exception, CORBA::OBJ_ADAPTER, to be thrown from org.omg.PortableServer.Servant._get_delegate when the delegate is null, in place of the standard exception CORBA::BAD_INV_ORDER.
When using an ORB whose POA implementation relies upon receiving the CORBA::OBJ_ADAPTER system exception without this property set, the following failure may be observed:
org.omg.CORBA.INTERNAL:org.omg.CORBA.BAD_INV_ORDER: The Servant has not been associated with an ORBinstance.
When running with a Java 2 SecurityManager, invocation of some methods
in the CORBA API classes might cause permission checks to be made, which might
result in a SecurityException. Affected methods include the following:
Table 1. Methods affected when running with Java 2 SecurityManager
| Class/Interface |
Method |
Required permission |
org.omg.CORBA.ORB
|
init |
java.net.SocketPermission resolve |
org.omg.CORBA.ORB
|
connect |
java.net.SocketPermission listen |
org.omg.CORBA.ORB
|
resolve_initial_references |
java.net.SocketPermission connect |
org.omg.CORBA.
portable.ObjectImpl
|
_is_a |
java.net.SocketPermission connect |
org.omg.CORBA.
portable.ObjectImpl
|
_non_existent |
java.net.SocketPermission connect |
org.omg.CORBA.
portable.ObjectImpl
|
OutputStream _request (String, boolean) |
java.net.SocketPermission connect |
org.omg.CORBA.
portable.ObjectImpl
|
_get_interface_def |
java.net.SocketPermission connect |
org.omg.CORBA.
Request
|
invoke |
java.net.SocketPermission connect |
org.omg.CORBA.
Request
|
send_deferred |
java.net.SocketPermission connect |
org.omg.CORBA.
Request
|
send_oneway |
java.net.SocketPermission connect |
javax.rmi.
PortableRemoteObject
|
narrow |
java.net.SocketPermission connect |
If your program uses any of these methods, ensure that it is granted the
necessary permissions.
The ORB implementation classes in this release are:
- org.omg.CORBA.ORBClass=com.ibm.CORBA.iiop.ORB
- org.omg.CORBA.ORBSingletonClass=com.ibm.rmi.corba.ORBSingleton
- javax.rmi.CORBA.UtilClass=com.ibm.CORBA.iiop.UtilDelegateImpl
- javax.rmi.CORBA.StubClass=com.ibm.rmi.javax.rmi.CORBA.StubDelegateImpl
- javax.rmi.CORBA.PortableRemoteObjectClass=com.ibm.rmi.javax.rmi.PortableRemoteObject
These are the default values, and you are advised not to set these properties
or refer to the implementation classes directly. For portability, make references
only to the CORBA API classes, and not to the implementation. These values
might be changed in future releases.
Java Remote Method Invocation (RMI) provides a simple mechanism to do distributed
Java programming. RMI over IIOP (RMI-IIOP) uses the Common Object Request
Broker Architecture (CORBA) standard Internet Inter-ORB Protocol (IIOP protocol)
to extend the base Java RMI to perform communication. This allows direct interaction
with any other CORBA Object Request Brokers (ORBs), whether they were implemented
in Java or another programming language.
For information about IBM and RMI-IIOP, see this IBM Web site:
http://www.ibm.com/developerworks/java/rmi-iiop
The following documentation is available:
- The RMI-IIOP Programmer's Guide is an
introduction to writing RMI-IIOP programs. The guide is installed when you
install this documentation. You can also find the guide on the Web site above
under Supporting documentation (on the right-hand side).
- The demo directory (in /usr/java14/) contains:
- A "Hello World" example that can switch between the Java Remote Method
Protocol (JRMP) and IIOP protocols (demo/rmi-iiop/hello)
- A "Hello World" example that interacts with a standard IDL program (demo/rmi-iiop/idl)
- The Java Language to IDL Mapping document is a
detailed technical specification of RMI-IIOP and can be found at:
http://www.omg.org/cgi-bin/doc?ptc/00-01-06.pdf
Java runs with system contention scope threads (AIXTHREAD_SCOPE=S). Among other things, this way of running means that a Java thread
is mapped one-to-one to each AIX kernel thread and that these threads are
scheduled against all other threads in the system. Each thread has an initial
priority that is dynamically modified by the AIX scheduler, according to the
thread's activity; thread execution is time-sliced. As such, the Java interfaces
for setting thread priority have no effect on the thread's actual priority.
For more details on AIX thread scheduling, see:
http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm
For maximum threads (with JIT), try setting the command-line parameter
with -Xss<size> by specifying the maximum
native stack size to be smaller than the default value of 512KB. A smaller setting allows
for a larger number of threads. For example:
java -Xss<size> <other params>
For maximum file descriptors, use the command line statement ulimit ;
for example:
ulimit -n 3000
or chuser; for example:
chuser nofiles=3000 <user_id>
to increase the limit. (ulimit -a shows the
current limit.)
The IBM 32-bit SDK for AIX, v1.4.1 supports AIX's Large Address-Space model. For more
details on the large program model, see:
http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/lrg_prg_support.htm
By default, Java reserves eight data segments (MAXDATA=0x80000000); this is the maximum number of data segments that is allowed; each
segment is 256 MB. You can see this by running dump -o on
the java executable. Here is a picture of Java's default virtual memory model:
Table 2. Java's default virtual memory model
| Segment |
Contents |
| 0 |
AIX kernel |
| 1 |
Java program |
| 2 |
Primordial Stack (main program stack) |
| 3 |
Data (r/w) |
| 4 |
Data (r/w) |
| 5 |
Data (r/w) |
| 6 |
Data (r/w) |
| 7 |
Data (r/w) |
| 8 |
Data (r/w) |
| 9 |
Data (r/w) |
| 10 |
Data (r/w) |
| 11 |
mmap/shmat |
| 12 |
mmap/shmat |
| 13 |
Shared library code |
| 14 |
mmap/shmat |
| 15 |
Shared library data |
Segments 3 through 10 are used for storing, among other things, the Java
heap, thread stack frames, and JIT buffers. You can monitor Java's use of
these segments with the svmon command: svmon -P <java_process_id> -m -i <interval>. See
http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/cmds/aixcmds5/svmon.htm#HDRC013820260JOY
for more information about svmon.
Java uses mmap to allocate heaps that are larger
than 1 GB. Because only two segments are available for mmap with Java's default memory model (segment 14 cannot be used because
the heap must be contiguous), you must change Java's default memory model
to make more segments available for mmap. You do this
by exporting the LDR_CNTRL environment variable:
export LDR_CNTRL=MAXDATA=0xn0000000
where n is the number of data segments that will
be allocated to the process. For example, if you set LDR_CNTRL=MAXDATA=0x30000000, Java's memory model will look as follows:
Table 3. Java's virtual memory model after setting MAXDATA
| Segment |
Contents |
| 0 |
AIX kernel |
| 1 |
Java program |
| 2 |
Primordial Stack (main program stack) |
| 3 |
Data (r/w) |
| 4 |
Data (r/w) |
| 5 |
Data (r/w) |
| 6 |
mmap/shmat |
| 7 |
mmap/shmat |
| 8 |
mmap/shmat |
| 9 |
mmap/shmat |
| 10 |
mmap/shmat |
| 11 |
mmap/shmat |
| 12 |
mmap/shmat |
| 13 |
Shared library code |
| 14 |
mmap/shmat |
| 15 |
Shared library data |
Segments 6 through 12 are available for Java's heap. So you could specify
a heap size of up to 7x256 MB or 1.75 GB. Note that you can force java to mmap its heap, regardless of heap size, by exporting the
environment variable IBM_JAVA_MMAP_JAVA_HEAP=true.
If you are writing a JNI program that makes extensive use of mmap/shmat,
you probably need to use LDR_CNTRL to reduce MAXDATA. Specifying LDR_CNTRL=MAXDATA=0x00000000 gives interesting results:
Table 4. Java's virtual memory model after setting MAXDATA to zero
| Segment |
Contents |
| 0 |
AIX kernel |
| 1 |
Java program |
| 2 |
Data (r/w) + Primordial Stack (main program stack) |
| 3 |
mmap/shmat |
| 4 |
mmap/shmat |
| 5 |
mmap/shmat |
| 6 |
mmap/shmat |
| 7 |
mmap/shmat |
| 8 |
mmap/shmat |
| 9 |
mmap/shmat |
| 10 |
mmap/shmat |
| 11 |
mmap/shmat |
| 12 |
mmap/shmat |
| 13 |
Shared library code |
| 14 |
mmap/shmat |
| 15 |
Shared library data |
In this case, Java's data area and stack both share segment 2. Segments
3 through 12 are available for the mmap, which means
that the Java heap could be as large as 2.5 GB. However, because non-object
memory allocations (thread stacks or JIT buffers, for example) must now fit
in less than one segment, you might see Out of Memory exceptions (depending
on the execution characteristics of your program). Consequently, you are
not advised to run with LDR_CNTRL=MAXDATA=0x00000000.
On AIX 5.2 and above, the SDK supports AIX's Very Large Address-Space Model.
With the very large address-space model, the SDK's Java heap can span up
to 13 segments (3.25 GB). This is possible because the program's shared library
code and data are loaded privately (making segments 13 and 15 available to
the SDK). To activate the Very Large Address-Space Model, set the DSA keyword in the LDR_CNTRL environment variable
as follows:
LDR_CNTRL=MAXDATA=0xn0000000@DSA, where n is either 0, B, C or D.
For example, with LDR_CNTRL=MAXDATA=0x00000000@DSA the
memory model looks like this (each segment maps 256 MB of virtual address
space):
Table 5. Memory model with LDR_CNTRL=MAXDATA=0x00000000@DSA
| Segment |
Contents |
| 0 |
AIX Kernel |
| 1 |
Java program |
| 2 |
Java native (C) heap and Primordial stack (main program
stack) |
| 3 |
mmap/shmat |
| 4 |
mmap/shmat |
| 5 |
mmap/shmat |
| 6 |
mmap/shmat |
| 7 |
mmap/shmat |
| 8 |
mmap/shmat |
| 9 |
mmap/shmat |
| 10 |
mmap/shmat |
| 11 |
mmap/shmat |
| 12 |
mmap/shmat |
| 13 |
mmap/shmat |
| 14 |
mmap/shmat |
| 15 |
mmap/shmat |
In this case, the native heap is in segment 2 and segments 3 through
15 are available for the Java heap (allocated using shmat/mmap). Note that
the mmap/shmat segments are allocated to start at segment 15 and grow up (toward
lower numbered segments). While this configuration permits the largest possible
Java heap (3.25 GB), Java's non-object memory allocations (for example, thread
stacks, JIT buffers, privately loaded shared library code/data, incremental
compaction buffers) must all be able to be contained in segment 2. This might
result in OutofMemory exceptions when you run your application.
With LDR_CNTRL=MAXDATA=0xB0000000@DSA the memory
model looks like this:
Table 6. Memory model with LDR_CNTRL=MAXDATA=0xB0000000@DSA
| Segment |
Contents |
| 0 |
AIX Kernel |
| 1 |
Java program Primordial stack (main program stack) |
| 2 |
Primordial stack (main program stack) |
| 3 |
Java native (C) heap or mmap/shmat |
| 4 |
Java native (C) heap or mmap/shmat |
| 5 |
Java native (C) heap or mmap/shmat |
| 6 |
Java native (C) heap or mmap/shmat |
| 7 |
Java native (C) heap or mmap/shmat |
| 8 |
Java native (C) heap or mmap/shmat |
| 9 |
Java native (C) heap or mmap/shmat |
| 10 |
Java native (C) heap or mmap/shmat |
| 11 |
Java native (C) heap or mmap/shmat |
| 12 |
Java native (C) heap or mmap/shmat |
| 13 |
Java native (C) heap or mmap/shmat |
| 14 |
mmap/shmat |
| 15 |
mmap/shmat |
This configuration allows you to run with a Java heap of up to 3 GB
(which would be allocated in segments 4 through 15). If you specify a 3 GB
heap, only one segment would be available for Java's non-object memory allocations.
As mentioned in the previous example, this could result in OutofMemory exceptions.
If you see these exceptions, try running with a smaller Java heap. A smaller
heap leaves more space for Java's native heap (the native C heap starts in
segment 3 and dynamically grows down (toward higher-numbered segments); mmap/shmat
allocations return an address in the highest available segment).
For more information about the AIX 5.2 Very Large Programming Model, see
the AIX 5.2 General Programming Concepts manual that is located at http://publib16.boulder.ibm.com/pseries/en_US/infocenter/base/aix52.htm.
Select General Programming Concepts -> Large Program Support
-> Understanding the Very Large Address-Space Model.
Note:
The Very Large Address-Space Model is also available on
AIX 5.1, but the implementation differs. Consequently, the SDK does not support
the use of the Very Large Address-Space Model on AIX 5.1.
The setting of the LDR_CNTRL=MAXDATA environment variable value is linked
to the size of the heap used by the JVM. To simplify the setting of LDR_CNTRL=MAXDATA,
the JVM sets an appropriate value that is based on the maximum size of the
heap. If LDR_CNTRL=MAXDATA is set before you start the JVM, the JVM uses the
specified value. The JVM uses the following algorithm to set LDR_CNTRL=MAXDATA:
- On AIX 5.2 or later:
- If the heap size is 3 GB or greater, LDR_CNTRL=MAXDATA=0@DSA is set.
- If the heap size is between 2.3 GB and 3 GB, LDR_CNTR=MAXDATA=0XB0000000@DSA
is set
- If the heap size is less than 2.3GB, LDR_CNTR=MAXDATA=0XA0000000@DSA is
set
- On AIX 5.1:
- If the heap size is greater than 1 GB, LDR_CNTRL=MAXDATA is set to an
appropriate value. Note that this is an inverse relationship because as the
the heap size increases, fewer segments are reserved through the LD_CNTRL=MAXDATA
value. For example for a 1 GB heap LDR_CNTRL=MAXDATA is set to 0X60000000,
while for a 1.5 GB heap, the LDR_CNTRL=MAXDATA value is 0X40000000
- If the heap sizes is smaller than 1 GB, LDR_CNTRL=MAXDATA is set to 0X80000000.
.
If you are writing a C/C++ program that uses the JNI Invocation API (that
is, the C/C++ program creates a Java Virtual Machine and calls Java code),
you might want to ensure that the following variables are set to the values
specified below. By default, all the Java launchers that are shipped with
the SDK (for example, java, jar) set up these environment variables to the
values that are specified below..
-
export AIXTHREAD_SCOPE=S
-
export AIXTHREAD_MUTEX_DEBUG=OFF
-
export AIXTHREAD_RWLOCK_DEBUG=OFF
-
export AIXTHREAD_COND_DEBUG=OFF
The C/C++ compiler on AIX 5.1 is installed in /usr/vacpp. Because of incompatibility between the IBM 32-bit SDK for AIX, v1.4.1 and
some system-defined types, compilation of JNI code requires that the compiler
uses the flag _AIX43. This flag is defined by
default in /etc/vacpp.cfg on AIX 5.1. Ensure that
you are building while in the correct SDK environment.
You must build:
- 32-bit executables and shared objects with the -qarch=ppc option
- JNI executables and shared objects as a 32-bit executable
or shared object.
The SDK does not support runtime linking (using the -brtl loader option). Any applications that are built for use with the SDK
should not rely on runtime linking functionality.
You are recommended to compile your native methods (C/C++ functions called
by Java) into AIX shared objects (dynamically loaded libraries). For example,
if your native methods are stored in the file nm.c, you could create the shared
object with the following command:
cc_r -G -qarch=ppc -I /usr/java14/include -o libnm.so nm.c Before running a Java program that uses native methods, ensure that LIBPATH contains the list of directories that are holding
the native methods' shared objects. For more information about building AIX
shared objects, see "C and C++ Application Development on AIX". Go to http://www.ibm.com/redbooks and search for "SG245674".
When building a C/C++ program that uses the JNI Invocation API to create
a java virtual machine and calls java code, you should use the:
- -L option to add /usr/lib and /lib to the list
of directories that are searched for shared objects. All programs need shared
objects stored in these directories.
- -L option to add /usr/java14/jre/bin/classic and /usr/java14/jre/bin
to the list of directories that are searched for shared objects. These directories
contain the Java SDK shared libraries. You will also want to link with libjvm.a
(using the -ljvm option).
- -bM:UR option to tell AIX to save all general-purpose
user registers across system calls that are made by an application. This
option is required to ensure correct operation of Java's garbage collector.
Note that this option can be used only for C/C++ programs that have a main
executable. It must NOT be used to build shared objects. (It could introduce
errors if used to build a shared object).
For example, you could use this command to build a C program (invAPITest.c)
that uses the JNI Invocation API:
cc_r -qarch=ppc -I/usr/java14/include
-o invAPITest
-bM:UR
-L/usr/lib
-L/lib
-L/usr/java14/jre/bin/classic
-L/usr/java14/jre/bin
-ljvm invAPITest.c
When executing a C/C++ program that uses the JNI Invocation API to run
Java classes, ensure that the CLASSPATH is set up correctly to enable the
Java Virtual Machine (JVM) to find your class files. If you modify Java's
boot class path, include the SDK files that are necessary to run your applications.
To determine whether a C/C++ program that is using the JNI Invocation API
was built with the -bM:UR option, use the command:
>dump -ov <program name>
***Object Module Header***
# Sections Symbol Ptr # Symbols Opt Hdr Len Flags
4 0x00000d4e 155 72 0x1002
Flags=( EXEC DYNLOAD )
Timestamp = "Sep 11 13:09:13 2002"
Magic = 0x1df (32-bit XCOFF)
***Optional Header***
Tsize Dsize Bsize Tstart Dstart
0x000004b8 0x000001a8 0x00000004 0x10000128 0x200005e0
SNloader SNentry SNtext SNtoc SNdata
0x0004 0x0002 0x0001 0x0002 0x0002
TXTalign DATAalign TOC vstamp entry
0x0002 0x0003 0x20000724 0x0001 0x20000704
maxSTACK maxDATA SNbss magic modtype
0x00000000 0x00000000 0x0003 0x010b UR
If the modtype is not UR ,
you can use the LDR_CNTRL environment variable to make
programs behave as though they were compiled with the -bM:UR binder option. For example:
export LDR_CNTRL=USERREGS
If you need to specify multiple options with LDR_CNTRL, separate those options with the "@" symbol.
Java threads that are created by the SDK use the POSIX pthreads model
that is supported on AIX. Currently, this is on a 1-to-1 mapping with the
kernel threads. When developing a JNI program, you must run with a 1-to-1
thread model and system contention scope if creating pthreads in your own
program. You can control this by using the following environment setting:
export AIXTHREAD_SCOPE=S
Another option is to preset the thread's scope attribute to PTHREAD_SCOPE_SYSTEM using the AIX pthread_attr_setscope function when
the thread is created. For more details on thread model and system contention
scope, see:
http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/understanding_threads.htm#D3A446E559manu
http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/genprogc/threads_sched.htm#D3A44A4324manu
AIX sets default value of the AIXTHREAD_MUTEX_DEBUG, AIXTHREAD_RWLOCK_DEBUG and AIX_THREAD_COND_DEBUG environment variables ON. A JNI program that creates
and attaches to a JVM must set these environment variables OFF. See http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixbman/prftungd/2365a81.htm#HDRI34490 (for AIX 5.1).
Note: The old-style native interface is no longer
supported.
There is a README file and example programs in the /usr/java14/demo/jni
directory. The demos can be optionally installed with the Java14.samples
package.
When a signal is raised that is of interest to the JVM, a signal handler
is called. This signal handler determines whether it has been called for a
Java or non-Java thread. If the signal is for a Java thread, the JVM takes
control of the signal handling. If the signal is for a non-Java thread, and
the application that installed the JVM had previously installed its own handler
for the signal, control is given to that handler. Otherwise, the signal is
ignored (whether or not this is not the signal's default action).
For exception and error signals the JVM either:
- Handles the condition and recovers (when the exception is caused by your
application code), or
- Enters a controlled shutdown sequence where it:
- Calls your application's signal handler for that signal
- Outputs a Javadump, to describe the JVM state at the point of failure
- Performs the necessary cleanup to give a clean shutdown
For interrupt signals, the JVM also enters a controlled shutdown sequence,
but this time it is treated as a normal termination that:
- Calls your application's signal handler for that signal
- Performs the necessary JVM cleanup
The shutdown is identical to the shutdown initiated by a call to the Java
method System.exit().
Other signals that are used by the JVM are for internal control purposes
and do not cause it to terminate. The only control signal of interest is SIGQUIT, which causes a
Javadump to be generated.
Table 7 below shows the signals that are used by the JVM.
The signals have been grouped in the table by type or use, as follows:
- Exceptions: The operating system synchronously raises
an appropriate exception signal whenever a fatal condition occurs.
- Errors: The JVM raises a SIGABRT if it detects a
condition from which it cannot recover.
- Interrupts: Interrupt signals are raised asynchronously,
from outside a JVM process, to request shutdown.
- Controls: Other signals that are used by the JVM
for control purposes.
Table 7. Signals used by the JVM
| Signal Name |
Signal type |
Description |
Disabled by -Xrs |
| SIGSEGV |
Exception |
Incorrect access to memory (write to inaccessible
memory) |
No |
| SIGILL |
Exception |
Illegal instruction (attempt to invoke an unknown
machine instruction) |
No |
| SIGFPE |
Exception |
Floating point exception (divide by zero) |
No |
| SIGBUS |
Exception |
Bus error (attempt to address nonexistent memory
location) |
Yes |
| SIGSYS |
Exception |
Bad system call issued |
Yes |
| SIGXCPU |
Exception |
CPU time limit exceeded (you have been running too
long) |
Yes |
| SIGXFSZ |
Exception |
File size limit exceeded |
Yes |
| SIGEMT |
Exception |
EMT instruction (AIX specific) |
Yes |
| SIGABRT |
Error |
Abnormal termination. The JVM raises this signal
whenever it detects a JVM fault. |
Yes |
| SIGINT |
Interrupt |
Interactive attention (CTRL-C). JVM exits normally. |
Yes |
| SIGTERM |
Interrupt |
Termination request. JVM will exit normally. |
Yes |
| SIGHUP |
Interrupt |
Hang up. JVM exits normally. |
Yes |
| SIGQUIT |
Control |
A quit signal for a terminal. JVM uses this for taking
Javadumps. |
Yes |
| SIGTRAP |
Control |
Internal for use by dbx or ptrace. Used by some JVMs
for internal control purposes. |
No |
| SIGPIPE |
Control |
A write to a pipe that is not being read. JVM ignores
this. |
No |
| No Name (40) |
|
An AIX reserved signal. Used by the AIX JVM for internal
control purposes. |
No |
Use the -Xrs (reduce signal usage) option to
prevent the JVM from handling most signals. For more information, see Sun's
Java application launcher page at http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/java.html.
Do not use the -qflttrap C
compiler setting because it provides the possibility of SIGTRAPs being generated,
which might then impact the JIT. If you want to have floating point exceptions
generated, include this call in your code:
fp_trap( FP_TRAP_SYNC) so
that it generates a SIGFPE signal.
If you install a signal handler for signal numbers 5 (SIGTRAP) or 40, you impact JVM performance because these signals
are used for internal control purposes.
Signals 1 (SIGHUP), 2 (SIGINT), 4 (SIGILL), 6 (SIGABRT), 7 (SIGEMT), 8 (SIGFPE), 10 (SIGBUS), 11 (SIGSEGV), 12 (SIGSYS), 15 (SIGTERM), 24 (SIGXCPU) , and 25 (SIGXFSZ) cause the JVM to
shut down; therefore, an application signal handler should not attempt to
recover from these unless it no longer requires the services of the JVM.
The JVM contains a new signal-chaining facility. Signal-chaining
enables the JVM to interoperate more efficiently with native code that installs
its own signal handlers.
The libjsig.a library ensures that calls such as signal(), sigset(), and sigaction() are intercepted
so that their handlers do not replace the JVM's signal handlers. Instead,
these calls save the new signal handlers, or "chain" them behind the handlers
that are installed by the JVM. Later, when any of these signals are raised
and found not to be targeted at the JVM, the preinstalled handlers are invoked.
To link libjsig with an application that uses the JNI Invocation API to
create a java virtual machine:
cc_r -qarch=ppc -I/usr/java14/include
-o invAPITest
-bM:UR
-L/usr/lib
-L/lib
-L/usr/java14/jre/bin/classic
-L/usr/java14/jre/bin
-ljsig
-ljvm invAPITest.c
Note:
The application is invAPITest .
To link libjsig when you are creating a shared library of native methods
(held in the file nm.c):
cc_r -G -qarch=ppc -I /usr/java14/include -L /usr/java14/jre/bin -ljsig -o libnm.so nm.c
If you install signal handlers that use sigaction(), some sa_flags are not observed when the JVM
uses the signal. These are:
- SA_RESTART - This is always set.
Java Web Start is a way of deploying Java technology-based applications.
It connects the computer and the Internet and allows the user to launch and
manage applications directly from the Web. Java Web Start provides one-click
activation of applications, and ensures that you are always running the latest
version, eliminating installation or upgrade procedures. Often, distributing
software across the Web requires you to find the installer on the Web, download
the installer, locate the installer, and execute the installer. After the
installer is executed, it prompts for installation directories and installation
options such as full, typical, or minimum. This can be a time-consuming and
complicated task that must be repeated for each new version of the software.
In contrast, Web-deployed applications, such as your HTML-based e-mail
client and calendar, are straightforward to install and use. The Web browser
has automated the process. There are no complicated download, setup, and configuration
steps, and you are guaranteed to be running the latest version. Java Web Start
provides the same benefits to full-featured applications.
For information on the browsers that support Web Start
see the section Supported browsers.
For more information about Web Start, see: http://java.sun.com/products/javawebstart and for more documentation, see: http://java.sun.com/j2se/1.4.1/docs/guide/jws/index.html.
The Web Start installation script is /usr/java14/jre/bin/webstart_install_sdk.sh.
To install Web Start, run the script. The installation process creates a
subdirectory called javaws in your current working directory.
The installation process also updates the mime-types that are used by Netscape
and other browsers.
The Web Start installation script is installed with the JRE
for Java 1.4.1.
You can invoke Web Start in two ways:
- Select a link on a Web page that is a reference to a .jnlp file.
- Start javaws from the javaws directory
that was created above, therefore starting the Web Start dialog from which
applications can be selected.
- At a shell script, type javaws <URL>, where <URL> is the location of a .jnlp file.
Either of these actions causes Web Start to start the selected application.
The application is downloaded if this is the first time it is being used.
On later invocations, the original Web site is checked to see whether any
updates are available. Web Start downloads these updates before the application
is started.
If an error occurs in a jnlp (such as an invalid tag name), Web Start aborts
without displaying an error message.
The IBM 32-bit SDK for AIX, v1.4.1 sets the Euro as the default currency for those
countries in the European Monetary Union (EMU) for dates on or after 1 January,
2002.
To use the old national currency, specify -Duser.variant=PREEURO on the Java command line.
If you are running the UK, Denmark, or Sweden locales and want to use the
Euro, specify -Duser.variant=EURO on the
Java command line.
The SDK includes enhanced BiDirectional support. For more information,
see http://www-106.ibm.com/developerworks/java/jdk/bidirectional/index.html.
The SDK includes
an enhanced BigDecimal class (com.ibm.math.BigDecimal) for Java programming.
It is provided (with its supporting class MathContext) as an alternative
to the java.math.BigDecimal class.
If you are using the java.math.BigDecimal class in a Java program, and
you want to access the enhanced BigDecimal class, you must change
the import statement in your source code as shown:
Change import java.math.*; to import com.ibm.math.*;
You do not need to change any other code.
The IBM 32-bit SDK for AIX, v1.4.1 provides a unified interface, the Java
Naming and Directory Interface (JNDI), to the following naming and directory
services:
- Lightweight Directory Access Protocol (LDAP)
- Corba Object Services (COS) Naming Service
- RMI Registry
- filesystem
- Domain Name Service (DNS)
The Java Virtual Machine Profiling Interface (JVMPI) has been extended
to include profiling in the IBM JIT. These additional definitions are defined
in jvmpi.h .
| 
