# IBM(R) zSeries Developer Kit for Linux, Java(TM) 2 Technology Edition

# -README-

Note: Before using this information and the product it supports, be sure to read the general information under Notices.

This edition of the README applies to the IBM zSeries Developer Kit for Linux, Java 2 Technology Edition, and to all subsequent releases and modifications until otherwise indicated in new editions.

(c) Copyright International Business Machines Corporation, 1999, 2002. All rights reserved.

(c) Copyright Sun Microsystems, Inc. 1997, 2001, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

This README file provides information about the IBM(R) zSeries Developer Kit for Linux, Java(TM) 2 Technology Edition, (Developer Kit for Linux) at the Sun 1.3.1 SDK level.

The Developer Kit for Linux enables you to write and then run Java applications and applets. Note that the Runtime Environment for Linux is a subset of this Developer Kit and enables you only to run Java applications. If you have installed the Developer Kit for Linux, you do not need the Runtime Environment.

For the list of distributions against which the Developer Kit for Linux has been tested, see:
http://www-106.ibm.com/developerworks/java/jdk/linux/tested.html

## Contents

- Overview
- Version compatibility
- Contents of the Developer Kit for Linux
- The just-in-time (JIT) compiler
- Configuring the Developer Kit for Linux
- Installing on SuSE
- Installing if using BEA Weblogic
- Uninstalling the Developer Kit for Linux
- Uninstalling the installable Red Hat Package Manager (RPM) package
- Uninstalling the compressed Tape Archive (TAR) package
- Using the Developer Kit
- PATH considerations
- CLASSPATH considerations
- Running applets with the Applet Viewer
- Debugging applets with the Applet Viewer
- Obtaining the IBM build and version number
- Working with floating stacks
- Debugging Java applications
- Java Platform Debugger Architecture (JPDA)
- Java Debugger (JDB)
- Switching the input method in DBCS languages
- Devanagari fonts
- Specifying garbage collection policy
  - Pause time
  - Pause time reduction
  - Environments with very full heaps
  - Further information about garbage collection
- Enhanced CORBA support
- Support for GIOP 1.2
- Support for Portable interceptors
- Support for Interoperable Naming Service
- System properties for tracing the ORB
- System properties for tuning the ORB
- System properties for vendor ORB Compatibilty
- Java 2 security permissions for the ORB
- ORB implementation classes
- RMI over IIOP
- Enhanced BigDecimal
- Shipping Java applications
- Troubleshooting
- Known limitations
- General information
- Information about memory allocation
- Information for Japanese users
- Service and support for independent software vendors
- Accessibility
- Java console accessibility
- Policy Tool and accessibility
- Notices
- Trademarks

## Overview

The Developer Kit for Linux is a development environment for writing applets and applications that conform to Sun's Java 1.3.1 Core Application Programming Interface (API).

### Version compatibility

Applets that depend on Sun's Java 1.3.1 APIs work only on browsers that support Java 1.3.1 APIs.

To read Sun's documentation on compatibility, search for it on the Sun Web site at http://java.sun.com.

### Contents of the Developer Kit for Linux

The following list describes the contents of the Developer Kit package.

- RUNTIME Environment - Classes (rt.jar)

  This file contains all of the compiled .class files for the platform and must remain zipped for the compiler and interpreter to properly access the class files within it.

- TOOLS

  The tools provided include:

  - Java Compiler (javac)

    Compiles programs written in the Java programming language into bytecodes (compiled Java code).

  - Java Interpreter (java)

    Executes Java bytecodes. The Java Interpreter runs programs written in the Java programming language.

  - Java Applet Viewer (appletviewer)

    Use for testing and running applets.

  - Java Debugger (jdb)

    Helps debug your Java programs.

  - Class File Disassembler (javap)

    Disassembles compiled files and prints a representation of the bytecodes.

  - Java Documentation Generator (javadoc)

    Parses the declarations and documentation comments in a set of source files and produces a set of HTML pages describing the public and protected classes, interfaces, constructors, methods, and fields. Also produces a class hierarchy and an index of all members.

  - C Header and Stub File Generator (javah)

    Attaches native methods to code written in the Java programming language.

  - Java Archive Tool (jar)

    Generates signatures for Java Archive (JAR) files, and verifies the signatures of signed JAR files.

  - JAR Signing and Verification Tool (jarsigner)

    Manages entities, including their keys, certificates, and the trust associated with them.

  - Key and Certificate Management Tool (keytool)

    Manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating 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.

  - Native-To-ASCII Converter (native2ascii)

    Converts a native encoding file to an ASCII file that includes the \udddd Unicode notation.

  - Java Remote Method Invocation (RMI) Stub Converter (rmic)

    Generates objects from the names of compiled classes that contain remote object implementations. Includes RMI over Internet Inter-ORB Protocol (IIOP), or RMI-IIOP, support.

  - RMI activation system daemon (rmid)

    Starts the activation system daemon so that objects can be registered and activated in a Java virtual machine (JVM).

  - IDL to Java Compiler (idlj)

    Compiles Object Management Group (OMG) Interface Definition Language (IDL) files to Java code.

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

  - Serial Version Command (serialver)

    Returns the serialVersionUID for one or more classes in a form 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.

  - Various C libraries and include files.

- JAVA DOCUMENTATION AND DEMOS

  The demo directory contains a number of subdirectories containing sample source code, demos, applications, and applets, which you may use.

- README:

  This file.

- COPYRIGHT:

  Copyright notice for the Developer Kit for Linux software.

- LICENSE:

  The LICENSE_xx.html file contains the license agreement for the Developer Kit for Linux software. (xx is an abbreviation for the language.)

  To view or print the license agreement, open the file in a Web browser.

- FIXES.LST:

  A text file that describes any defects fixed after the initial release of this version.

Note: This README file and the accompanying license, copyright files, and demo directory are the only documentation included in this Developer Kit for Linux. You can view Sun's software documentation by visiting the Sun Web site, or you can download Sun's Software documentation package from the Sun Web site http://java.sun.com.

The documentation package is designed to be extracted into the Developer Kit for Linux software installation directory. If you download the zip file archive version, be sure to preserve the file path names when you extract the files from the archive. If you use pkunzip, specify the -d option.

### The just-in-time (JIT) compiler

The Developer Kit for Linux includes the IBM just-in-time (JIT) compiler (libjitc.so). The JIT compiler generates machine code dynamically for frequently used bytecode sequences in a Java application or applet while it is running.

All Developer Kit for Linux tools can disable the JIT to isolate a problem with a Java application, an applet, or the compiler itself. To disable the JIT, type the following at a shell prompt.

        export JAVA_COMPILER=NONE

To enable the JIT, type the following at a shell prompt:

        export JAVA_COMPILER=jitc

To determine if the JIT is enabled, type the following at a shell prompt:

`java -version`

If a JIT is enabled, one of the following messages is displayed:

- `(JIT enabled: jitc)`
- `compiler = enabled: jitc`

If a JIT is not enabled, one of the following messages is displayed:

- `(JIT disabled)`
- `compiler = disabled`

## Configuring the Developer Kit for Linux

After you install the Developer Kit for Linux, edit your shell script and add the directory where you installed the Developer Kit to your PATH statement. For more information about the PATH statement, see PATH considerations.

### Installing on SuSE

If you are running a SuSE system, there may be a version of this Developer Kit already installed. If this version was supplied by SuSE, it will have been packaged so that it installs under a different directory tree. To avoid unexpected results, you should use YaST2 to remove the SuSE-supplied Developer Kit.

### Installing if using BEA Weblogic

If you intend to use the BEA Weblogic server, when you install the Developer Kit for Linux packages you must unselect the JAAS optional installation. The BEA Weblogic server contains its own implementation of JAAS.

## Uninstalling the Developer Kit for Linux

The process you use to remove the Developer Kit for Linux depends on whether you installed the installable Red Hat Package Manager (RPM) package or the compressed Tape Archive (TAR) package. See Uninstalling the installable Red Hat Package Manager (RPM) package or Uninstalling the compressed TAR package for instructions.

### Uninstalling the installable Red Hat Package Manager (RPM) package

To uninstall the Developer Kit for Linux if you installed the installable RPM package:

1. At a shell script, type:

           rpm -qa | grep IBM

   The name of the package is displayed.

2. Use the rpm command:

           rpm -e pkgname

   where pkgname is the name of the package that was displayed.

3. Modify your shell script. Remove the directory where you installed the Developer Kit from your PATH statement.

### Uninstalling the compressed Tape Archive (TAR) package

To uninstall the Developer Kit for Linux if you installed the compressed TAR package:

1. Remove the Developer Kit files from the directory where you installed the Developer Kit.

2. Modify your shell script. Remove the directory where you installed the Developer Kit from your PATH statement.

## Using the Developer Kit

The Java tools are programs that are run from a shell prompt; they do not have a Graphical User Interface (GUI).

The following sections give information on using the Developer Kit for Linux.

### PATH considerations

After installing the Developer Kit for Linux, you can run a tool by typing its name at a shell prompt with a filename as an argument.

You can specify the path to a tool by typing the path before the name of the tool each time. For example, if the Developer Kit for Linux software is installed in /opt/IBMJava2-s390-131/bin, you can compile a file named myfile.java by typing the following at a shell prompt:

      /opt/IBMJava2-s390-131/bin/javac myfile.java

To avoid typing the full path each time:

1. Add the following directories to the PATH environment variable:

   - /opt/IBMJava2-s390-131/bin
   - /opt/IBMJava2-s390-131/jre/bin

2. Compile the file with the javac tool. For example, compile the file myfile.java by typing the following at a shell prompt:

         javac myfile.java

   The PATH environment variable enables Linux to find executable files, such as javac, java, and javadoc, from any current directory. To display the current value of your PATH, type the following at a shell prompt:

         echo $PATH

To change the PATH environment variable:

1. Edit your shell startup file (usually .bash_profile, .profile, or .login depending on the shell) and add the absolute paths to the PATH environment variable as follows:
   - /opt/IBMJava2-s390-131/bin
   - /opt/IBMJava2-s390-131/jre/bin

2. Log on again or run the updated shell script to activate the new PATH setting.

### CLASSPATH considerations

The CLASSPATH tells the Developer Kit for Linux tools, such as java, javac, and javadoc, where to find the Java class libraries. If you keep the bin and lib directories under the same parent directory level, the executable files can find the classes.

You need to explicitly set the CLASSPATH only if one of the following applies:

- You require a different library, such as one you develop.

- You change the location of the bin and lib directories such that they no longer have the same common parent directory.

- You plan to develop or run applications using different runtime environments on the same system.

- You are running TurboLinux.

To display the current value of your CLASSPATH, type the following at a shell prompt:

      echo $CLASSPATH

If you plan to develop and run applications using different runtime environments, including other versions that you have installed separately, you need to set the CLASSPATH (and PATH) explicitly for each application. If you plan to run multiple applications simultaneously using different runtime environments, be sure each application is run in its own shell.

If you want to run only one version of Java at a time, you can use a shell script to switch between the different runtime environments.

### Running applets with the Applet Viewer

With the Applet Viewer, you can run one or more applets that are called by reference in a Web page (HTML file) using the APPLET tag. The Applet Viewer finds the APPLET tags in the HTML file and runs the applets, in separate windows.

Because the Applet Viewer is for viewing applets, it cannot display an entire Web page that contains numerous HTML tags. It parses only the APPLET tag and no other HTML on the Web page.

To run an applet with the Applet Viewer, type the following at a shell 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 the following at a shell 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 the following at a shell prompt:

      appletviewer http://java.sun.com/applets/NervousText/example1.html

### Debugging applets with the Applet Viewer

You can debug applets using the -debug option of Applet Viewer. When debugging applets, it is best to invoke Applet Viewer from the directory that contains the HTML file that calls the applet. For example:

         cd demo/TicTacToe
         ../../bin/appletviewer -debug example1.html

You might find documentation on the debugger and its API at the following Sun Web site (see http://java.sun.com for any legal statements regarding this information):

http://java.sun.com/products/jdk/1.2/debugging/

### Obtaining the IBM build and version number

To obtain the IBM build and version number, type the following at a shell prompt:

`java -version`

### Working with floating stacks

On a non-floating stack Linux system, regardless of what is set for -Xss, a minimum native stack size of 256KB for each thread is provided. On a floating stack Linux system, the -Xss values are honored. Thus, if you are migrating from a non-floating stack Linux system, you must ensure that any -Xss values are large enough and are not relying on a minimum of 256KB.

### Debugging Java applications

To debug Java programs, you can use the Java Debugger (JDB) application. This debugger communicates with the Java Platform Debugger Architecture (JPDA) provided by the Developer Kit for Linux. For native JNI binary programs, you can still use gdb for debugging.

#### Java Platform Debugger Architecture (JPDA)

The JPDA classes are included in the tools.jar file, which must be included in the CLASSPATH when running Java programs that use the JPDA (for example, JDB). Only socket communication is supported on Linux.

#### Java Debugger (JDB)

A new JDB application is included in the Developer Kit for Linux. The JDB application runs the class com.sun.tools.example.debug.tty.TTY. The Java Virtual Machine Debugging Interface (JVMDI) is now fully supported. The jdb tool included in earlier versions is now included as oldjdb.

The new JDB application uses the JPDA and enables the jdb example tool to attach to a listening Virtual Machine (VM) or to start a new debug session. It is invoked by the jdb command and can be used in the same way as the oldjdb.

You can use the JDB application to debug remote Java applications, including Java applications running on remote machines over a TCP/IP link. To debug a remote Java program,start the java program as follows:

    java -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,
    suspend=y
         -Djava.compiler=NONE <other args> <myapp> <myapp class args>

The port on which the JPDA is listening is displayed. At the remote debugging machine, type:

    jdb -attach <machine name or ip address>:<port>

When you launch a debug session using the dt_socket transport, be sure that the specified ports are actually free to use.

### Switching the input method in DBCS languages

On double-byte character set (DBCS) systems, if you want to switch the input method, you must set an environment variable that represents the keycode you use for switching. Optionally, you can set another environment variable that represents the modifiers of the keycode.

To specify the keycode to use for switching, set the IBMJAVA_INPUTMETHOD_SWITCHKEY environment variable to a keycode definition in the java.awt.event.KeyEvent class, for example, VK_F4.

Optionally, specify modifiers of the keycode. To specify modifiers of the keycode, set the IBMJAVA_INPUTMETHOD_SWITCHKEY_MODIFIERS environment variable to any combination of the following three mask definitions in the java.awt.event.InputEvent class:

- ALT_MASK
- CTRL_MASK
- SHIFT_MASK

Separate the masks by commas.

For example, you might set the IBMJAVA_INPUTMETHOD_SWITCHKEY_MODIFIERS environment variable to ALT_MASK, CTRL_MASK.

During Java initialization, the two environment variables are stored. To be sure you have set the environment variables correctly, press a key and check it with the key combination you specified. If it matches, a Java pop-up menu with selectable input methods is displayed.

### Devanagari fonts

This Developer Kit does not ship Devanagari fonts (Devamt.ttf and Devamtb.ttf) in the jre/lib/fonts directory. Instead, where appropriate, Java uses the Monotype Unicode fonts (Times New Roman WorldType and Sans Monospace WorldType) shipped with the IBM platform or IBM software product to support Devanagari (Hindi) fonts.

### Enhanced CORBA support

IBM zSeries Developer Kit for Linux, Java 2 Technology Edition adds support for these CORBA specifications:

#### Support for GIOP 1.2

This Developer Kit 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://cgi.omg.org/cgi-bin/doc?formal/99-10-07

Bi-directional GIOP is not supported.

#### Support for Portable Interceptors

This Developer Kit supports Portable Interceptors, as defined by the OMG in the document formal/01-09-58, which you can obtain from:

http://cgi.omg.org/cgi-bin/doc?formal/01-09-58

Portable Interceptors are hooks into the ORB through which ORB services can intercept the normal flow of execution of the ORB.

Several new classes are introduced in the API to support Portable Interceptors. These are:

org.omg.CORBA.LocalObject
org.omg.Dynamic.Parameter
org.omg.IOP.Codec
org.omg.IOP.CodecFactory
org.omg.IOP.CodecFactoryHelper
org.omg.IOP.CodecFactoryOperations
org.omg.IOP.CodecFactoryPackage.UnknownEncoding
org.omg.IOP.CodecOperations
org.omg.IOP.CodecPackage.FormatMismatch
org.omg.IOP.CodecPackage.InvalidTypeForEncoding
org.omg.IOP.CodecPackage.TypeMismatch
org.omg.IOP.ENCODING_CDR_ENCAPS
org.omg.IOP.Encoding
org.omg.IOP.ServiceContext
org.omg.IOP.TaggedComponent
org.omg.IOP.TaggedProfile
org.omg.Messaging.SYNC_NONE
org.omg.Messaging.SYNC_WITH_SERVER
org.omg.Messaging.SYNC_WITH_TARGET
org.omg.Messaging.SYNC_WITH_TRANSPORT
org.omg.PortableInterceptor.ClientRequestInfo
org.omg.PortableInterceptor.ClientRequestInfoOperations
org.omg.PortableInterceptor.ClientRequestInterceptor
org.omg.PortableInterceptor.ClientRequestInterceptorOperations
org.omg.PortableInterceptor.Current
org.omg.PortableInterceptor.CurrentHelper
org.omg.PortableInterceptor.CurrentOperations
org.omg.PortableInterceptor.ForwardRequest
org.omg.PortableInterceptor.IORInfo
org.omg.PortableInterceptor.IORInfoOperations
org.omg.PortableInterceptor.IORInterceptor
org.omg.PortableInterceptor.IORInterceptorOperations
org.omg.PortableInterceptor.Interceptor
org.omg.PortableInterceptor.InterceptorOperations
org.omg.PortableInterceptor.InvalidSlot
org.omg.PortableInterceptor.LOCATION_FORWARD
org.omg.PortableInterceptor.ORBInitInfo
org.omg.PortableInterceptor.ORBInitInfoOperations
org.omg.PortableInterceptor.ORBInitInfoPackage.DuplicateName
org.omg.PortableInterceptor.ORBInitInfoPackage.InvalidName
org.omg.PortableInterceptor.ORBInitializer
org.omg.PortableInterceptor.ORBInitializerOperations
org.omg.PortableInterceptor.PolicyFactory
org.omg.PortableInterceptor.PolicyFactoryOperations
org.omg.PortableInterceptor.RequestInfo
org.omg.PortableInterceptor.RequestInfoOperations
org.omg.PortableInterceptor.SUCCESSFUL
org.omg.PortableInterceptor.SYSTEM_EXCEPTION
org.omg.PortableInterceptor.ServerRequestInfo
org.omg.PortableInterceptor.ServerRequestInfoOperations
org.omg.PortableInterceptor.ServerRequestInterceptor
org.omg.PortableInterceptor.ServerRequestInterceptorOperations
org.omg.PortableInterceptor.TRANSPORT_RETRY
org.omg.PortableInterceptor.USER_EXCEPTION

These classes are not part of the Sun Java 1.3 Core API, and could change in future versions of the IBM Developer Kit.

#### Support for Interoperable Naming Service

This Developer Kit has added support for the Interoperable Naming Service, as defined by the OMG in the document ptc/00-08-07, which you can obtain from:

http://cgi.omg.org/cgi-bin/doc?ptc/00-08-07

The default port 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 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.

Several new classes are introduced in the API to support the Interoperable Naming Service:

org.omg.CosNaming.NamingContextExt
org.omg.CosNaming.NamingContextExtHelper
org.omg.CosNaming.NamingContextExtHolder
org.omg.CosNaming.NamingContextExtOperations
org.omg.CosNaming.NamingContextExtPackage.AddressHelper
org.omg.CosNaming.NamingContextExtPackage.InvalidAddress
org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHelper
org.omg.CosNaming.NamingContextExtPackage.InvalidAddressHolder
org.omg.CosNaming.NamingContextExtPackage.StringNameHelper
org.omg.CosNaming.NamingContextExtPackage.URLStringHelper
org.omg.CosNaming._NamingContextExtImplBase
org.omg.CosNaming._NamingContextExtStub

These classes are not part of the Sun Java 1.3 Core API, and could change in future versions of the IBM Developer Kit.

The initial context returned from the Transient Name Server is now an `org.omg.CosNaming.NamingContextExt`. Existing programs that narrow the reference to an `org.omg.CosNaming.NamingContext` will still work, and do not need to be recompiled.

The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters defined by the Interoperable Naming Service specification, and the ORB::string_to_object operation now supports the ObjectURL string formats (corbaloc: and corbaname:) 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.3.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`, returned from `ORB.init()`, and `serviceRef` is a CORBA Object, connected to the ORB. This mechanism is an interim one, and is not compatible with future versions or portable to non-IBM ORBs.

#### System properties for tracing the ORB

A new 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. Set `com.ibm.CORBA.Debug=true` to turn on tracing. To format and add to the trace GIOP messages sent and received, set `com.ibm.CORBA.CommTrace=true`. By default, ORB tracing goes to the standard error stream, `java.lang.System.err`. To direct it to a file, set `com.ibm.CORBA.Debug.Output`. For example, to trace events and formatted GIOP messages to a file:

    java -Dcom.ibm.CORBA.Debug=true -Dcom.ibm.CORBA.Debug.Output=
    -Dcom.ibm.CORBA.CommTrace=true myapp

The trace will be sent to the files orbtrc.DDMMYYYY.HHmm.SS.txt and orbmsg.DDMMYYYY.HHmm.SS.txt.

Do not turn on tracing for normal operation, because it might cause performance degradation.

The content and format of the trace output could vary from version to version.

#### System properties for tuning the ORB

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 could be delayed or lost. You can set the maximum time to wait 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:

      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 using the system property com.ibm.CORBA.ListenerPort. For example, to make the ORB use port 1050:

      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.

#### System properties for vendor ORB Compatibilty

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

#### Java 2 security permissions for the ORB

When running with a Java 2 SecurityManager, invocation of some methods in the CORBA API classes might cause permission checks to be made, which could result in a SecurityException. Affected methods include the following:

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.

#### ORB implementation classes

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. Theses values might be changed in future releases.

## RMI over IIOP

Java Remote Method Invocation (RMI) provides a simple mechanism to do distributed Java programming. RMI over IIOP (RMI-IIOP) extends the base Java RMI to perform communication using the Common Object Request Broker Architecture (CORBA) standard Internet Inter-ORB Protocol (IIOP protocol). 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 the Developer Kit and is on the Web site under "Documents".

- The IDL-to-Java Compiler User's Guide describes how to use the tool that generates Java code from IDL. The guide is installed when you install the Developer Kit and is on the Web site under "Documents".

- The samples directory 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://cgi.omg.org/cgi-bin/doc?ptc/00-01-06.pdf

## Enhanced BigDecimal

The Runtime Environment 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 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.

## Shipping Java applications

A Java application, unlike a Java applet, cannot rely on a Web browser for installation and runtime services. When you ship a Java application, your software package probably consists of the following parts:

- Your own class, resource, and data files
- An installation procedure or program

To run your application, a user needs the Runtime Environment for Linux. The Developer Kit for Linux software contains a runtime environment. However, you cannot assume that your users have the Developer Kit for Linux software installed.

Your Developer Kit for Linux software license does not allow you to redistribute the Developer Kit for Linux software files. You should ensure that a licensed version of the Developer Kit for Linux is installed on the target machine.

## Troubleshooting

If you encounter a problem after you install the Developer Kit for Linux, check the following list:

- Exception when running applets

  If you use the Applet Viewer to run an applet that is in the CLASSPATH, you might get an AccessControlException in Swing.

  To work around this problem, be sure of the following:

  - There are no CLASSPATH references to the applet you are attempting to run in the Applet Viewer.
  - You are not running the applet from the same directory as the class.

- `Unable to load libjava.so library` message.

  If you receive a message indicating that the libjava.so library could not be loaded because of a symbol not found, you might have a down-level version of the C Runtime Library, libc, installed. The Developer Kit for Linux thread implementation requires libc version 2.1.3-176 or later.

- Applet Viewer does not load applets.

  If the Applet Viewer does not load applets, type the following at a shell prompt:

          java -verbose sun.applet.AppletViewer

  This command lists the classes that are being loaded. From this output, you can determine which class the Applet Viewer is trying to load and where it is trying to load it from. Check to make sure that the class exists and is not damaged.

- Application does not handle EINTR return code correctly.

  If you are writing a Java application, particularly a Java Native Interface (JNI) application, be sure that the application handles the EINTR return code correctly; otherwise the application will fail.

## Known limitations

The following sections explain known limitations of the Developer Kit for Linux.

### General information

- If you use the Java FontMetrics class to calculate the width of a font to use the draw method, it returns the wrong answer, and the text does not display properly. This problem occurs because the numbers used in the calculation come from the Java2D, and the calculations are performed in the Abstract Widows Toolkit (AWT). The workaround for this problem is to get the numbers from and perform the calculations in the AWT. You can do this by setting the JAVA2D_USEAWTFONTS system variable to zero before starting the Developer Kit for Linux.

- If you use audio on a machine without a soundcard, you may get an error message stating that you are out of memory when Java tries to play a sound. The message is displayed in the console, but it does not affect your Java application.

- You might not be able to use the system clipboard to copy information between Linux applications and Java applications if you are running K Desktop Environment (KDE) as your window manager.

- The Developer Kit for Linux implements Java threads as native threads, which results in each thread being a separate Linux process. If the number of Java threads exceeds the maximum number of processes allowed, your program might get an error message, a SIGSEGV error, or your system might hang.

  The maximum number of threads available is determined by the minimum of:

  - The user processes setting (ulimit -u) in /etc/security/limits.conf
  - The limit defined in /proc/sys/kernel/threads-max
  - The limit PTHREAD_THREADS_MAX defined in libpthreads.so (change requires glibc to be recompiled)

  However, you might run out of virtual storage prior to reaching the maximum number of threads.

- If a Java application is terminated with a Ctrl-C by the user, a number of processes might be left orphaned.

- The javap program, when run on an interface, duplicates the string "interface" in the result. For example, running javap on "java.lang.Runnable" produces:

           public interface interface java.lang.Runnable extends java.lang.Object...

- Displaying dialog boxes created with Swing might cause a delay of a few seconds before they are displayed in the window.

- KeyEvent results involving the ALT key differ when using different window managers in Linux. They also differ from results in other operating systems. In the Enlightenment window manager, Alt+A and Shift+Alt+A produce different modifiers, and Ctrl+Alt+A produces no key event at all. However, using the WindowMaker window manager, Ctrl+Alt+A produces a key event.

  On the Linux X Window System, the keymap is set to: 64 0xffe9 (Alt_L) 0xffe7 (Meta_L), and 113 0xffea (Alt_R) 0xffe8 (Meta_R). You can check this by typing the following at a shell prompt:

               xmodmap -pk

  This is why the Developer Kit for Linux considers that Meta is being pressed together with Alt. As a workaround, you can remove the Meta_x mapping by typing the following at a shell prompt:

               xmodmap -e "keysym Alt_L = Alt_L" -e "keysym Alt_R = Alt_R"

  Note: This workaround might affect other X-Windows applications running on the same display if they use the Meta-key that was removed.

### Information about Linux memory allocation

Java applications that use many threads can exceed the systems memory capacity. Use the following formula to estimate the maximum number of threads a Java application can use:

        heap_size(MB) + 2*thread_count <      910   (approximately)

When memory is exhausted, the JVM or the JIT will report an error condition similar to one of the following:

       Exception in thread "main"
          java.lang.OutOfMemoryError
          at java.lang.Thread.start(Native Method)
          at serling.main(serling.java:29)

       COMPILER ERROR: java/io/ObjectStreamClass.compareClassNames - JIT:
          Out of memory, emitcode

It is the "out of memory" indication that is significant, not the specific files or methods that are named. It is also possible that other error messages may follow the above which do not indicate additional errors, but instead indicate secondary effects of the out of memory condition.

### Information for Japanese users

This release supports only US English and Japanese. Japanese language support was tested only with TurboLinux Server 6.5 for zSeries and S/390, and not tested with SuSE Linux 7.0. This was because, at present, only TurboLinux Server for zSeries and S/390 supports Japanese.

#### Japanese Fonts

Java uses the Japanese TrueType fonts supplied by the distribution.

TurboLinux Japan have made the Japanese TrueType fonts available from their website - http://www.turbolinux.co.jp (Search word : truetype).

#### Tested environments

S/390 does not have any natively attached graphical displays. Therefore a remote system, which has a graphical display, is required. There are two ways to display X applications on the remote systems.

1. XDMCP (X Display Manager Control Protocol): The Graphic Client displays the entire X screen of the Linux S/390 system.
2. DISPLAY contents: The Graphic Client displays the application window of the Linux S/390 system.

TurboLinux Server 6.5 for zSeries and S/390 does not have any IM (Input Method) interface such as kinput2. As a result, only the second option above has been tested for this release.

The following environments have been tested :

System | OS | Language | Window Manager | Host Attached Input Method Engine
Java System | TurboLinux for S/390 | Japanese (EUC) | FVWM2 lesstif-mwm, twm (no kinput2) | Canna 3.5 (no kinput2)
Graphic Client | TurboLinux Server J6.5 | Japanese (EUC) | Sawfish1 with GNOME | Canna 3.5 with kinput2 FreeWnn with kinput2

#### Japanese Kana-Kanji conversion users

On Japanese versions of Linux, you can use a Japanese input method such as Canna, ATOK12(TM) SE, Wnn4(TM), or Wnn6. Use the following sections to avoid problems when using these Japanese input methods.

All Input Method users

- If you use an IME on a TextArea or a TextField component, the committed text sometimes disappears when you commit the composed text. To avoid this problem, move the mouse pointer away from the composed text and away from the status information line when you commit the composed text. If you do encounter the problem, press the Enter key again, and then the committed text is displayed.

- If you use an IME on a TextArea or a TextField component, the composed text is sometimes displayed in the wrong position. To avoid this problem, do not change the component position vertically after you commit a string. If you do encounter this problem, re-activate the IME, and then the composed text is displayed at the correct position. The committed text is always displayed at the correct position.

- If you use an IME with the Sawfish (previously known as Sawmill) window manager, an Input Method Framework (IMF) status window, which is a small window attached to the Java client window, always stays on the top of all the windows on your desktop, even if you switch to another window.

  To bring another window to the top, do one of the following:

  - Minimize the Java client window
  - Drag the Java client window to move it away from the desktop.

Canna users
  If you are using the Canna input method with the kinput2 input method server, some visual feedback from the input method is not visible while you are in KIGOU input mode. To avoid the problem, move the focus onto the client window after the Auxiliary Control Window opens.

ATOK12 SE users

- If you are using ATOK12 SE for Linux, composed text might not be committed immediately after you select a candidate in the lookup window. If you continue to input a character, then the committed candidate is displayed.
- If you are using ATOK12 SE for Linux, changing the input focus between the components neither commits nor flushes the composed text, and you can continue to edit the composed text while other input methods commit or flush the composed text when the focus changes.

Wnn4 users
  If you are using Wnn4, the Enter key does not create a new line and a carriage return while the Input Method Editor (IME) is activated. To create a new line and carriage return, deactivate the IME.

Wnn6 users
  The xwnmo Input Method server is not supported. Use kinput2 as the Input Method server.

IIIMP IME users
  IME's (Input Method Editor) using Internet-Intranet Input Method Protocol(IIIMP) are not supported on TurboLinux Workstation 6.0J.

## Service and support for independent software vendors

If you are entitled to services for the Program code pursuant to the IBM Solutions Developer Program, contact the IBM Solutions Developer Program through your normal method of access or on the Web at http://www.developer.ibm.com.

If you have purchased a service contract (that is, IBM's Personal Systems Support Line or equivalent service by country), the terms and conditions of that service contract will determine what services, if any, you are entitled to receive with respect to the Program.

## Accessibility

The READMEs supplied with this Developer Kit and the Runtime Environment have been tested using screen readers. You can use a screen reader such as the Home Page Reader or the JAWS screen reader with these READMEs.

To change the font sizes in the READMEs, use the function supplied with your browser, usually found under the View menu option.

### Java console accessibility

The Java console does not respond to the tab key for navigation. Use the control-tab key pair to navigate the console.

### Policy Tool and accessibility

Policy Tool does not meet accessibility requirements. Policy Tool is used to edit a JVM's security policy files. Because these files are in regular text format, you may edit them with any standard text editor (Notepad on Windows or vi on Unix systems, for example). Information on the policy file location and contents, including required format, can be found at: http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html.

Information about the permissions granted in a policy file can be found at: http://java.sun.com/j2se/1.3/docs/guide/security/permissions.html

## Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

- IBM Director of Licensing
  IBM Corporation
  North Castle Drive, Armonk
  NY 10504-1758 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

- IBM World Trade Asia Corporation Licensing
  2-31 Roppongi 3-chome, Minato-ku
  Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the information. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this information at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

- JTCMAIL@uk.ibm.com
  [Hursley Java Technology Center (JTC) contact]

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

### Trademarks

IBM is a trademark of International Business Machines Corporation in the United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. The Java technology is owned and exclusively licensed by Sun Microsystems, Inc.

Other company, product, and service names may be trademarks or service marks of others.

This product is also based in part on the work of the FreeType Project. For more information about FreeType see http://www.freetype.org.