Version 8 IBM SDK, Java Technology Edition · 2020-05-01 · Version 8 IBM SDK, Java Technology...

IBM SDK, Java Technology EditionVersion 8

User Guide

IBM

Note

Before you use this information and the product it supports, read the information in “Notices” on page331.

Copyright information

This edition of the user guide applies to IBM® SDK, Java™ Technology Edition, Version 8, and to all subsequent releases,modifications, and fix packs, until otherwise indicated in new editions.

IBM SDK, Java Technology Edition, Version 8 might be identified by one of the following platform-specific programnames in the SDK license file:

IBM(R) 32-bit SDK for AIX, Java(TM) Technology Edition, Version 8 (6213-001)IBM(R) 64-bit SDK for AIX, Java(TM) Technology Edition, Version 8 (6213-001)IBM (R) 31-bit SDK for z/OS, Java (TM) Technology Edition, Version 8 (5655-DGG)IBM (R) 64-bit SDK for z/OS, Java (TM) Technology Edition, Version 8 (5655-DGH)IBM(R) 64-bit SDK for Mac OS(R), Java(TM) Technology Edition, Version 8 (6213-001)IBM(R) 64-bit SDK for Solaris(TM) on AMD64/EM64T architecture, Java(TM) Technology Edition Version 8 (6213-001)IBM(R) 64-bit SDK for Solaris(TM), Java(TM) Technology Edition Version 8HP(R) JDK(TM) for J2SE(TM) HP-UX(R) 11i platform adapted by IBM(R) for IBM(R) Software Version 8 for 64-bit Itanium (6213-001)HP(R) JDK(TM) for J2SE(TM) HP-UX(R) 11i platform adapted by IBM(R) for IBM(R) Software Version 8 for 32-bit Itanium (6213-001)

Note: On Windows, MacOS, Solaris, and HP-UX platforms, the SDK is available only as part of an IBM product or service.© Copyright International Business Machines Corporation 2015, 2020.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Preface................................................................................................................vii

Chapter 1. Product overview..................................................................................1Introduction................................................................................................................................................. 1

IBM Software Developers Kit (SDK).......................................................................................................1Runtime Environment.............................................................................................................................4Small Footprint JRE (Linux only)............................................................................................................ 6Java virtual machine............................................................................................................................ 11

What's new.................................................................................................................................................12First release..........................................................................................................................................13Service refresh 1.................................................................................................................................. 16Service refresh 2.................................................................................................................................. 18Service refresh 3.................................................................................................................................. 20Service refresh 4.................................................................................................................................. 22Service refresh 5.................................................................................................................................. 23Service refresh 6.................................................................................................................................. 34

Conventions............................................................................................................................................... 36Other sources of information.....................................................................................................................37Accessibility............................................................................................................................................... 37

Chapter 2. Migrating............................................................................................ 39Migrating from earlier releases of the IBM SDK, Java Technology Edition..............................................39Version compatibility................................................................................................................................. 41

Chapter 3. Installing............................................................................................43Supported environments...........................................................................................................................44Support for virtualization software............................................................................................................47installp packages (AIX only)......................................................................................................................48

Installation verification........................................................................................................................ 49Upgrading the SDK............................................................................................................................... 50Relocating an installp package............................................................................................................ 50

InstallAnywhere packages (AIX and Linux only)...................................................................................... 51Attended installation............................................................................................................................52Unattended installation........................................................................................................................53Interrupted installation........................................................................................................................54Known issues and limitations.............................................................................................................. 54Uninstalling...........................................................................................................................................55

SMP/E and non-SMP/E packages (z/OS only)........................................................................................... 56

Chapter 4. Configuring.........................................................................................57Setting the path..........................................................................................................................................57Setting the class path................................................................................................................................ 57Setting the library path on AIX and Linux................................................................................................. 58Configuring your system............................................................................................................................ 59Enabling Java accessibility support.......................................................................................................... 60z/OS code pages........................................................................................................................................ 60Updating Daylight Saving Time..................................................................................................................61

Chapter 5. Developing Java applications.............................................................. 63Debugging Java applications.....................................................................................................................63

iii

The Java Debugger...............................................................................................................................63Determining whether your application is running on a 32-bit (31-bit on IBM Z) or 64-bit JVM ............ 64Native threads (AIX only)...........................................................................................................................64Support for XToolkit (AIX, Linux, and z/OS only)...................................................................................... 65Default Swing key bindings........................................................................................................................65Distributing Java applications................................................................................................................... 78

Chapter 6. Running Java applications.................................................................. 81Obtaining version information................................................................................................................... 82Specifying Java options and system properties....................................................................................... 83Standard options........................................................................................................................................84Support for bidirectional data................................................................................................................... 85

Special Arabic characters.................................................................................................................... 85Known limitations.................................................................................................................................87Bidirectional system property command-line options........................................................................87

Globalization of the java command.........................................................................................................90Running Java applications on the Little Endian (LE) Runtime Environment (Linux only)........................ 91

Chapter 7. Performance tuning............................................................................ 93

Chapter 8. Security..............................................................................................95Security considerations............................................................................................................................. 95Security components and tools.................................................................................................................96

Chapter 9. Troubleshooting and support...............................................................99Submitting problem reports...................................................................................................................... 99Known issues and limitations....................................................................................................................99

Issues and limitations on AIX............................................................................................................101Issues and limitations on Linux......................................................................................................... 102Issues and limitations on Windows...................................................................................................103Issues and limitations on z/OS.......................................................................................................... 104

Problem determination........................................................................................................................... 105First steps in problem determination................................................................................................ 105AIX problem determination............................................................................................................... 106Linux problem determination............................................................................................................ 136Windows problem determination...................................................................................................... 150z/OS problem determination............................................................................................................. 159NLS problem determination...............................................................................................................175

Using diagnostic tools..............................................................................................................................177Using the IBM Monitoring and Diagnostic Tools............................................................................... 177IBM Support Assistant Data Collector...............................................................................................179Using the HPROF Profiler................................................................................................................... 179

Chapter 10. Exploiting data compression devices............................................... 185Enabling hardware compression acceleration (AIX, Linux only)........................................................... 185

Hardware compression acceleration issues on Power Systems and IBM Z systems (AIX, Linuxonly)...............................................................................................................................................187

zEnterprise Data Compression (z/OS only).............................................................................................188

Chapter 11. Exploiting RDMA............................................................................. 193Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)................................................ 193

Comparing JSOR with Java TCP communications (Linux only)........................................................ 193Comparing JSOR to Java Sockets Direct Protocol (SDP) communications (Linux only)..................194JSOR features and design (Linux only)..............................................................................................195JSOR system requirements and supported APIs (Linux only)..........................................................198When to choose JSOR (Linux only)....................................................................................................200

iv

JSOR limitations (Linux only).............................................................................................................201Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)............................203JSOR problem determination (Linux only)........................................................................................ 208JSOR environment settings (Linux only)........................................................................................... 219RDMA system property command-line options................................................................................ 221

The jVerbs library (Linux only)..............................................................................................................232jVerbs application system and runtime requirements (Linux only)..................................................234Writing Java applications that use the jVerbs library (Linux only).................................................235jVerbs problem determination (Linux only).......................................................................................249

Shared Memory Communications via Remote Direct Memory Access (z/OS only)............................... 253

Chapter 12. Java Plug-in, Applet Viewer, and Web Start (AIX, Linux, andWindows only)............................................................................................... 255Using the Java plug-in (AIX, Linux 32-bit, and Windows only).............................................................. 255

Supported browsers for the Java plug-in (AIX, Linux, and Windows only)...................................... 255Installing the Java plug-in by using the Java control panel on Windows.........................................256Installing the Java plug-in on AIX and Linux.....................................................................................256Changing the properties of the Java Plug-in (AIX only)....................................................................257Java plug-in environment variables (AIX and Linux only)................................................................ 257Common Document Object Model (DOM) support (AIX, Linux, and Windows only)....................... 257Using DBCS parameters (AIX, Linux, and Windows only).................................................................258

Working with applets (AIX, Linux, and Windows only)...........................................................................258Running and debugging applets with the Applet Viewer (AIX, Linux, and Windows only).............. 258Unique CLSIDs (Windows only)......................................................................................................... 259Java Applet Viewer and the classpath (AIX only)............................................................................. 259

Using Web Start (AIX, Linux, and Windows only)................................................................................... 259Running Web Start (AIX, Linux, and Windows only)......................................................................... 260

Chapter 13. Using XML.......................................................................................261Migrating to the XL-TXE-J....................................................................................................................... 263Securing Java API for XML processing (JAXP) against malformed input.............................................. 265XML reference information......................................................................................................................265

XL XP-J reference information...........................................................................................................265XL TXE-J reference information.........................................................................................................268Using an older version of Xerces or Xalan......................................................................................... 270

XML system property command-line options.........................................................................................271-Dcom.ibm.xtq.processor.overrideSecureProcessing...................................................................... 271-Djdk.xml.entityExpansionLimit........................................................................................................ 271-Djdk.xml.maxGeneralEntitySizeLimit...............................................................................................272-Djdk.xml.maxOccur.......................................................................................................................... 272-Djdk.xml.maxParameterEntitySizeLimit.......................................................................................... 273-Djdk.xml.maxXMLNameLimit........................................................................................................... 274-Djdk.xml.resolveExternalEntities.....................................................................................................274-Djdk.xml.totalEntitySizeLimit........................................................................................................... 275

Known issues and limitations..................................................................................................................276

Chapter 14. The ORB..........................................................................................277CORBA......................................................................................................................................................277RMI and RMI-IIOP...................................................................................................................................277Java IDL or RMI-IIOP?............................................................................................................................ 278RMI-IIOP limitations............................................................................................................................... 278Examples of client–server applications..................................................................................................278

Interfaces........................................................................................................................................... 278Remote object implementation (or servant)..................................................................................... 279Stubs and ties generation.................................................................................................................. 279Server code.........................................................................................................................................280

How the ORB works.................................................................................................................................282

v

The client side.................................................................................................................................... 282The server side................................................................................................................................... 287

Additional features of the ORB................................................................................................................289Portable object adapter..................................................................................................................... 289Interoperable Naming Service (INS)................................................................................................. 290

Using the ORB..........................................................................................................................................291ORB problem determination .................................................................................................................. 293

Identifying an ORB problem.............................................................................................................. 294Debug properties................................................................................................................................295ORB exceptions..................................................................................................................................296Completion status and minor codes..................................................................................................297Java security permissions for the ORB..............................................................................................298Interpreting the stack trace...............................................................................................................299Interpreting ORB traces.....................................................................................................................299Common problems.............................................................................................................................302IBM ORB service: collecting data...................................................................................................... 304

CORBA support........................................................................................................................................305ORB implementation classes.............................................................................................................306CORBA system property command-line options.............................................................................. 306CORBA minor codes...........................................................................................................................313

Chapter 15. RMI, IIOP, and RMI-IIOP.................................................................317The RMI implementation.........................................................................................................................318Using RMI-IIOP....................................................................................................................................... 319

The rmic compiler.............................................................................................................................. 319The idlj compiler.................................................................................................................................320Making RMI programs use IIOP.........................................................................................................320Connecting IIOP stubs to the ORB.................................................................................................... 322Thread pooling for RMI connection handlers....................................................................................323Understanding distributed garbage collection..................................................................................323Restrictions when running RMI programs over IIOP........................................................................ 323

Debugging applications involving RMI.................................................................................................... 324Issues and limitations............................................................................................................................. 324

Chapter 16. Miscellaneous system property command-line options.....................327-Dcom.ibm.dbgmalloc property.............................................................................................................. 327-Dcom.ibm.mappedByteBufferForce option.......................................................................................... 327-Dcom.ibm.rational.mvfs.checking (Windows only)...............................................................................327-Dcom.ibm.signalhandling.ignoreLogoff (Windows only)...................................................................... 328-Dcom.ibm.zipfile.closeinputstreams option......................................................................................... 328-Dibm.awt.mediumColor (AIX only)........................................................................................................328-Dil8n.vs option....................................................................................................................................... 328-Dsun.rmi.transport.tcp.connectionPool option.....................................................................................329

Notices..............................................................................................................331Trademarks..............................................................................................................................................332Terms and conditions for product documentation.................................................................................332IBM Online Privacy Statement................................................................................................................ 333

vi

Preface

This guide provides general information about the IBM SDK, Java Technology Edition, Version 8. Theguide gives specific information about any differences in the IBM implementation compared with theOracle implementation.

Read this information in conjunction with the documentation on the Oracle website: http://www.oracle.com/technetwork/java/index.html.

Useful websites for AIX include:

• The Java technologies download site for AIX®.• IBM home page for Java technologies.

The terms Runtime Environment and Java Virtual Machine are used interchangeably throughout thisguide.

The Program Code is not designed or intended for use in real-time applications such as (but not limitedto) the online control of aircraft, air traffic, aircraft navigation, or aircraft communications; or in the design,construction, operation, or maintenance of any nuclear facility.

© Copyright IBM Corp. 2015, 2020 vii

http://www.oracle.com/technetwork/java/index.html

http://www.oracle.com/technetwork/java/index.html

https://www.ibm.com/developerworks/java/jdk/aix/

https://www.ibm.com/java/

viii IBM SDK, Java Technology Edition, Version 8: User Guide

Chapter 1. Product overviewGain a quick understanding of the product, its new features, and conventions that are used elsewhere inthis documentation.

This edition of the user guide applies to IBM SDK, Java Technology Edition Version 8 and to allsubsequent releases and modifications until otherwise indicated in new editions.

In this guide, the name IBM SDK, Java Technology Edition, Version 8 is used to refer to any of thesupported configurations, unless specifically called out in the text.

This user guide is updated for each refresh of IBM SDK, Java Technology Edition, Version 8 that containsan Oracle Critical Patch Update (CPU). Oracle CPUs are scheduled every 3 months, as outlined in thefollowing bulletin: https://www.oracle.com/technetwork/topics/security/alerts-086861.html. IBMpackages that contain the CPU are made available shortly afterward.

Late breaking information about the IBM SDK, Java Technology Edition, Version 8 that is not available inthe user guide can be found here: https://www.ibm.com/support/docview.wss?uid=swg21672834

To determine the service refresh or fix pack level of an installed version, see “Obtaining versioninformation” on page 82.

Any new modifications that are made to this user guide are indicated by vertical bars to the left of thechanges.

IntroductionThe IBM implementation of the Java platform provides development tools and an application runtimeenvironment.

The Java programming language is a high-level, object-oriented language. When written, a Java programis compiled into bytecode. The bytecode is interpreted at run time by a platform-specific Java component.This component acts as a translator between the language and the underlying operating system andhardware. This staged approach to compiling and interpreting Java applications means that applicationcode can be easily ported across hardware platforms and operating systems.

The IBM implementation of the Java platform is based upon the Java Technology developed by OracleCorporation. IBM supply an installable package, the Software Developers Kit (SDK). The key componentsin this package are detailed in the sections that follow.

Note: Any reference to Oracle is intended as a reference to Oracle Corporation.

IBM Software Developers Kit (SDK)The SDK contains development tools and a Java runtime environment.

The SDK is an installable Java package, which contains the Java Application Programming Interface (API).The Java API is a large collection of ready-made classes, grouped into libraries, that help you develop anddeploy applications. The SDK also includes:

• A Java compiler.• A Java Virtual Machine (JVM or VM).• Tools for monitoring, debugging, and documenting applications.• Tools for developing user interfaces, or GUIs.• Integration libraries for applications that must access databases and remote objects.

AIX, Linux®, Windows, and z/OS®The SDK for these platforms contains the Eclipse OpenJ9 virtual machine and Just-In-Time (JIT)compiler technology.

© Copyright IBM Corp. 2015, 2020 1

https://www.oracle.com/technetwork/topics/security/alerts-086861.html

https://www.ibm.com/support/docview.wss?uid=swg21672834

Note for Windows operating systems: IBM generates an SDK for this platform to develop IBM productsthat contain the IBM runtime environment. However, the SDK for Windows is available only as part of anIBM product or service and is not available to download separately. Therefore some content, such asinstallation, is not provided in this user guide.

The SDK package contains a readme file that provides links to the online documentation in IBMKnowledge Center, and to downloadable documentation. The documentation available for downloadincludes this guide, in multiple formats.

When the package is installed, the SDK tools can be found in the install_dir/jre /bin directory.

Applications written entirely in Java must have no dependencies on the IBM SDK directory structure (orfiles in those directories). Any dependency on the SDK directory structure (or the files in those directories)might result in application portability problems.

Note: On Windows 32-bit operating systems, Java Native Interface (JNI) applications have some minordependencies.

Contents of the SDKSDK tools:

appletviewer (Java Applet Viewer)Tests and runs applets outside a web browser.

extcheck (Extcheck utility)Detects version conflicts between a target jar file and jar files that are currently installed.

ControlPanel (Java Control Panel)AIX and Linux (except on IBM Z®) operating systems only. Configures your runtime environment.

hwkeytoolz/OS operating systems only. Manages a keystore of private keys and their associated X.509certificate chains authenticating the corresponding public keys.

idlj (IDL to Java Compiler)Generates Java bindings from a given IDL file.

jar (Java Archive Tool)Combines multiple files into a single Java Archive (JAR) file.

jarsigner (JAR Signing and Verification Tool)Generates signatures for JAR files and verifies the signatures of signed JAR files.

java (Java Interpreter)Runs Java classes. The Java Interpreter runs programs that are written in the Java programminglanguage.

java-rmi (HTTP-to-CGI request forward tool)Except 64-bit AIX operating systems. Accepts RMI-over-HTTP requests and forwards them to anRMI server listening on any port.

javac (Java Compiler)Compiles programs that are written in the Java programming language into bytecodes (compiledJava code).

javadoc (Java Documentation Generator)A utility to generate HTML pages of API documentation from Java source files.

javah (C Header and Stub File Generator)Enables you to associate native methods with code written in the Java programming language.

javap (Class File Disassembler)Disassembles compiled files and can print a representation of the bytecodes.

javaw (Java Interpreter)Runs Java classes in the same way as the java command does, but does not use a consolewindow.

2 IBM SDK, Java Technology Edition, Version 8: User Guide

javaws (Java Web Start)AIX, Linux (IA® and 64-bit Power® architecures), and Windows operating systems only. Enablesthe deployment and automatic maintenance of Java applications. For more information, see“Running Web Start (AIX, Linux, and Windows only)” on page 260.

jconsole (JConsole Monitoring and Management Tool)Monitors local and remote JVMs using a GUI. JMX-compliant. From version 8, this tool has aslightly different look and feel, see“Accessibility issues with the jconsole utility” on page 100.

jdb (Java Debugger)Except z/OS operating systems. Helps debug your Java programs.

jdmpview (AIX, Linux, Windows, and z/OS only)Analyzes dumps produced by the J9 VM. For more information, see the Dump viewer.

keytool (Key and Certificate Management Tool)Manages a keystore (database) of private keys and their associated X.509 certificate chains thatauthenticate the corresponding public keys.

native2ascii (Native-To-ASCII Converter)Converts a native encoding file to an ASCII file that contains characters encoded in either Latin-1or Unicode, or both.

packager (JavaBean to ActiveX packager)32-bit Windows operating systems only. Packages a JavaBean in a jar file for use as an ActiveXcontrol.

policytool (Policy File Creation and Management Tool)Creates and modifies the external policy configuration files that define the Java security policy foryour installation. From Version 8, the graphical user interface of this tool has a slightly differentlook and feel. See “Accessibility issues with the policytool graphical user interface (GUI) utility” onpage 100.

rmic (Java Remote Method Invocation (RMI) Stub Converter)Generates stubs, skeletons, and ties for remote objects. Includes RMI over Internet Inter-ORBProtocol (RMI-IIOP) support.

rmid (RMI activation system daemon)Starts the activation system daemon so that objects can be registered and activated in a JavaVirtual Machine (JVM).

rmiregistry (Java remote object registry)Creates and starts a remote object registry on the specified port of the current host.

schemagenCreates a schema file for each namespace referenced in your Java classes.

serialver (Serial Version Command)Returns the serialVersionUID for one or more classes in a format that is suitable for copying intoan evolving class.

tnameserv (Common Object Request Broker Architecture (CORBA) transient naming service)Starts the CORBA transient naming service.

wsgenGenerates JAX-WS portable artifacts used in JAX-WS Web services.

wsimportGenerates JAX-WS portable artifacts from a Web Services Description Language (WSDL) file.

xjcCompiles XML Schema files.

z/OS batch toolkit (z/OS only)A set of tools that enhances Java batch capabilities and use of system interfaces on z/OS. Thetoolkit includes:

• A native launcher for running Java applications directly as batch jobs or started tasks.

Chapter 1. Product overview 3

• A set of Java classes that make access to traditional z/OS data and key system services directlyavailable from Java applications.

• Console communication, multiline WTO (write to operator), and return code passing capability.

For more information about the z/OS batch toolkit, see: JZOS Batch Launcher and Toolkit.Include Files

C headers for JNI programs.Demos

The demo directory (installed from a separate package on Windows operating systems) contains anumber of subdirectories containing sample source code, demos, applications, and applets that youcan use.

readme fileA text file containing minimal information about how to get started. This file provides links to onlineand downloadable documentation, including IBM API documentation for the SDK.

Copyright noticeThe copyright notice for this release.

License fileExcept z/OS operating systems.

The License file contains the license agreement for the SDK. To view or print the license agreement,open the file in a Web browser. The path to the license file is as follows, where <locale> is the name ofyour locale, for example en.

• AIX: /usr/swlag/locale/Java6_64.la• Windows: install_dir\docs\content\locale\license_locale

Note: The Annotation Processing Tool (APT) is no longer included. The tool was superseded by thePluggable Annotation Processing API (JSR269) in Java SE Version 8. This annotation processing facilityhas been available since Java SE Version 6.

Runtime EnvironmentThe Java runtime environment provides runtime support for Java applications.

The runtime environment includes a Java Virtual Machine (VM), which interprets Java bytecode at runtime. Although the runtime environment is included with the IBM SDK, it is also available as a separatepackage on Linux and Windows operating systems. There are a number of tools included with the runtimeenvironment that are installed into the install_dir/jre/bin directory, unless otherwise specified.

Contents of the runtime environmentCore Classes

These classes are the compiled class files for the platform and must remain compressed for thecompiler and interpreter to access them. Do not modify these classes; instead, create subclasses andoverride where you need to.

Trusted root certificatesFrom certificate signing authorities. These certificates are used to validate the identity of signedmaterial.

Runtime environment toolsControlPanel (Java Control Panel)

AIX and Linux operating systems only, except Linux on IBM Z. Configures your RuntimeEnvironment.

ikeycmd (iKeyman command-line utility)Allows you to manage keys, certificates, and certificate requests from the command line. For moreinformation see the accompanying Security documentation.


ikeyman (iKeyman GUI utility)Allows you to manage keys, certificates, and certificate requests. For more information see theaccompanying Security documentation, which includes the iKeyman User Guide. There is also acommand-line version of this utility.

Note: The GUI version of this utility is not supported on the z/OS operating system.

jaaslogon (Windows only)A Windows service that enables JAAS Active Login applications to change their effective user atrun time using the JAAS Active Login API.

java (Java Interpreter)Runs Java classes. The Java Interpreter runs programs that are written in the Java programminglanguage.

javacpl (Java Control Panel)Windows operating systems only. Configures your Runtime Environment.

javaw (Java Interpreter)Runs Java classes in the same way as the java command does, but does not use a consolewindow.

javaws (Java Web Start)AIX, Linux (IA 32-bit, PPC32, and PPC64), and Windows operating systems only. Enables thedeployment and automatic maintenance of Java applications. For more information, see “RunningWeb Start (AIX, Linux, and Windows only)” on page 260.

jcontrol (Java Control Panel)AIX and Linux operating systems only, except Linux on IBM Z. Configures your RuntimeEnvironment.

jextractLinux and AIX operating systems only. Packages system dumps with executable files and libraries,to create an archive file. This file can be used by the dump viewer tool (jdmpview) to get moreinformation than from a system dump alone. For more information, see Dump extractor(jextract).

keytool (Key and Certificate Management Tool)Manages a keystore (database) of private keys and their associated X.509 certificate chains thatauthenticate the corresponding public keys.

kinitObtains and caches Kerberos ticket-granting tickets.

klistDisplays entries in the local credentials cache and key table.

ktabManages the principal names and service keys stored in a local key table.

pack200Transforms a JAR file into a compressed pack200 file using the Java gzip compressor.

policytool (Policy File Creation and Management Tool)Creates and modifies the external policy configuration files that define the Java security policy foryour installation. From Version 8, the graphical user interface of this tool has a slightly differentlook and feel. See “Accessibility issues with the policytool graphical user interface (GUI) utility” onpage 100.

rmid (RMI activation system daemon)Starts the activation system daemon so that objects can be registered and activated in a JavaVirtual Machine (JVM).

rmiregistry (Java remote object registry)Creates and starts a remote object registry on the specified port of the current host.

tnameserv (Common Object Request Broker Architecture (CORBA) transient naming service)Starts the CORBA transient naming service.


unpack200Transforms a packed file produced by pack200 into a JAR file.

Small Footprint JRE (Linux only)The Small Footprint JRE, available on Linux operating systems only, contains a lightweight version of theIBM runtime environment for Java.

This lightweight version of the runtime environment is based on the runtime environment within the IBMSDK, Java Technology Edition product for Linux. The lightweight runtime environment is designed for webdevelopers who want to develop and deploy Java applications in the cloud environment. The SmallFootprint JRE is available in IBM Cloud and as a Docker image. For more information about using theSmall Footprint JRE in the IBM Cloud, see Customize the runtime environment in the IBM Clouddocumentation. For more information about the runtime environment and Docker, see IBM SDK, JavaTechnology Edition and Docker.

Java tools and functions that are not required in the cloud environment, such as the Java control panel,are removed from the lightweight runtime environment. The runtime environment is stripped down toprovide core, essential function that has a greatly reduced disk and memory footprint.

The lightweight runtime environment uses compressed references for 64-bit runtime environments.When the virtual machine uses compressed references, all references to objects, classes, threads, andmonitors are stored as 32-bit values. The use of compressed references improves the performance ofmany applications because objects are smaller, resulting in less frequent garbage collection andimproved memory cache utilization.

You can identify the implementation in the output from the java -version command, which is similarto the following example:

java version "1.8.0"Java(TM) SE Runtime Environment (build pxa6480sr3-20160428_01(SR3) Small Footprint)IBM J9 VM (build 2.8, JRE 1.8.0 Linux amd64-64 Compressed References 20160427_301573 (JIT enabled, AOT enabled)J9VM - R28_Java8_SR3_20160427_1620_B301573JIT - tr.r14.java.green_20160329_114288GC - R28_Java8_SR3_20160427_1620_B301573_CMPRSSJ9CL - 20160427_301573)JCL - 20160421_01 based on Oracle jdk8u91-b14

The first line shows the version: java version "1.8.0".

This guide explains which tools and functions are removed from the lightweight runtime environment. Ifyou are using the runtime environment in the IBM Cloud and require libraries or classes that are notavailable, you can customize the runtime environment by packaging extra files in a resources folder. Formore information, see Customize the runtime environment in the IBM Cloud documentation.

Runtime functions and tools for the Small Footprint JRE (Linux only)Specific tools, libraries, and JAR files are removed from the IBM runtime environment for Java, to reducememory and disk requirements.

Java functions

The following functions are not available with the runtime environment, to reduce memory and diskstorage:Domain Name Service (DNS)

lib/ext/dnsns.jarJavascript support

lib/ext/javascript.jarUncompressed references support

lib/amd64/classic


https://cloud.ibm.com/docs/runtimes/liberty?topic=liberty-customizing_jre

https://hub.docker.com/r/ibmcom/ibmjava/

https://hub.docker.com/r/ibmcom/ibmjava/


lib/amd64/defaultJava language management source code support

lib/jlm.src.jarAggressive performance function

lib/aggressive.jar

Tools provided with the runtime environment

The following tools are removed :Java tools

bin/classic/*bin/j9vm/*

Java executable programbin/javaw: Runs without using a console window.

Kerberos toolsbin/kinit: Obtains and caches tickets.bin/klist: Displays entries in the local credentials cache and key table.bin/ktab: Manages the principal names and service keys stored in a local key table.

Common Object Request Broker Architecture (CORBA) toolbin/tnameserv: Transient naming service.

Compression toolbin/pack200: Transforms a JAR file into a compressed pack200 file.bin/unpack200: Transforms a compressed pack200 file into a JAR file.

Desktop toollib/jexec: Runs JAR files.

Classes, locale, and font support for the Small Footprint JRE (Linux only)To reduce disk footprint, certain classes in the rt.jar file are removed, together with some languageand locale support.

Classes in rt.jar

The following classes are removed from the rt.jar file.

• com/sun/javadoc/• com/sun/jdi/• com/sun/jarsigner/• com/sun/mirror/• com/sun/source/• com/sun/istack/internal/tools/• com/sun/istack/internal/ws/• META-INF/services/com.sun.jdi.connect.Connector• META-INF/services/com.sun.jdi.connect.spi.TransportService• META-INF/services/com.sun.mirror.apt.AnnotationProcessorFactory• META-INF/services/com.sun.tools.xjc.Plugin• com/sun/tools/• sun/jvmstat/• sun/nio/cs/ext/


• sun/awt/HKSCS.class• sun/awt/motif/X11GB2312$Decoder.class• sun/awt/motif/X11GB2312$Encoder.class• sun/awt/motif/X11GB2312.class• sun/awt/motif/X11GBK$Encoder.class• sun/awt/motif/X11GBK.class• sun/awt/motif/X11KSC5601$Decoder.class• sun/awt/motif/X11KSC5601$Encoder.class• sun/awt/motif/X11KSC5601.class• sun/rmi/rmic/• sun/tools/asm/• sun/tools/java/• sun/tools/javac/• com/sun/tools/classfile/• com/sun/tools/javap/• sun/tools/jcmd/• sun/tools/jconsole/• sun/tools/jps/• sun/tools/jstat/• sun/tools/jstatd/• sun/tools/native2ascii/• sun/tools/serialver/• sun/tools/tree/• sun/tools/util/• sun/security/tools/JarBASE64Encoder.class• sun/security/tools/JarSigner.class• sun/security/tools/JarSignerParameters.class• sun/security/tools/JarSignerResources*.class• sun/security/tools/SignatureFile$Block.class• sun/security/tools/SignatureFile.class• sun/security/tools/TimestampedSigner.class• sun/security/provider/Sun.class• sun/security/rsa/SunRsaSign.class• sun/security/ssl/• com/sun/net/ssl/internal/ssl/• javax/crypto/• sun/security/internal/• com/sun/crypto/provider/• META-INF/services/com.sun.tools.attach.spi.AttachProvider• com/sun/tools/attach/• org/relaxng/datatype/• com/sun/codemodel/• com/sun/xml/internal/dtdparser/


• com/sun/xml/internal/rngom/• com/sun/xml/internal/xsom/• com/sun/tools/script/shell/• sun/tools/attach/• sun/tools/jstack/• sun/tools/jinfo/• sun/tools/jmap/• sun/awt/motif/• sun/awt/X11/• sun/applet/• sun/java2d/opengl/• com/sun/java/swing/plaf/

Locale support

The following files associated with locale support are removed:

• lib/ext/localedata.jar• lib/locale• lib/charsets.jar• lib/resources.jar

Font support

The following fonts are removed:

• lib/fonts/LucidaBright*.ttf• lib/fonts/LucidaSansDemiBold.ttf• lib/fonts/LucidaTypewriter*.ttf• lib/oblique-fonts

Desktop, plug-in, and Web Start support for the Small Footprint JRE (Linux only)In Docker and in the IBM Cloud, you cannot use IBM runtime environment for Java functions that areassociated with a user interface. Files associated with these functions are removed from the runtimeenvironment to reduce memory and disk space.

Desktop files

These files are associated with desktop capabilities and are removed:

• lib/desktop• lib/amd64/libsoundalsa.so• lib/amd64/libsplashscreen.so• lib/images/icons

Browser plug-in, Applet viewer, and Web Start support

These JAR files and libraries are removed because they support user interface functions:

• bin/ControlPanel• bin/jcontrol• bin/java_vm


• lib/amd64/libjavaplugin*.so• lib/amd64/libnpjp2.so• lib/locale• lib/plugin.jar• plugin• bin/javaws• lib/deploy• lib/amd64/libdeploy.so• lib/security/javaws.policy• lib/deploy.jar• lib/javaws.jar

IBM security support for the Small Footprint JRE (Linux only)Some security providers are removed from the IBM runtime environment for Java to leave only coresecurity functions.

IBM provides a range of security providers that implement various security algorithms and mechanisms.To minimize the disk and memory footprint, the following functions are removed from the runtimeenvironment:Security policy file creation and management tool

bin/policytooliKeyman command-line utility

bin/ikeycmdiKeyman utility (graphical user interface)

bin/ikeymanPKI Certificate Management Protocols implementation

lib/ext/CmpCrmf.jarJNDI implementation for Domain Name Service look-up

lib/ext/dnsns.jarIBM Certificate Management

lib/ext/ibmcmsprovider.jarIBM JCE FIPS certified cryptographic algorithms

lib/ext/ibmjcefips.jarIBM Key Certificate Management

lib/ext/ibmkeycert.jarIBM PKCS11# implementation provider

lib/ext/ibmpkcs11impl.jarPKCS key management

lib/ext/gskikm.jarIBM Simple Authentication and Security Layer (SASL) provider

lib/ext/ibmsaslprovider.jarIBM XML cryptography

lib/ext/ibmxmlcrypto.jarIBM XML security

lib/ext/ibmxmlencprovider.jarXML encryption

lib/ext/xmlencfw.jar


If you require one of these security providers, you can customize the runtime environment by packagingextra files in a resources folder. For more information, see Customize the runtime environment.

For more information about IBM security, see the Security Reference information available in IBMKnowledge Center.

Diagnostic tool support for the Small Footprint JRE (Linux only)Trace and dump formatting tools are removed from the IBM runtime environment for Java™ because theyare not needed for the normal functioning of an application.

The following functions are removed from the runtime environment:

Diagnostic Tool Framework for Javalib/ext/dtfj-interface.jarlib/ext/dtfj.jarlib/ddr

Dump utilitiesbin/jdmpviewlib/ext/jdmpview.jarlib/ext/dtfjview.jarbin/jextract

Trace functionslib/ext/traceformat.jar

Java virtual machineThe Java virtual machine (VM) is the platform-specific component that runs a Java program.

At run time, the VM interprets the Java bytecode that has been compiled by the Java Compiler. The VMacts as a translator between the language and the underlying operating system and hardware. A Javaprogram requires a specific VM to run on a particular platform.

Eclipse OpenJ9 virtual machine

The Eclipse OpenJ9 VM is included in the SDK for AIX, Linux, Windows, and z/OS. This VM, formerlyknown as the IBM J9 VM, was contributed by IBM to the Eclipse Foundation in September 2017. EclipseOpenJ9 includes the following main components:

• VM Application Programming Interface (API)• Diagnostic component• Memory management• Class loader• Interpreter• Platform port layer

For further information about the OpenJ9 VM, see JVM components in the J9 VM reference.

Different versions of the IBM SDK contain different implementations of the VM. You can identify theimplementation in the output from the java -version command, which gives these strings for thedifferent implementations:



https://www.ibm.com/support/knowledgecenter/SSYKE2/welcome_javasdk_family.html

https://www.ibm.com/support/knowledgecenter/SSYKE2/welcome_javasdk_family.html

Implementation Output

8IBM J9 VM (build 2.9, JRE 1.8.0 ...

Before service refresh 5:

IBM J9 VM (build 2.8, JRE 1.8.0 ...

7 Release 1IBM J9 VM (build 2.7, JRE 1.7.0 ...

7IBM J9 VM (build 2.6, JRE 1.7.0 ...

6IBM J9 VM (build 2.4, JRE 1.6.0 IBM...

IBM J9 VM (build 2.6, JRE 1.6.0 ...

What's newIBM SDK, Java Technology Edition, Version 8 is a new release that is fully compatible with Oracle Java SEversion 8 class libraries.

The IBM implementation of Java contains IBM technology and extensions.

Any new modifications made to this user guide are indicated by vertical bars at the start of the changedline.

Monthly refreshes of the SDK for certain platforms are made available on the JavaSDK developer center.These refreshes can contain new features and serviceability improvements, plus fixes from Oracle andIBM. Only levels that contain significant changes are documented in this user guide. For any updates toIBM security in this release, see Security Reference: What's new.

The following table lists all the SDK levels that include an Oracle Critical Patch Update (CPU).

Table 1. SDK refreshes

SDK level Oracle CPU

8.0.0.0 January 2015 CPU

8.0.1.0 April 2015 CPU

8.0.1.10 July 2015 CPU

8.0.2.0 October 2015 CPU


8.0.3.0 April 2016 CPU

8.0.3.10 July 2016 CPU



8.0.4.5 April 2017 CPU

8.0.4.10 July 2017 CPU



https://developer.ibm.com/javasdk/downloads/

Table 1. SDK refreshes (continued)

SDK level Oracle CPU


8.0.5.15 April 2018 CPU

8.0.5.20 July 2018 CPU



8.0.5.35 April 2019 CPU

8.0.5.40 July 2019 CPU

8.0.6 October 2019 CPU


8.0.6.10 April 2020 CPU

Note: For a list of IBM fixes, see https://www.ibm.com/developerworks/java/jdk/fixes/8/index.html.

First releaseLearn about the new features and functions available with this release.

Version 8 includes the following new features:

• “Packed object technology preview” on page 13• “Improved tracing for the Object Request Broker (ORB)” on page 13• “Autonomic connection management for the Object Request Broker (ORB)” on page 14• IBM J9 virtual machine updates:

– “Java Native Interface (JNI) static linking” on page 14– “JIT compiler exploitation of a graphics processing unit (GPU) (Linux only)” on page 14– “Reserving memory space for compressed references” on page 14– “Advanced dump filtering on exception strings” on page 14– “New MXBean for measuring and categorizing CPU usage of the Java virtual machine” on page 14– “Command line option -Xgc:splitheap deprecated (Windows only)” on page 14

• “Oracle enhancements for Java SE 8” on page 14

If you are upgrading from an earlier release of the SDK, other important changes are included in“Migrating from earlier releases of the IBM SDK, Java Technology Edition” on page 39.

Packed object technology preview

Packed object support is available as a technology preview for evaluation purposes. This enhancementallows greater control over the layout of objects in memory. The capability enables greater flexibilitywhen dealing with non-Java memory structures, for example, when exchanging and using data betweenJava code and other languages or environments.

Note: This technology preview was removed in service refresh 5, and is no longer documented.

Improved tracing for the Object Request Broker (ORB)

Component level tracing is now available to improve the debugging of ORB problems. A new systemproperty allows you to generate trace information for one or more ORB components, such as DISPATCH


https://www.ibm.com/developerworks/java/jdk/fixes/8/index.html

or MARSHAL. For more information about this system property, see “-Dcom.ibm.CORBA.Debug.Component” on page 308.

Autonomic connection management for the Object Request Broker (ORB)

From this release, the ORB automatically manages the number of concurrent connections to the serverendpoint, which can improve efficiency. If you want to retain control of these connections, you can turnoff this feature by setting the system property com.ibm.CORBA.ConnectionMultiplicity. For moreinformation, see “Using the ORB” on page 291.

Java Native Interface (JNI) static linking

The Java Native Interface (JNI) now enables runtime linking to static native libraries. You can package aJava runtime, native application code, and Java application code together into a single binary executablethat does not require the use of shared native libraries. A Java application can use a combination of staticand dynamic native libraries, although static libraries must be in memory before they can be used. Formore information, see JNI runtime linking in the J9 VM reference.

JIT compiler exploitation of a graphics processing unit (GPU) (Linux only)

A GPU is designed to optimize parallel processing with potentially thousands of cores that can processthe same instruction at the same time. The JIT compiler takes advantage of this capability by offloadingcertain parallel processing tasks from the CPU to a GPU, which can improve the performance of yourapplication. Specific hardware and software requirements apply. For more information, see How the JITcompiler uses a GPU.

Reserving memory space for compressed references

A new option is available for securing space in memory for any native classes, monitors, and threads thatare used by compressed references. Setting this option can help prevent OutOfMemoryError exceptionsthat might occur if the lowest 4 GB of address space becomes full. For more information, see -Xmcrsoption in the OpenJ9 user documentation.

Advanced dump filtering on exception strings

A new -Xdump suboption is available that allows you to filter dump events to produce dumps only forexceptions that contain a specific text string in the exception detail message. This capability allows you tofine tune the point at which a dump is produced, and reduce the time taken for problem diagnosis. Formore information, see msg_filter option in the OpenJ9 user documentation.

New MXBean for measuring and categorizing CPU usage of the Java virtual machine

A new MXBean is available that monitors CPU consumption of the Java virtual machine and providesdetailed accounting for analysis. You can discover the amount of CPU time that is used by system andapplication threads, with a further breakdown to show time that is spent on Garbage Collection and theJIT compilation processes. You can also control the level of accounting that you want to see becausecertain complex accounting processes can introduce a small increase in application startup time. Formore information about monitoring the CPU consumption, see the JVMCpuMonitorMXBean interface inthe com.ibm.lang.management API reference. For more information about controlling the level ofaccounting, see -XX:[+|-]ReduceCPUMonitorOverhead (AIX, Linux, Windows only) in the OpenJ9 userdocumentation.

Command line option -Xgc:splitheap deprecated (Windows only)The -Xgc:splitheap option is deprecated and will be removed from future versions of the IBM SDK.

Oracle enhancements for Java SE 8The following JEPS are included in this release of the SDK:

• Generalized Target-Type Inference JEP 101


• Parallel Array Sorting JEP 103• Annotations on Java Types JEP 104• DocTree API JEP 105• Add Javadoc to javax.tools JEP 106• Bulk Data Operations for Collections JEP 107• Enhance Core Libraries with Lambda JEP 109• Charset improvements JEP 112• MS-SFU Kerberos 5 Extensions JEP 113• TLS Server name Indication (SNI) Extension JEP 114• AEAD Cipher Suites JEP 115 (Already available in earlier versions of the IBM SDK)• Remove the Annotation-Processing Tool (apt) JEP 117• Access to Parameter Names at Runtime JEP 118• javax.lang.model Implementation Backed by Core Reflection JEP 119• Repeating Annotations JEP 120• Stronger Algorithm for Password-Based Encryption JEP 121 (Generating 2048-bit DSA and Diffie-Hellman public key pairs is already supported in earlier versions of the IBM SDK)

• Enhance the Certificate Revocation-Checking API JEP 124• Lambda Expressions & Virtual Extension Methods JEP 126• Improve Locale Data Packaging and Adopt Unicode CLDR Data JEP 127• BCP 47 Locale Matching JEP 128• NSA Cipher Suites JEP 129 (Already available in earlier versions of the IBM SDK)• SHA-224 Message Digests JEP 130 (There is limited support for the SHA224 algorithm in earlier

versions of the IBM SDK)• PKCS#11 Crypto Provider for 64-bit Windows JEP 131• Unicode 6.2 JEP 133• Base64 Encoding & Decoding JEP 135• Enhance javac to Improve Build Speed JEP 139• Limited doPrivileged JEP 140• Date & Time API JEP 150• Launch JavaFX Applications JEP 153 (JavaFX is not supported by IBM SDK, Java Technology Edition,

Version 8)• Concurrency Updates JEP 155• Prepare for Modularization JEP 162• Leverage CPU Instructions for AES Cryptography JEP 164• JDBC 4.2 JEP 170

Note: You must use a supported JDBC driver. For more information, see “JDBC V4.2 incompatibledrivers” on page 100.

• Fence Intrinsics JEP 171• DocLint JEP 172• Nashorn JavaScript Engine JEP 174• Mechanical Checking of Caller-Sensitive Methods JEP 176• Optimize java.text.DecimalFormat.format JEP 177• Statically Linked JNI Libraries JEP 178• Document JDK API Support and Stability JEP 179


• Handle Frequent HashMap Collisions with Balanced Trees JEP 180• HTTP URL Permissions JEP 184• Restrict Fetching of External XML Resources JEP 185

For detailed information about these JEPS, see http://openjdk.java.net/jeps/0.

Service refresh 1Understand the changes that are implemented in service refresh 1 and later fix packs.

Skip to “Service refresh 1 fix pack 10” on page 17

Service refresh 1

This service refresh provides performance enhancements and serviceability improvements. There is alsoa change in default behavior for applets and Web Start applications.

• “Support for new operating systems (Linux only)” on page 16• “Change to applet or Web start application behavior (AIX, Linux, and Windows only)” on page 16• “Changes to InstallAnywhere unattended installation” on page 16• IBM J9 virtual machine updates:

– “Hardware compression acceleration is available on Little Endian Power Systems and IBM Z systems(Linux only)” on page 16

– “Runtime Instrumentation (RI) facility (Linux and AIX only)” on page 17– “Additional support for saving and restoring non-persistent shared caches (AIX, Linux, and z/OS

only)” on page 17– “New methods in the CUDA4J API (Linux only)” on page 17

Support for new operating systems (Linux only)

Support for Red Hat Enterprise Linux 7.1 is now available with this release. For a list of supportedoperating systems, see “Supported environments” on page 44.

Change to applet or Web start application behavior (AIX, Linux, and Windows only)

When an applet or Web Start application is started, a warning is displayed if a later release of theruntime environment is available that contains security updates. A user can choose to continue orblock the application from continuing. If the runtime environment is unable to determine whether alater release is available, a similar warning message is shown if the runtime environment is more thansix months old.

Changes to InstallAnywhere unattended installation

If you use an existing response file to install packages without user intervention, you must include theline LICENSE_ACCEPTED=TRUE in the response file to indicate that you have read the terms of thelicense agreement and confirm your acceptance. This line is automatically added if you create a newresponse file by using the attended installation process. For more information, see “Installing from anInstallAnywhere package (AIX and Linux only)” on page 51.

Hardware compression acceleration is available on Little Endian Power Systems and IBM Z systems(Linux only)

You can now use hardware compression acceleration on Little-Endian Power Systems and IBM Zsystems with the following operating systems:

• SUSE Linux Enterprise Server for System z® 12• Red Hat Enterprise Linux 7.1 for 64-bit Power Systems (Little Endian)

For more information, see “Enabling hardware compression acceleration (AIX, Linux only)” on page185.


http://openjdk.java.net/jeps/0

Runtime Instrumentation (RI) facility (Linux and AIX only)

The RI facility is a feature that is available in Power 8, zEC12, and later processors that offershardware support for collecting profiling information at run time. The process uses minimal resources.The JVM uses the RI facility by default on all platforms that support it. For more information aboutcontrolling the use of the RI facility, see -XX:[+|-]RuntimeInstrumentation (AIX, Linux only).

Note: Due to the current Linux kernel implementation, a user cannot reliably profile a Java applicationwhen RI is enabled on IBM Power systems. If you want to use system profilers like oprofile orperf, you must turn off the use of the RI facility.

Additional support for saving and restoring non-persistent shared caches (AIX, Linux, and z/OS only)

You can now create a snapshot file of a non-persistent shared cache. After the next IPL, the snapshotfile is used to restore a copy of the non-persistent cache into shared memory. When snapshot files areno longer required, you can remove them. The following suboptions have been added to the -Xsharedclasses command line option:

snapshotCacheCreates a snapshot file of an existing non-persistent shared cache.

restoreFromSnapshotRestores a new non-persistent shared cache from a snapshot file.

destroySnapshotDestroys a specific shared cache snapshot.

destroyAllSnapshotsDestroys all available shared cache snapshots.

For more information, see -Xshareclasses option.

New methods in the CUDA4J API (Linux only)

The CUDA4J API contains the following new methods. These methods enable you to specifyjava.lang.Object instances when you create a Parameters object or launch a kernel:

• In class CudaKernel: public final void launch(CudaGridgrid,java.lang.Object... parameters)

• In class CudaKernel.Parameters: Parameters(java.lang.Object... values)

The CUDA4J application programming interface (API) is used to develop applications that specifywhen to use the graphics processing unit (GPU) for application processing. For more information, seeThe CUDA4J application programming interface.

Service refresh 1 fix pack 10

This service refresh includes serviceability improvements.

• IBM J9 virtual machine changes (AIX, Linux, Windows, and z/OS):

– Invalidating AOT methods in the shared classes cache• Support for Windows 10

Invalidating AOT methods in the shared classes cacheYou can now invalidate failing AOT methods in the shared classes cache to prevent them being loadedwithout destroying and re-creating the cache. Three new -Xshareclasses suboptions are availableto find (findAotMethods), invalidate (invalidateAotMethods), or revalidate(revalidateAotMethods) these methods. For more information, see -Xshareclasses option.

Support for Windows 10Microsoft Windows 10 is now supported.


Service refresh 2Service refresh 2 introduces extended Remote Direct Memory Access (RDMA) support on Linux systems.This refresh and subsequent fix packs introduce serviceability improvements.


Service refresh 2

This service refresh provides extended Remote Direct Memory Access (RDMA) support on Linux systems,additional operating system support, and serviceability improvements.

• “AIX V7.2 support” on page 18• “z/OS V2.2 support” on page 18• “Support for KVM for z Systems V1.1 (Linux on IBM Z only)” on page 18• “RDMA support on IBM Little Endian Power platforms (Linux only)” on page 18• IBM J9 virtual machine changes:

– “Ability to check for the use of large pages” on page 18– “Time information added to Java core files” on page 18

• “Changes to the -Djava.security.debug property” on page 18• “New system property -Djdk.xml.max.xmlNameLimit” on page 18

AIX V7.2 supportThis release now supports AIX V7.2 on POWER7® and later processors.

z/OS V2.2 supportThis release now supports z/OS V2.2. For more information about supported hardware and operatingsystem software, see “Supported environments” on page 44.

Support for KVM for z Systems® V1.1 (Linux on IBM Z only)Support is now included for this virtualization software on IBM Z. For more information aboutsupported virtualization software, see “Support for virtualization software” on page 47.

RDMA support on IBM Little Endian Power platforms (Linux only)IBM provides options that allow Java applications to communicate over high performance RDMA-capable network infrastructures. This support, which includes Java Sockets over Remote DirectMemory Access (JSOR) and the jVerbs library, is now extended to Little Endian Power platforms. Formore information about these options, see Chapter 11, “Exploiting RDMA,” on page 193.

Ability to check for the use of large pagesYou can now check whether large pages are obtained for the object heap when they are requested bythe -Xlp:objectheap:pagesize option. The warn suboption generates a warning message if largepages are not obtained and allows the process to continue. Alternatively, you can use the strictsuboption to generate an error message and end the process if large pages are not obtained. For moreinformation, see -Xlp:objectheap option in the OpenJ9 user documentation.

Time information added to Java core filesJava dumps and system dumps now record the time that the dump was taken, the JVM start time inmilliseconds, and system nanotime. This time information can be obtained by using the DTFJ API andthe jdmpview tool. If your application records these values in log files, you can more easily correlatethe values with the information in the core file. For sample output, see TITLE, GPINFO, and ENVINFOsections in the OpenJ9 user documentation.

Changes to the -Djava.security.debug propertyThe -Djava.security.debug property is updated to include the missing access suboptions,which are codebase and permission. Three new suboptions are added to allow furthercustomization of the output, namely permname, permactions, and thread. For more informationabout these suboptions, see the output from running -Djava.security.debug=help.

New system property -Djdk.xml.max.xmlNameLimitIf your application takes untrusted XML, XSD or XSL files as input, you can enforce specific limitsduring JAXP processing to protect your application from malformed data. The -


Djdk.xml.max.xmlNameLimit option can be used to limit the length of XML names in XMLdocuments. For more information, see “Securing Java API for XML processing (JAXP) againstmalformed input” on page 265.


This fix pack contains changes for the IBM J9 virtual machine, including default settings and serviceabilityimprovements.

• “Changes to default settings for the IBM J9 virtual machine (AIX, Linux, and Windows systems)” onpage 19

• “Changes to class data sharing for 64-bit IBM J9 virtual machines” on page 19• “Change to default behavior for memory protection of a shared classes cache (Linux and Windows

only)” on page 19• “Command enhancements for the jdmpview dump viewer tool” on page 19• “Improved diagnostic content in Windows Java VM dumps” on page 19

Changes to default settings for the IBM J9 virtual machine (AIX, Linux, and Windows systems)When you run a 64-bit Java virtual machine (VM), compressed references are activated by default ifthe value of the -Xmx setting, which controls the maximum heap size, is at or below a specificthreshold. In this release, the threshold value is increased from 25 GB to 57 GB. The use ofcompressed references improves the performance of many applications because objects are smaller,resulting in less frequent garbage collection, and improved memory cache utilization. For moreinformation, see More effective heap usage using compressed references in the J9 VM reference.

Note: This change in default behavior is not supported for the metronome garbage collection policy,where the threshold remains at 25 GB.

Changes to class data sharing for 64-bit IBM J9 virtual machinesClass data sharing is not allowed between 64-bit and 64-bit compressed references VMs. For 64-bitshared classes caches, you can determine the compressed reference mode by looking at the output of-Xshareclasses:listAllCaches and cache statistics. A new API,getCacheCompressedRefsMode(), is also available in thecom.ibm.oti.shared.SharedClassCacheInfo class that returns the compressed referencemode. For more information, see Shared classes API reference. You can also use an IBM JVMTIextension to search for caches. For more information, see in the OpenJ9 user documentation.

Change to default behavior for memory protection of a shared classes cache (Linux and Windowsonly)

New options are available to protect partially filled pages in the shared classes cache. These optionsprevent accidental memory overwrites, which can cause cache corruption. After the startup phase, aVM now protects partially filled pages by default. For more information about these options and thedefault setting, see the mprotect sub option in -Xshareclasses option in the OpenJ9 userdocumentation.

Command enhancements for the jdmpview dump viewer tool

You can redirect output from a jdmpview command to a file, either overwriting the contents of thatfile or appending to it. You can also pipe the output from the command to the grep command, tosearch for lines that match a specified pattern. For more information, see Processing output in theOpenJ9 user documentation.

You can now use a z/OS TCB address as a parameter in the info thread command. For moreinformation about this command, see Session parameters in the OpenJ9 user documentation.

Improved diagnostic content in Windows Java VM dumpsAdditional dump flags are set in the Java VM when system dumps are triggered on the Windowsoperating system.

Windows system dump files are created with the following options set: MiniDumpWithFullMemory,MiniDumpWithHandleData, MiniDumpWithUnloadedModules,


MiniDumpWithFullMemoryInfo and MiniDumpWithThreadInfo. These options are equivalent tothe options that are set when a dump is created by using the Windows task manager.

Service refresh 3Read about the changes in service refresh 3 and subsequent fix packs.



Service refresh 3

This release includes new operating system support, serviceability improvements, Oracle fixes, and IBMfixes to the code base.

• “Support for offloading Java application processing to a graphics processing unit (GPU) on x86-64systems (Linux and Windows only)” on page 20

• “Changes to system requirements for offloading Java application processing to a graphics processingunit (GPU) on IBM POWER systems (Linux only)” on page 20

• “New operating system support for zEnterprise Data Compression” on page 20• “Ubuntu 16.04 LTS support” on page 20• IBM J9 virtual machine changes:

– “Changes to default settings for the IBM J9 virtual machine (z/OS only)” on page 20– “New -Xdump:suspendwith suboption for the -Xdump option syntax” on page 21– “Updates to the jdmpview tool” on page 21– “Changes to the shared classes cache generation number” on page 21

Support for offloading Java application processing to a graphics processing unit (GPU) on x86-64systems (Linux and Windows only)

Providing you meet certain hardware and software requirements, you can now offload Javaapplication processing to a GPU on x86-64 systems.

For more information, see: GPU system requirements.

Changes to system requirements for offloading Java application processing to a graphics processingunit (GPU) on IBM POWER® systems (Linux only)

Support is added for Red Hat Enterprise Linux (RHEL) 7.2 on IBM POWER 8 systems with the LittleEndian (LE) version of the SDK.

From this release, you must update your Compute Unified Device Architecture (CUDA) software fromCUDA 5.5 to the CUDA Toolkit 7.5.

For more information, see: GPU system requirements.

New operating system support for zEnterprise® Data CompressionRed Hat Enterprise Linux 7.2 for z Systems is now a supported operating system for zEnterprise DataCompression. For more information, see “Enabling hardware compression acceleration (AIX, Linuxonly)” on page 185.

Ubuntu 16.04 LTS supportSupport is now included for Ubuntu 16.04 LTS on x-86, IBM Little Endian Power Systems, and 64-bitIBM Z.

Changes to default settings for the IBM J9 virtual machine (z/OS only)When you run a 64-bit Java virtual machine (VM), compressed references are activated by default ifthe value of the -Xmx setting, which controls the maximum heap size, is at or below a specificthreshold. In this release, the threshold value is increased from 25 GB to 57 GB when you have theAPAR for OA49416 installed. The use of compressed references improves the performance of manyapplications because objects are smaller, resulting in less frequent garbage collection, and improved


memory cache utilization. For more information, see: More effective heap usage using compressedreferences in the J9 VM reference.

New -Xdump:suspendwith suboption for the -Xdump option syntaxYou can now use -Xdump:suspendwith to modify the signal that is used to suspend VM threadswhile a dump is being written. For more information about this option, see the -Xdump option in theOpenJ9 user documentation.

Updates to the jdmpview tool

jdmpview is a command-line dump viewer tool that you can use to examine the contents of systemdumps produced from the Java VM. This refresh provides the following updates to the jdmpview tool:

• You can now use the cmdfile command to run all of the commands in a file, line by line andsequentially. For more information about this command, see: jdmpview session parameters in theOpenJ9 user documentation.

• You can now use the history command to view your recent commands in the jdmpview tool. Youcan also specify and rerun a command from the command history. For more information about thisfeature, see: jdmpview session parameters in the OpenJ9 user documentation.

• You can now use the -append option to append new messages to the end of an existing -outfilewhen you run jdmpview in batch mode. For more information about this option, see: Starting inbatch mode in the OpenJ9 user documentation.

Changes to the shared classes cache generation numberThe format of classes that are stored in the shared classes cache is changed due to an Oracle securityupdate. As a result, the shared cache generation number is changed, which causes the JVM to createa new shared classes cache, rather than re-creating or reusing an existing cache. To save space, allexisting shared caches can be removed unless they are in use by an earlier release of IBM SDK, JavaTechnology Edition, Version 8. For more information about deleting a shared classes cache, see -Xshareclasses option in the OpenJ9 user documentation.


This release contains support for the EPoll selector for Java Sockets over RDMA (JSOR), updates to thejdmpview tool, changes in behavior, and Oracle and IBM fixes to the code base.

• “Support for the EPoll selector for JSOR” on page 21• “Change in ORB initialization process” on page 21• IBM J9 virtual machine changes:

– “New charsFrom, charsTo, and tokens commands in the jdmpview tool” on page 22

Support for the EPoll selector for JSOR

When you enable JSOR, you can now use the -Dcom.ibm.nio.rdma.EPollSelectorProvider=[true|false] property to specify whether theEPoll selector is used instead of the default Poll selector. The EPoll selector increases the number ofconcurrent clients that are supported in Java client and server testing from 200 to 1000, and reduceslatency in the channel selection process.

For more information about this property, see: “-Dcom.ibm.nio.rdma.EPollSelectorProvider (Linuxonly)” on page 225. For more information about the current limitations of this property, see: “JSORlimitations (Linux only)” on page 201.

Change in ORB initialization processWhen the Object Request Broker (ORB) initializes, ORB property settings are processed in a particularorder. The order of precedence is now changed. For more information, see “ORB initialization” onpage 283. In addition, a new system property is available to set the absolute path to the ORBproperties file. For more information about this property, see “-Dcom.ibm.CORBA.ORBPropertyFilePath” on page 311.


New charsFrom, charsTo, and tokens commands in the jdmpview tool

You can now use three new commands to specify, isolate, and display parts of the jdmpview tooloutput. Use charsFrom and charsTo to isolate specified words or characters on each resulting line,or use tokens to isolate specified tokens on each resulting line.

For more information, see: Processing output in the OpenJ9 user documentation.


This release contains the latest IBM fixes and the October 2016 Oracle Critical Patch Update (CPU).

For more information about the Oracle CPU, see Critical Patch Updates, Security Alerts and Third PartyBulletin on the Oracle website.

Service refresh 4Learn what's new in service refresh 4 and service refresh 4 fix pack 5.



Service refresh 4

This release contains the latest IBM fixes and the January 2017 Oracle Critical Patch Update (CPU).Support for Windows Server 2016 is also included at this refresh level.


This release comprises new improvements, Oracle fixes, and IBM® fixes to the code base, including thefollowing new features:

• “Jar files signed with MD5 are treated as unsigned” on page 22• IBM J9 virtual machine changes:

– “Specify Java options using a manifest file” on page 22– “-XX:[+|-]IgnoreUnrecognizedVMOptions” on page 22

Jar files signed with MD5 are treated as unsignedTo improve security, a new restriction is introduced in this refresh as part of the Oracle Critical PatchUpdate (CPU). Applications, including Applets or Web Start applications that use jar files that aresigned with MD5 are affected. These jar files are treated as unsigned. To address the issue, the jar filemust be re-signed with a stronger algorithm or key size. For more information about this change,which includes a short term workaround, see the Oracle JRE and JDK Cryptographic roadmap.

Specify Java options using a manifest fileJava options can now be specified by using a manifest file. In introducing this new capability, theorder in which options are passed to the VM at start up is changed. For more information, see:Specifying command-line options.

-XX:[+|-]IgnoreUnrecognizedVMOptionsUnrecognized top-level Java VM options can now be ignored using the -XX:+IgnoreUnrecognizedVMOptions option. This behavior prevents the VM failing on startup. Formore information, see: -XX:[+|-]IgnoreUnrecognizedVMOptions option.


The following operating systems are now supported:

• Red Hat Enterprise Linux (RHEL) 7.4• z/OS v2.3


https://www.oracle.com/technetwork/topics/security/alerts-086861.html?cm_mc_uid=47742250772614713635491&cm_mc_sid_50200000=1476777623#CriticalPatchUpdates

https://www.oracle.com/technetwork/topics/security/alerts-086861.html?cm_mc_uid=47742250772614713635491&cm_mc_sid_50200000=1476777623#CriticalPatchUpdates

https://java.com/en/jre-jdk-cryptoroadmap.html

Service refresh 5This refresh contains significant changes.

Skip to “Service refresh 5 fix pack 5” on page 26.
















Service refresh 5

This release includes the following new features:

• “Changes to the Java version output ” on page 24• IBM J9 virtual machine changes:

– “Managing the Java object heap when the JVM is idle (Linux only)” on page 24– “New garbage collection mode for reduced pause times” on page 24– “Ability for the JIT compiler to allocate memory higher than the 2 GB bar (z/OS only)” on page 24– “Tuning the shared classes cache” on page 24– “Improved MXBean compatibility” on page 24– “Change in the return value of the OperatingSystemMXBean.getProcessCpuTime() method” on page

25– “Improved monitoring of memory pools and garbage collection activity” on page 25– “-XX:[+|-]InterleaveMemory disabled by default (AIX, Linux, and Windows)” on page 25– “Late attach agents can redefine or retransform classes” on page 25– “Improved diagnostic information for VM hooks” on page 25– “Extra page of memory no longer required when using large page sizes (Linux on IBM Z and z/OS

only)” on page 25– “Default value for the initial Java heap size” on page 25– “-Xthr:<fastNotify|noFastNotify> option” on page 26– “Some -Xzero sub-options no longer supported” on page 26– “Attach API exceptions now begin with com.sun” on page 26– “Runtime Instrumentation facility turned off by default (AIX, Linux, and z/OS only)” on page 26– “Packed object evaluation technology removed” on page 26


Changes to the Java version outputThe output from the java -version and java -showversion command-line options and thejava.version system property are updated to contain the Oracle build number that the IBM SDK isbased on. For example, the string 1.8.0_141 indicates that the SDK is based on Oracle SE 1.8 classlibraries, update 141 (U141).

The output also contains changes to indicate the Version, Release, Modification, and Fix pack number(V.R.M.F). For example, Java(TM) SE Runtime Environment (build 8.0.5.0 ... reflectsVersion 8, Service Refresh 5.

Managing the Java object heap when the JVM is idle (Linux only)The following tuning options are available to manage the Java object heap when the JVM is idle:

• The -XX:IdleTuningMinIdleWaitTime option option controls how long the JVM must be idle beforethe other tuning options take effect.

• The -XX:[+|-]IdleTuningCompactOnIdle option option controls whether the garbage collector shouldcollect and compact the Java object heap, which improves the use of the heap.

• The -XX:[+|-]IdleTuningGcOnIdle option option controls whether free memory pages are released toreduce the memory footprint.

• The -XX:IdleTuningMinFreeHeapOnIdle option option can be used with -XX:+IdleTuningGcOnIdle to set the minimum amount of free memory that should remain in theobject heap.

This option applies only to Linux on x86-32 and x86-64 architectures when the GenerationalConcurrent (gencon) garbage collection policy is in use. This option is not effective if the objectheap is configured to use large pages.

New garbage collection mode for reduced pause timesA new mode is available that works with the Generational Concurrent (gencon) garbage collectionpolicy. When this mode is enabled, the JVM attempts to reduce GC pause-times for response-timesensitive, large heap applications, which improve throughput stability. The mode is controlled by the -Xgc:concurrentScavenge option, which requires a minimum of z/OS V2R3 (or z/OS V2R2 withAPAR OA51643) and z14 hardware, and is supported only for the 64-bit JVM. If the operating systemand hardware requirement is not met, the option is ignored.

Ability for the JIT compiler to allocate memory higher than the 2 GB bar (z/OS only)On z/OS V2R3 systems, residency mode for 64-bit programs (RMODE64) is enabled by default. Thisfeature allows the JIT to allocate executable code caches higher than the 2 GB memory bar. Thisbehavior is the default unless the -Xjit:disableRMODE64 option is specified on the command line.For more information, see disableRMODE64 (z/OS only).

Tuning the shared classes cacheYou can now create a soft limit on the contents of the shared classes cache that can beprogrammatically queried and adjusted by using an MXBean or modified by using command-lineoptions. The ability to monitor and tune the size of the cache can help you reduce footprint andstartup time when running multiple similar servers.

If you specify the -Xscmx option as in earlier releases, there is no change in behavior; this optionspecifies the size of a new shared class cache. However, if you also specify the new -XX:SharedCacheHardLimit option, the -Xscmx option specifies the soft maximum size of the newshared class cache, and the -XX:SharedCacheHardLimit option specifies the actual maximumsize. When the soft maximum limit is reached (the cache is soft full), data cannot be added to thecache unless you increase the soft maximum limit. For more information, see -Xscmx option and -XX:SharedCacheHardLimit option.

Improved MXBean compatibilityThe monitoring and management interface extensions of the java.lang.mangement APIs areupdated for improved compatibility with the following com.sun.management classes.

• GarbageCollectorMXBean• GarbageCollectionNotificationInfo


• GcInfo• OperatingSystemMXBean• UnixOperatingSystemMXBean

This compatibility includes class cast compatibility and implementation of the full set of APIsprovided by these com.sun.management classes. For more information, see the LanguageManagement API Reference.

If you rely on the output from the earlier interface extensions, the following new options are availableto revert to the behavior of that implementation:

• -Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns• -XX:[+|-]HeapManagementMXBeanCompatibility

For more information about these options, see “Change in the return value of theOperatingSystemMXBean.getProcessCpuTime() method” on page 25 and “Improved monitoring ofmemory pools and garbage collection activity” on page 25.

Change in the return value of the OperatingSystemMXBean.getProcessCpuTime() methodThe OperatingSystemMXBean.getProcessCpuTime() method is changed to return values innanoseconds instead of hundreds of nanoseconds, for compatibility with thecom.sun.management.OperatingSystemMXBean and UnixOperatingSystemMXBeaninterfaces. You can revert to the previous behavior by using the -Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns option system property.

Improved monitoring of memory pools and garbage collection activityTo help you understand the behavior of your application, enhancements are made to the IBM GarbageCollector and Memory Pool MXbeans. In earlier releases, memory pool information is aggregated andreported for the entire Java heap. In this release, more detailed information can be obtained aboutmemory pools and garbage collector activity for a garbage collection policy.

If your monitoring application is written to expect only one heap memory pool, or relies on thememory pool name Java heap, you can revert to the earlier implementation by using the -XX:+HeapManagementMXBeanCompatibility option. For more information about this option andthe new MemoryPool and GarbageCollector names that are provided, see -XX:[+|-]HeapManagementMXBeanCompatibility option.

-XX:[+|-]InterleaveMemory disabled by default (AIX, Linux, and Windows)Memory interleaving is now disabled by default. For more information, see -XX:[+|-]InterleaveMemoryoption (AIX, Linux, and Windows).

Late attach agents can redefine or retransform classesLate attach agents can redefine or retransform classes by default. You no longer need to use the -XX:+EnableHCR option, described in IBM SDK, Java Technology Edition, Version 8: Current news, toenable this function. For more information about the Java attach API, see Support for the Java AttachAPI in the J9 VM reference.

Improved diagnostic information for VM hooksNew tracepoints are added that are triggered when the callbacks for a VM hook, such as the classunload hook, exceed a time threshold. When triggered, a new section is produced in the Java dumpoutput. The tracepoints and Java dump provide enough information to identify the callbacks.

For more information about the HOOK section of a Java dump file, see Hook (HOOK) in the OpenJ9user documentation. For more information about tracepoints, see Tracing Java applications in the J9VM reference.

Extra page of memory no longer required when using large page sizes (Linux on IBM Z and z/OS only)You no longer have to allow for another page of memory when specifying an object heap size that is amultiple of a large page size. For more information, see Configuring large page memory allocation inthe J9 VM reference.

Default value for the initial Java heap sizeThe -Xms option sets the initial size of the Java heap. If this option is not set on the command line,the garbage collector sets an initial size of 8 MB by default. In earlier releases of the SDK, the garbage


https://www.ibm.com/support/pages/ibm-sdk-java-technology-edition-version-8-current-news

collector sets a default value of 4 MB. For more information about this setting, see -Xms option in theOpenJ9 user documentation.

-Xthr:<fastNotify|noFastNotify> optionYou can now use -Xthr:fastNotify to increase the throughput of an application, specifically whenregular usage of wait and notify causes a large number of threads to try to acquire a Java monitor.For more information, see -Xthr option in the OpenJ9 user documentation.

Some -Xzero sub-options no longer supportedThe j9zip, noj9zip, sharezip, and nosharezip sub-options are no longer supported. If youspecify these options, they are parsed but do nothing. For more information about these options, see -Xms option in the OpenJ9 user documentation.

Attach API exceptions now begin with com.sunAttach API exceptions are now prefixed with com.sun.tools.attach instead ofcom.ibm.tools.attach.

Runtime Instrumentation facility turned off by default (AIX, Linux, and z/OS only)In earlier updates, the RI facility was enabled by default on all platforms that support it. The RI facilityis now disabled by default. For more information, see -XX:[+|-]RuntimeInstrumentation in the OpenJ9user documentation.

Packed object evaluation technology removedThe packed object technology preview is no longer available.


This release contains the latest IBM fixes, the October 2017 Oracle Critical Patch Update (CPU), and thefollowing updates:Changes to the Java version information

Output from the java -version command is changed. Here is an example:

java version "1.8.0_151"Java(TM) SE Runtime Environment (build 8.0.5.5 - pxa6480sr5fp5-20171109_02(SR5 FP5))IBM J9 VM (build 2.9, JRE 1.8.0 Linux amd64-64 Compressed References 20171102_369060 (JIT enabled, AOT enabled)OpenJ9 - 7ade437OMR - 1b656cbIBM - 59c3d96)JCL - 20171109_01 based on Oracle jdk8u151-b12

The line starting with OpenJ9 replaces the lines J9VM and JIT in the output from earlier refreshes,because these components are now contributed to the Eclipse Foundation under the Eclipse OpenJ9project.

AIX supportFrom this refresh and for all future interim fixes (ifixes), the minimum supported level of AIX 6.1 isnow TL9. If you are on a lower maintenance level, the use of certaincom.ibm.language.management API extensions can result inProcessorUsageRetrievalException and GuestOSInfoRetrievalException exceptions.

Configuring the open file descriptor count for the Java processThe maximum number of open file descriptors in a process is controlled by the operating system. OnUNIX systems, you configure this number by setting the system hard limit or ulimit.

To avoid excessive resource usage during startup processing, the IBM SDK limits the maximum filedescriptor count for a Java process to 64K. The following rules apply:

• If your ulimit value is greater than 64K, the file descriptor count defaults to 64K.• If your ulimit value is less than 64K, the file descriptor count matches the ulimit value.

If your application needs a larger number of open file descriptors or the startup performance isaffected by the default limit that is set, you can configure the value by setting the followingenvironment variable:

export IBM_JAVA_FDLIMIT=file_descriptor_count


https://www.eclipse.org/openj9/


where file_descriptor_count is a value that is less than your system ulimit.


This release contains the latest IBM fixes and the January 2018 Oracle Critical Patch Update (CPU).

Security checkingFor the Eclipse OpenJ9 VM, to improve security, the security checks in the following APIs are nowenabled by default, when the SecurityManger is enabled:

• com.ibm.jvm.Dump.JavaDump()• com.ibm.jvm.Dump.HeapDump()• com.ibm.jvm.Dump.SnapDump()• com.ibm.jvm.Log.QueryOptions()• com.ibm.jvm.Log.SetOptions(String)• com.ibm.jvm.Trace.set(String)• com.ibm.jvm.Trace.snap()• com.ibm.jvm.Trace.suspend()• com.ibm.jvm.Trace.suspendThis()• com.ibm.jvm.Trace.resume()• com.ibm.jvm.Trace.resumeThis()• com.ibm.jvm.Trace.registerApplication(String, String[])• com.ibm.jvm.Trace.trace(<any parameters>)

You can disable security checking for these APIs by setting the following system properties on thecommand line:

• -Dcom.ibm.jvm.enableLegacyTraceSecurity=false• -Dcom.ibm.jvm.enableLegacyDumpSecurity=false• -Dcom.ibm.jvm.enableLegacyLogSecurity=false


This release contains the following changes in addition to the latest IBM fixes and the April 2018 OracleCritical Patch Update (CPU):Security checking

If a SecurityManager is being used with class data sharing and the running application is calling thecom.ibm.oti.shared.SharedClassUtilities APIs getSharedCacheInfo() ordestroySharedCache(), you must grant the code calling these APIs the appropriateSharedClassesNamedPermission. For example code, see Using a SecurityManager with class datasharing in the J9 VM reference.

New MXBean for controlling dump processingThe production of dump and trace diagnostic data can be controlled by the command-line options -Xdump at startup. If you want to change the dump configuration, you must restart the application. Toavoid the restart you can use the com.ibm.jvm.Dump applications processing interface (API) todynamically change the configuration. A new MXBean is now available that calls the Dump APImethods so that you can dynamically configure dump while remotely monitoring an application that isrunning in a remote server or container.For more information about the configuration options, see the API documentation.

Hardware supportIBM POWER9™ support was added in this refresh, but important fixes, including security fixes, havebeen made since. If you are using IBM POWER9, you should upgrade to at least fix pack 30.

Operating system supportThe following operating systems are now supported:


https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.api.80.doc/com.ibm.lang.management/index.html

• Red Hat Enterprise Linux (RHEL) 7.5• Ubuntu 18.04

Concurrent scavenge mode is now supported for Linux on IBM ZThe -Xgc:concurrentScavenge option is now supported on IBM z14 hardware with RHEL 7.5 andUbuntu 18.04 at the following levels and configurations:Operating systems

• RHEL 7.5 (minimum kernel level 4.14)• Ubuntu 18.04

Hypervisors

• KVM solutions with QEMU 2.10 or later and a minimum host kernel level 4.12

New environment variable to switch between ICONV and Java converters on z/OSBy default, the ICONV utility is used to convert characters from one code page set to another.However, in some instances ICONV converts to a character that is not recognized on certainplatforms. For example, ICONV converts the EBCDIC code x'25' (line feed) to Unicode '\u0085'(next line), which causes problems for XML parsers.The following environment variable can be set to select the Java converter:

USE_JAVA_CONV=1

By default, the environment variable is set to USE_JAVA_CONV=0, which uses the ICONV utility.


Fix pack 16 includes the following new features in the Eclipse OpenJ9 virtual machine:

Extended support for the idle tuning featureThe idle tuning feature in the Eclipse OpenJ9 VM keeps your memory footprint small by releasingunused memory back to the operating system. This feature is now available on Linux for IBM POWER™

and IBM Z® in addition to x86 architectures when used with the generational concurrent (gencon)garbage collection policy. For more information about this feature, see the following command-lineoptions (in the OpenJ9 user documentation), which control this behavior:

• -XX:[+|-]IdleTuningCompactOnIdle• -XX:[+|-]IdleTuningGcOnIdle• -XX:[+|-]IdleTuningMinFreeHeapOnIdle• -XX:[+|-]IdleTuningMinIdleWaitTime

Change to the default maximum Java heap size for applications that run in a containerWhen using container technology, applications are typically run on their own and do not need tocompete for memory. In this update, changes are introduced to detect when the OpenJ9 VM isrunning inside a container. If your application is running in a container and you want the VM toallocate a larger fraction of memory to the Java heap, you can now set the -XX:+UseContainerSupport option on the command line to obtain a larger percentage of availablememory. The percentage allocated depends on the container memory limit. For more information, see-XX:[+|-]UseContainerSupport in the OpenJ9 user documentation.


Fix pack 17 includes the following new features in the Eclipse OpenJ9 virtual machine:

New garbage collection policyA new policy is introduced in the Eclipse OpenJ9 VM that expands the Java heap in the normal way,but does not reclaim memory through garbage collection operations. This mode is useful for short-lived applications where sufficient memory exists to satisfy the runtime requirements. For moreinformation, see -Xgcpolicy:nogc in the OpenJ9 user documentation.


Specifying the maximum Java heap size as a percentage valueThe OpenJ9 VM now supports setting the heap size as a percentage of the physical memory. Thefollowing Oracle HotSpot options are recognized and can be set for the VM:

• -XX:InitialRAMPercentage (OpenJ9 user documentation)• -XX:MaxRAMPercentage (OpenJ9 user documentation)

If your application is running in a container and you have specified -XX:+UseContainerSupport,both the default heap size for containers and the values for these new options are based on theavailable container memory.

Shared classes support for nested jar filesChanges are made to the com.ibm.oti.shared application programming interface to supportnested jar files.


This release contains the latest IBM fixes and the July 2018 Oracle Critical Patch Update (CPU).


This release contains the latest IBM fixes and the October 2018 Oracle Critical Patch Update (CPU).

The documentation to support IBM SDK, Java Technology Edition Version 8 is changed in this refresh. Inaddition to this SDK guide, and the supporting J9 VM reference, the IBM Knowledge Center now containsthe Eclipse OpenJ9 VM user documentation. Some material previously found in the J9 VM reference isremoved to avoid duplication. Redirection is in place to minimize the impact of this change.

For any new changes to the Eclipse OpenJ9 VM, see the following release notes in the OpenJ9 userdocumentation:

• Version 0.10.0


Fix pack 26 includes the following new features in the Eclipse OpenJ9 virtual machine, as described in theOpenJ9 user documentation:New class data sharing suboptions

The -Xshareclasses:bootClassesOnly option disables caching of classes that are loaded bynon-bootstrap class loaders. This suboption also enables the nonfatal suboption, which allows theVM to start even if there was an error creating the shared classes cache.

The -Xshareclasses:fatal option prevents the VM from starting if there was an error creating theshared classes cache. You might want to enable this suboption when using the -Xshareclasses:bootClassesOnly suboption, to troubleshoot problems when creating the cache.

Container awareness in the OpenJ9 VM is now enabled by default

When using container technology, applications are typically run on their own and do not need tocompete for memory. If the VM detects that it is running in a container environment, and a memorylimit for the container is set, the VM automatically adjusts the maximum default Java heap size.

In earlier releases, this behavior was enabled by setting the -XX:+UseContainerSupport option.This setting is now the default.

Pause-less garbage collection mode is now available on Linux x86 platforms

Pause-less garbage collection mode is aimed at large heap, response-time sensitive applications.When enabled, the VM attempts to reduce GC pause times. In earlier releases, pause-less garbagecollection mode (-Xgc:concurrentScavenge) was available only on IBM z14 hardware. This modeis now available on 64-bit x86 Linux platforms.

Note: The Generational Concurrent (gencon) garbage collection policy must be used. (This is thedefault policy.)


You can now restrict identity hash codes to non-negative valuesOpenJ9 allows both positive and negative identity hashcodes, which can be problematic if yourprogram (incorrectly) assumes hashcodes can only be positive. However, you can now use the -XX:+PositiveIdentityHash option to limit identity hash codes to non-negative values. Becauselimiting identity hash codes to non-negative values can have an impact on the performance of hash-intensive operations, this option is not enabled by default.

Support for OpenJDK HotSpot optionsFor compatibility, the following OpenJDK Hotspot options are now supported by OpenJ9:

• -XX:MaxHeapSize, which is equivalent to the -Xmx option.• -XX:InitialHeapSize, which is equivalent to the -Xms option.

IBM_JAVA_OPTIONS is deprecatedThe IBM_JAVA_OPTIONS environment variable is deprecated. Instead, use the newOPENJ9_JAVA_OPTIONS environment variable.


Fix pack 27 includes the following new features in the Eclipse OpenJ9 virtual machine, as described in theOpenJ9 user documentation:Improved flexibility for managing the size of the JIT code cache

The JIT code cache stores the native code of compiled Java methods. By default, the size of the codecache is 256 MB for a 64-bit VM and 64 MB for a 31/32-bit VM. In earlier releases the size of the codecache could be increased from the default value by using the -Xcodecachetotal command-lineoption. In this release the size can also be decreased by using this option, with a minimum size of 2MB. The size of the JIT code cache also affects the size of the JIT data cache, which holds metadataabout compiled methods. If you use the -Xcodecachetotal option to manage the size of the codecache, the size of the data cache is adjusted by the same proportion.


Fix pack 30 includes the following new features in the Eclipse OpenJ9 virtual machine, as described in theOpenJ9 user documentation:Improved support for pause-less garbage collection

Concurrent scavenge mode (-Xgc:concurrentScavenge) is now supported on 64-bit Windowsoperating systems.

Idle tuning is enabled by default when the VM runs in a docker container

In an earlier release, a set of idle-tuning options were introduced to manage the footprint of the Javaheap when the OpenJ9 VM is in an idle state. The following two options are now enabled by defaultwhen the OpenJ9 VM detects that it is running in a container and that the VM has entered an idlestate:

• -XX:[+|-]IdleTuningGcOnIdle, which runs a garbage collection cycle and releases freememory pages back to the operating system.

• -XX:[+|-]IdleTuningCompactOnIdle, which compacts the object heap to reducefragmentation.

By default, the VM is checked every 180 seconds to detect an idle status. To control the wait timebetween checks, use the -XX:[+|-]IdleTuningMinIdleWaitTime option (OpenJ9 user documentation).To turn off idle detection, set the value to 0.

Changes to default shared classes cache directory permissions (not Windows)If you do not use the cachDirPerm suboption to specify permissions for a shared classes cachedirectory, and the cache directory is not the /tmp/javasharedresources default, the followingchanges apply:

• When creating a new cache directory, the default permissions are now stricter.


• If the cache directory already exists, permissions are now unchanged (previously, when a cachewas opened using this directory, the permissions would be set to 0777).

For more information, see -Xshareclasses in the OpenJ9 user documentation.


Fix pack 31 includes the following new features in the Eclipse OpenJ9 virtual machine, as described in theOpenJ9 user documentation:Better diagnostic information for Linux systems that implement control groups

If you use control groups (cgroups) to manage resources on Linux systems, information about CPUand memory limits is now recorded in a Java dump file. This information is particularly important forapplications that run in Docker containers, because when resource limits are set inside a container,the Docker Engine relies on cgroups to enforce the settings. If you are getting a JavaOutOfMemoryError error because a container limit has been set on the amount of memory available toan application and this allocation is not sufficient, you can diagnose this problem from the Java dumpfile. You can find the cgroup information in the ENVINFO section.

Writing a Java dump to STDOUT or STDERRYou can now write a Java dump file to STDOUT or STDERR by using the -Xdump command-lineoption.

Improved support for pause-less garbage collectionConcurrent scavenge mode is now supported on the following platforms:

• Linux on IBM POWER LE• AIX


Fix pack 35 includes the following updates:Support for the new Japanese era

Support is added for the new era name, Reiwa. For more information about the changes, seeJapanese era changes for the IBM SDK, Java Technology Edition.

Support for more operating system versionsSupport is added for Red Hat Enterprise Linux (RHEL) version 8 and Windows Server 2019. For lists ofsupported operating systems, see “Supported environments” on page 44.

Change to the default native stack size on 64-bit z/OSThe default stack size for operating system threads on 64-bit z/OS is changed from 384 KB to theoperating system minimum of 1 MB. For more information about this setting, see -Xmso.

Fix pack 35 also includes the following new features and enhancements in the Eclipse OpenJ9 virtualmachine, as described in the OpenJ9 user documentation:New option for ignoring or reporting unrecognized -XX: options

By default, unrecognized -XX: command-line options are ignored, which prevents an applicationfailing to start. You can now use -XX:-IgnoreUnrecognizedXXColonOptions to turn off thisbehavior, so that unrecognized -XX: options are reported instead. For more information, see -XX:[+|-]IgnoreUnrecognizedXXColonOptions in the OpenJ9 user documentation.

Writing a Java dump to STDOUT or STDERR

You can now write a Java dump file to STDOUT or STDERR by using the -Xdump command-line option.See Writing to STDOUT/STDERR in the OpenJ9 user documentation for details.

Better diagnostic information for Linux systems that implement control groups

If you use control groups (cgroups) to manage resources on Linux systems, information about CPUand memory limits is now recorded in a Java dump file. This information is particularly important forapplications that run in Docker containers, because when resource limits are set inside a container,the Docker Engine relies on cgroups to enforce the settings. If you are getting a JavaOutOfMemoryError error because a container limit has been set on the amount of memory available


https://www-01.ibm.com/support/docview.wss?uid=ibm10881392

to an application and this allocation is not sufficient, you can diagnose this problem from the Javadump file. You can find the cgroup information in the ENVINFO section. For sample output, see Javadump (ENVINFO) in the OpenJ9 user documentation.

Improved support for pause-less garbage collection

Concurrent scavenge mode (-Xgc:concurrentScavenge) is now supported on AIX and Linux onPOWER.

New OpenJ9 option to prevent a network query being used to determine host name and IP address

By default, a network query is used to determine the host name and IP address for troubleshootingpurposes. To avoid your program waiting to time out if a nameserver cannot be contacted, you cannow prevent the query from being performed. For more information, see -XX:[+|-]ReadIPInfoForRASin the OpenJ9 user documentation.

New experimental option to improve the performance of JVMTI watched fieldsThe -XX:[+|-]JITInlineWatches option (OpenJ9 user documentation) is introduced in this release.When enabled, the option turns on experimental JIT operations that are intended to improve theperformance of JVMTI watched fields. This option is currently supported only on x86 platforms(Windows, macOS, and Linux).

Change to the default native stack size on 64-bit z/OSThe default stack size for operating system threads on 64-bit z/OS is changed from 384 KB to 1 MB.For more information about this setting, see -Xmso.


Fix pack 36 includes the following new features and changes in the Eclipse OpenJ9 virtual machine, asdescribed in the OpenJ9 user documentation:

Changes to the shared classes cache generation number

On all platforms, the format of classes that are stored in the shared classes cache is changed, whichcauses the JVM to create a new shared classes cache, rather than re-creating or reusing an existingcache. To save space, all existing shared caches can be removed unless they are in use by an earlierrelease.



Improved platform support for pause-less garbage collection

Support for concurrent scavenge mode is now extended to z/OS and Linux on IBM Z.

Support for Transparent HugePage

The VM now supports the allocation of huge pages on Linux when you use the madvise setting. Toenable this feature, specify the -XX:+TransparentHugePage option on the command line whenyou start your application.

-XX:[+|-]JITInlineWatches option supported on z/OS and Linux on IBM Z, and enabled by default

This option, introduced in an earlier release, turns on experimental JIT operations that are intended toimprove the performance of JVMTI watched fields. The option is now supported on z/OS and Linux onIBM Z, and is enabled by default.

Support for OpenJDK HotSpot options

The -XX:OnOutOfMemoryError OpenJDK Hotspot option is now supported for compatibility.

Removal of -Xdiagnosticscollector option

This option was redundant and has now been removed.



Fix pack 40 includes the following updates:JDWP implementation replaced with OpenJDK equivalent

JDWP is used to debug Java applications, for example as mentioned in “Standard options” on page84, and Java Virtual Machine Tool Interface in the OpenJ9 documentation. The previousimplementation of JDWP is now replaced with the OpenJDK equivalent. This change removes an issuewith the previous implementation and increases alignment with open source software. Because thesetwo implementations are different, the options that are available are also different. These options nolonger exist: version, src, log, and trace. These options are new: launch, onthrow,onuncaught, mutf8, and quiet. For more information about the options for the new JDWPimplementation, see the command-line help:

java -agentlib:jdwp=help

Fix pack 40 also includes the following new features and changes in the Eclipse OpenJ9 virtual machine,as described in the OpenJ9 user documentation:Automatically setting an initial heap size

The VM can now learn and set an appropriate initial heap size for an application as an alternative to auser manually sizing and setting an -Xms value. The VM records the size of the heap when startupprocessing ends, writing this data to the shared classes cache. An average value is set over a fewrestarts, helping to ensure that the value used for the initial heap size is as accurate as possible. Theheap size recorded is specific to the application command line, therefore a different hint is stored forevery unique command line.

To turn on this behavior, set the -XX:+UseGCStartupHints option on the command line when youstart your application.

Heuristics for compaction during idle GCThe VM now automatically compacts the heap when certain triggers are met during idle garbagecollection. As a result of this change, the -XX:[+|-]IdleTuningCompactOnIdle option is deprecated.

Change in behavior of -XX:IdleTuningCompactOnIdleThe -XX:[+|-]IdleTuningCompactOnIdle option is now no longer effective when the -XX:+IdleTuningGcOnIdle option is not specified.

Internal interface changesAttach API internal interfaces are changed slightly, affecting the SDK's internal class library and thetools.jar and healthcenter.jar files.

• If an application uses a private copy of the tools.jar file from an earlier release, the applicationmight be unable to use the attach API in this release because the Java classes do not match. Usethe tools.jar file from this release instead.

• Similarly, the healthcenter.jar file from this release is not compatible with earlier releases.



Automatic setting of initial heap size is enabled by defaultThe -XX:[+|-]UseGCStartupHints option, which, when enabled, turned on the automaticlearning and setting of an appropriate heap size for an application, is now enabled by default.

Option to share VM anonymous classesIn earlier releases, anonymous classes, those created by Unsafe.defineAnonymousClass, werenot stored in the shared classes cache. These classes are now stored there by default, which meansthey are available for ahead-of-time (AOT) compilation, potentially improving startup performance. Anew option, -XX:[+|-]ShareAnonymousClasses, is introduced that enables you to stopanonymous classes being stored in the shared classes cache.


Performance improvements for JVMTI watched fields on Power SystemsThe -XX:[+|-]JITInlineWatches option, which turns on JIT operations to improve theperformance of JVMTI watched fields, is now also supported on AIX and Linux on Power Systems.

Linux on x86: Support for Transparent Huge Pages (THP)When you use the madvise (/sys/kernel/mm/transparent_hugepage/enabled) setting onLinux on x86 systems, THP is now enabled by default. To disable this feature, set -XX:-TransparentHugePage on the command line when you start your application. The THP setting onother systems remains disabled by default when you use madvise, but can be enabled by setting -XX:+TransparentHugePage.

Changes to the shared classes cache generation numberThe format of classes that are stored in the shared classes cache is changed, which causes the JVM tocreate a new shared classes cache rather than re-creating or reusing an existing cache. To savespace, you can remove all existing shared caches unless they are in use by an earlier release. As aresult of the format change, a layer column now appears in the output of the -Xshareclasses:listAllCaches option. This change is to support a future enhancement.

Service refresh 6Read about the changes in service refresh 6, and subsequent fix packs.




Service refresh 6

This release contains the latest IBM fixes, the most recent Oracle Critical Patch Update (CPU), and thefollowing new features:

• IBM security features, as listed in Security guide.• Features from the latest Eclipse OpenJ9 release, as listed in OpenJ9 user documentation.• Other SDK features, as listed in the following section.

Other SDK featuresNew hardware and operating system support

This release supports IBM z15 hardware, and the following operating systems:

• Red Hat Enterprise Linux 7.7• SUSE Linux Enterprise Server 15 SP1• z/OS 2.4


Fix pack 5 contains the latest IBM fixes, the most recent Oracle Critical Patch Update (CPU), and thefollowing new features:

• IBM security features, as listed in Security guide• Features from the latest Eclipse OpenJ9 release, as listed in OpenJ9 user documentation• Other OpenJ9 features, as listed in the following section

Other OpenJ9 featuresNew shared classes cache suboptions for layered caches (64-bit only)

The following new suboptions are available for creating layered caches, where a cache builds onanother cache with the same name. You can use these suboptions to save space when you build aDocker container, for example.

• createLayer


• layer=<number> (see this section for general information about layered caches)• printTopLayerStats• destroyAllLayers

New shared classes cache suboption to skip disk space checking

When the OpenJ9 VM creates a persistent shared classes cache, it checks that there is sufficientdisk space available on the file system. For file systems that do not support the checking of freespace, you can set the -Xshareclasses:noPersistentDiskSpaceCheck option, whichcauses the VM to skip the space checking operation. If there isn't enough disk space availablewhen the cache is written, a SIGBUS or SIGSEGV signal occurs and the VM ends. For moreinformation, see the -Xshareclasses:noPersistentDiskSpaceCheck option.

Option to share 'Unsafe' classesClasses that are created by using the Unsafe.defineClass class are now stored by default inthe shared classes cache. You can use the -XX:-ShareUnsafeClasses option to change thedefault behavior. For more information, see -XX:[+|-]ShareUnsafeClasses.

Option to record class relationships in the verifierYou can use the new command line option -XX:+ClassRelationshipVerifier to record classrelationships in the verifier, which avoids unnecessary class loading and reduces VM startup time.This change is a new approach to bytecode verification that delays the validation of therelationships between classes until the classes must be loaded to run a program, thus loadingonly those classes that are required. For more information, see -XX:[+|-]ClassRelationshipVerifier.


Fix pack 7 includes the latest IBM fixes and features from the latest Eclipse OpenJ9 release, as describedin the OpenJ9 user documentation.


Fix pack 10 contains the latest IBM fixes, the most recent Oracle Critical Patch Update (CPU), and thefollowing new features:

• IBM security features, as listed in Security guide• Features from the latest Eclipse OpenJ9 releases, as listed in the OpenJ9 user documentation.• Other SDK features, as listed in the following section.

Other SDK featuresNew operating system support

This release supports the following operating systems:

• Red Hat Enterprise Linux 7.8 and 8.2• Ubuntu 20.04 LTS

Signal handling implementation changeThe IBM signal handling implementation is replaced in this release with the OpenJDKimplementation. As a result, the -Dcom.ibm.signalhandling.ignoreLogoff systemproperty command-line option is now ignored. For more information, see “-Dcom.ibm.signalhandling.ignoreLogoff (Windows only)” on page 328.


ConventionsThe install directory, library directory, and VM directory are different depending on the operating system.In this documentation, these directories are referred to as variable names. The actual directory locationfor each platform is indicated in this topic.

In the following directories, <version> is a single-digit version number that represents the productversion, and <release> is a single-digit version number that represents the product release. <arch> is oneof the following Linux architectures:

Table 2. Linux architecture values for directories

Linux architecture Value of <arch>

x-86 32-bit i386

AMD 64-bit x86_64 (install_dir) or amd64 (lib_dir)

PPC 32-bit ppc

PPC 64-bit ppc64

PPC 64-bit (Little Endian) ppc64le

IBM Z 31-bit s390

IBM Z 64-bit s390x

install_dir

The installation directory is referred to as install_dir in this documentation. Where the SDK isinstalled by using an installer program, the following default installation directories are used:

• AIX: /usr/java<version>[_64]/• Linux: /opt/ibm/java-<arch>-<version><release>/• Windows: C:\Program Files\IBM\Java<version><release>\• z/OS: /usr/lpp/java/J<version>.<release>[_64]/

For example:

• AIX: /usr/java8_64/• Linux: /opt/ibm/java-ppc64le-80/• Windows: C:\Program Files\IBM\Java80\• z/OS: /usr/lpp/java/J8.0_64/

If an installer is not used, install_dir refers to the location that is chosen for the SDK programfiles. For example, if the SDK is embedded in an IBM product, refer to the documentation for thatproduct to determine the directory location.

lib_dirThe Java library directory is referred to as lib_dir in this documentation. The library directory is asfollows:

• AIX: install_dir/jre/lib/ppc[64]/• Linux: install_dir/jre/lib/<arch>/• z/OS: install_dir/jre/lib/s390[x]• Windows: install_dir\jre\bin\

vm_dirThe Eclipse OpenJ9 virtual machine (VM) directory is referred to as vm_dir in the productdocumentation. The VM directory is as follows:


• AIX: install_dir/jre/lib/ppc[64]/default• Linux: install_dir/jre/lib/<arch>/default• z/OS: install_dir/jre/lib/s390[x]/default• Windows: install_dir\jre\bin\default

If you are using compressed references, the vm_dir points to the compressedrefs subdirectory, notthe default subdirectory on the same path.

Other sources of informationYou can obtain additional information about the latest tools, Java documentation, and the IBM softwaredeveloper kits (SDK) by following the links.

• The SDK for AIX, Linux, and z/OS can be downloaded from the

Java SDK developer center• To download IBM SDK documentation as an Eclipse plug-in, or in PDF format for printing, see the

"Downloadable documentation" topic alongside the user guides.• For any late breaking information that is not in this guide, see:


• For API documentation that has been generated from the IBM SDK, see:

API documentation• For articles, tutorials and other technical resources about Java Technology, see IBM developerWorks®

at:

https://www.ibm.com/developerworks/java/• For Java documentation produced by Oracle, see:

https://www.oracle.com/technetwork/java/index.html

AccessibilityAccessibility features help users who have a disability, such as restricted mobility or limited vision, to useinformation technology products successfully.

IBM strives to provide products with usable access for everyone, regardless of age or ability.

For example, you can operate IBM SDK, Java Technology Edition without a mouse, by using only thekeyboard. You can also use a screen reader, such as JAWS for Windows, by configuring your runtimeenvironment to use Java accessibility features such as the Oracle Java Access Bridge . For moreinformation, see “Enabling Java accessibility support” on page 60.

Issues that affect accessibility are included in “Known issues and limitations” on page 99.

Keyboard navigation

This product uses standard Microsoft Windows navigation keys.

If you want to use keyboard navigation, see “Default Swing key bindings” on page 65 for a description ofuseful keystrokes for Swing applications.

IBM and accessibility

See the IBM Human Ability and Accessibility Center for more information about the commitment that IBMhas to accessibility.


https://developer.ibm.com/javasdk/


https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.api.80.doc/api_overview.html

https://www.ibm.com/developerworks/java/

https://www.oracle.com/technetwork/java/index.html

https://www.ibm.com/able

Chapter 2. MigratingThis version of the SDK and runtime environment contains changes compared to earlier releases. If youare migrating from an earlier version of the SDK or runtime environment, you should read this section ofthe User Guide to determine whether any changes might be needed to your applications.

Migrating from earlier releases of the IBM SDK, Java Technology EditionConsiderations when migrating from earlier releases of the IBM SDK, Java Technology Edition.

This release contains many new features and functions compared with earlier releases, which mightrequire careful planning. For an overview, read the “What's new” on page 12 section.

If you are migrating from IBM SDK, Java Technology Edition Version 7 or Version 7 Release 1, thefollowing changes apply:

• For z/OS, the JRIO component was deprecated in IBM SDK, Java Technology Edition Version 7 and isremoved from this release. Instead, use the record I/O facilities that are provided in the JZOScomponent. For more information about JZOS, see: Java Batch Launcher and Toolkit for z/OS.

• The system property jdk.map.althashing.threshold is no longer available with this releasebecause the alternative hashing algorithm for hashed maps is no longer used. The alternative hashingalgorithm was introduced in earlier releases of Java to improve the performance ofjava.util.HashMap under certain conditions. This implementation is improved in this release byusing balanced trees rather than linked lists to store map entries. Classes WeakHashMap andHashtable revert to the behavior before the alternative hashing algorithm. However, changes to theclasses HashMap and HashSet can change the iteration order of items that are returned from hashedmaps.

• The Annotation Processing Tool is no longer supplied with this release. The tool was deprecated inVersion 7, and is superseded by the Pluggable Annotation Processing API (JSR269). If you useannotation processing, you must migrate to this new facility, which was introduced in Version 6. Formore information, see https://docs.oracle.com/javase/7/docs/technotes/guides/apt/index.html.

• The IBM accessibility feature, JawBridge, is no longer supported in this release. If you want to use ascreen reader, such as JAWS for Windows, configure your runtime environment to use the Oracle JavaAccess Bridge. For more information, see “Enabling Java accessibility support” on page 60.

• The Nashorn Javascript Engine replaces the Rhino implementation in this release. The Rhinojavascript.jar file is removed from the jre/lib/ext directory.

• On AIX, the Common Desktop Environment (CDE) color palette now supports high color settings. As aresult, the default SystemColor settings for the Abstract Windows Toolkit (AWT) are now the same asMotif Toolkit on earlier releases. To revert to the earlier AWT color palette settings, set theibm.awt.mediumColor system property to true. For more information, see -Dibm.awt.mediumColoroption.

• The system property com.ibm.IgnoreMalformedInput is removed in this release because it isapplicable only to IO converters, which are no longer available in Java SE 8.

• The system property ibm.stream.nio is removed in this release. The function of this property was toenable the use of NIO converters by default instead of IO converters. However, IO converters are nolonger available in Java SE 8 and therefore the property is redundant.

• From this release, the ORB automatically manages the number of concurrent connections to the serverendpoint. This change in behavior can cause some issues, which are detailed in “Autonomic connectionmanagement issues” on page 304.

• From service refresh 5 on z/OS, there is a new minimum hardware requirement of IBMSystem z9 or newer. The older z800 and z900 systems are no longer supported.


https://docs.oracle.com/javase/7/docs/technotes/guides/apt/index.html

• Linux: To satisfy a dynamic linking dependency, the standard C++ library, libstdc++.so.6,must be installed.

• In service refresh 5, the following changes apply to the IBM J9 virtual machine:

– The default value for the -Xloaminimum option is changed from 0 to 0.01. This setting allocates aminimum tenure space of 1% to the large object area (LOA) instead of 0%.

– Enhancements are made to the IBM Garbage Collector and Memory Pool MXBeans to provide moredetailed information about Garbage collection activity and associated memory pools. If yourmonitoring application is written to expect only one heap memory pool, or relies on the memory poolname Java heap, you can revert to the earlier implementation by using the -XX:+HeapManagementMXBeanCompatibility option. For more information about this option andthe new MemoryPool and GarbageCollector names that are provided, see -XX:[+|-]HeapManagementMXBeanCompatibility.

– The OperatingSystemMXBean.getProcessCpuTime() method is changed to return values innanoseconds instead of hundreds of nanoseconds. If your application uses this method, eithermodify the application or revert to the previous behavior by using the -Dcom.ibm.lang.management.OperatingSystemMXBean.isCpuTime100ns system property.

– The Runtime Instrumentation facility, available in Power 8, zEC12, and later processors is disabled bydefault. This facility can be enabled with the -XX:+RuntimeInstrumentation option.

• The minimum supported maintenance level for AIX V6.1 is now TL9.

• The default size of a shared class cache is now 300 MB, with exceptions for persistent cacheswith less than 6 GB of free disk space, and non-persistent caches on Linux. For more information, see -Xshareclasses.

• AIX, Linux, and z/OS: The ALT-key no longer highlights the first menu in the active window of the userinterface unless your application uses a Windows Look and Feel(com.sun.java.swing.plaf.windows.WindowsLookAndFeel).

• The character set name IBM1047_LF is changed to x-IBM1047_LF.

The following deprecation statements apply to this release:

• The IBM XML implementation is deprecated and will be replaced by the Oracle XML implementation in afuture release.

• The -Xgc:splitheap option is deprecated and will be removed from a future release of the EclipseOpenJ9 VM.

• The -Xfastresolve option is deprecated and will be removed from a future release of the EclipseOpenJ9 VM.

• The -Xlp option is deprecated and will be removed from a future release of the Eclipse OpenJ9 VM.Instead, use the -Xlp:objectheap option to allocate the Java object heap by using large page sizesand the -Xlp:codecache option to allocate the JIT code cache by using large page sizes.

• The IBM_JAVA_OPTIONS environment variable is deprecated and will be removed from afuture release of the Eclipse OpenJ9 VM. Instead, use the OPENJ9_JAVA_OPTIONS environmentvariable.

If you are migrating from a release before Version 7, read the topic entitled Migrating from earlier releasesin the appropriate platform user guide for Version 7. These user guides can be found at the followingpage: IBM SDK, Java Technology Edition, Version 7.


https://www.ibm.com/support/knowledgecenter/SSYKE2_7.0.0/welcome/welcome_javasdk_version.html

Version compatibilityIn general, any applet or application that ran with a previous version of the SDK should run correctly withthis release. Classes that are compiled with this release are not guaranteed to work on previous releases.

The following exceptions apply to applications written and compiled under earlier releases of the SDK:

• The underlying operating system or hardware introduces a change that requires the application to berecompiled.

• The application has added a method name that clashes with the name of a new method, introduced inthis release.

• The application uses an API that was deprecated before this release, and that API is now removed.

The 32-bit Windows edition of IBM SDK, Java Technology Edition is built with Microsoft Visual Studio .NET2003.

For information about compatibility issues between releases, see the Oracle website at: https://www.oracle.com/technetwork/java/javase/8-compatibility-guide-2156366.html

Chapter 2. Migrating 41

https://www.oracle.com/technetwork/java/javase/8-compatibility-guide-2156366.html

https://www.oracle.com/technetwork/java/javase/8-compatibility-guide-2156366.html

Chapter 3. Installing the SDKThe installation method depends on your operating system.

AIX

On AIX systems, you can install the SDK from an InstallAnywhere package, or from an installp package.InstallAnywhere package

The InstallAnywhere package for AIX is an archive package. Use this package when you want toinstall the product without any configuration. For more information, see “Installing from anInstallAnywhere package (AIX and Linux only)” on page 51.

installp packages

Use these packages when you want to install the product with associated configuration, such as thesetting of environment variables.

If you are using one of the supported non-UTF8 CJK locales, you must install one of the following file sets:

• 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)

Note: The installation images are available on the AIX base CDs. Updates are available from the AIX fixdistribution website.

When using the zh_TW.IBM-eucTW locale on 64-bit AIX 6.1, you might get a result that usesISO-8859-1 instead of IBM-eucTW, in response to the following command:

$ LANG=zh_TW locale charmap

The different return might affect the operation of this release. If you encounter this effect, see APARIV05072.

Linux

You install the SDK from an InstallAnywhere package. The InstallAnywhere packages for Linux are eitherarchive packages or installable packages. Use the archive packages when you want to install the productwithout any configuration. Use the installable packages when you want to install the product withassociated configuration, such as the setting of environment variables.

The examples elsewhere in this guide assume that you installed the SDK in the default installationdirectory, as listed in “Conventions” on page 36.

Windows

The SDK is available only as part of an IBM product. For more information about obtaining, installing andperforming initial configuration of IBM SDK, Java Technology Edition in such a product on Windows,please contact your IBM support representative. You can, however, configure the SDK by usingenvironment variables, command-line options, and properties files.

z/OS

Packages can be ordered in System Modification Program /Extended (SMP/E) format or downloaded fromthe web in non-SMP/E format. See the z/OS website for instructions about ordering, downloading,installing, and verifying the SDK.


https://www.ibm.com/servers/eserver/support/unixservers/aixfixes.html

https://www.ibm.com/servers/eserver/support/unixservers/aixfixes.html

https://www.ibm.com/systems/z/os/zos/tools/java/

Supported environmentsThis release is supported on certain hardware platforms and operating systems, and is tested on specificvirtualization environments.

Any new updates to these support statements can be found in the Current® news technote.

• “AIX systems” on page 44• “Linux systems” on page 44• “Windows systems” on page 46• “z/OS systems” on page 46• “Specialized hardware features” on page 47

AIX systems

The 32-bit and 64-bit releases of the SDK and Runtime environment run on hardware that supports thefollowing platform architectures:

• IBM POWER 5• IBM POWER 6• IBM POWER 7• IBM POWER8®

• IBM POWER9

The following table shows the operating systems supported for each platform architecture. The table alsoindicates whether support for an operating system release was included at the general availability (GA)date for the release, or at a later date in a service refresh (SR) or fix pack (FP):

Table 3. Supported AIX environments

Operating system 32-bit release 64-bit release

AIX 6.1 TL9 (previouslyTL7)

GA GA

AIX 7.1 TL3 (see note 1) GA GA

AIX 7.2 (see note 2) SR2 SR2

Notes:

1. For IBM POWER8 systems, the minimum level for AIX 7.1 is TL3.2. AIX 7.2 is supported only on IBM POWER 7 and later processors.

To avoid problems when using the Java runtime environment, ensure that you have any prerequisite AIXAPARs installed. For further information about the APARs needed for an AIX level, see https://www.ibm.com/support/docview.wss?uid=swg21605167.

If you want to use the Java 2D graphics pipeline, based on the X11 XRender extension, you must installthe libXrender.so library, version 0.9.3 or later.

Linux systems

There are a number of distributions provided for the Linux operating system.

For Linux on x86, the following platform architectures are supported:

• x86-32• x86-64





For Linux on IBM POWER, the following hardware is supported:

• IBM POWER 6• IBM POWER 7• IBM POWER8

• IBM POWER9

Note: IBM POWER8 systems can operate in both Big Endian (BE) or Little Endian (LE) format. An LEversion of the SDK is available for 64-bit Power Systems to support those operating systems that areavailable in LE format. For example, SUSE Linux Enterprise Server (SLES) 12 or Ubuntu 18.04 LTS.

For Linux on IBM Z, the following hardware is supported:

• IBM z15• IBM z14• IBM z13®

• IBM zEnterprise EC12• IBM zEnterprise BC12• IBM zEnterprise 114• IBM zEnterprise 196• IBM System z10


Table 4. Supported Linux environments

Operatingsystem

x86 systems,32-bit

x86 systems,64-bit

ARMsystems, 32-bit

Powersystems, 64-bit

IBM Z, 31-bit IBM Z, 64-bit

SLES 12 GA GA - GA (see note1)

GA GA

SLES 15 SP1 SR6 SR6 - SR6 (see note1)

- SR6

Red HatEnterpriseLinux (RHEL)7.4

SR4 FP10 SR4 FP10 SR4 FP10 SR4 FP10(see note 2)

SR4 FP10 SR4 FP10

RHEL 7.5 SR5 FP15 SR5 FP15 SR5 FP15 SR5 FP15(see note 2)

SR5 FP15 SR5 FP15

RHEL 7.6 SR5 FP25 SR5 FP25 SR5 FP25 SR5 FP25(see note 2)

SR5 FP25 SR5 FP25

RHEL 7.7 SR6 SR6 - SR6 (see note2)

- SR6

RHEL 7.8 SR6 FP10 SR6 FP10 - SR6 FP10(see note 2)

- SR6 FP10

RHEL 8 SR5 FP35 SR5 FP35 - SR5 FP35(see note 3)

- SR5 FP35

RHEL 8.2 SR6 FP10 SR6 FP10 - SR6 FP10(see note 3)

- SR6 FP10

Chapter 3. Installing the SDK 45

Table 4. Supported Linux environments (continued)

Operatingsystem

x86 systems,32-bit

x86 systems,64-bit

ARMsystems, 32-bit

Powersystems, 64-bit

IBM Z, 31-bit IBM Z, 64-bit

Ubuntu 16.04LTS

SR3 SR3 - SR3 (see note2)

- SR3

Ubuntu 18.04LTS

SR5 FP15 SR5 FP15 SR5 FP15 SR5 FP15(see note 2)

- SR5 FP15

Ubuntu 20.04LTS

SR6 FP10 SR6 FP10 - SR6 FP10(see note 3)

- SR6 FP10

Notes:

1. Supported only on POWER8 (or later) systems with the LE version of the SDK.2. Supported on POWER systems with the BE version of the SDK, and on POWER8 (or later) systems with

the LE version of the SDK.3. Not supported on POWER systems with the BE version of the SDK.

Note: To satisfy a dynamic linking dependency, the Standard C++ library, libstdc++.so.6,must be installed.

Windows systems

The 32-bit release for Windows runs on hardware that supports the x86 32-bit and 64-bit architectures.

The 64-bit release for Windows runs on hardware that supports the x86 64-bit architecture.


Table 5. Supported Windows environments


Windows 8.1 GA GA

Windows 10 SR1 FP10 SR1 FP10

Windows Server 2016 SR4 SR4

Windows Server 2019 SR5 FP35 SR5 FP35

z/OS systems

The z/OS 31-bit and 64-bit releases run on the following IBM Z systems:

• IBM z15• IBM z14• IBM z13• IBM zEnterprise EC12• IBM zEnterprise BC12• IBM zEnterprise 114• IBM zEnterprise 196• IBM System z10



Table 6. Supported z/OS environments


z/OS 2.2 SR2 SR2

z/OS 2.3 SR4 FP10 SR4 FP10

z/OS 2.4 SR6 SR6

Specialized hardware features

The following hardware features have additional prerequisites to those listed in this topic:

• Remote Direct Memory Access (RDMA) adapters (Linux): “JSOR system requirements and supportedAPIs (Linux only)” on page 198

• Remote Direct Memory Access (RDMA) adapters (Linux): “jVerbs application system and runtimerequirements (Linux only)” on page 234

• Graphics processing unit (GPU) adapters (Linux and Windows): GPU system requirements• Hardware compression acceleration (AIX and Linux): “Enabling hardware compression acceleration

(AIX, Linux only)” on page 185

Virtualization software

For information about the virtualization software tested, see “Support for virtualization software” on page47.

Support for virtualization softwareThis release is tested with a number of virtualized server products.

This release has been tested on current versions of the following virtualization software:

Table 7. Virtualization software tested

Vendor Architecture Server virtualization Version

IBM IBM Z PR/SM z13, z10, z11, z196,zEC12

IBM IBM Z z/VM® 6.1, 6.2

IBM IBM Z KVM for IBM z Systems 1.1.0

IBM POWER PowerVM® Hypervisor Power 6, Power 7,Power 8

VMware x86-64 VMware ESX and ESXiServer

5.5, 6.0

Microsoft x86-64 Hyper-V Server 2012

Docker, Inc x86-64 Docker V1.6 or later (see note)

Note: IBM supports all versions of the SDK that run in Docker containers, provided that the Dockerimages are based on supported operating systems. To find out which operating systems are supported forthe IBM SDK, see “Supported environments” on page 44 .


installp packages (AIX only)Use installp packages when you want to install the product on AIX with associated configuration, such asthe setting of environment variables.

Note: To install into a directory other than the default, use relocation commands as described in“Relocating an installp package (AIX only)” on page 50.

This package is required:

• 32-bit: Java8.sdk (license, base SDK, Web Start, and dt.jar)• 64-bit: Java8_64.sdk (license, base SDK and dt.jar)

These packages are optional:

For 32-bit systems:

• Java8.samples (demos)• Java8.jclsource (src.jar)• Java8.sampsource (src.jar)• Java8.msg.$LANG (Localized messages)

For 64-bit systems:

• Java8_64.ext (Comm API)• Java8_64.samples (demos)• Java8_64.jclsource (src.jar)• Java8_64.sampsource (src.jar)• Java8_64.msg.$LANG (Localized messages)

$LANG is one of the following locales. These packages do not include any files but pull in requiredUnicode TrueType fonts, if not already installed, for these locales:

• Zh_CN• zh_CN• ko_KR• Ja_JP• ja_JP• Zh_TW• zh_TW

installp packages are installed by the AIX installp command. For more information about using thiscommand, see the AIX product documentation. For example, if you are using AIX 7.1, see https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds3/installp.html.

The SDK is installed in the default directory, as listed in “Conventions” on page 36.

The following user-configurable files are installed to /etc/java8_64/ (64-bit) to support a configurationwhere the files are not shared:

• jre/lib/jaxp.properties• jre/lib/logging.properties• jre/lib/management/jmxremote.access• jre/lib/management/jmxremote.password.template• jre/lib/management/management.properties• jre/lib/management/snmp.acl• jre/lib/management/snmp.acl.template


https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds3/installp.html

https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds3/installp.html

• jre/lib/security/java.policy• jre/lib/security/java.security• jre/lib/security/javaws.policy• jre/lib/xalan.properties• jre/lib/xerces.properties

There are symbolic links in the installation directory (for the default, see “Conventions” on page 36)pointing to the files in /etc/java8_64/ for 64-bit systems.

Verifying your installation (AIX only)When you complete your SDK installation on an AIX system by using an installp package, you can verifythat the installation was successful by removing any environment settings and running the java -version command.

Before you begin

To ensure that the verification process behaves consistently, enter the following commands:

unset LIBPATHunset CLASSPATHunset JAVA_COMPILERexport PATH=install_dir/jre/bin:install_dir/bin:$PATH

About this task

When you issue the command:

java -version

you see output like the following messages, where dates, times, and specific build numbers might bedifferent:

• On AIX from service refresh 5 fix pack 5:

java version "1.8.0_151"Java(TM) SE Runtime Environment (build 8.0.5.5 - pap6480sr5fp5-20171109_02(SR5 FP5))IBM J9 VM (build 2.9, JRE 1.8.0 AIX ppc64-64 Compressed References 20171102_369060 (JIT enabled, AOT enabled)OpenJ9 - 7ade437OMR - 1b656cbIBM - 59c3d96)JCL - 20171109_01 based on Oracle jdk8u151-b12

• On AIX before service refresh 5:

java version "1.8.0"Java(TM) SE Runtime Environment (build pap6480-20140729_01)IBM J9 VM (build 2.8, JRE 1.8.0 AIX ppc64-64 Compressed References 20140725_207966 (JIT enabled, AOT enabled)J9VM - R28_jvm.28_20140725_0202_B207966JIT - tr.r14.java_20140714_68218.03GC - R28_jvm.28_20140725_0202_B207966_CMPRSSJ9CL - 20140725_207966)JCL - 20140722_01 based on Oracle jdk8u20-b20

What to do next

When verification is complete, log on again and review your environment settings. Check for conflicts thatmight arise from the values that you assigned to these variables.


On 32-bit AIX, if the directory .hotjava does not exist, the applet viewer creates thedirectory .hotjava in your home directory. To confirm that the directory has been created, use thecommand:

ls -a ~

Upgrading the SDK (AIX only)If you are upgrading the SDK from a previous release, back up all the configuration files and securitypolicy files before you start the upgrade.

After the upgrade, you might have to restore or reconfigure these files because they might have beenoverwritten during the upgrade process. Check the syntax of the new files before restoring the originalfiles because the format or options for the files might have changed.

Relocating an installp package (AIX only)If you install the product on an AIX system from an InstallAnywhere package, you can choose theinstallation directory during the installation process. If you install from the installp packages, the productis installed in the default directory. To install the product in another directory, use the AIX relocationcommands.

Delete any .toc files in the directory containing your installp images or PTFs before using the AIXrelocation commands.

Commands

See the AIX man pages for more information about the command-line options for these commands.

installp_rInstall the SDK:

installp_r -a -Y -R /<Install Path>/ -d '.' Java8_64.sdk

Remove the SDK:

installp_r -u -R /<Install Path>/ Java8_64.sdk

lsusilList the user-defined installation paths.

lsusil

lslpp_rFind details of installed products.

lslpp_r -R /<Install Path>/ -S [A|O]

rmusilRemove existing user-defined installation paths.

rmusil -R /<Install Path>/

Related information“Conventions” on page 36The default directory is listed in this topic.


Installing from an InstallAnywhere package (AIX and Linux only)These packages provide an interactive program that guides you through the installation options. You canrun the program as a graphical user interface, or from a system console.

Before you begin

If you are upgrading the SDK from an earlier release, as a precaution, back up all the configuration filesand security policy files before you start the upgrade.

For Linux operating systems, be aware of the following conditions:

• If you are installing an installable package, you must have the rpm-build tool installed on your system,otherwise the installation program cannot register the new package in the RPM database. To find out ifthe rpm-build tool is installed, enter the following command:

rpm -q rpm-build

• For Linux IA 32-bit Chinese users: Because of inconsistencies in the font encodings on Red HatAdvanced Server, when you install for an environment in which you want Chinese to be the defaultlanguage, it is better to install with a default language of English and then change to Chinese after theinstallation is complete. Otherwise, you might find that the Chinese fonts do not display.

About this task

The InstallAnywhere packages have a .bin file extension.

There are two types of package:Installable (Linux only)

Installing these packages also configures your system, for example by setting environment variables.You must use a user account with ROOT authority to install this type of package.

Archive (AIX and Linux)Installing these packages extracts the files to your system, but does not perform any configuration.This type of package does not require ROOT authority to complete the installation.

Procedure

• To install the package in an interactive way, complete an attended installation.• To install the package without any additional user interaction, complete an unattended installation.

You might choose this option if you want to install many systems.

Results

The product is installed.

Note: Do not interrupt the installation process, for example by pressing Ctrl+C. If you interrupt theprocess, you might have to reinstall the product. For more information, see “Interrupted installation (AIXand Linux only)” on page 54.

If you are using an installable package on Linux, you might see messages advising that a problem hasbeen found. Installation of the archive packages does not produce any messages. Some of the messagesthat you might see when using an installable package are shown in the following list:The installer cannot run on your configuration. It will now quit.

This error message occurs when your user ID is not authorized to run the installation process.Because it cannot continue, the installation program ends. To fix the problem, start the installationagain but with a user ID that has root authority.

An RPM package is already installed. Uninstall the package before proceeding.This message indicates that an RPM package is already installed. Because it cannot continue, theinstallation program ends. To fix the problem, uninstall the RPM package before proceeding.


Warning: there may be a version of this package already installed. If thisversion was supplied by SuSE, it will have been packaged so that it installsunder a different directory tree. To avoid unexpected results, you should useYaST2 to remove the SuSE-supplied version.

This message appears when you attempt to install on a SuSE system. The reason is that there mightbe an SDK or runtime environment already installed. The installation program proceeds, but mightencounter a problem during the process. If this situation occurs, uninstall any existing packages andtry again.

Completing an attended installation on AIX or LinuxInstall the product from an InstallAnywhere package, in an interactive way.

Before you begin

On AIX, check the following condition before you begin the installation process:

• You must install the following dependent library for your environment: XL C++ runtime environmentxlC.aix61.rte

On Linux, check the following conditions before you begin the installation process:

• If you have previously installed the IBM SDK from an RPM package, you must uninstall this packagebefore proceeding.

• If you have a SUSE Linux system, a different version of Java might already be installed. Uninstall thispackage before proceeding.

• You must have the following dependent libraries for your environment:

– IBM POWER (Little Endian architecture):

- GNU C Library: eglibc V2.19 or later- Standard C++ library: libstdc++.so.6

– All other architectures (x86, IBM POWER, and POWER Linux on IBM Z):

- GNU C Library: glibc V2.3.4 or later- Standard C++ library: libstdc++.so.6

Procedure

1. If your system does not have the dependent libraries that are defined, obtain and install the library.2. Download the installation package file to a temporary directory.3. Change to the temporary directory.4. Start the installation process by typing ./package.bin at a shell prompt, where package is the name

of the package that you are installing.5. To read the installation instructions in another language, select a language from the list that is shown

in the installer window, then click Next. The list of available languages is based on the locale settingfor your system.

6. Read the license agreement. To proceed with the installation, you must accept the terms of the licenseagreement. To accept the terms, read to the end of the license text by using the scroll bar. Select theradio button, then click OK.

Note: To read the license agreement in your chosen language, you might need to change your systemlocale.

7. You are asked to choose the target directory for the installation. If you do not want to install into thedefault directory, click Choose to select an alternative directory, by using the browser window. Whenyou have chosen the installation directory, click Next to continue.

8. You are asked to review the choices that you made. To change your selection, click Previous. If yourchoices are correct, click Install to proceed with installation.


9. When the installation process is complete, click Done to finish.

Completing an unattended installation on AIX or LinuxIf you have more than one system to install, and you already know the installation options that you wantto use, you might want to use the unattended installation process. The unattended process uses aresponse file to complete installations without any user interaction.

Before you beginCheck the conditions that are documented in “Completing an attended installation on AIX or Linux” onpage 52.

About this taskBefore you use the unattended installation process, you must accept the terms of the license agreement.You can do this by running an attended installation to generate a new response file that sets a specificvalue, or by reading the license agreement and manually updating an existing response file. Moreinformation is provided in the first step.

Procedure

1. To create a new response file, complete an attended installation. Use one of the following options:

• Use the GUI and specify that the installation program creates a response file. The response file iscalled installer.properties, and is created in the installation directory.

• Use the command line and append the -r option to the attended installation command, specifyingthe full path to the response file. For example:

./package -r /path/installer.properties

Example response file contents:

INSTALLER_UI=silent USER_INSTALL_DIR=/my_directoryLICENSE_ACCEPTED=TRUE

In this example, /my_directory is the target installation directory that you chose for the IBM SDK.

Note: The value LICENSE_ACCEPTED=TRUE is added when you create the response file byrunning an attended installation and accepting the license agreement. If you edit an existing responsefile, you must read the license agreement and include this line to confirm your license acceptance, orthe installation fails.

2. Optional: If required, edit the response file to change options.

If you are creating more than one response file, each with different installation options, specify aunique name for each response file, in the format myfile.properties.

3. Optional: Generate a log file.Because you are installing silently, no status messages are displayed at the end of the installationprocess. To generate a log file that contains the status of the installation, complete the followingsteps:a) Set the required system properties by using the following command.

export _JAVA_OPTIONS="-Dlax.debug.level=3 -Dlax.debug.all=true"

b) Set the following environment variable to send the log output to the console.

export LAX_DEBUG=1

4. Start an unattended installation by running the package installer with the -i silent option, and the -foption to specify the response file.For example:


./package -i silent -f /path/installer.properties 1>console.txt 2>&1

./package -i silent -f /path/myfile.properties 1>console.txt 2>&1

You can use a fully qualified path or relative path to the properties file. In these examples, the string1>console.txt 2>&1 redirects installation process information from the stderr and stdout streamsto the console.txt log file in the current directory. Review this log file if you think there was aproblem with the installation.

Note: If your installation directory contains multiple response files, the default response file,installer.properties is used.

Interrupted installation (AIX and Linux only)If the package installer on an AIX or Linux system is unexpectedly stopped during installation, forexample if you press Ctrl+C, the installation is corrupted and you cannot uninstall or reinstall the product.If you try to uninstall or reinstall you might see the message Fatal Application Error.

About this taskTo solve this problem, delete files and reinstall, as described in the following steps.

Procedure

1. Delete the \var\.com.zerog.registry.xml registry file.2. Delete the directory containing the IBM SDK installation, if it was created. The default installation

directory is listed in “Conventions” on page 36.3. Run the installation program again.

Known issues and limitations on AIX and Linux installationsThe InstallAnywhere packages have some known issues and limitations.

General

• On Linux, If you do not have the libstdc++.so.5 shared library on your system, the installation fails,producing a Java core dump. For more information, see “Installing from an InstallAnywhere package(AIX and Linux only)” on page 51.

• The installation package GUI does not support the Orca screen-reading program. You can use theunattended installation mode as an alternative to the GUI.

• If you install the package, then attempt to install again in a different mode, for example console orsilent, you might see the following error message:

Invocation of this Java Application has caused an InvocationTargetException. This application will now exit

You should not see this message if you installed by using the GUI mode and are running the installationprogram again in console mode. If you see this error on Linux, and are running the program to select theuninstall option (installable packages only), use the ./_uninstall/uninstall command instead, asdescribed in “Uninstalling an InstallAnywhere package (AIX and Linux only)” on page 55.

Installable packages (Linux only)

• You cannot upgrade an existing IBM SDK by using the InstallAnywhere packages. To upgrade your IBMSDK you must first uninstall any previous versions.

• You cannot install two different instances of the same version of the IBM SDK on the same system atthe same time, even if you use different installation directories. For example, you cannotsimultaneously have IBM SDK, Java Technology Edition, Version 8 in directory /previous, and anupdated IBM SDK, Java Technology Edition, Version 8 installation in directory /current. The


installation program checks the version number. If the program finds an existing package with the sameversion number, you are asked to uninstall the existing package.

• If the package is installed, and you run the package installer again by using the GUI, you can select touninstall the package. This uninstall option is not available in unattended mode. If you run the packageinstaller again in unattended mode, the program runs but does not perform any actions.

• If, after installation, you enter ./package.bin to start the program again, the program displays thefollowing message:

ENTER THE NUMBER OF THE DESIRED CHOICE, OR PRESS <ENTER> TO ACCEPT THE DEFAULT:

If you press Enter to accept the default, the program does not respond. Type a number, then pressEnter.

Archive packages (AIX and Linux)

• If you change the installation directory in a response file, and then run an unattended installation byusing that response file, the installation program ignores the new installation directory and uses thedefault directory instead. If a previous installation exists in the default directory, it is overwritten.

Uninstalling an InstallAnywhere package (AIX and Linux only)The process that you use to remove the SDK depends on what type of installation you used:InstallAnywhere installable packages (available for Linux operating systems only) or InstallAnywherearchive packages (available for AIX and Linux operating systems).

Before you beginFor InstallAnywhere installable packages, you must have a user ID with root authority.

About this task

There is no uninstallation process for InstallAnywhere archive packages. To remove an archive packagefrom your system, delete the target directory that you chose when you installed the package. ForInstallAnywhere installable packages on Linux, you uninstall the product by using a command, or byrunning the installation program again, as described in the following steps.

Note: Do not attempt to uninstall the product by using the rpm -e command, because this will corruptthe installed package.

Procedure

• Optional: Uninstall manually by using the uninstall command.a) Change to the directory that contains the IBM SDK installation.

The default installation directory is listed in “Conventions” on page 36.b) Start the uninstallation process by entering the following command: ./_uninstall/uninstall

• Optional: If you cannot locate the uninstall program easily, as an alternative you can run anotherattended installation. The installation program detects that the product is already installed, then givesyou the opportunity to uninstall the previous installation.

ResultsThe product is uninstalled.

Note: If you installed the product on a system that does not have the rpm-build tool, files such as<package>.spec remain after uninstallation. The rpm-build tool is a requirement for successfulinstallation. For more information, see “Installing from an InstallAnywhere package (AIX and Linux only)”on page 51.


SMP/E and non-SMP/E packages (z/OS only)On z/OS systems, packages can be ordered in System Modification Program /Extended (SMP/E) format ordownloaded from the web in non-SMP/E format.

If you order the SDK, the package is provided in SMP/E RELFILE format, which can be installed by usingSMP/E. A program directory is available to guide you through the installation process.

Alternatively, non-SMP/E format packages are available to download directly from the web. Thesepackages contain compressed code archives. Instructions for uncompressing and installing the packagesare provided in an accompanying README file.

Note: The 64–bit z/OS SDK installation is designed to install to a different directory tree from anycurrently installed 31-bit SDK. This means that both 31-bit and 64-bit SDK installations can coexist on thesame system.

For more information about ordering, downloading, installing, and verifying the SDK, see the Java on z/OSwebsite.




Chapter 4. Configuring your environmentAlthough some configuration options must be set before you run your Java application, many options areconfigured when you launch the runtime environment from the command line. Configuration options thatmust be set before you start your application include environment variables, operating system resources,and hardware components that can be exploited by applications.

While some configuration options apply to all platforms, a number are platform-specific, particularlywhen the option relates to hardware or operating system resources.

Setting the pathIf you alter the PATH environment variable, you will override any existing Java launchers in your path.

About this task

The PATH environment variable enables the operating system to find programs and utilities, such asjavac, java, and javadoc tool, from any current directory. To display the current value of your PATH,type the following command at a command prompt:

• On Windows systems: echo %PATH%• On other operating systems: echo $PATH

To add the Java launchers to your path on Windows systems:

1. If the SDK was installed in the default installation directory (see “Conventions” on page 36), add theinstall_dir\bin directory to the PATH environment variable.

2. Close and reopen any command prompt windows to activate the new PATH environment variable.

To add the Java launchers to your path on other operating systems:

1. Edit the shell startup file in your home directory (typically .bashrc, depending on your shell) and addthe absolute paths to the PATH environment variable; for example:

export PATH=/opt/ibm/java-ppc64-80/bin:/opt/ibm/java-ppc64-80/bin:$PATH

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

ResultsAfter setting the path, you can run a tool by typing its name at a command prompt from any directory. Forexample, to compile the file Myfile.Java, at a command prompt, type:

javac Myfile.Java

Setting the class pathThe class path tells the SDK tools, such as java, javac, and the javadoc tool, where to find the Javaclass libraries.

About this task

You should set the class path explicitly only if:

• You require a different library or class file, such as one that you develop, and it is not in the currentdirectory.

• You change the location of the bin and lib directories and they no longer have the same parentdirectory.


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

To display the current value of your CLASSPATH environment variable, type the following command at acommand or shell prompt:

• On Windows systems: echo %CLASSPATH%• On other operating systems: echo $CLASSPATH

If you develop and run applications that use different runtime environments, including other versions thatyou have installed separately, you must set the CLASSPATH and PATH explicitly for each application. Ifyou run multiple applications simultaneously and use different runtime environments, each applicationmust run in its own shell or command prompt.

Setting the library path on AIX and Linux systemsThe library path environment variable tells Java applications that run on AIX and Linux, such as the JVM,where to find shared libraries. The location of shared libraries is important when they are located in adifferent directory from the directory that is specified in the header section of the program.

The following environment variables are used to specify the shared library path:

• AIX: LIBPATH• Linux: LD_LIBRARY_PATH

The following example shows the header section of the java command on AIX:

> dump -X64 -H install_dir/jre/bin/javainstall_dir/jre/bin/java: ***Loader Section*** Loader Header InformationVERSION# #SYMtableENT #RELOCent LENidSTR0x00000001 0x0000003f 0x0000006d 0x00000090

#IMPfilID OFFidSTR LENstrTBL OFFstrTBL0x00000006 0x00000b24 0x00000099 0x00000bb4

***Import File Strings***INDEX PATH BASE MEMBER0 /usr/lib:/lib

1 libc.a shr.o2 libC.a shr.o3 libpthreads.a shr_comm.o4 libpthreads.a shr_xpg5.o5 libbsd.a shr.o

Index 0 in the example contains the list of directories that are searched for shared objects if the librarypath environment variable is not specified. If the library path environment variable is set, the specifieddirectories are searched for shared objects before the directories listed in Index 0 of the header.

The shared libraries for the SDK are contained in the following directories:AIX

install_dir/jre/lib/ppc[64]install_dir/jre/lib/ppc[64]/j9vm

Linux/usr/java8/jre/lib/<platform>//usr/java8/jre/lib/<platform>/j9vmWhere <platform> is one of the following values:

• Linux on 32-bit IBM Power systems: ppc• Linux on 64-bit IBM Power systems: ppc64• Linux on 31-bit IBM Z: s390


• Linux on 64-bit IBM Z: s390x• Linux 32-bit x86 systems: i386• Linux 64-bit x86 systems: amd64

The SDK launcher programs, including java, javac, and jar automatically search these directories. IfJava is installed as an AIX file set, the parent directory is install_dir, but packages that bundle Javamight use different directories. The parent directory on Linux is usually /usr/java8/, but packages thatbundle Java might use different directories. This path is already set by the Java launcher programs suchas java, javac, or jar.

Set the library path environment variable if one of the following conditions applies:

• You are using other shared libraries, including JNI native libraries that you use or develop. Set thelibrary path environment variable to include the directory or directories that contain your libraries.

• You are using the JNI Invocation API to call Java code from your C/C++ application. Set the library pathenvironment variable to include the directories that contain the JVM libraries in addition to thedirectories that contain your own libraries.

Configuring your systemDepending on your system environment, you might want to set configuration options that allow the VM touse hardware and operating system features. Some features have additional software dependencies.

These configuration options can be set for the Eclipse OpenJ9 VM. Click the links in the following list tolearn more about these options:

• To ensure that your operating system allocates sufficient resources for your application, set a suitablevalue for ulimits. For more information, see Setting system resource limits on AIX and Linux systemsin the J9 VM reference.

• To ensure that z/OS resources are sufficient for your application, you might want to set region size,BPXPRM parameters, and Language Environment® runtime options. For more information, see Settingsystem resource limits on z/OS systems in the J9 VM reference.

• If your application allocates a large amount of memory and frequently accesses that memory, you mightwant to enable large page support on your system. For more information, see Configuring large pagememory allocation in the J9 VM reference.

• If you are running your application on an IBM Power system and want to take advantage of DLPARcapabilities for the dynamic movement of memory, CPU capacity, and I/O interfaces between LPARs,see Dynamic Logical Partitioning (DLPAR) support (AIX only) in the J9 VM reference.

• To configure your system to use Graphics Processing Units (GPU), see GPU system requirements.• To configure your system to use RDMA network infrastructure by using Java Sockets over RDMA (JSOR),

see “JSOR system requirements and supported APIs (Linux only)” on page 198 and “Shared MemoryCommunications via Remote Direct Memory Access (z/OS only)” on page 253.

• To configure your system to use RDMA network infrastructure by writing applications that use thejVerbs library, see “jVerbs application system and runtime requirements (Linux only)” on page 234.

• To configure your system to use z/Enterprise data compression, see “zEnterprise Data Compression(z/OS only)” on page 188 .

• To configure your system to use other hardware compression acceleration devices, see “Enablinghardware compression acceleration (AIX, Linux only)” on page 185 .

Chapter 4. Configuring your environment 59

Enabling Java accessibility supportYou can use the Oracle Java Access Bridge to give native Windows assistive technologies, such as screenreaders, access to the Java Accessibility support in a Java application. These native Windows assistivetechnologies must support calls to the bridge components.

The Oracle Java Access Bridge is provided in the runtime environment by default. To use the Oracle JavaAccess Bridge, uncomment the assistive_technologies entry in the jre/lib/accessibility.properties file to read:

assistive_technologies=com.sun.java.accessibility.AccessBridge

To learn more about Java accessibility utilities, see https://www.oracle.com/technetwork/java/javase/tech/index-jsp-140174.html.

Running the JVM under a different z/OS code pageJava files for z/OS are shipped in only one version: EN_US. To run the JVM under a different locale,convert all the text files in your Java installation from the default (IBM-1047) to your code page.

The jdkconv utility converts text files to a local encoding. The utility might be helpful if you get errormessages about an invalid format for text files. To check if your code page setting might be the cause ofthe problem, find which locale you are using by checking the environment variables LANG or LC_ALL. Ifthe locale value is not C or EN_US then you might see the invalid format message.

To convert your Java installation to a different code page, use the jdkconv utility. The utility requires atool called cpmod, which is also provided in your Java installation.

1. Make a copy of your Java installation directory. The reason is that the script overwrites files in the Javainstallation directory. If you want to undo the changes, you must either reinstall Java, or restore yourcopy of the directory.

2. The jdkconv utility itself is shipped in code page IBM-1047. Before you run the utility, convert it toyour code page as follows:

cp -p jdkconv jdkconv.backupiconv -f IBM-1047 -t CODEPAGE jdkconv.backup >jdkconvchmod 755 jdkconv

In this command sequence, replace CODEPAGE with your code page.3. Ensure that the directory containing both jdkconv and cpmod is in your PATH setting.4. Run jdkconv as follows:

jdkconv CODEPAGE JAVATREE

In this command, CODEPAGE is your code page, and JAVATREE is your Java installation directory.

After running the jdkconv utility, test the changes by running a Java application that is sensitive to thesystem locale.


https://www.oracle.com/technetwork/java/javase/tech/index-jsp-140174.html


Updating your SDK or runtime environment for Daylight Saving Timechanges

You can apply recent changes to Daylight Saving Time by using the IBM Time Zone Update Utility for Java(JTZU).

About this task

Many countries around the world use a Daylight Saving Time (DST) convention. Typically, clocks moveforward by 1 hour during the summer months to create more daylight hours during the afternoon and lessduring the morning. This practice has many implications, including the need to adjust system clocks incomputer systems. Occasionally, countries change their DST start and end dates. These changes canaffect the date and time functions in applications because the original start and end dates areprogrammed into the operating system and in Java software. To avoid this problem, you must updateoperating systems and Java installations with the new DST information.

The Olson time zone database is an external resource that compiles information about the time zonesaround the world. This database establishes standard names for time zones, such as "America/New_York", and provides regular updates to time zone information that can be used as reference data. Toensure that IBM developer kits and Runtime Environments contain up to date DST information, IBMincorporates the latest Olson time zone level into every updated release. To find out which Olson timezone level is included for a particular SDK or refresh, see https://www.ibm.com/developerworks/java/jdk/dst/olson_table.html.

If a DST change has been introduced since the last IBM update of the SDK, you can use JTZU to directlyupdate your Java installation. You can also use this tool to update your installation if you are unable tomove straight to the latest SDK update. JTZU is available from IBM developerWorks at the following link:https://www.ibm.com/developerworks/java/jdk/dst/jtzu.html.

ResultsAfter updating your Java installation with any recent DST changes, your application can handle time anddate calculations correctly.

Chapter 4. Configuring your environment 61

https://www.ibm.com/developerworks/java/jdk/dst/olson_table.html

https://www.ibm.com/developerworks/java/jdk/dst/olson_table.html

https://www.ibm.com/developerworks/java/jdk/dst/jtzu.html

Chapter 5. Developing Java applicationsThe SDK contains many tools and libraries required for Java software development.

See “IBM Software Developers Kit (SDK)” on page 1 for details of the tools available.

Debugging Java applicationsTo debug Java programs, you can use the Java Debugger (JDB) application or other debuggers thatcommunicate by using the Java Platform Debugger Architecture (JPDA) that is provided by the SDK forthe operating system.

Information about problem diagnosis using Java can be found in Troubleshooting and support.

Note:

• The selective debugging feature, enabled using the command-line option -XselectiveDebug, is nolonger supported.

• On AIX systems, the SDK includes a Plug-in for the AIX debugger, DBX. Although the DBX plug-in issupplied as part of the SDK, it is not supported. However, IBM will accept bug reports.

The Java DebuggerThe Java Debugger (JDB) is included in the SDK. The debugger is started with the jdb command; itattaches to the JVM using JPDA.

Note: The Java Virtual Machine Debugging Interface (JVMDI) is not supported in this release. It has beenreplaced by the Java Virtual Machine Tool Interface (JVMTI).

To debug a Java application:

1. Start the JVM with the following options:

• On Windows systems:

java -agentlib:jdwp=transport=dt_shmem,server=y,address=<port> <class>

• On other systems:

java -agentlib:jdwp=transport=dt_socket,server=y,address=<port> <class>

The JVM starts, but suspends execution before it starts the Java application.2. In a separate session, you can attach the debugger to the JVM:

jdb -attach <port>

The debugger will attach to the JVM, and you can now issue a range of commands to examine andcontrol the Java application; for example, type run to allow the Java application to start.

To debug Java applications running on remote workstations:JPDA uses a TCP/IP socket to connect to the remote JVM.

1. Start the JVM with the following options:


java -agentlib:jdwp=transport=dt_shmem,server=y,address=<port> <class>


java -agentlib:jdwp=transport=dt_socket,server=y,address=<port> <class>


The JVM starts, but suspends execution before it starts the Java application.2. Attach the debugger to the remote JVM:


jdb -connect com.sun.jdi.SocketAttach:hostname=<host>,port=<port>


jdb -attach <host>:<port>

For further information:

• For more information about JDB options, type: jdb -help• For more information about JDB commands:

1. Type jdb2. At the jdb prompt, type help

• For more information about JDB and JPDA and their usage, see:

– https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/– https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdb.html

Determining whether your application is running on a 32-bit (31-bit on IBMZ) or 64-bit JVM

Some Java applications must be able to determine whether they are running on a 32-bit (31-bit on IBM Z)or 64-bit JVM.

About this task

If your application has a native code library, the library must be compiled separately in 32-bit (31-bit onIBM Z) and 64-bit forms for platforms that support both 32-bit and 64-bit modes of operation. In thiscase, your application must load the correct library at run time, because it is not possible to mix 32-bit(31-bit on IBM Z) and 64-bit code.

For Eclipse OpenJ9 VM, the system property com.ibm.vm.bitmode allows applications to determinethe mode in which your JVM is running. It returns the following values:

• 32 - the JVM is running in 32-bit (31-bit on IBM Z) mode• 64 - the JVM is running in 64-bit mode

You can inspect the com.ibm.vm.bitmode property from inside your application code using the call:System.getProperty("com.ibm.vm.bitmode");

Native threads (AIX only)On AIX systems, programs can set the priority of system contention scope threads. Calls tojava.lang.Thread.setPriority() will change the priority of Java threads running on AIX.

For more information about AIX thread scheduling, see the documentation for your level of AIX. Forexample:

pthread_setschedparam Subroutine and Scheduling Threads.


https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/

https://docs.oracle.com/javase/8/docs/technotes/guides/jpda/jdb.html

https://www.ibm.com/support/knowledgecenter/ssw_aix_72/com.ibm.aix.basetrf1/pthread_setschedparam.htm

https://www.ibm.com/support/knowledgecenter/ssw_aix_72/com.ibm.aix.genprogc/threads_sched.htm

Support for XToolkit (AIX, Linux, and z/OS only)XToolkit is included by default. You need XToolkit when using the SWT_AWT bridge in Eclipse to build anapplication that uses both SWT and Swing.

Restriction: Motif is no longer supported and will be removed in a later release.

Related links:

• Reference Information in the Eclipse information center: http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/awt/SWT_AWT.html

• Set up information is available on the Oracle Corporation website: https://docs.oracle.com/javase/8/docs/technotes/guides/awt/1.5/xawt.html

Default Swing key bindingsThe default key bindings that are used to change the "look and feel" of your application's GUI.

• Standard components• Structured components• Menu, Toolbar, and ToolTip components• Text components• Containers: Frames, Windows, Panes, and Icons

Standard componentsJButton

Action Metal look-and-feel keys Windows look-and-feelkeys

Motif look-and-feel keys

Navigate Forward Tab Tab Tab

Navigate backward Shift+Tab Shift+Tab Shift+Tab

Activate default Enter Enter Enter

Activate any Space bar Space bar Space bar

Activate any Alt+Char accel. key, ifdefined

Alt+Char accel. key, ifdefined


JCheckBox



Navigate forward Tab Tab Tab


Navigate within group Arrow keys Arrow keys Arrow keys

Check and Uncheck Space bar Space bar Space bar

JRadioButton




Chapter 5. Developing Java applications 65

http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/awt/SWT_AWT.html

http://help.eclipse.org/kepler/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/swt/awt/SWT_AWT.html

https://docs.oracle.com/javase/8/docs/technotes/guides/awt/1.5/xawt.html

https://docs.oracle.com/javase/8/docs/technotes/guides/awt/1.5/xawt.html






Note: Navigating with the Tab keys does not select the button you navigate to, but navigating withArrow keys does select the button.

JToggleButton







JComboBox

See also JList for other navigation keys.



Navigate out backward Shift+Tab Shift+Tab Shift+Tab

Post menu Alt+Down arrow Alt+Down arrow Alt+Down arrow

Retract menu Esc Esc Esc

Retract menu Alt+Up arrow Alt+Up arrow Alt+Up arrow

Toggle menu up or down Alt+Up arrow, Alt+Downarrow

Alt+Up arrow, Alt+Downarrow

Alt+Up arrow, Alt+Downarrow

Activate menu item Enter Enter Enter

Jump to menu itemwithout selecting it

Initial character of item Initial character of item Initial character of item

Move up or down Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

EditField

See JTextField in Text components.

JList



Navigate out forward Tab Tab Tab


Move within list Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move to beginning of list Ctrl+Home Ctrl+Home Ctrl+Home

Move to end of list Ctrl+End Ctrl+End Ctrl+End




Select all entries Ctrl+A Ctrl+A Ctrl+A

Make a selection (this willclear the previousselection)

Space bar Space bar Space bar

Extend selection up Shift+Up arrow Shift+Up arrow Shift+Up arrow

Extend selection down Shift+Down arrow Shift+Down arrow Shift+Down arrow

Extend selection to top Shift+Home Shift+Home Shift+Home

Extend selection to end Shift+End Shift+End Shift+End

Block extend up Shift+PgUp Shift+PgUp Shift+PgUp

Block extend down Shift+PgDn Shift+PgDn Shift+PgDn

Block move PgUp, PgDn PgUp, PgDn PgUp, PgDn

JSlider





Increase value Up arrow, Right arrow Up arrow, Right arrow Up arrow, Right arrow

Decrease value Left arrow, Down arrow Left arrow, Down arrow Left arrow, Down arrow

Minimum value Home Home Home

Maximum value End End End

Block increase PgUp PgUp PgUp

Block decrease PgDn PgDn PgDn

Structured componentsJTable



Navigate out forward Ctrl+Tab Ctrl+Tab Ctrl+Tab

Navigate out backward Ctrl+Shift+Tab Ctrl+Shift+Tab Ctrl+Shift+Tab

Move to next cell Tab Tab Tab

Move to next cell Right arrow Right arrow Right arrow

Move to previous cell Shift+Tab Shift+Tab Shift+Tab

Move to previous cell Left arrow Left arrow Left arrow

Wrap to next row Tab Tab Tab

Wrap to previous row Shift+Tab Shift+Tab Shift+Tab

Block move vertical PgUp, PgDn PgUp, PgDn PgUp, PgDn




Block move left Ctrl+PgUp Ctrl+PgUp Ctrl+PgUp

Block move right Ctrl+PgDn Ctrl+PgDn Ctrl+PgDn

Block extend vertical Shift+PgUp, Shift+PgDn Shift+PgUp, Shift+PgDn Shift+PgUp, Shift+PgDn

Block extend left Ctrl+Shift+PgUp Ctrl+Shift+PgUp Ctrl+Shift+PgUp

Block extend right Ctrl+Shift+PgDn Ctrl+Shift+PgDn Ctrl+Shift+PgDn

Move to first cell in row Home Home Home

Move to last cell in row End End End

Move to first cell in table Ctrl+Home Ctrl+Home Ctrl+Home

Move to last cell in table Ctrl+End Ctrl+End Ctrl+End

Select all cells Ctrl+A Ctrl+A Ctrl+A

Deselect current selection Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Deselect current selection Ctrl+Up arrow, Ctrl+Downarrow

Ctrl+Up arrow, Ctrl+Downarrow

Deselect current selection PgUp, PgDn PgUp, PgDn PgUp, PgDn

Deselect current selection Ctrl+PgUp, Ctrl+PgDn Ctrl+PgUp, Ctrl+PgDn Ctrl+PgUp, Ctrl+PgDn

Deselect current selection Home, End Home, End Home, End

Deselect current selection Ctrl+Home, Ctrl+End Ctrl+Home, Ctrl+End Ctrl+Home, Ctrl+End

Extend selection one row Shift+Up arrow, Shift+Down arrow

Shift+Up arrow, Shift+Down arrow


Extend selection onecolumn

Shift+Left arrow, Shift+Right arrow



Extend selection tobeginning or end of row

Shift+Home, Shift+End Shift+Home, Shift+End Shift+Home, Shift+End

Extend selection tobeginning or end ofcolumn

Ctrl+Shift+Home, Ctrl+Shift+End



Edit cell withoutoverriding currentcontents

F2 F2 F2

Reset cell content prior toediting

Esc Esc Esc

JTree





Expand entry Right arrow Right arrow Right arrow

Collapse entry Left arrow Left arrow Left arrow




Toggle expand andcollapse for entry

Enter Enter Enter

Move up or down oneentry

Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move to first entry Home Home Home

Move to last visible entry End End End

Block move vertical PgUp, PgDn PgUp, PgDn PgUp, PgDn

Block extend vertical Shift+PgUp, Shift+PgDn Shift+PgUp, Shift+PgDn Shift+PgUp, Shift+PgDn

Select all Ctrl+A Ctrl+A Ctrl+A

Select all Ctrl+Forward Slash (/) Ctrl+Forward Slash (/) Ctrl+Forward Slash (/)

Deselect all Ctrl+Backslash (\) Ctrl+Backslash (\) Ctrl+Backslash (\)

Single select Ctrl+Space bar Ctrl+Space bar Ctrl+Space bar

Extend selection up Shift+Up arrow Shift+Up arrow Shift+Up arrow

Extend selection down Shift+Down arrow Shift+Down arrow Shift+Down arrow

Extend selection to startof data

Shift+Home Shift+Home Shift+Home

Extend selection to end ofdata

Shift+End Shift+End Shift+End

Menu, Toolbar, and ToolTip componentsJMenuBar



Jump to menubar Alt Alt Alt

Navigate out Esc Esc Esc

Navigate out Alt Alt Alt

Navigate between itemswithin menu

Arrow keys Arrow keys Arrow keys

Select first item (if no itemselected)

F10 F10 F10

Select next item Right arrow Right arrow Right arrow

Select previous item Left arrow Left arrow Left arrow

Post menu Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Post menu Enter Enter Enter

Post menu Space bar Space bar Space bar

Un-post menu Esc Esc Esc

Un-post menu Alt Alt Alt


JMenu



Post menu F10 F10 F10

Post submenu Right arrow Right arrow Right arrow

Move to next item (wrapto top)

Down arrow Down arrow Down arrow

Move to previous item(wrap to bottom)

Up arrow Up arrow Up arrow


Retract submenu Left arrow Left arrow Left arrow

Activate default orselected item

Enter Enter Enter

JMenuItem



Navigate in Arrow keys Arrow keys Arrow keys

Navigate out Arrow keys Arrow keys Arrow keys

Activate item Enter Enter Enter

Activate item Space bar Space bar Space bar

Activate item Alt+Char accel. key, ifdefined




Retract submenu Left arrow Left arrow Left arrow

Retract submenu Esc Esc Esc

JCheckBoxMenuItem





Check or Uncheck itemand retract menu

Enter Enter Enter

JRadioButtonMenuItem








Check or Uncheck itemand retract menu

Enter Enter Enter

JPopupMenu




Close submenu Left arrow Left arrow Left arrow


Move within menu Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Activate entry Enter Enter Enter

Activate entry Space bar Space bar Space bar

JToolBar





Navigate within Arrow keys Arrow keys Arrow keys

Activate item Space bar Space bar Space bar

JToolTip



Post tip Ctrl+F1 Ctrl+F1 Ctrl+F1

Retract tip Esc Esc Esc

Retract tip Ctrl+F1 Ctrl+F1 Ctrl+F1

Text componentsJTextField





Move to previous or nextcharacter

Left arrow, Right arrow Left arrow, Right arrow Left arrow, Right arrow

Move to previous or nextword

Ctrl+Left arrow, Ctrl+Rightarrow






Move to start or end offield

Home, End Home, End Home, End

Select all Ctrl+A Ctrl+A

Deselect all Arrow keys Arrow keys Arrow keys

Extend selection left orright




Extend selection to startor end


Extend selection toprevious or next word

Ctrl+Shift+Left arrow, Ctrl+Shift+Right arrow



Copy selection Ctrl+C Ctrl+C

Cut selection Ctrl+X Ctrl+X

Paste from clipboard Ctrl+V Ctrl+V

Delete next character Delete Delete Delete

Delete previous character Backspace Backspace Backspace

Note: The Ctrl+A, Ctrl+C, Ctrl+X and Ctrl+V combinations only work on JFormattedTextFieldobjects.

JPasswordField

See JTextField in Text components for information about how to navigate or move within the fieldand make selections.

JTextArea and JEditorPane



Navigate in Tab Tab Tab



Move up or down one line Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move left or right onecharacter

Left arrow, Right arrow Left arrow, Right arrow Left arrow, Right arrow

Move to start or end ofline






Move to start or end oftext area

Ctrl+Home, Ctrl+End Ctrl+Home, Ctrl+End Ctrl+Home, Ctrl+End

Block move up or down PgUp, PgDn PgUp, PgDn PgUp, PgDn

Block move left Ctrl+PgUp Ctrl+PgUp

Block move right Ctrl+PgDn Ctrl+PgDn




Block extend up Shift+PgUp Shift+PgUp Shift+PgUp

Block extend down Shift+PgDn Shift+PgDn Shift+PgDn

Block extend left Ctrl+Shift+PgUp Ctrl+Shift+PgUp Ctrl+Shift+PgUp

Block extend right Ctrl+Shift+PgDn Ctrl+Shift+PgDn Ctrl+Shift+PgDn


Deselect all Arrow keys Arrow keys Arrow keys

Extend selection Shift+Up arrow, Shift+Down arrow



Extend selection left orright




Extend selection to startor end of line


Extend selection to startor end of text area








Copy selection Ctrl+C Ctrl+C

Cut selection Ctrl+X Ctrl+X

Paste Selected Text Ctrl+V Ctrl+V

Delete next character Delete Delete Delete

Delete previous character Backspace Backspace Backspace

Insert line break Enter Enter Enter

Insert tab Tab Tab Tab

JTextPane




Navigate out Ctrl+Tab Ctrl+Tab

Navigate out backwards Shift+Ctrl+Tab Shift+Ctrl+Tab Shift+Ctrl+Tab

Move up or down a line Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move left or right acomponent or character

Left/Right arrow Left/Right arrow Left/Right arrow

Move up or down onevertical block

PgUp, PgDn PgUp, PgDn PgUp, PgDn

Move to start or end ofline









Move to start or end ofdata



Extend selection up oneline

Shift+Up arrow Shift+Up arrow Shift+Up arrow

Extend selection downone line

Shift+Down arrow Shift+Down arrow Shift+Down arrow

Extend selection tobeginning of line

Shift+Home Shift+Home Shift+Home

Extend selection to end ofline

Shift+End Shift+End Shift+End

Extend selection tobeginning of data

Ctrl+Shift+Home Ctrl+Shift+Home Ctrl+Shift+Home

Extend selection to end ofdata

Ctrl+Shift+End Ctrl+Shift+End Ctrl+Shift+End

Extend selection left Shift+Left arrow Shift+Left arrow Shift+Left arrow

Extend selection right Shift+Right arrow Shift+Right arrow Shift+Right arrow

Extend selection up onevertical block

Shift+PgUp Shift+PgUp Shift+PgUp

Extend selection downone vertical block

Shift+PgDn Shift+PgDn Shift+PgDn

Extend selection left oneword

Ctrl+Shift+Left arrow Ctrl+Shift+Left arrow Ctrl+Shift+Left arrow

Extend selection right oneword

Ctrl+Shift+Right arrow Ctrl+Shift+Right arrow Ctrl+Shift+Right arrow

Move to next HTML link orother focusable element

Ctrl+T (letter T, not Tab) Ctrl+T (letter T, not Tab) Ctrl+T

Move to previous HTMLlink or other focusableelement

Ctrl+Shift+T (letter T, notTab)

Ctrl+Shift+T (letter T, notTab)

Ctrl+Shift+T

Activate an HTML link Ctrl+Space bar Ctrl+Space bar Ctrl+Space bar

Navigate out backwards Ctrl+Shift+Tab Ctrl+Shift+Tab Ctrl+Shift+Tab

Move up or down one line Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move left or right onecomponent or character

Left/Right arrow Left/Right arrow Left/Right arrow

Move up or down onevertical block

PgUp, PgDn PgUp, PgDn PgUp, PgDn

Move to beginning or endof line









Move to beginning or endof data


Move left or right oneblock

Ctrl+PgUp, Ctrl+PgDn Ctrl+PgUp, Ctrl+PgDn


Extend selection up ordown one line




Extend selection left orright one component orcharacter




Extend selection to startor end of line


Extend selection to startor end of data




Extend selection up ordown one vertical block

Shift+PgUp, Shift+PgDn Shift+PgUp, Shift+PgDn Shift+PgUp, Shift+PgDn





Extend selection left orright one block

Ctrl+Shift+PgUp, Ctrl+Shift+PgDn



Containers: Frames, Windows, Panes, and IconsJDesktopPane



Navigate forward amongopen applicationwindows, then desktopicons

Alt+Tab Alt+Tab Alt+Tab

Navigate forward amongopen applicationwindows, then desktopicons

Alt+Esc Alt+Esc Alt+Esc

Navigate backward amongopen applicationwindows, then desktopicons

Alt+Shift+Tab Alt+Shift+Tab Alt+Shift+Tab

Navigate forward amongopen associated windows

Ctrl+F6 Ctrl+F6 Ctrl+F6

Navigate backward amongopen associated windows

Ctrl+Shift+F6

Post menu of windowoptions

Alt+Space bar





Shift+Esc Shift+Esc


Ctrl+Space bar Ctrl+Space bar

Open window (wheniconized)

Enter Enter Enter

JOptionPane



Retract dialog Esc Esc Esc

Activate the defaultbutton (if defined)

Enter Enter Enter

JDialog



Retract dialog Esc Esc Esc


Enter Enter Enter

JScrollPane





Move up or down Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move left or right Left arrow, Right arrow Left arrow, Right arrow Left arrow, Right arrow

Move to start or end ofdata


Block move up or down PgUp, PgDn PgUp, PgDn PgUp, PgDn

Block move right Ctrl+PgDn Ctrl+PgDn Ctrl+PgDn

Block move left Ctrl+PgUp Ctrl+PgUp Ctrl+PgUp

JSplitPane










Move between panes Tab Tab Tab

Move between panes F6 F6 F6

Move to splitter bar F8 F8 F8

Resize pane vertical Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Resize pane horizontal Left arrow, Right arrow Left arrow, Right arrow Left arrow, Right arrow

Resize to min or max Home, End Home, End Home, End

JTabbedPane




Navigate out Ctrl+Tab Ctrl+Tab Ctrl+Tab

Move to tab left or right Left arrow, Right arrow Left arrow, Right arrow Left arrow, Right arrow

Move to tab above orbelow

Up arrow, Down arrow Up arrow, Down arrow Up arrow, Down arrow

Move from tab to page Ctrl+Down arrow Ctrl+Down arrow Ctrl+Down arrow

Move from page to tab Ctrl+Up arrow Ctrl+Up arrow Ctrl+Up arrow

Move from page toprevious page

Ctrl+PgUp Ctrl+PgUp Ctrl+PgUp

Move from page to nextpage

Ctrl+PgDn Ctrl+PgDn Ctrl+PgDn

JFrame



Navigate out Alt+Esc Alt+Esc Alt+Esc

Display window menu Alt+Space bar Alt+Space bar Alt+Space bar


Enter Enter Enter

JInternalFrame



Open (Restore) Ctrl+F5 Ctrl+F5 Ctrl+F5

Open (Restore) Alt+F5 Alt+F5 Alt+F5

Open (Restore) Enter Enter Enter

Close Ctrl+F5 Ctrl+F5 Ctrl+F5

Close Alt+F5 Alt+F5 Alt+F5




Move Ctrl+F7 Ctrl+F7 Ctrl+F7

Move Alt+F7 Alt+F7 Alt+F7

Resize Ctrl+F8 Ctrl+F8 Ctrl+F8

Resize Alt+F8 Alt+F8 Alt+F8

Minimize Ctrl+F9 Ctrl+F9 Ctrl+F9

Minimize Alt+F9 Alt+F9 Alt+F9

Display window menu Alt+Space bar Alt+Space bar Alt+Space bar


Enter Enter Enter

JWindow




Enter Enter Enter

Distributing Java applicationsJava applications typically consist of class, resource, and data files.

When you distribute a Java application, your software package probably consists of the following parts:

• Your own class, resource, and data files• Optional: On AIX systems, the AIX Runtime Environment• An installation procedure or program

On AIX systems:

To run your application, a user needs the IBM SDK, Java Technology Edition. The IBM SDK, JavaTechnology Edition software contains a Runtime Environment. However, you cannot assume that yourusers have the IBM SDK, Java Technology Edition software installed.

Your application can either make the SDK for AIX a prerequisite or include a version of the SDK that isspecifically for the purpose of redistribution. The SDK for AIX license does not allow you toredistribute any of the SDK files installed in the installation directory by installp. You canredistribute the SDK files in the j832redist.tar, j864redist.tar or j832redist.tar.gz, j864redist.tar.gzfiles (after viewing and agreeing to the associated online license) available from the AIX downloadpage of the Java SDK developer center.

On Linux systems:


Your IBM SDK, Java Technology Edition software license does not allow you to redistribute any of theSDK files with your application. You must ensure that a licensed version of the IBM SDK, JavaTechnology Edition is installed on the target workstation.


https://developer.ibm.com/javasdk/support/aix-download-service/

On Windows systems:



On z/OS systems:


When distributing your application for use on a z/OS platform, make the z/OS SDK a prerequisite,because z/OS does not have a separate runtime environment.


Chapter 6. Running Java applicationsJava applications can be started using the java launcher or through JNI. Settings are passed to a Javaapplication using command-line arguments, environment variables, and properties files.

Purpose

The java and javaw tools start a Java application by starting a Java Runtime Environment and loading aspecified class.

On AIX, Linux, and Windows systems, the javaw command is identical to java, except that javaw has noassociated console window. Use javaw when you do not want a command prompt window to bedisplayed. The javaw launcher displays a window with error information if it fails.

On z/OS systems, the javaw command is identical to java, and is supported on z/OS for compatibilitywith other platforms.

Note: On Windows systems, a process has two code pages: the ANSI (or Windows) code page and theOEM (or DOS) code page. By default, javaw uses the ANSI code page whereas java, launched from thecommand prompt, typically uses the OEM code page. Use the -Dconsole.encoding property to specifythe code page to use for output from the java or javaw command. For example, -Dconsole.encoding=Cp1252 causes all output to be in the Windows ANSI Latin1 code page (1252).

Usage

The JVM searches for the initial class (and other classes that are used) in three sets of locations: thebootstrap class path, the installed extensions, and the user class path. The arguments that you specifyafter the class name or .jar file name are passed to the main function.

The java and javaw commands have the following syntax:

java [options] <class> [arguments]java [options] -jar <file.jar> [arguments]javaw [options] <class> [arguments]javaw [options] -jar <file.jar> [arguments]

Parameters[options]

Command-line options to be passed to the runtime environment.<class>

Startup class. The class must contain a main() method.<file.jar>

Name of the .jar file to start. It is used only with the -jar option. The named .jar file must containclass and resource files for the application, with the startup class indicated by the Main-Classmanifest header.

[arguments]Command-line arguments to be passed to the main() function of the startup class.


Obtaining version informationYou obtain the IBM build and version number for your Java installation by using the -version or -fullversion options. You can also obtain version information for all jar files on the class path by usingthe -Xjarversion option.

Procedure

1. Open a shell or command prompt.2. Type the following command:

java -version

From service refresh 5 fix pack 5, the output is similar to the following extract:

java version "1.8.0_151"Java(TM) SE Runtime Environment (build 8.0.5.5 - pxa6480sr5fp5-20171109_02(SR5 FP5))IBM J9 VM (build 2.9, JRE 1.8.0 Linux amd64-64 Compressed References 20171102_369060 (JIT enabled, AOT enabled)OpenJ9 - 7ade437OMR - 1b656cbIBM - 59c3d96)JCL - 20171109_01 based on Oracle jdk8u151-b12

Most notably, the line starting OpenJ9 replaces the lines J9VM and JIT in the output from earlierrefreshes, because these components are now contributed to the Eclipse Foundation under theEclipse OpenJ9 project.

Before service refresh 5:

java version "1.8.0"Java(TM) SE Runtime Environment (build pap3280-20140729_01(SR1))IBM J9 VM (build 2.8, JRE 1.8.0 AIX ppc-32 20140725_207966 (JIT enabled, AOT enabled)J9VM - R28_jvm.28_20140725_0202_B207966JIT - tr.r14.java_20140714_68218.03GC - R28_jvm.28_20140725_0202_B207966J9CL - 20140725_207966)JCL - 20140722_01 based on Oracle jdk8u20-b20

The output provides the following information:

• The first line indicates the Java standard edition class library level.• The second line includes information about the build level of the runtime environment. Service

refresh (SR), fix pack (FP), and APAR (Interim fixes only) numbers are appended to the build string.• The third line indicates the build level of the Java virtual machine.• Subsequent lines provide detailed information about the levels of components that make up the

runtime environment.

Exact build dates and versions change for service refreshes and fix packs.3. To obtain only the build information for the runtime environment, type the following command:

java -fullversion

System output that is similar to the following extract is displayed:

java full version "JRE 1.8.0 IBM Windows 64 build pwa6480-20170614_01"



What to do nextYou can also list the version information for all available jar files on the class path, the boot class path,and in the extensions directory. Type the following command:

java -Xjarversion -version

System output that is similar to the following extract is displayed:

java version "1.8.0_141"Java(TM) SE Runtime Environment (build pxi3280sr5-20170614_01(SR5))IBM J9 VM (build 2.9, JRE 1.8.0 Linux x86-32 20170612_352001 (JIT enabled, AOT enabled)J9VM - 19c7794JIT - tr.open_20170612_104744_b26aea0OMR - 559b08c)JCL - 20170613_01 based on Oracle jdk8u141-b11/opt/ibm/java-i386-80/jre/lib/se-service.jar/opt/ibm/java-i386-80/jre/lib/cuda4j.jar/opt/ibm/java-i386-80/jre/lib/math.jar/opt/ibm/java-i386-80/jre/lib/ibmorb.jar/opt/ibm/java-i386-80/jre/lib/ibmorbapi.jar/opt/ibm/java-i386-80/jre/lib/ibmcfw.jar VERSION: CCX.CF [o1537.01]...

The information available varies for each jar file and is taken from the Implementation-Version andBuild-Level properties in the manifest of the jar file.

Specifying Java options and system propertiesYou can specify Java options and system properties directly on the command line. You can also use anoptions file or an environment variable.

About this taskThe sequence of the Java options on the command line defines which options take precedence duringstartup. Rightmost options have precedence over leftmost options. In the following example, the -Xjitoption takes precedence:

java -Xint -Xjit myClass

For more information about how the Eclipse OpenJ9 VM constructs the runtime environment at startup,see Specifying command line options.

Use one of more of the options that are shown in the procedure to customize your runtime environment.

Procedure

1. Specify options or system properties on the command line, as shown in the following example:

java -Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump MyJavaClass

2. Create an environment variable that is called IBM_JAVA_OPTIONS containing the options, as shown inthe following example:

export IBM_JAVA_OPTIONS="-Dmysysprop1=tcpip -Dmysysprop2=wait -Xdisablejavadump"

On Windows, use set instead of export.3. Create a file that contains the options, and specify that file on the command line or in theIBM_JAVA_OPTIONS environment variable by using the -Xoptionsfile parameter. For moreinformation about constructing this file, see -Xoptionsfile.

Chapter 6. Running Java applications 83

Standard optionsThe definitions for the standard options.

For the Eclipse OpenJ9 VM, see OpenJ9 command-line options for information about nonstandard (-X)options.

-agentlib:<libname>[=<options>]Loads a native agent library <libname>; for example -agentlib:jdwp. For more information, specify-agentlib:jdwp=help on the command line.

-agentpath:libname[=<options>]Loads a native agent library by full path name.

-cp <directories and .zip or .jar files separated by :>(Use ; on Windows systems)Sets the search path for application classes and resources. If -classpath and -cp are not used andthe CLASSPATH environment variable is not set, the user class path is, by default, the currentdirectory (.).

-classpath <directories and .zip or .jar files separated by :>(Use ; on Windows systems)Sets the search path for application classes and resources. If -classpath and -cp are not used andthe CLASSPATH environment variable is not set, the user class path is, by default, the currentdirectory (.).

-D<property name>=<value>Sets a system property.

-help or -?Prints a usage message.

-javaagent:<jarpath>[=<options>]Load a Java programming language agent. For more information, see the java.lang.instrumentAPI documentation.

-jre-restrict-searchInclude user private Java runtime environments in the version search.

-no-jre-restrict-searchExclude user private Java runtime environments in the version search.

-showversionPrints product version and continues.

-verbose:<option>[,<option>...]Enables verbose output. Separate multiple options using commas. The available options are:class

Writes an entry to stderr for each class that is loaded.gc

Writes verbose garbage collection information to stderr. Use -Xverbosegclog (see -Xverbosegclog option in the OpenJ9 user documentation for more information) to control theoutput. See Verbose garbage collection logging in the J9 VM reference for more information.

jniWrites information to stderr describing the JNI services called by the application and JVM.

sizesWrites information to stderr describing the active memory usage settings.

stackWrites information to stderr describing the Java and C stack usage for each thread.

-versionPrints product version.

-version:<value>Requires the specified version to run, for example 1.5.


-XPrints help on nonstandard options.

Support for bidirectional dataThe runtime environment includes support for bidirectional data, where text is written from right to leftand also from left to right.

Within the Java runtime environment, character data is manipulated as Unicode UTF-16 values. However,character data outside the Java runtime environment frequently conforms to different encodings. For thisreason, file input/output operations, along with the conversion of bytes to characters and back, alsoinvolve conversion from an external encoding to UTF-16 and back. You can specify the external encoding,for example in the constructor of an InputStreamReader or OutputStreamWriter object, or rely on adefault encoding.

Through its implementation of the Unicode standard, the Java runtime environment supports manylanguages, which have various alphabets or scripts.These languages include Arabic and Hebrew, whosescripts are written from right to left. Because Arabic and Hebrew text is frequently mixed with otherlanguages (and numbers), which are written from left to right, the Java runtime environment must be ableto handle bidirectional data.

Bidirectional data is more variable than non-bidirectional data because it can be stored not only in variousencodings, but also in various layouts. Each layout is a combination of rules for the ordering of thecharacters (for Arabic and Hebrew) and the shaping of Arabic letters (choosing the appropriate shape ofan Arabic letter from several possibilities).

For the same reasons that the Java runtime environment transforms data from external encodings intointernal encodings and back, it should transform bidirectional data from external layouts to the layoutused within the Java runtime environment, and back. For example, older applications might store data ina visual layout while Java APIs assume an implicit layout (also known as logical layout).

In the Java runtime environment, you can request that layout transformations are run for bidirectionaldata whenever encoding conversions are run. These transformations are disabled by default. To enablethe transformations, set the JAVABIDI system property when you start your Java application. For moreinformation, see “-DJAVABIDI” on page 88.

You can also use the Bidirectional Layout Engine API directly in your Java code. For more information, seeBidirectional support in the API reference documentation.

Related informationIntroduction to bidirectional languages

Special Arabic charactersSome Arabic characters have different representations in different code pages, and so need specialhandling during code page conversion.

Because these characters are not represented in all code pages, a normal conversion results in substitutecontrol characters (SUB), which is a loss of data.

Lam-AlefThis character is represented as a single character in code pages 420, 864, and 1046, which are usedfor visual presentation in addition to the Unicode Arabic Presentation Forms-B (uFExx range). Thischaracter is represented as two characters, Lam and Alef, in code pages 425, 1089, and 1256, whichare used for implicit representation in addition to the Unicode Arabic u06xx range.

Tail of Seen family of charactersThe visual code pages 420, 864, and 1046 represent the final form of the Seen family of characters astwo adjacent characters: the three quarters shape and the Tail. The implicit code pages 425, 1089,1256, and the Unicode Arabic u06xx range, do not represent the Tail character. In Unicode ArabicPresentation Forms-B (uFExx range), the final form for characters in the Seen family is represented asone character.


https://www.ibm.com/software/globalization/topics/languages.html

Tashkeel or diacritic characters except for ShaddaThese characters are not represented in code pages 420 and 864. Conversion of Tashkeel charactersfrom code pages 425, 1046, 1089, 1256, and Unicode to 420 or 864 results in SUB characters.

Yeh-Hamza final formCode pages 420 and 864 have no unique character for the Yeh-Hamza final form; it is represented astwo characters: Yeh final form and Hamza. In other code pages, such as 425, 1046, 1089, 1256, andUnicode, the Yeh-Hamza final form is represented as one character or two characters depending onthe user's input; whether it is one key stroke (Yeh-Hamza key) or two strokes (Yeh key + Hamza key).The conversion from the previous code pages to 420 or 864 converts the Yeh-Hamza final formcharacter to the Yeh-Hamza initial form; a special handling process must convert it to the Yeh finalform and Hamza.

To avoid the loss of such characters during conversion, various Arabic shaping options are available toproperly handle them.

Arabic shaping optionsA set of shaping options is available for each Arabic character that requires special handling so that suchcharacters are not lost during code page conversion.

Lam-Alef

During conversion from visual to implicit code pages, each Lam-Alef character is expanded to Lam plusAlef, consuming a blank space. If no blank space is available, the Lam-Alef character remains as it is inthe Unicode uFExx range, and becomes a substitute control character (SUB) when it is converted toimplicit single-byte code pages. During conversion from implicit to visual code pages, a space isgenerated by Lam-Alef compression. The position of the space that is consumed or generated depends onthe shaping option, as described in the following table:

Table 8. The position of the blank space that is consumed or generated during code page conversion ofthe Lam-Alef character

Shaping option Position of the blank space that is consumed or generated

Near Next to the character that is being converted

At Begin The beginning of the buffer (buffer[0])

At End The end of the buffer (buffer[length - 1])

Auto The beginning of the buffer relative to the orientation of the text: buffer[0] forleft-to-right text and buffer[length - 1] for right-to-left text

Resize buffer A space is not consumed or generated. Instead, the buffer size is increased to allowfor the extra character, or decreased to eliminate the space that results from thecontraction process.

Seen Tail

Near

During conversion from visual to implicit code pages, each two-character final form of the Seen familyof characters (comprising the three quarters shape character and the Tail character) is converted tothe corresponding single-character final form, with a space replacing the Tail. The space is positionednext to the Seen character. During conversion from implicit to visual code pages, each single-character final form is converted to the corresponding two-character final form, consuming the spacenext to the Seen character. If no space is available, the character is converted to the single, threequarters shape character.


Tashkeel

Auto

No special processing is done.

Customized At Begin

All Tashkeel characters except for Shadda are replaced by spaces. The resulting spaces are moved tothe beginning of the buffer (buffer[0]).

Customized At End

All Tashkeel characters except for Shadda are replaced by spaces. The resulting spaces are moved tothe end of the buffer (buffer[length - 1]).

Customized With WidthAll Tashkeel characters are converted to their corresponding spacing characters. This option is notavailable for visual to implicit code page conversion because Tashkeel characters in the Arabic u06xxrange are represented by using only non-spacing (zero-width) characters.

Customized With Zero WidthAll Tashkeel characters are converted to their corresponding non-spacing (zero-width) characters.

Keep

No special processing is done.

Yeh-Hamza

Near

During conversion from visual to implicit code pages, each Yeh character that is followed by a Hamzacharacter is converted to a Yeh-Hamza character. The space that results from the contraction processis positioned next to the Yeh-Hamza character. In conversion from implicit to visual code pages, eachYeh-Hamza character is expanded to two characters, Yeh and Hamza, consuming the space that islocated next to the original Yeh-Hamza character. If no space is available, the Yeh-Hamza character isconverted to the single character Yeh.

Known limitationsYou might come across the following issues when you use bidirectional support.

• If an application program reads from a file, or writes to a file, pieces of text that do not constitute alogical unit, the bidirectional layout transformations produce unexpected results. For example, anapplication that reads or writes characters one at a time does not benefit from the bidirectional support.This limitation is not likely to be removed in future releases.

• When unmappable characters (characters that are not valid in the declared code page) appear in single-byte character set (SBCS) data, they might cause previous and following data to be transformedindependently from one another, which can lead to unexpected results.

• When an application reads or writes a unit of text (a line for example) that crosses the boundarybetween buffers that are used by the input or output file, the bidirectional transformation might be doneindependently on the part of the text unit that is in each buffer, leading to unexpected results. When thefile is not too large, you can avoid this problem by setting the buffer size to a value that is sufficient tocontain the whole file. For example, you can specify the buffer size when you construct aBufferedInputStream or a BufferedOutputStream object.

Bidirectional system property command-line optionsUse the system property command-line options to set up your system.-D<name>=<value>

Sets a system property.


-DJAVABIDIThis system property specifies whether bidirectional layout transformations are run.

JAVABIDI=[S(<TOSHNALEYZ>)],[U(<TOSHNALEYZ>)],[C(<codepage1;codepage2;...>)]

The default value for the JAVABIDI system property is NO, which specifies that no bidirectional layouttransformations are run.

When the JAVABIDI system property is not set to NO, its value can contain 1 - 3 parts. Each partstarts with a letter identifier followed by a set of values within parentheses.

The letter identifiers are as follows:

• S: the single-byte character set (SBCS) part, which describes the bidirectional attributes of the SBCSdata that is consumed or produced by the conversions. This part designates the data as it is storedoutside the Java runtime environment.

• U: the Unicode part, which describes the bidirectional attributes of the Unicode data that isconsumed or produced by the conversions.

• C: the CodePage part, which specifies one or more encodings. If you specify this part, only data withencodings that are listed in this part are submitted to the bidirectional layout transformation. If youomit this part, the layout transformations are run for all encodings except Cp850.

Note: Applications should not try to modify the value of the JAVABIDI property after the initializationof the Java virtual machine (VM). For performance reasons, VM implementations might check thevalue of the JAVABIDI property only at start-up time, so later changes have no effect.

S and U Parts

Each part has the following format:

part_id(TOSHNALEYZ)

Where part_id is the part identifier, either S or U. TOSHNALEYZ is a list of symbols, each of which isreplaced in the command by a value, as described in the following table.

Notes:

1. The part identifier and the values are case-sensitive.2. You can use a hyphen ("-") in place of a symbol to use the default value for that symbol.

Table 9. Symbols for the S and U parts, their possible values and definitions

Symbol Meaning Valid values and their meaning Default value Languageapplicability

T Text type I (implicit)V (visual)

V (for S part)I (for U part)

Arabic and Hebrew

O Orientation L (left to right) R (right to left)C (contextual left to right)D (contextual right to left)

L Arabic and Hebrew

S Swapping Y (yes) N (no)

N (for S part)Y (for U part)

Arabic and Hebrew


Table 9. Symbols for the S and U parts, their possible values and definitions (continued)

Symbol Meaning Valid values and their meaning Default value Languageapplicability

H Text shaping N (nominal) S (shaped) I (initial) M (middle) F (final) B (isolated)

S (for S part)N (for U part)

Arabic only

N Numerals N (nominal) H (national) C (contextual)

N Arabic only

A Bidirectionalalgorithm

U (Unicode) R (roundtrip)

U Arabic and Hebrew

L Lam-Alef shapingoption

N (Near) B (At Begin) E (At End) A (Auto)R (Resize)

A Arabic only

E Seen Tail shapingoption

B (At Begin) A (Auto)N (Near) E (At End)

A Arabic only

Y Yeh-Hamzashaping option

E (At End)A (Auto)N (Near) O (One cell) B (At Begin)

A Arabic only

Z Tashkeel shapingoption

A (Auto) B (At Begin) E (At End) W (With Width)Z (Zero Width)K (Keep)

A Arabic only

C Part

This part has the following format:

C(codepage1;codepage2;...)

The variables codepage1 and codepage2 are one of the following bidirectional code pages.

Table 10. Supported bidirectional code pages

Code page Canonical name for NIO Language

Cp420 IBM-420 Arabic


Table 10. Supported bidirectional code pages (continued)

Code page Canonical name for NIO Language

Cp424 IBM-424 Hebrew






Cp1255 windows-1255 Hebrew

Cp1256 windows-1256 Arabic

ISO8859_6 ISO8859_6 Arabic

ISO8859_8 ISO8859_8 Hebrew

MacArabic MacArabic Arabic

MacHebrew MacHebrew Hebrew

Examples

JAVABIDI=U(ILYNNUNNNK),S(VLNSNUNNNK),C(Cp420)

JAVABIDI=C(Cp420),S(VLNSNUNNNK),U(ILYNNUNNNK)

The order of the part specifications is not significant.

JAVABIDI=U(ILYNNUNNNK),S(VLNSN--NK),C(Cp420;IBM-420)

The hyphens in the S part represent default values for the corresponding symbols.

JAVABIDI=C(Cp420)

Because both the S and the U parts are omitted, those parts receive default values for all the symbols.Related concepts“Support for bidirectional data” on page 85The runtime environment includes support for bidirectional data, where text is written from right to leftand also from left to right.

Globalization of the java commandThe java and javaw launchers accept arguments and class names containing any character that is in thecharacter set of the current locale. You can also specify any Unicode character in the class name andarguments by using Java escape sequences.

To do this, use the -Xargencoding command-line option.

-XargencodingUse argument encoding. To specify a Unicode character, use escape sequences in the form \u####,where # is a hexadecimal digit (0 to 9, A to F).

-Xargencoding:utf8Use UTF8 encoding.

-Xargencoding:latinUse ISO8859_1 encoding.


For example, to specify a class called HelloWorld using Unicode encoding for both capital letters, use thiscommand:

java -Xargencoding '\u0048ello\u0057orld'

The java and javaw commands provide translated messages. These messages differ based on thelocale in which Java is running. The detailed error descriptions and other debug information that isreturned by java is in English.

Running Java applications on the Little Endian (LE) Runtime Environment(Linux only)

Because Java applications are typically platform-neutral, they can run on an LE Runtime Environmentwithout modification. However, certain platform-sensitive areas of Java code might cause portabilityissues.

The following areas of Java code might cause issues when you run applications that were developed forthe 64-bit Power Systems (Big Endian) architecture on the 64-bit Power Systems LE RuntimeEnvironment:

• Application programming interfaces (APIs) in the sun.misc.Unsafe class are used to manipulate databy mixing data types. For example, the same data field is written as an integer and read as a byte.

• Similarly, APIs in the java.nio.ByteBuffer class are used to manipulate data by mixing data types.• To be used by the LE JVM, any native code for JNI methods must be ported to the LE environment.

Note: There are currently no certified hardware cryptographic accelerator devices available for the 64-bitPower Systems LE architecture. As such, the PKCS11 library is not available.


Chapter 7. Performance tuningYou can improve the performance of applications by tuning the Eclipse OpenJ9 VM, enabling hardwarefeatures, or by using specific APIs in your application code.

OpenJ9 is configured to start with a set of default options that provide the optimal runtime environmentfor Java applications with typical workloads. However, if your application is atypical, you can improveperformance by tuning the VM. Click the links to learn more about the following options:Choosing a garbage collection policy

OpenJ9 includes several garbage collection policies. To learn more about these policies and the typesof application workload that can benefit from them, see Specifying a garbage collection policy in theJ9 VM reference.

Improving startup times with class data sharingYou can share class data between running VMs, which can reduce the startup time for a VM after thecache has been created. For more information, see Class data sharing in the J9 VM reference.

Choosing large pagesIf your application allocates a large amount of memory and frequently accesses that memory, youmight want to enable large page support on your system. For more information, see Configuring largepage memory allocation in the J9 VM reference.

Native dataIf your Java application manipulates native data, consider writing your application to take advantageof methods in the Data Access Accelerator API.For more information, see The Data Access Accelerator Library in the J9 VM reference.

Optimizing for cloud environmentsIf you are running on Linux with the generational concurrent garbage collection policy, you can usethe -XX:IdleTuningMinIdleWaitTime option to tune when free memory pages are released. Thissetting can reduce memory use and therefore can help to reduce the cost of running applications in acloud environment. For more information, see -XX:IdleTuningMinIdleWaitTime in the OpenJ9 userdocumentation.

You can also improve performance by enabling hardware features or by using specific APIs in yourapplication code. Click the links to learn more about the following options:Using hardware compression acceleration devices

OpenJ9 can exploit hardware compression devices to reduce CPU consumption and shortenprocessing times. For AIX and Linux systems, see “Enabling hardware compression acceleration (AIX,Linux only)” on page 185. For IBM zEnterprise systems, see “zEnterprise Data Compression (z/OSonly)” on page 188 .

Exploiting Remote Direct Memory Access (RDMA)High performance network infrastructure that supports Remote Direct Memory Access (RDMA) isdesigned to speed up communications between applications.

• On Linux systems, existing Java socket applications can take advantage of RDMA-capable networkadapters by using extensions to the Socket and ServerSocket APIs. For more information, see“Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 193. Alternatively,you can write applications that use APIs in the jVerbs library to communicate directly over RDMA-capable infrastructure. See “The jVerbs library (Linux only)” on page 232.

• On z/OS systems, OpenJ9 supports the use of the SMC-R protocol solution to enable TCP socketapplications to transparently use RDMA. For more information, see “Shared MemoryCommunications via Remote Direct Memory Access (z/OS only)” on page 253 .

Exploiting Graphics Processing Units (GPU)On Linux and Windows systems, you can improve the performance of your Java applications byoffloading certain processing functions from your processor (CPU) to a graphics processing unit. Formore information, see Exploiting Graphics processing units.


Debugging performance problems

If you are having problems with performance, see:

• “Debugging performance problems on AIX” on page 130• “Debugging performance problems on Linux” on page 146• “Debugging performance problems on Windows” on page 158• “Debugging performance problems on z/OS” on page 174


Chapter 8. SecurityThe product contains components and tools that you can use to increase the security of your Javaapplications, for example by creating keys or using APIs such as Java Cryptography Extension (JCE).Some other features of the product, for example shared classes, also have security aspects that youshould be aware of. Read the subtopics for an overview.

If a security vulnerability is found in the IBM or Oracle code, it is documented in the Security alerts pagein the Java SDK Developer Center and a fix provided in the Fixes in the IBM Developer Kits page.

If you want to receive security bulletins and fix notifications, subscribe to the My Notifications service,selecting the appropriate document types. You can also choose to receive notifications about otherdocument types such as news and flash alerts. Security bulletins for all IBM products are published onthe IBM Product Security Incident Response blog site.

Security considerationsReview the following information so that you are aware of the security issues and solutions that areavailable in the product. Some product features affect the security of the runtime environment itself,others affect the security of applications that you run in the environment:

Attach APIYou can use the Java Attach API to connect an application to a different virtual machine. Security ishandled by Windows security mechanisms on Windows, and by POSIX file permissions on otheroperating systems. Check and secure access to ensure that only authorized users or processes canconnect to another virtual machine, or disable the Java Attach API capability by specifying a systemproperty. For more information, see Support for the Attach API in the J9 VM reference.

Dump filesBe careful when handling dump files, because they can contain all the information from yourapplication, some of which might be sensitive. For example, dump files can contain personalinformation or bank account details. For more information about dump files, see Diagnosticcomponent in the J9 VM reference.

JConsoleJConsole is a graphical tool which you can use to monitor and manage the behavior of Javaapplications. You can specify options to disable password authentication and encryption, allowing anyJMX agent to connect to your Java application. Use these non-secure options only in a developmentor testing environment. For more information, see Using JConsole in the J9 VM reference.

Securing XML processingIf your application takes untrusted XML, XSD or XSL files as input, you can enforce specific limitsduring Java API for XML (JAXP) processing to protect your application from malformed data. For moreinformation, see “Securing Java API for XML processing (JAXP) against malformed input” on page265.

Shared classesYou can share class data between virtual machines by storing it in a cache, which can reduce virtualstorage consumption and startup time for virtual machines.

• Access to the shared class cache is limited by operating system permissions and Java securitypermissions. For more information, see the Cache security section of the following topic: Overviewof class data sharing in the J9 VM reference.

• You can also restrict access to the cache by specifying the cache location, the permissions for thatlocation, and by including user names in cache names. For more information, see Cache naming inthe J9 VM reference.


https://www.ibm.com/developerworks/java/jdk/alerts

https://www.ibm.com/developerworks/java/jdk/fixes/

https://www-01.ibm.com/software/support/einfo.html

https://www.ibm.com/blogs/psirt/

Java securityBy default, Java security is not enabled, which allows applets or untrusted code to run withoutrestrictions. For example, read or write to a file, read process memory, or start new processes. Inorder to secure Java the SecurityManager needs to be enabled, which can be achieved byspecifying the -Djava.security.manager system property on the command line when you startyour application.

Security settings for the Java Plug-in and Web Start, in the Java Control PanelYou use the Java Control Panel to control how Java applications that are embedded in a browser, orlaunched from a browser, run on your computer. Some of the settings in the Java Control Panel affectsecurity, for example you can prevent all Java applications from running in, or from, a browser. Formore information, see Java Control Panel, but note that there are some differences in the IBMimplementation of the control panel. For example, there is no Update tab.

Security componentsThe SDK provides security components that contain APIs and tools for securing your Javaapplications. These components cover areas such as cryptography, keys and certification, accesscontrol, secure communication, and authentication, by using standards such as the following:

• Java Certification Path (CertPath)• Java Authentication and Authorization Service (JAAS)• Java Cryptography Extension (JCE)• Java Generic Security Services (JGSS)• Java Secure Socket Extension 2 (JSSE2)• PKCS 11• Simple Authentication and Security Layer (SASL)• Java XML Digital Signature and Encryption

For more information, see “Security components and tools” on page 96.Upgrading

An SDK upgrade can overwrite configuration files and security policy files. Back up these files in caseyou need to restore them after the upgrade.

OtherThe following topics might also contain information about security:

• “Known issues and limitations” on page 99• “What's new” on page 12• “Migrating from earlier releases of the IBM SDK, Java Technology Edition” on page 39• IBM SDK, Java Technology Edition, Version 8: Current news: support information that is not

available at the time of publication of this documentation

The IBM SDK is based on Java Technology developed by Oracle Corporation, so also refer to thedocumentation available on the Oracle website. For example:

• Java SE Security• Secure Coding Guidelines for Java SE• Security Manager API• RMI security considerations

Security components and toolsThe security components and utilities that are listed here are shipped with IBM SDK, Java TechnologyEdition, Version 8. The security components contain the IBM implementation of various securityalgorithms and mechanisms.

The following list summarizes the IBM security components and utilities that are available with the SDK:


https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/jcp.html


https://www.oracle.com/technetwork/java/javase/overview/index.html


https://www.oracle.com/technetwork/java/seccodeguide-139067.html

https://docs.oracle.com/javase/8/docs/api/java/lang/SecurityManager.html

https://docs.oracle.com/javase/8/docs/technotes/guides/jndi/jndi-rmi.html#SEC

• Java Certification path• Java Authentication and Authorization Service (JAAS)• Java Cryptographic Extension (JCE)• Java Cryptographic Extension (JCE) FIPS• IBM SecureRandom provider• Java Generic Security Services (JGSS)• Java Secure Socket Extension 2 (JSSE2)• Public Key Cryptographic Standard (PKCS #11) Implementation Provider• Simple Authentication and Security Layer (SASL)• IBM Key Certificate Management• Java XML Digital Signature• Java XML Encryption• IBM Common Access Card (CAC) provider• iKeyman• Keytool

Further information about IBM security, including samples and API documentation, can be found here:https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.security.component.80.doc/security-component/security-overview.html

By default, the IBM® SDK, on all platforms, provides strong but limited JCE jurisdiction policy files. If youwant to use unlimited jurisdiction policy files, you must obtain these files from Oracle.

Note: The IBM XML implementation is deprecated in IBM® SDK, Java Technology Edition, Version 8 andwill be replaced by the Oracle XML implementation in a future release.

Chapter 8. Security 97

https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.security.component.80.doc/security-component/security-overview.html

https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.security.component.80.doc/security-component/security-overview.html

Chapter 9. Troubleshooting and supportUse the information in this section to help you diagnose problems, run diagnostic tools, or submit aproblem report.

Submitting problem reportsIf you find a problem with the IBM SDK, make a report through the product that supplied the SDK. On AIX,Linux, and Windows, you can also make a report through the operating system if there is no bundlingproduct.

The SDK for HP-UX, Solaris, Mac OS, and Windows is only available as part of an IBM product or service. Ifyou have an IBM support contract, consider Reporting the problem to IBM support. More informationabout support contracts for IBM products can be found in the Software Support Handbook.

On z/OS, the 31-bit and 64-bit Java SDKs are bundled with WebSphere® Application Server. These SDKsare also delivered as stand-alone z/OS program products:

• IBM 31-bit SDK for z/OS, Java Technology Edition, V8 (5655-DGG)• IBM 64-bit SDK for z/OS, Java Technology Edition, V8 (5655-DGH)

If you are using these standalone products, support is available through the normal z/OS operatingsystem support structure. For more information, seehttps://www.ibm.com/systems/z/os/zos/tools/java/index.html.

On all operating systems, there are several things you can try before submitting a Java problem to IBM. Auseful starting point is the support page in the Java SDK developer center. The "How do I..." sectioncontains information about troubleshooting and looking for known problems. If you are unable to fix theproblem, and you have an IBM support contract, follow the instructions on that page for reporting theproblem to IBM Support.

More information about support contracts for IBM products can be found in the Software SupportHandbook.

If you do not have an IBM support contract, you might get informal support through other methods,described in the "How do I..." section.

Known issues and limitationsKnown issues or limitations that you might encounter in specific system environments, or configurations.

The problems described in this topic might not be limitations with the release. Instructions are providedto work around problems, where possible.

Error when using JavaFX application launcher

The JavaFX application launcher is a feature provided by Oracle in Java SE V8. However, JavaFX is notcurrently supported by the IBM release. An error occurs if you attempt to run a JavaFX applicationfrom the command-line.

Chinese characters stored as ? in an Oracle database

When you configure an Oracle database to use the ZHS16GBK character set, some Chinese charactersor symbols that are encoded with the GBK character set are incorrectly stored as a question mark (?).This problem is caused by an incompatibility of the GBK undefined code range Unicode mapping


https://developer.ibm.com/javasdk/support/

http://www14.software.ibm.com/webapp/set2/sas/f/handbook/home.html

https://www.ibm.com/systems/z/os/zos/tools/java/index.html


https://developer.ibm.com/javasdk/support/



between the Oracle ZHS16GBK character set and the IBM GBK converter. To fix this problem, use anew code page, MS936A, by including the following system property when you start the JVM:

-Dfile.encoding=MS936A

For IBM WebSphere Application Server users, this problem might occur when web applications thatuse JDBC configure Oracle as the WebSphere Application Server data source. To fix this problem, usea new code page, MS936A, as follows:

1. Use the following system property when you start the JVM:

-Dfile.encoding=MS936A

2. Add the following lines to the WAS_HOME/properties/converter.properties file, whereWAS_HOME is your WebSphere Application Server installation directory.

GBK=MS936AGB2312=MS936A

Accessibility issues with the policytool graphical user interface (GUI) utility

The Policy File Creation and Management Tool, policytool, is provided in two formats: command-line utility and GUI utility. For consistency, IBM is including the standard Oracle utilities with thisrelease. The GUI utility has a slightly different look and feel to the equivalent tool provided in earlierversions of the release. If you have issues with the accessibility features of this utility, use thecommand-line version instead.

Accessibility issues with the jconsole utility

For consistency, IBM has included the standard Oracle jconsole utility from version 8 of theproduct. The graphical user interface of this utility has a slightly different look and feel to theequivalent tool provided in earlier versions. If you have issues with the accessibility features of thereplacement utility, use the IBM Health Center tool, which has equivalent function. For moreinformation about this IBM Monitoring and Diagnostic tool, see “Health Center” on page 178.

JDBC V4.2 incompatible drivers

Version 4.2 of this data access application programming interface is available with the IBM SDK. JDBCV4.2 functions properly only with supported JDBC drivers. If you use an incompatible driver, or anolder driver, an exception of type SQLFeatureNotSupportedException is thrown. Consult theproduct documentation for your driver to check whether you have the correct version. For example, toaccess an Apache Derby database, the Derby driver version must be 10.10.2.1.1597921 or later.

These known issues and limitations also apply to earlier releases:

Unexpected XSLT error on extension elements or extension functions when security is enabled

Any attempt to use extension elements or extension functions when security is enabled, results in ajavax.xml.transform.TransformerException error during XSLT processing.

The following XSLT message is generated when extension functions are used: Use of the extensionfunction '<method name>' is not allowed when Java security is enabled. Tooverride this, set the com.ibm.xtq.processor.overrideSecureProcessing propertyto true. This override only affects XSLT processing.

The following XSLT message is generated when extension elements are used: Use of the extensionelement '<element name>' is not allowed when Java security is enabled. Tooverride this, set the com.ibm.xtq.processor.overrideSecureProcessing propertyto true. This override only affects XSLT processing.

To allow extensions when security is enabled, set thecom.ibm.xtq.processor.overrideSecureProcessing system property to true. For moreinformation about this system property, see “-Dcom.ibm.xtq.processor.overrideSecureProcessing” onpage 271.


Issues and limitations on AIXKnown issues or limitations that you might encounter in specific AIX system environments, orconfigurations.

Desktop API

If one or more GNOME libraries are not available, the Desktop API might not work.

Graphics terminal

If you are using this release on 64-bit AIX, with UTF-8 locale and the local graphics terminal uses theUTF-8 locale, you might see an exception from java.io.Console.

On AIX 6.1, the exception is:

IZ97736: CANNOT CONTROL TTY ATTRIBUTE BY USING 64BIT PROGRAM

For more information, see the APAR https://www-304.ibm.com/support/docview.wss?uid=isg1IZ97736.

On AIX 7.1, the exception is:

IZ97912: CANNOT CONTROL TTY ATTRIBUTE BY USING 64BIT PROGRAM

For more information, see the APAR https://www-304.ibm.com/support/docview.wss?uid=isg1IZ97912.

Switching input methods

You must close the candidate window and commit pre-edited strings before you switch the InputMethod (IM) by using the IM selection menu. If you open the IM selection menu without either closingthe candidate window or committing a pre-edited string, cancel the menu, then close the candidatewindow, and finally commit the pre-edited string. You can then try to switch the IM again.

Displaying DBCS characters in a JFrame

DBCS characters might not display correctly in the title of a JFrame. To avoid this problem, set thelanguage in the terminal login screen instead of in a prompt after you have logged in.

Unicode Shift_JIS code page alias

Note: This limitation applies to Japanese users only.

The Unicode code page alias "\u30b7\u30d5\u30c8\u7b26\u53f7\u5316\u8868\u73fe" forShift_JIS has been removed. If you use this code page in your applications, replace it with Shift_JIS.

Swing application problems with GTK look and feel

Swing applications might not render GUI components correctly if the GTK libraries are not correctlyinstalled on your system. This issue is not seen on Version 7, which is not sensitive to the sameconditions. If you receive console messages that indicate libraries are missing, install those librariesto rectify the problem.

UDP datagram socket failure

By default on AIX, the system-wide udp_sendspace setting is 9216 bytes. If you are trying to sendbuffer data with a length greater than 9216 bytes, a UDP Datagram socket failure occurs. You canincrease the size of the buffer by using the setSendBufferSize() function available inDatagramSocket.socket.setSendBufferSize(SEND_SIZE);.

Color palette changes on Abstract Windows Toolkit (AWT)

The Common Desktop Environment (CDE) color palette now supports high color settings. As a result,the default SystemColor settings for the Abstract Windows Toolkit (AWT) are now the same as MotifToolkit on earlier releases. To revert to the earlier AWT color palette settings, set theibm.awt.mediumColor system property to true. For more information, see -Dibm.awt.mediumColoroption.

Chapter 9. Troubleshooting and support 101

https://www-304.ibm.com/support/docview.wss?uid=isg1IZ97736




Issues and limitations on LinuxKnown issues or limitations that you might encounter in specific Linux system environments, orconfigurations.

XRender drawing issue: no text on AWT components

If you are using Ubuntu version 12.04 with an Intel graphics chip, and text is not displayed on AWTcomponents, specify the following property on the command-line when you start your Javaapplication: -Dsun.java2d.xrender=false. This property avoids the issue by disabling theXRender extension.

This limitation is due to Bug 48045 in X-Window.

Java NIO.2 file system problems on a ReiserFS file system

Heavily loaded systems with a ReiserFS file system might experience problems when using the JavaNIO.2 file system facilities. The cause of the problem is with the ReiserFS file system, and results ininconsistent information being passed to the Java technology subsystem. To avoid this issue, use analternative file system.

Desktop API

If one or more GNOME libraries are not available, the Desktop API might not work.




GUI applications, such as the JConsole monitoring tool, on 64-bit Ubuntu with a 32-bit JVM

When running a 32-bit JVM on a 64-bit Ubuntu system, GUI applications do not start because someAWT libraries are missing. To fix the problem, install the 32-bit libraries provided in the ia32-libspackage:

sudo apt-get install ia32-libs

If the libraries are not available, the following exception is thrown:

Exception in thread "main" java.lang.UnsatisfiedLinkError: awt (An exception was pending after running JNI_OnLoad) at java.lang.ClassLoader.loadLibraryWithPath(ClassLoader.java:993) at java.lang.ClassLoader.loadLibraryWithClassLoader(ClassLoader.java:962) at java.lang.System.loadLibrary(System.java:465) ... lines removed for clarity ...

If problems are encountered with DNS name resolution, install the package lib32nss-mdns.

Globalization on Ubuntu

Note: This limitation applies to Chinese, Korean, and Japanese language users of Ubuntu only.

Chinese, Korean, and Japanese locales do not display the correct fonts if CJK fonts are not installed.

GTK Look and Feel and NullPointerException exception

Note: This limitation applies to DBCS environments only.

If your application fails with a NullPointerException exception when using the GTK Look andFeel, unset the GNOME_DESKTOP_SESSION_ID environment variable.

Position for ibus composition window is incorrect on Red Hat Enterprise Linux version 6

This problem occurs when using the ibus input method. The effect is that the Input Method Editor(IME) composition window is not displayed under the cursor position. An additional effect is that thecomposition window does not follow the xterm window if it is moved.


https://bugs.freedesktop.org/show_bug.cgi?id=48045

This problem affects IBM POWER and s390 platforms only.

If you encounter this problem, refer to RHBA-2011:0518-1.

BIOS settings on AMD64 SMP systems

The Node memory interleaving BIOS setting must be set to DISABLED. Otherwise,unpredictable results might occur, including application crashes and hangs. This instruction is inaccordance with recommendations from AMD.

JNI calls with more than eight parameters on PPC platforms

PPC platforms only: If your code uses JNI calls, and any specific call has more than eight float ordouble parameters, your JNI C code must be compiled with the gcc-2.95.3 Free Software Foundation(FSF) level of GNU C Compiler (GCC) or later.

Input Method Editor (IME) character composition

If you are using Smart Common Input Method/Intelligent Input Bus (SCIM/IBus) as the input methodserver, complete the character composition before you change focus. Do not change focus rapidlywith key input because your application might not receive the key event properly.

Note: This limitation applies only to Chinese, Korean, and Japanese language users.

Runtime crash when running on SUSE Linux Enterprise Server (SLES) 11 service pack 2 (Linux only)When running on SLES 11 service pack 2, with a kernel level before 3.0.31-0.9.1, the JVM can crash.This problem occurs when calling the operating system APIs mmap() and munmap(). Sometimes thememory returned from mmap() overlaps with a previous allocation that was not freed. To fix thisproblem, upgrade to a version of the kernel that is the same or later than Jun-01-20123.0.31-0.9.1.

Swing application problems with GTK look and feel

Swing applications might not render GUI components correctly if the GTK libraries are not correctlyinstalled on your system. This issue is not seen on Version 7, which is not sensitive to the sameconditions. If you receive console messages that indicate libraries are missing, install those librariesto rectify the problem.

Issues and limitations on WindowsKnown issues or limitations that you might encounter in specific Windows system environments, orconfigurations.

IPv6 support on Windows XP and Windows 2003

Version 7 introduced a new NIO.2 application programming interface (API) for asynchronous input/output (IO). However, sockets created with the NIO.2 APIs support only IPv4 network interfaces onthe Windows XP and Windows 2003 platforms. The IBM implementation of NIO.2 is consistent withthis behavior.

Although sockets created with the earlier IBM NIO APIs or java.net can support either IPv4 or IPv6network interfaces on Windows 2003 and Windows XP, this capability is deprecated in Version 7 andno longer supported in this release.




Font problems in supported locales

This version supports the following locales:

• Bengali (bn_IN)• Malayalam (ml_IN)


http://rhn.redhat.com/errata/RHBA-2011-0518.html

• Oriya (or_IN)

However, the fonts from these locales might not work on AWT components.

Use of sockets with IPv6

The 64-bit SDK supports IPv6. However, because the current IPv6 support in Windows is not dual-stack, the release emulates dual-stack behavior on an IPv6 enabled system. The emulation meansthat your application might use up to twice as many sockets.

To disable the emulation, disable IPv6 support by setting the system propertyjava.net.preferIPv4Stack to true.

Input Method Editor (IME)

When working with an Input Method Editor (IME), before using the workspace for any other operationensure that you complete the character composition and select the candidate.

If a user types text in an AWT TextArea while using an Input Method Editor (IME), then resizes theapplication window before committing the text, the text is committed automatically.

DBCS characters

If you are typing DBCS characters in a JTextArea, JTextField, or JFileChooser, switching from someChinese IMEs (in particular, Chinese Internal Code and Zhengma) to Intelligent ABC IME might causea core dump to be produced.

BIOS settings on AMD64 SMP systems

The Node memory interleaving BIOS setting must be set to DISABLED. Otherwise,unpredictable results might occur, including application crashes and hangs. This instruction is inaccordance with recommendations from AMD.

Inconsistent timers on multicore or multiprocessor systems

On some multicore or multiprocessor systems, System.nanoTime() might not increasemonotonically. Alternatively, System.nanoTime() might exhibit unexpectedly large time jumps.This behavior might be caused by a limitation in the Windows functionQueryPerformanceCounter(). For more information, see Microsoft Knowledge Base article:Programs that use the QueryPerformanceCounter function may perform poorly.

Issues and limitations on z/OSKnown issues or limitations that you might encounter in specific z/OS system environments, orconfigurations.

Java 2D rendering pipeline

The improved Java 2D graphics pipeline, based on the X11 XRender extension, accelerates renderingusing hardware support. However, the XRender library is not supported on the z/OS operating system,and is therefore not available in this release. If the new pipeline is not present, Java 2D uses theexisting X11 pipeline.

Limitation of class path length

If there are more than 2031 characters in your class path, the shell truncates your class path to 2031characters. If you need a class path longer than 2031 characters, use the extension class loaderoption to refer to directories containing your .jar files, for example:

-Djava.ext.dirs=<directory>

Where <directory> is the directory containing your .jar files.


https://support.microsoft.com/kb/895980

Other issues

If you find a problem that you have been unable to solve, see https://www.ibm.com/systems/z/os/zos/tools/java/index.html for advice and information about how to raise problems.

Problem determinationProblem determination helps you understand the kind of fault you have, and the appropriate course ofaction.

When you know what kind of problem you have, you might do one or more of the following tasks:

• Fix the problem• Find a good workaround• Collect the necessary data with which to generate a bug report to IBM

If your application runs on more than one platform and is exhibiting the same problem on them all, readthe section about the platform to which you have the easiest access.

First steps in problem determinationBefore proceeding in problem determination, there are some initial questions to be answered.

Have you changed anything recently?If you have changed, added, or removed software or hardware just before the problem occurred, backout the change and see if the problem persists.

What else is running on the workstation?If you have other software, including a firewall, try switching it off to see if the problem persists.

Is the problem reproducible on the same workstation?Knowing that this defect occurs every time the described steps are taken is helpful because itindicates a straightforward programming error. If the problem occurs at alternate times, oroccasionally, thread interaction and timing problems in general are much more likely.

Is the problem reproducible on another workstation?A problem that is not evident on another workstation might help you find the cause. A difference inhardware might make the problem disappear; for example, the number of processors. Also,differences in the operating system and application software installed might make a difference to theJVM. For example, the visibility of a race condition in the JVM or a user Java application might beinfluenced by the speed at which certain operations are performed by the system.

Does the problem occur on multiple platforms?If the problem occurs only on one platform, it might be related to a platform-specific part of the JVM.Alternatively, it might be related to local code used inside a user application. If the problem occurs onmultiple platforms, the problem might be related to the user Java application. Alternatively, it mightbe related to a cross-platform part of the JVM such as the Java Swing API. Some problems might beevident only on particular hardware; for example, Intel 32 bit architecture. A problem on particularhardware might indicate a JIT problem.

Can you reproduce the problem with the latest Service Refresh?The problem might also have been fixed in a recent service refresh. Make sure that you are using thelatest service refresh for your environment. Check the latest downloads that are available on the JavaSDK developer center..

Are you using a supported Operating System (OS) with the latest patches installed?It is important to use an OS or distribution that supports the JVM and to have the latest patches foroperating system components. For example, upgrading system libraries can solve problems.Moreover, later versions of system software can provide a richer set of diagnostic information. SeeSetting up and checking environment topics in the “Problem determination” on page 105 section.

Does turning off the JIT or AOT help?If turning off the JIT or AOT prevents the problem, there might be a problem with the JIT or AOT. Theproblem can also indicate a race condition in your Java application that surfaces only in certain






conditions. If the problem is intermittent, reducing the JIT compilation threshold to 0 might helpreproduce the problem more consistently. (See Diagnosing a JIT or AOT problem in the J9 VMreference.)

Have you tried reinstalling the JVM or other software and rebuilding relevant application files?Some problems occur from a damaged or incorrect installation of the JVM or other software. It is alsopossible that an application might have inconsistent versions of binary files or packages.Inconsistency is likely in a development or testing environment and could potentially be solved bygetting a fresh build or installation.

Is the problem particular to a multiprocessor (or SMP) platform? If you are working on amultiprocessor platform, does the problem still exist on a uniprocessor platform?

This information is valuable to IBM Service.Have you installed the latest patches for other software that interacts with the JVM? For example,the IBM WebSphere Application Server and DB2®.

The problem might be related to configuration of the JVM in a larger environment, and might havebeen solved already in a fix pack. Is the problem reproducible when the latest patches have beeninstalled?

Have you enabled core dumps?Core dumps are essential to enable IBM Service to debug a problem. Core dumps are enabled bydefault for the Java process. See Using dump agents for details. The operating system settings mightalso need to be in place to enable the dump to be generated and to ensure that it is complete. Detailsof the required operating system settings are contained in the relevant problem determination sectionfor the platform.

What logging information is available?The JVM logs information about problems as they occur. You can enable more detailed logging, andcontrol where the logging information goes. For more details, see OpenJ9 VM Messages.

AIX problem determinationThis section describes problem determination on AIX.

Setting up and checking your environment on AIXSet up the correct environment for the AIX Java virtual machine (VM) to run correctly during AIXinstallation from either the installp image or the product with which it is packaged.

Note that the 64-bit Java VM can work on a 32-bit kernel if the hardware is 64-bit. In that case, you mustenable a 64-bit application environment using smitty:System Environments -> Enable 64-bitApplication Environment.

Occasionally the configuration process does not work correctly, or the environment might be altered,affecting the operation of the VM. In these conditions, you can make checks to ensure that the Java VM'srequired settings are in place:

1. Check that the SDK and Java runtime files were installed in the correct location and that the correctpermissions are set. Test the java and javac commands to ensure they are executable.

The default installation directory is listed in “Conventions” on page 36. For developer kits packagedwith other products, the installation directory might be different; consult your product documentation.

2. Ensure that the PATH environment variable points to the correct Java executable (using whichjava), or that the application you are using is pointing to the correct Java directory. You mustinclude /usr/java8/jre/bin:/usr/java8/bin in your PATH environment variable . If it is not present, add itby using export PATH=/usr/java8/jre/bin:/usr/java8/bin:$PATH.

3. Ensure that the LANG environment variable is set to a supported locale. You can find the languageenvironment in use using echo $LANG, which should report one of the supported locales asdocumented in the User Guide shipped with the SDK.

4. Ensure that all the prerequisite AIX maintenance and APARs have been installed. The prerequisiteAPARs and filesets will have been checked during an installation by using smitty or installp. Youcan find the list of prerequisites in the User Guide that is shipped with the SDK. Use lslpp -l to find


the list of current filesets. Use instfix -i -k <apar number> to test for the presence of an APARand instfix -i | grep _ML to find the installed maintenance level.

Directory requirements

The system dump agent must be configured to target a directory.

Both the user running the Java application and the group the user is in must have execute and writepermissions for that directory. This can be set using the IBM_COREDIR environment variable.

The system dump agents can also be configured on the command line. See Using dump agents for moreinformation.

Enabling full AIX core filesYou must have the correct operating system settings to ensure that the system dump (process core file) isgenerated when a failure occurs.

When a failure occurs, the most important diagnostic data to obtain is the system dump. The majority ofthe JVM settings are suitable by default but to ensure the system dump is generated on AIX, you mustcheck a number of operating system settings.

If you do not enable full core dumps the only native thread details stored in the system dump are thedetails for the thread that was running when the JVM crashed. With full core dumps enabled, all nativethread details are stored in the system dump.

Operating system settings

1. To obtain full system dumps, set the following ulimit options for the user running the JVM:

ulimit -c unlimited turn on corefiles with unlimited sizeulimit -n unlimited allows an unlimited number of open file descriptorsulimit -d unlimited sets the user data limit to unlimitedulimit -f unlimited sets the file limit to unlimited

For more information about ulimit settings, see Setting system resource limits on AIX and Linuxsystems in the J9 VM reference.

When the JVM generates a system dump it overrides the soft limit and uses the hard limit. You candisable the generation of system dumps by using the -Xdump:system:none command-lineoption.

2. Set the following options in smitty:

a. Start smitty as rootb. Go to System Environments > Change/Show Characteristics of Operating Systemc. Set the Enable full CORE dump option to TRUEd. Ensure that the Use pre-430 style CORE dump option is set to FALSE

Alternatively, you can run:

chdev -l sys0 -a fullcore='true' -a pre430core='false'

Java Virtual Machine settingsThe JVM settings should be in place by default, but you can check these settings using the followinginstructions.

To check that the JVM is set to produce a system dump when a failure occurs, run the followingcommand:

java -Xdump:what

which should produce something like the following output:


-Xdump:system: events=gpf+abort, label=/u/cbailey/core.%Y%m%d.%H%M%S.%pid.dmp, range=1..0, priority=999, request=serial

At least events=gpf must be set to generate a system dump when a failure occurs.

You can change and set options using the command-line option -Xdump, which is described in Usingdump agents in the OpenJ9 user documentation.

Available disk spaceYou must ensure that the disk space available is sufficient for the system dump to be written to it. Thesystem dump is written to the directory specified in the label option. Up to 2 GB of free space mightbe required for 32-bit system dumps and over 6 GB for 64-bit system dumps. The Java process musthave the correct permissions to write to the location specified in the label option.

Maximum file sizeThe target file system for the system dump must support file sizes that are as large as the systemdump, as well as an appropriate ulimit. If the supported file size is too small, dumps might betruncated to the maximum supported file size. To check your current file size and learn how to createa filesystem with a file size greater than 2GB, see https://www.ibm.com/support/docview.wss?uid=isg3T1023245.

General debugging techniquesA short guide to the diagnostic tools provided by the JVM and the AIX commands that can be useful whendiagnosing problems with the AIX JVM.

In addition to this information, you can obtain AIX publications from the IBM System p and AIXinformation on IBM Knowledge Center. Of particular interest are:

• Performance management and tuning• Programming for AIX

You might also find Developing and Porting C and C++ Applications on AIX (SG24-5674) helpful, availablefrom: http://www.redbooks.ibm.com.

There are several diagnostic tools available with the JVM to help diagnose problems:

• Starting Javadumps, see Using Javadumps in the J9 VM reference.• Starting Heapdumps, see Using Heapdumps in the J9 VM reference.• Starting system dumps, see Dump viewer in the OpenJ9 user documentation.

AIX provides various commands and tools that can be useful in diagnosing problems.

AIX debugging commandsList of debugging commands.bindprocessor –q

Lists the available processors.bootinfo –K

Shows if the 64–bit kernel is active.bootinfo –y

Shows whether the hardware in use is 32-bit or 64-bit.dbx

The AIX debugger. Examples of use can be found throughout this set of topics.

The SDK also includes a dbx Plug-in for additional help debugging Java applications. See “DBX Plug-in” on page 117 for more information.


https://www.ibm.com/support/docview.wss?uid=isg3T1023245


https://www.ibm.com/support/knowledgecenter/ssw_aix_72/com.ibm.aix.base/welcome_72.htm

https://www.ibm.com/support/knowledgecenter/ssw_aix_72/com.ibm.aix.base/welcome_72.htm

http://www.redbooks.ibm.com

iostat

Reports the read and write rate to all disks. This tool can help determine if disk workload should bespread across multiple disks. iostat also reports the same CPU activity that vmstat does.

lsattrDetails characteristics and values for devices in the system.

To obtain the type and speed of processor 0, use:

# lsattr -El proc0state enable Processor state Falsetype PowerPC_POWER3 Processor type Falsefrequency 200000000 Processor Speed False

Processor 0 might not be available to you if you are using an LPAR. Use bindprocessor -q to list theavailable processors.

lsconfShows basic hardware and configuration details. See “lsconf” on page 110 for an example.

netpmonuses the trace facility to obtain a detailed picture of network activity during a time interval. See“netpmon” on page 111 for an example.

netstatShows information about socket and network memory usage. Use this command with the –m optionto look at mbuf memory usage. See “netstat” on page 112 for more details.

nmonGives much of the same information as topas, but saves the information to a file in Lotus® 123 andExcel formats.

The download site is https://www.ibm.com/developerworks/mydeveloperworks/wikis/home/wiki/Power%20Systems/page/nmon. The information that is collected includes CPU, disk, network,adapter statistics, kernel counters, memory, and the top process information.

noConfigures network attributes. For example, to see the size of the wall use:

# no -a | grep wall thewall = 524288# no -o thewall = 1000000

The wall is the maximum amount of memory assigned to the network memory buffer.ps

Shows process information. See “ps” on page 112 for more details.sar

Shows usage by multiple CPUs. See “sar” on page 114 for more details.svmon

Captures snapshots of virtual memory. See “svmon” on page 114 for more details.tprof

The tprof command reports CPU usage for individual programs and the system as a whole. Thecommand is useful for analyzing a Java program that might be CPU-bound. You can determine whichsections of the program are most heavily using the CPU.

The tprof command can charge, or record, CPU time to object files, processes, threads andsubroutines (user mode, kernel mode and shared library). The tprof command can also charge CPUtime to individual lines of source code, or to individual instructions in the source code. Charging CPUtime to subroutines is called profiling and charging CPU time to source program lines is called micro-profiling.

topasA graphical interface to system activity. See “topas” on page 116 for more details.


https://www.ibm.com/developerworks/mydeveloperworks/wikis/home/wiki/Power%20Systems/page/nmon

https://www.ibm.com/developerworks/mydeveloperworks/wikis/home/wiki/Power%20Systems/page/nmon

traceCaptures a sequential flow of time-stamped system events. The trace is a valuable tool for observingsystem and application execution. See “trace” on page 116 for more details.

trussTraces the following details for a process: system calls, dynamically loaded user-level function calls,received signals, and incurred machine faults.

vmstatReports statistics about kernel threads in the run and wait queue, memory paging, interrupts, systemcalls, context switches, and CPU activity. See “vmstat” on page 117 for more details.

lsconfThis command shows basic hardware and configuration details.

For example:

System Model: IBM,7040-681Machine Serial Number: 835A7AAProcessor Type: PowerPC_POWER4Number Of Processors: 8Processor Clock Speed: 1100 MHzCPU Type: 64-bitKernel Type: 64-bitLPAR Info: 5 JAVADEV1 - kukichaMemory Size: 10240 MBGood Memory Size: 10240 MBPlatform Firmware level: 3H041021Firmware Version: IBM,RG041021_d78e05_sConsole Login: enableAuto Restart: trueFull Core: true Network Information Host Name: bb1p5-1.hursley.ibm.com IP Address: 9.20.136.92 Sub Netmask: 255.255.255.128 Gateway: 9.20.136.1 Name Server: 9.20.136.11 Domain Name: hursley.ibm.com Paging Space Information Total Paging Space: 512MB Percent Used: 21% Volume Groups Information============================================================================== rootvg:PV_NAME PV STATE TOTAL PPs FREE PPs FREE DISTRIBUTIONhdisk0 active 546 290 109..06..04..65..106============================================================================== INSTALLED RESOURCE LIST

The following resources are installed on the machine.+/- = Added or deleted from Resource List.* = Diagnostic support not available. Model Architecture: chrp Model Implementation: Multiple Processor, PCI bus + sys0 System Object+ sysplanar0 System Planar* vio0 Virtual I/O Bus* vsa0 LPAR Virtual Serial Adapter* vty0 Asynchronous Terminal* pci12 U1.5-P2 PCI Bus* pci11 U1.5-P2 PCI Bus* pci10 U1.5-P2 PCI Bus* pci9 U1.5-P1 PCI Bus* pci14 U1.5-P1 PCI Bus+ scsi0 U1.5-P1/Z2 Wide/Ultra-3 SCSI I/O Controller+ hdisk0 U1.5-P1/Z2-A8 16 Bit LVD SCSI Disk Drive (73400 MB)+ ses0 U1.5-P1/Z2-Af SCSI Enclosure Services Device* pci8 U1.5-P1 PCI Bus* pci7 U1.5-P1 PCI Bus* pci6 U1.9-P2 PCI Bus


* pci5 U1.9-P2 PCI Bus* pci4 U1.9-P2 PCI Bus* pci13 U1.9-P2 PCI Bus+ ent0 U1.9-P2-I3/E1 Gigabit Ethernet-SX PCI Adapter (14100401)* pci3 U1.9-P1 PCI Bus* pci2 U1.9-P1 PCI Bus* pci1 U1.9-P1 PCI Bus* pci0 U1.18-P1-H2 PCI Bus+ L2cache0 L2 Cache+ mem0 Memory+ proc11 U1.18-P1-C3 Processor+ proc12 U1.18-P1-C3 Processor+ proc13 U1.18-P1-C3 Processor+ proc16 U1.18-P1-C4 Processor+ proc17 U1.18-P1-C4 Processor+ proc18 U1.18-P1-C4 Processor+ proc22 U1.18-P1-C4 Processor+ proc23 U1.18-P1-C4 Processor

netpmonThis command uses the trace facility to obtain a detailed picture of network activity during a time interval.

It also displays process CPU statistics that show:

• The total amount of CPU time used by this process,• The CPU usage for the process as a percentage of total time• The total time that this process spent executing network-related code.

For example,

netpmon -o /tmp/netpmon.log; sleep 20; trcstop

is used to look for a number of things such as CPU usage by program, first level interrupt handler, networkdevice driver statistics, and network statistics by program. Add the -t flag to produce thread level reports.The following output shows the processor view from netpmon.

Process CPU Usage Statistics:----------------------------- NetworkProcess (top 20) PID CPU Time CPU % CPU %----------------------------------------------------------java 12192 2.0277 5.061 1.370UNKNOWN 13758 0.8588 2.144 0.000gil 1806 0.0699 0.174 0.174UNKNOWN 18136 0.0635 0.159 0.000dtgreet 3678 0.0376 0.094 0.000swapper 0 0.0138 0.034 0.000trcstop 18460 0.0121 0.030 0.000sleep 18458 0.0061 0.015 0.000

The adapter usage is shown here:

----------- Xmit ----------- -------- Recv ---------Device Pkts/s Bytes/s Util QLen Pkts/s Bytes/s Demux------------------------------------------------------------------------------token ring 0 288.95 22678 0.0%518.498 552.84 36761 0.0222...DEVICE: token ring 0recv packets: 11074 recv sizes (bytes): avg 66.5 min 52 max 1514 sdev 15.1 recv times (msec): avg 0.008 min 0.005 max 0.029 sdev 0.001 demux times (msec): avg 0.040 min 0.009 max 0.650 sdev 0.028 xmit packets: 5788 xmit sizes (bytes): avg 78.5 min 62 max 1514 sdev 32.0 xmit times (msec): avg 1794.434 min 0.083 max 6443.266 sdev 2013.966

The following example shows the java extract:

PROCESS: java PID: 12192reads: 2700 read sizes (bytes): avg 8192.0 min 8192 max 8192 sdev 0.0 read times (msec): avg 184.061 min 12.430 max 2137.371 sdev 259.156writes: 3000


write sizes (bytes): avg 21.3 min 5 max 56 sdev 17.6 write times (msec): avg 0.081 min 0.054 max 11.426 sdev 0.211

To see a thread level report, add the -t as shown here.

netpmon -O so -t -o /tmp/netpmon_so_thread.txt; sleep 20; trcstop

The following extract shows the thread output:

THREAD TID: 114559reads: 9 read sizes (bytes): avg 8192.0 min 8192 max 8192 sdev 0.0 read times (msec): avg 988.850 min 19.082 max 2106.933 sdev 810.518writes: 10 write sizes (bytes): avg 21.3 min 5 max 56 sdev 17.6 write times (msec): avg 0.389 min 0.059 max 3.321 sdev 0.977

You can also request that less information is gathered. For example to look at socket level traffic use the"-O so" option:

netpmon -O so -o /tmp/netpmon_so.txt; sleep 20; trcstop

netstatUse this command with the –m option to look at mbuf memory usage, which will tell you something aboutsocket and network memory usage.

By default, the extended netstat statistics are turned off in /etc/tc.net with the line:

/usr/sbin/no -o extendednetstats=0 >>/dev/null 2>&1

To enable these statistics, change to extendednetstats=1 and reboot. You can also try to set thisdirectly with no. When using netstat -m, pipe to page because the first information is some of the mostimportant:

67 mbufs in use:64 mbuf cluster pages in use272 Kbytes allocated to mbufs0 requests for mbufs denied0 calls to protocol drain routines0 sockets not created because sockthresh was reached

-- At the end of the file:Streams mblk statistic failures:0 high priority mblk failures0 medium priority mblk failures0 low priority mblk failures

Use netstat -i <interval to collect data> to look at network usage and possible droppedpackets.

psShows process information.

The Process Status (ps) is used to monitor:

• A process.• Whether the process is still consuming CPU cycles.• Which threads of a process are still running.

To start ps monitoring a process, type:

ps -fp <PID>

Your output should be:

UID PID PPID C STIME TTY TIME CMD user12 29730 27936 0 21 Jun - 12:26 java StartCruise


WhereUID

The userid of the process owner. The login name is printed under the -f flag.PPID

The Parent Process ID.PID

The Process ID.C

CPU utilization, incremented each time the system clock ticks and the process is found to be running.The value is decayed by the scheduler by dividing it by 2 every second. For the sched_other policy,CPU utilization is used in determining process scheduling priority. Large values indicate a CPUintensive process and result in lower process priority whereas small values indicate an I/O intensiveprocess and result in a more favorable priority.

STIMEThe start time of the process, given in hours, minutes, and seconds. The start time of a process begunmore than twenty-four hours before the ps inquiry is executed is given in months and days.

TTYThe controlling workstation for the process.

TIMEThe total execution time for the process.

CMDThe full command name and its parameters.

To see which threads are still running, type:

ps -mp <PID> -o THREAD

Your output should be:

USER PID PPID TID ST CP PRI SC WCHAN F TT BND COMMAND user12 29730 27936 - A 4 60 8 * 200001 pts/10 0 java StartCruise - - - 31823 S 0 60 1 e6007cbc 8400400 - 0 - - - - 44183 S 0 60 1 e600acbc 8400400 - 0 - - - - 83405 S 2 60 1 50c72558 400400 - 0 - - - - 114071 S 0 60 1 e601bdbc 8400400 - 0 - - - - 116243 S 2 61 1 e601c6bc 8400400 - 0 - - - - 133137 S 0 60 1 e60208bc 8400400 - 0 - - - - 138275 S 0 60 1 e6021cbc 8400400 - 0 - - - - 140587 S 0 60 1 e60225bc 8400400 - 0 -

WhereUSER

The user name of the person running the process.TID

The Kernel Thread ID of each thread.ST

The state of the thread:O

Nonexistent.R

Running.S

Sleeping.W

Swapped.


ZCanceled.

TStopped.

CPCPU utilization of the thread.

PRIPriority of the thread.

SCSuspend count.

ARCHONWait channel.

FFlags.

TATControlling terminal.

BANDCPU to which thread is bound.

For more details, see the manual page for ps.

sarUse the sar command to check the balance of processor usage for multiple processors.

In this following example, two samples are taken every 5 seconds on a twin-processor system that isrunning at 80% utilization.

# sar -u -P ALL 5 2

AIX aix4prt 0 5 000544144C00 02/09/01

15:29:32 cpu %usr %sys %wio %idle15:29:37 0 34 46 0 20 1 32 47 0 21 - 33 47 0 2015:29:42 0 31 48 0 21 1 35 42 0 22 - 33 45 0 22

Average 0 32 47 0 20 1 34 45 0 22 - 33 46 0 21

svmonThis command captures snapshots of virtual memory. Using svmon to take snapshots of the memoryusage of a process over regular intervals allows you to monitor memory usage.

The following usage of svmon generates regular snapshots of a process memory usage and writes theoutput to a file:

svmon -P [process id] -m -r -i [interval] > output.file

Gives output like:

Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd 25084 AppS 78907 1570 182 67840 N Y Vsid Esid Type Description Inuse Pin Pgsp Virtual Addr Range 2c7ea 3 work shmat/mmap 36678 0 0 36656 0..65513 3c80e 4 work shmat/mmap 7956 0 0 7956 0..65515 5cd36 5 work shmat/mmap 7946 0 0 7946 0..65517 14e04 6 work shmat/mmap 7151 0 0 7151 0..65519 7001c d work shared library text 6781 0 0 736 0..65535 0 0 work kernel seg 4218 1552 182 3602 0..22017 : 65474..65535


6cb5a 7 work shmat/mmap 2157 0 0 2157 0..65461 48733 c work shmat/mmap 1244 0 0 1244 0..1243 cac3 - pers /dev/hd2:176297 1159 0 - - 0..1158 54bb5 - pers /dev/hd2:176307 473 0 - - 0..472 78b9e - pers /dev/hd2:176301 454 0 - - 0..453 58bb6 - pers /dev/hd2:176308 254 0 - - 0..253 cee2 - work 246 17 0 246 0..49746 4cbb3 - pers /dev/hd2:176305 226 0 - - 0..225 7881e - pers /dev/e2axa702-1:2048 186 0 - - 0..1856 68f5b - pers /dev/e2axa702-1:2048 185 0 - - 0..1847 28b8a - pers /dev/hd2:176299 119 0 - - 0..118 108c4 - pers /dev/e2axa702-1:1843 109 0 - - 0..1087 24b68 f work shared library data 97 0 0 78 0..1470 64bb9 - pers /dev/hd2:176311 93 0 - - 0..92 74bbd - pers /dev/hd2:176315 68 0 - - 0..67 3082d 2 work process private 68 1 0 68 65287..65535 10bc4 - pers /dev/hd2:176322 63 0 - - 0..62 50815 1 pers code,/dev/hd2:210969 9 0 - - 0..8 44bb1 - pers /dev/hd2:176303 7 0 - - 0..6 7c83e - pers /dev/e2axa702-1:2048 4 0 - - 0..300 34a6c a mmap mapped to sid 44ab0 0 0 - - 70b3d 8 mmap mapped to sid 1c866 0 0 - - 5cb36 b mmap mapped to sid 7cb5e 0 0 - - 58b37 9 mmap mapped to sid 1cb66 0 0 - - 1c7c7 - pers /dev/hd2:243801 0 0 - -

in which:

VsidSegment ID

EsidSegment ID: corresponds to virtual memory segment. The Esid maps to the Virtual Memory Managersegments. By understanding the memory model that is being used by the JVM, you can use thesevalues to determine whether you are allocating or committing memory on the native or Java heap.

TypeIdentifies the type of the segment:pers

Indicates a persistent segment.work

Indicates a working segment.clnt

Indicates a client segment.mmap

Indicates a mapped segment. This is memory allocated using mmap in a large memory modelprogram.

Description

If the segment is a persistent segment, the device name and i-node number of the associated file aredisplayed.

If the segment is a persistent segment and is associated with a log, the string log is displayed.

If the segment is a working segment, the svmon command attempts to determine the role of thesegment:kernel

The segment is used by the kernel.shared library

The segment is used for shared library text or data.process private

Private data for the process.


shmat/mmapShared memory segments that are being used for process private data, because you are using alarge memory model program.

InuseThe number of pages in real memory from this segment.

PinThe number of pages pinned from this segment.

PgspThe number of pages used on paging space by this segment. This value is relevant only for workingsegments.

Addr RangeThe range of pages that have been allocated in this segment. Addr Range displays the range of pagesthat have been allocated in each segment, whereas Inuse displays the number of pages that havebeen committed. For instance, Addr Range might detail more pages than Inuse because pages havebeen allocated that are not yet in use.

topasTopas is a useful graphical interface that will give you immediate information about system activity.

The screen looks like this:

Topas Monitor for host: aix4prt EVENTS/QUEUES FILE/TTYMon Apr 16 16:16:50 2001 Interval: 2 Cswitch 5984 Readch 4864 Syscall 15776 Writech 34280Kernel 63.1 |################## | Reads 8 Rawin 0User 36.8 |########## | Writes 2469 Ttyout 0Wait 0.0 | | Forks 0 Igets 0Idle 0.0 | | Execs 0 Namei 4 Runqueue 11.5 Dirblk 0Network KBPS I-Pack O-Pack KB-In KB-Out Waitqueue 0.0lo0 213.9 2154.2 2153.7 107.0 106.9tr0 34.7 16.9 34.4 0.9 33.8 PAGING MEMORY Faults 3862 Real,MB 1023Disk Busy% KBPS TPS KB-Read KB-Writ Steals 1580 % Comp 27.0hdisk0 0.0 0.0 0.0 0.0 0.0 PgspIn 0 % Noncomp 73.9 PgspOut 0 % Client 0.5Name PID CPU% PgSp Owner PageIn 0java 16684 83.6 35.1 root PageOut 0 PAGING SPACEjava 12192 12.7 86.2 root Sios 0 Size,MB 512lrud 1032 2.7 0.0 root % Used 1.2aixterm 19502 0.5 0.7 root NFS (calls/sec) % Free 98.7topas 6908 0.5 0.8 root ServerV2 0ksh 18148 0.0 0.7 root ClientV2 0 Press:gil 1806 0.0 0.0 root ServerV3 0 "h" for help

traceThis command captures a sequential flow of time-stamped system events. The trace is a valuable tool forobserving system and application execution.

While many of the other tools provide general statistics such as CPU and I/O utilization, the trace facilityprovides more detailed information. For example, you can find out:

• Where an event occurred in the code.• Which process caused an event to occur.• When an event took place.• How an event is affecting the system.

The curt postprocessing tool can extract information from the trace. It provides statistics on CPUutilization and process and thread activity. Another postprocessing tool is splat, the Simple PerformanceLock Analysis Tool. This tool can be used to analyze simple locks in the AIX kernel and kernel extensions.


vmstatUse this command to give multiple statistics on the system. The vmstat command reports statisticsabout kernel threads in the run and wait queue, memory paging, interrupts, system calls, contextswitches, and CPU activity.

The CPU activity is percentage breakdown of user mode, system mode, idle time, and waits for disk I/O.

The general syntax of this command is:

vmstat <time_between_samples_in_seconds> <number_of_samples> -t

A typical output looks like this:

kthr memory page faults cpu time----- ----------- ------------------------ ------------ ----------- -------- r b avm fre re pi po fr sr cy in sy cs us sy id wa hr mi se 0 0 45483 221 0 0 0 0 1 0 224 326 362 24 7 69 0 15:10:22 0 0 45483 220 0 0 0 0 0 0 159 83 53 1 1 98 0 15:10:23 2 0 45483 220 0 0 0 0 0 0 145 115 46 0 9 90 1 15:10:24

In this output, look for:

• Columns r (run queue) and b (blocked) starting to increase, especially beyond 10. This rise usuallyindicates that you have too many processes competing for CPU.

• Values in the pi, po (page in/out) columns at non-zero, possibly indicating that you are paging and needmore memory. The stack size might be set too high for some of your JVM instances.

• cs (contact switches) going very high compared to the number of processes. You might have to tune thesystem with vmtune.

• In the cpu section, us (user time) indicating the time being spent in programs. Assuming Java is the firstin the list in tprof, you need to tune the Java application. In the cpu section, if sys (system time) ishigher than expected, and you still have id (idle) time remaining, you might have lock contention. Checkthe tprof for lock–related calls in the kernel time. You might want to try multiple instances of the JVM.

• The -t flag, which adds the time for each sample at the end of the line.

DBX Plug-inThe Plug-in for the AIX DBX debugger gives DBX users enhanced features when working on Javaprocesses or core files generated by Java processes.

The Plug-in requires a version of DBX that supports the Plug-in interface. Use the DBX commandpluginload to find out whether your version of DBX has this support. All supported AIX versions includethis support.

To enable the Plug-in, use the DBX command pluginload:

pluginload /usr/java/jre/bin/libdbx_j9.so

You can also set the DBX_PLUGIN_PATH environment variable to /usr/java8/jre/bin. DBXautomatically loads any Plug-ins found in the path given.

The commands available after loading the Plug-in can be listed by running:

plugin java help

from the DBX prompt.

You can also use DBX to debug your native JNI code by specifying the full path to the Java program asfollows:

dbx /usr/java8/jre/bin/java

Under DBX, issue the command:

(dbx) run <MyAppClass>


Before you start working with DBX, you must set the $java variable. Start DBX and use the dbx setsubcommand. Setting this variable causes DBX to ignore the non-breakpoint traps generated by the JIT.You can also use a pre-edited command file by launching DBX with the -c option to specify the commandfile:

dbx -c .dbxinit

where .dbxinit is the default command file.

Although the DBX Plug-in is supplied as part of the SDK, it is not supported. However, IBM will accept bugreports.

Diagnosing crashesIf a crash occurs, you should gather some basic documents. These documents either point to the problemthat is in the application or vendor package JNI code, or help the IBM VM Support team to diagnose thefault.

Key data filesWhen a crash takes place, diagnostic data is required to help diagnose the problem.

• To find the core file, look for the location shown in the JVMDUMP messages issued by the JVM.• On Linux and AIX operating systems, process the core file using the jextract utility. For more

information, see Dump extractor (jextract).• Collect the Javadump file. To find the Javadump file, look for the location shown in the JVMDUMP

messages issued by the JVM.• Collect any stdout and stderr output generated by the Java process• Collect the system error report:

errpt -a > errpt.out

Locating the point of failureIf a stack trace is present, examining the function running at the point of failure should give you a goodindication of the code that caused the failure, and whether the failure is in the IBM JVM code, or is causedby application or vendor-supplied JNI code.

If dbx produces no stack trace, the crash might have two possible causes:

• A stack overflow of the native AIX stack.• Java code is running (either JIT compiled or interpreted)

A failing instruction reported by dbx as stwu indicates that there might have been a stack overflow. Forexample:

Segmentation fault in strlen at 0xd01733a0 ($t1)0xd01733a0 (strlen+0x08) 88ac0000 stwu r1,-80(r1)

You can check for the first cause by using the dbx command thread info and looking at the stackpointer, stack limit, and stack base values for the current thread. If the value of the stack pointer is closeto that of the stack base, you might have had a stack overflow. A stack overflow occurs because the stackon AIX grows from the stack limit downwards, towards the stack base. If the problem is a native stackoverflow, you can solve the overflow by increasing the size of the native stack from the default size of400K using the command-line option -Xss<size>. Check for a stack overflow, regardless of the failinginstruction. To reduce the possibility of a JVM crash, you must set an appropriate native stack size whenyou run a Java program using a lot of native stack.

(dbx) thread info 1 thread state-k wchan state-u k-tid mode held scope function>$t1 run running 85965 k no sys oflow

general: pthread addr = 0x302027e8 size = 0x22c


vp addr = 0x302057e4 size = 0x294 thread errno = 0 start pc = 0x10001120 joinable = yes pthread_t = 1 scheduler: kernel = user = 1 (other) event : event = 0x0 cancel = enabled, deferred, not pending stack storage: base = 0x2df23000 size = 0x1fff7b0 limit = 0x2ff227b0 sp = 0x2df2cc70

For the second cause, dbx does not understand the structure of the JIT and Interpreter stack frames, andis not capable of generating a stack trace from them. The Javadump, however, does not suffer from thislimitation and can be used to examine the stack trace. A failure in JIT-compiled code can be verified andexamined using the JIT problem determination guidance, see Diagnosing a JIT or AOT problem in the J9VM reference.

Debugging hangsThe JVM is hanging if the process is still present but is not responding in some sense.

This lack of response can be caused because:

• The process has come to a complete halt because of a deadlock condition• The process has become caught in an infinite loop• The process is running very slowly

AIX deadlocksIf the process is not taking up any CPU time, it is deadlocked. Use the ps -fp [process id] command toinvestigate whether the process is still using CPU time.

The ps command is described in “AIX debugging commands” on page 108. For example:

$ ps -fp 30450 UID PID PPID C STIME TTY TIME CMD root 30450 32332 2 15 May pts/17 12:51 java ...

If the value of 'TIME' increases over the course of a few minutes, the process is still using the CPU and isnot deadlocked.

For an explanation of deadlocks and how the Javadump tool is used to diagnose them, see LOCKS.

AIX busy hangsIf there is no deadlock between threads, consider other reasons why threads are not carrying out usefulwork.

Usually, this state occurs for one of the following reasons:

1. Threads are in a 'wait' state waiting to be 'notified' of work to be done.2. Threads are in explicit sleep cycles.3. Threads are in I/O calls waiting to do work.

The first two reasons imply a fault in the Java code, either that of the application, or that of the standardclass files included in the SDK.

The third reason, where threads are waiting (for instance, on sockets) for I/O, requires furtherinvestigation. Has the process at the other end of the I/O failed? Do any network problems exist?

To see how the javadump tool is used to diagnose loops, see THREADS. If you cannot diagnose theproblem from the javadump and if the process still seems to be using processor cycles, either it hasentered an infinite loop or it is suffering from very bad performance. Using ps -mp [process id] -oTHREAD allows individual threads in a particular process to be monitored to determine which threads are


using the CPU time. If the process has entered an infinite loop, it is likely that a small number of threadswill be using the time. For example:

$ ps -mp 43824 -o THREAD USER PID PPID TID ST CP PRI SC WCHAN F TT BND COMMAND wsuser 43824 51762 - A 66 60 77 * 200001 pts/4 - java ... - - - 4021 S 0 60 1 22c4d670 c00400 - - - - - - 11343 S 0 60 1 e6002cbc 8400400 - - - - - - 14289 S 0 60 1 22c4d670 c00400 - - - - - - 14379 S 0 60 1 22c4d670 c00400 - - -... - - - 43187 S 0 60 1 701e6114 400400 - - - - - - 43939 R 33 76 1 20039c88 c00000 - - - - - - 50275 S 0 60 1 22c4d670 c00400 - - - - - - 52477 S 0 60 1 e600ccbc 8400400 - - -... - - - 98911 S 0 60 1 7023d46c 400400 - - - - - - 99345 R 33 76 0 - 400000 - - - - - - 99877 S 0 60 1 22c4d670 c00400 - - - - - - 100661 S 0 60 1 22c4d670 c00400 - - - - - - 102599 S 0 60 1 22c4d670 c00400 - - -...

Those threads with the value 'R' under 'ST' are in the 'runnable' state, and therefore are able toaccumulate processor time. What are these threads doing? The output from ps shows the TID (KernelThread ID) for each thread. This can be mapped to the Java thread ID using dbx. The output of the dbxthread command gives an output of the form of:

thread state-k wchan state-u k-tid mode held scope function $t1 wait 0xe60196bc blocked 104099 k no sys _pthread_ksleep>$t2 run blocked 68851 k no sys _pthread_ksleep $t3 wait 0x2015a458 running 29871 k no sys pthread_mutex_lock... $t50 wait running 86077 k no sys getLinkRegister $t51 run running 43939 u no sys reverseHandle $t52 wait running 56273 k no sys getLinkRegister $t53 wait running 37797 k no sys getLinkRegister $t60 wait running 4021 k no sys getLinkRegister $t61 wait running 18791 k no sys getLinkRegister $t62 wait running 99345 k no sys getLinkRegister $t63 wait running 20995 k no sys getLinkRegister

By matching the TID value from ps to the k-tid value from the dbx thread command, you can see that thecurrently running methods in this case are reverseHandle and getLinkRegister.

Now you can use dbx to generate the C thread stack for these two threads using the dbx threadcommand for the corresponding dbx thread numbers ($tx). To obtain the full stack trace including Javaframes, map the dbx thread number to the threads pthread_t value, which is listed by the Javadump file,and can be obtained from the ExecEnv structure for each thread using the Dump Viewer. Do this with thedbx command thread info [dbx thread number], which produces an output of the form:

thread state-k wchan state-u k-tid mode held scope function $t51 run running 43939 u no sys reverseHandle general: pthread addr = 0x220c2dc0 size = 0x18c vp addr = 0x22109f94 size = 0x284 thread errno = 61 start pc = 0xf04b4e64 joinable = yes pthread_t = 3233 scheduler: kernel = user = 1 (other) event : event = 0x0 cancel = enabled, deferred, not pending stack storage: base = 0x220c8018 size = 0x40000 limit = 0x22108018 sp = 0x22106930


Showing that the TID value from ps (k-tid in dbx) corresponds to dbx thread number 51, which has apthread_t of 3233. Looking for the pthread_t in the Javadump file, you now have a full stack trace:

"Worker#31" (TID:0x36288b10, sys_thread_t:0x220c2db8) Native Thread State: ThreadID: 00003233 Reuse: 1 USER SUSPENDED Native Stack Data : base: 22107f80 pointer 22106390 used(7152) free(250896) ----- Monitors held -----java.io.OutputStreamWriter@3636a930 com.ibm.servlet.engine.webapp.BufferedWriter@3636be78 com.ibm.servlet.engine.webapp.WebAppRequestDispatcher@3636c270 com.ibm.servlet.engine.srt.SRTOutputStream@36941820 com.ibm.servlet.engine.oselistener.nativeEntry.NativeServerConnection@36d84490 JNI pinning lock

----- Native stack -----

_spin_lock_global_common pthread_mutex_lock - blocked on Heap Lock sysMonitorEnterQuicker sysMonitorEnter unpin_object unpinObj jni_ReleaseScalarArrayElements jni_ReleaseByteArrayElements Java_com_ibm_servlet_engine_oselistener_nativeEntry_NativeServerConnection_nativeWrite

------ Java stack ------ () prio=5

com.ibm.servlet.engine.oselistener.nativeEntry.NativeServerConnection.write(Compiled Code) com.ibm.servlet.engine.srp.SRPConnection.write(Compiled Code) com.ibm.servlet.engine.srt.SRTOutputStream.write(Compiled Code) java.io.OutputStreamWriter.flushBuffer(Compiled Code) java.io.OutputStreamWriter.flush(Compiled Code) java.io.PrintWriter.flush(Compiled Code) com.ibm.servlet.engine.webapp.BufferedWriter.flushChars(Compiled Code) com.ibm.servlet.engine.webapp.BufferedWriter.write(Compiled Code) java.io.Writer.write(Compiled Code) java.io.PrintWriter.write(Compiled Code) java.io.PrintWriter.write(Compiled Code) java.io.PrintWriter.print(Compiled Code) java.io.PrintWriter.println(Compiled Code)pagecompile._identifycustomer_xjsp.service(Compiled Code) javax.servlet.http.HttpServlet.service(Compiled Code) com.ibm.servlet.jsp.http.pagecompile.JSPState.service(Compiled Code) com.ibm.servlet.jsp.http.pagecompile.PageCompileServlet.doService(Compiled Code) com.ibm.servlet.jsp.http.pagecompile.PageCompileServlet.doGet(Compiled Code) javax.servlet.http.HttpServlet.service(Compiled Code) javax.servlet.http.HttpServlet.service(Compiled Code)

And, using the full stack trace, it should be possible to identify any infinite loop that might be occurring.The previous example shows the use of spin_lock_global_common, which is a busy wait on a lock,hence the use of CPU time.

Poor performance on AIXIf no infinite loop is occurring, look at the process that is working, but having bad performance.

In this case, change your focus from what individual threads are doing to what the process as a whole isdoing. This is described in the AIX documentation.

See “Debugging performance problems on AIX” on page 130 for more information about performance onAIX.

Understanding memory usageBefore you can properly diagnose memory problems on AIX, first you must have an understanding of theAIX virtual memory model and how the JVM interacts with it.

32-bit and 64-bit JVMsMost of the information in this section about altering the memory model and running out of native heap isrelevant only to the 32-bit model, because the 64-bit model does not suffer from the same kind ofmemory constraints.

The 64-bit JVM can suffer from memory leaks in the native heap, and the same methods can be used toidentify and pinpoint those leaks. The information regarding the Java heap relates to both 32-bit and 64-bit JVMs.


The 32-bit AIX Virtual Memory ModelAIX assigns a virtual address space partitioned into 16 segments of 256 MB.

Processing address space to data is managed at the segment level, so a data segment can either beshared (between processes), or private.

• Segment 0 is assigned to the kernel.• Segment 1 is application program text (static native code).• Segment 2 is the application program data and application stack (primordial thread stack and private

data).• Segments 3 to C are shared memory available to all processes.• Segment D is the shared library text.• Segment E is also shared memory and miscellaneous kernel usage.• Segment F is the data area.

The 64-bit AIX Virtual Memory ModelThe 64-bit model allows many more segments, although each segment is still 256 MB.

Again, the address space is managed at segment level, but the granularity of function for each segment ismuch finer.

With the large address space available to the 64-bit process, you are unlikely to encounter the same kindof problems with relation to native heap usage as described later in this section, although you might stillsuffer from a leak in the native heap.

Changing the Memory Model (32-bit JVM)Three memory models are available on the 32-bit JVM.

Further details of the AIX Memory Models can be found in the documentation for your release of AIX. Forexample: Large program support.


https://www.ibm.com/support/knowledgecenter/en/ssw_aix_71/com.ibm.aix.genprogc/lrg_prg_support.htm

The small memory model

With the default small memory model for an application, the application has only one segment, segment2, in which it can malloc() data and allocate additional thread stacks. It does, however, have 11segments of shared memory into which it can mmap() or shmat() data.

The large memory model

This single segment for data that is allocated by using malloc() might not be enough, so it is possible tomove the boundary between Private and Shared memory, providing more Private memory to theapplication, but reducing the amount of Shared memory. You move the boundary by altering theo_maxdata setting in the Executable Common Object File Format (XCOFF) header for an application.

You can alter the o_maxdata setting by:

• Setting the value of o_maxdata at compile time by using the -bmaxdata flag with the ld command.• Setting the o_maxdata value by using the LDR_CNTRL=MAXDATA=0xn0000000 (n segments)

environment variable.

The very large memory model

Activate the very large memory model by adding "@DSA" onto the end of the MAXDATA setting. Itprovides two additional capabilities:

• The dynamic movement of the private and shared memory boundary between a single segment and thesegment specified by the MAXDATA setting. This dynamic movement is achieved by allocating privatememory upwards from segment 3 and shared memory downwards from segment C. The privatememory area can expand upwards into a new segment if the segment is not being used by the shmat ormmap routines.

• The ability to load shared libraries into the process private area. If you specify a MAXDATA value of 0 orgreater than 0xAFFFFFFF, the process will not use global shared libraries, but load them privately.Therefore, the shmat and mmap procedures begin allocating at higher segments because they are nolonger reserved for shared libraries. In this way, the process has more contiguous memory.

Altering the MAXDATA setting applies only to a 32-bit process and not the 64-bit JVM.

The native and Java heapsThe JVM maintains two memory areas, the Java heap, and the native (or system) heap. These two heapshave different purposes and are maintained by different mechanisms.

The Java heap contains the instances of Java objects and is often referred to as 'the heap'. It is the Javaheap that is maintained by Garbage Collection, and it is the Java heap that is changed by the command-line heap settings. The Java heap is allocated using mmap, or shmat if large page support is requested.The maximum size of the Java heap is preallocated during JVM startup as one contiguous area, even if theminimum heap size setting is lower. This allocation allows the artificial heap size limit imposed by theminimum heap size setting to move toward the actual heap size limit with heap expansion. See Memorymanagement in the J9 VM reference for more information.

The native, or system heap, is allocated by using the underlying malloc and free mechanisms of theoperating system, and is used for the underlying implementation of particular Java objects; for example:

• Motif objects required by AWT and Swing• Buffers for data compression routines, which are the memory space that the Java Class Libraries

require to read or write compressed data like .zip or .jar files.• Malloc allocations by application JNI code• Compiled code generated by the Just In Time (JIT) Compiler• Threads to map to Java threads


The AIX 32-bit JVM default memory models

The AIX 5.0 Java launcher alters its MAXDATA setting in response to the command-line options tooptimize the amount of memory available to the process. The default are as follows:

-Xmx <= 2304M 0xA0000000@DSA2304M < -Xmx <= 3072M 0xB0000000@DSA3072M < -Xmx 0x0@DSA

Monitoring the native heapYou can monitor the memory usage of a process by taking a series of snapshots over regular timeintervals of the memory currently allocated and committed.

Use svmon like this:

svmon -P [pid] -m -r -i [interval] > output.filename

Use the -r flag to print the address range.

Because the Java heap is allocated using the mmap() or shmat() methods, it is clear whether memoryallocated to a specific segment of memory (under Esid) is allocated to the Java heap or the native heap.Use the type and description fields for each of the segments to determine which sections are native orJava heap. Segments that are allocated by using the mmap() or shmat() methods are listed as mmapmapped to or extended shm segments, and are in the Java heap. Segments that are allocated byusing malloc are marked as working storage, and are in the native heap. You can use this demarcationto monitor the growth of the native heap separately from the Java heap (which should be monitored usingverbose GC).

Here is the svmon output from the command that is shown previously:

------------------------------------------------------------------------------- Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd LPage 29670 java 87347 4782 5181 95830 N Y N

Vsid Esid Type Description LPage Inuse Pin Pgsp Virtual 50e9 - work - 41382 0 0 41382 Addr Range: 0..41381 9dfb - work - 28170 0 2550 30720 Addr Range: 0..30719 ddf3 3 work working storage - 9165 0 979 10140 Addr Range: 0..16944 0 0 work kernel seg - 5118 4766 1322 6420 Addr Range: 0..11167 c819 d work text or shared-lib code seg - 2038 0 283 6813 Addr Range: 0..10219 2ded f work working storage - 191 0 20 224 Addr Range: 0..4150 f5f6 - work - 41 14 4 45 Addr Range: 0..49377 6e05 2 work process private - 35 2 23 58 Addr Range: 65296..65535 1140 6 work other segments - 26 0 0 26 Addr Range: 0..32780 cdf1 - work - 2 0 0 2 Addr Range: 0..5277 e93f - work - 0 0 0 0 3164 c mmap mapped to sid 1941 - 0 0 - - 2166 - work - 0 0 0 0 496b b mmap mapped to sid 2166 - 0 0 - - b51e - clnt /dev/fslv00:44722 - 0 0 - - Addr Range: 0..207 ee1c a mmap mapped to sid e93f - 0 0 - - 1941 - work - 0 0 0 0 1081 7 mmap mapped to sid 9dfb - 0 0 - - edf5 8 mmap mapped to sid 50e9 - 0 0 - - c01b 9 mmap mapped to sid cdf1 - 0 0 - -

The actual memory values for the mmap allocated segments are stored against a Vsid of type work. Forexample, the memory usage in segment 7 (Java heap):

1081 7 mmap mapped to sid 9dfb - 0 0 - -


is described against Vsid 9dfb, which reads as follows:

9dfb - work - 28170 0 2550 30720 Addr Range: 0..30719

Native heap usageThe native heap usage will normally grow to a stable level, and then stay at around that level. You canmonitor the amount of memory committed to the native heap by observing the number of 'Inuse' pages inthe svmon output.

However, note that as JIT compiled code is allocated to the native heap with malloc(), there might be asteady slow increase in native heap usage as little used methods reach the threshold to undergo JITcompilation.

You can monitor the JIT compiling of code to avoid confusing this behavior with a memory leak. To dothis, run with the command-line option -Xjit:verbose={compileStart|compileEnd}. This commandcauses each method name to print to stderr as it is being compiled and, as it finishes compiling, thelocation in memory where the compiled code is stored.

(warm) Compiling java/lang/System.getEncoding(I)Ljava/lang/String; + (warm) java/lang/System.getEncoding(I)Ljava/lang/String; @ 0x02BA0028-0x02BA0113 (2) Compiling java/lang/String.hashCode()I + (warm) java/lang/String.hashCode()I @ 0x02BA0150-0x02BA0229 (2) Compiling java/util/HashMap.put(Ljava/lang/Object;Ljava/lang/Object;) Ljava/lang/Object; + (warm) java/util/HashMap.put(Ljava/lang/Object;Ljava/lang/Object;) Ljava/lang/Object; @ 0x02BA0270-0x02BA03F7 (2) Compiling java/lang/String.charAt(I)C + (warm) java/lang/String.charAt(I)C @ 0x02BA0430-0x02BA04AC (2) Compiling java/util/Locale.toLowerCase(Ljava/lang/String;) Ljava/lang/String; + (warm) java/util/Locale.toLowerCase(Ljava/lang/String;)Ljava/lang/String; @ 0x02BA04D0-0x02BA064C

When you have monitored how much native heap you are using, you can increase or decrease themaximum native heap available by altering the size of the Java heap. This relationship between the heapsoccurs because the process address space not used by the Java heap is available for the native heapusage.

You must increase the native heap if the process is generating errors relating to a failure to allocate nativeresources or exhaustion of process address space. These errors can take the form of a JVM internal errormessage or a detail message associated with an OutOfMemoryError. The message associated with therelevant errors will make it clear that the problem is native heap exhaustion.

Specifying MALLOCTYPEYou can set the MALLOCTYPE=watson environment variable in AIX, for use with the IBM JVM. For mostapplications the performance gains that result from using the variable are likely to be small. It particularlybenefits any application that makes heavy use of malloc calls in the code.

For more information, see the AIX documentation in IBM Knowledge Center. For example: SystemMemory Allocation Using the malloc Subsystem.

Monitoring the Java heapThe most straightforward, and often most useful, way of monitoring the Java heap is by seeing whatgarbage collection is doing.

Start verbose tracing of garbage collection by using the command-line option -verbose:gc. The optioncauses a report to be written to stderr each time garbage collection occurs. You can also direct thisoutput to a log file using:

-Xverbosegclog:[DIR_PATH][FILE_NAME]

where:

[DIR_PATH] is the directory where the file should be written [FILE_NAME] is the name of the file to write the logging to


https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.genprogc/sys_mem_alloc.htm

https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.genprogc/sys_mem_alloc.htm

See Garbage Collector diagnostic data in the J9 VM reference for more information for more informationabout verbose GC output and monitoring.

Receiving OutOfMemoryError exceptionsAn OutOfMemoryError exception results from running out of space on the Java heap or the native heap.

If the Java heap is exhausted, an error message is received indicating an OutOfMemoryError conditionwith the Java heap. If the process address space (that is, the native heap) is exhausted, an error messageis received that explains that a native allocation has failed. In either case, the problem might not be amemory leak, just that the steady state of memory use that is required is higher than that available.Therefore, the first step is to determine which heap is being exhausted and increase the size of that heap.

If the problem is occurring because of a real memory leak, increasing the heap size does not solve theproblem, but does delay the onset of the OutOfMemoryError exception or error conditions. That delay canbe helpful on production systems.

The maximum size of an object that can be allocated is limited only by available memory. The maximumnumber of array elements supported is 2^31 - 1, the maximum permitted by the Java Virtual Machinespecification. In practice, you might not be able to allocate large arrays due to available memory.Configure the total amount of memory available for objects using the -Xmx command-line option. Theselimits apply to 32-bit and 64-bit JVMs.

Is the Java or native heap exhausted?Some OutOfMemory conditions also carry an explanatory message, including an error code.

If a received OutOfMemory condition has one of these codes or messages, consulting the JVM messagesguide might point to the origin of the error, either native or Java heap.

If no error message is present, the first stage is to monitor the Java and native heap usages. The Javaheap usage can be monitored by using the -verbose:gc option. The native heap can be monitored usingsvmon.

Java heap exhaustionThe Java heap becomes exhausted when garbage collection cannot free enough objects to make a newobject allocation.

Garbage collection can free only objects that are no longer referenced by other objects, or are referencedfrom the thread stacks (see Memory management in the J9 VM reference for more details).

Java heap exhaustion can be identified from the -verbose:gc output by garbage collection occurring moreand more frequently, with less memory being freed. Eventually the JVM will fail, and the heap occupancywill be at, or almost at, 100% (See Verbose garbage collection logging in the J9 VM reference for moredetails on -verbose:gc output).

If the Java heap is being exhausted, and increasing the Java heap size does not solve the problem, thenext stage is to examine the objects that are on the heap, and look for suspect data structures that arereferencing large numbers of Java objects that should have been released. Use Heapdump Analysis, asdetailed in Using Heapdump in the J9 VM reference. Similar information can be gained by using othertools, such as JProbe and OptimizeIt.

Native heap exhaustionYou can identify native heap exhaustion by monitoring the svmon snapshot output

Each segment is 256 MB of space, which corresponds to 65535 pages. (Inuse is measured in 4 KBpages.)

If each of the segments has approximately 65535 Inuse pages, the process is suffering from native heapexhaustion. At this point, extending the native heap size might solve the problem, but you shouldinvestigate the memory usage profile to ensure that you do not have a leak.

If DB2 is running on your AIX system, you can change the application code to use the "net" (thin client)drivers and, in the case of WebSphere MQ you can use the "client" (out of process) drivers.


AIX fragmentation problems

Native heap exhaustion can also occur without the Inuse pages approaching 65535 Inuse pages. It can becaused by fragmentation of the AIX malloc heaps, which is how AIX handles the native heap of the JVM.

This OutOfMemory condition can again be identified from the svmon snapshots. Previously the importantcolumn to look at for a memory leak was the Inuse value. For problems in the AIX malloc heaps it isimportant to look at the Addr Range column. The Addr Range column details the pages that have beenallocated, whereas the Inuse column details the number of pages that are being used (committed).

It is possible that pages that have been allocated have not been released back to the process when theyhave been freed. Not releasing the pages leads to the discrepancy between the number of allocated andcommitted pages.

You have a range of environment variables to change the behavior of the malloc algorithm itself andsolve problems of this type:MALLOCTYPE=3.1

This option enables the system to move back to an older version of memory allocation scheme inwhich memory allocation is done in powers of 2. The 3.1 Malloc allocator, as opposed to the defaultalgorithm, frees pages of memory back to the system for reuse. The 3.1 allocation policy is availablefor use only with 32-bit applications.

MALLOCMULTIHEAP=heaps:n,considersizeBy default, the malloc subsystem uses a single heap. MALLOCMULTIHEAP lets users enable the useof multiple heaps of memory. Multiple heaps of memory can lead to memory fragmentation, and sothe use of this environment variable is to be avoided.

MALLOCTYPE=bucketsMalloc buckets provide an optional buckets-based extension of the default allocator. It is intendedto improve malloc performance for applications that issue large numbers of small allocationrequests. When malloc buckets are enabled, allocation requests that fall inside a predefined range ofblock sizes are processed by malloc buckets. Because of variations in memory requirements andusage, some applications might not benefit from the memory allocation scheme used by mallocbuckets. Therefore, it is not advisable to enable malloc buckets system-wide. For optimalperformance, enable and configure malloc buckets on a per-application basis.

Note: These options might cause a percentage of performance impact. Also the 3.1 malloc allocatordoes not support the Malloc Multiheap and Malloc Buckets options.

MALLOCBUCKETS=number_of_buckets:128,bucket_sizing_factor:64,blocks_per_bucket:1024:bucket_statistics: <path name of file for malloc statistics>

See MALLOCTYPE=buckets.

Tracing leaksSome useful techniques for tracing leaks are built into the JVM.

You can use the -verbose:gc option to trace leaks. For more information, see Verbose garbagecollection logging in the J9 VM reference.

Tracing application use of direct byte buffersYou can use the trace facility to diagnose the cause of excessive memory usage or OutOfMemoryErrorexceptions from applications that use direct byte buffers.

Trace points are available to help diagnose memory problems associated with the use of direct bytebuffers. The trace point IDs are j9jcl.335 to j9jcl.338, and have the following form:

• Trace point j9jcl.335 prints the amount of memory being allocated:>sun_misc_Unsafe_allocateDBBMemory(0x%zx)

• Trace point j9jcl.336 prints when memory cannot be allocated:<sun_misc_Unsafe_allocateDBBMemory -- OutOfMemory

• Trace point j9jcl.337 prints the address of the allocated memory:<sun_misc_Unsafe_allocateDBBMemory result = %p


• Trace point j9jcl.338 prints the address of the memory being freed:>sun_misc_Unsafe_freeDBBMemory(%p)

Note: Trace point IDs are subject to change without notice. To achieve reliable results, see Determiningthe tracepoint ID of a trace point in the J9 VM reference.

The trace point IDs can be used with the -Xtrace option to track down problems within a component.The -Xtrace command can direct output to a file or the console, or to internal buffers, which aredumped to a file when a problem occurs. There are many options associated with the trace facility thatcan be used to diagnose problems. See the section Tracing Java applications in the J9 VM reference. Forspecific information about setting -Xtrace options, see Controlling the trace in the J9 VM reference.

For example, to generate console output when the trace points are called, use the command:

-Xtrace:print=j9jcl.335-338

The output generated is similar to:

17:41:05.420 0x61fa00 j9jcl.335 > sun_misc_Unsafe_allocateDBBMemory(0x21d8)17:41:05.421 0x61fa00 j9jcl.337 < sun_misc_Unsafe_allocateDBBMemory result = 6B71CC1017:41:05.428*0x6b926600 j9jcl.338 > sun_misc_Unsafe_freeDBBMemory(6B71CC10)

You can also include stack traces in the console output with the command:

-Xtrace:print=j9jcl.335-338,trigger=tpnid{j9jcl.335-338,jstacktrace}

Here is an example that includes stack trace output, generated by the command:

-Xtrace:print=j9jcl.335-338,trigger=tpnid{j9jcl.335,jstacktrace},trigger=tpnid{j9jcl.338,jstacktrace}

17:54:40.377 0x2dfd00 j9jcl.335 > sun_misc_Unsafe_allocateDBBMemory(0x21d8)17:54:40.378 0x2dfd00 j9trc_aux.0 - jstacktrace:17:54:40.379 0x2dfd00 j9trc_aux.1 - [1] sun.misc.Unsafe.allocateDBBMemory (Native Method)17:54:40.380 0x2dfd00 j9trc_aux.1 - [2] java.nio.DirectByteBuffer.<init> (DirectByteBuffer.java:102)17:54:40.381 0x2dfd00 j9trc_aux.1 - [3] java.nio.ByteBuffer.allocateDirect (ByteBuffer.java:288)17:54:40.382 0x2dfd00 j9trc_aux.1 - [4] test.Test1a.allocatebuf (Test1a.java:10)17:54:40.383 0x2dfd00 j9trc_aux.1 - [5] test.Test1a.main (Test1a.java:14)17:54:40.383 0x2dfd00 j9jcl.337 < sun_misc_Unsafe_allocateDBBMemory result = 6B79D77017:54:40.388*0x6ba02300 j9jcl.338 > sun_misc_Unsafe_freeDBBMemory(6B79D770)17:54:40.389 0x6ba02300 j9trc_aux.0 - jstacktrace:17:54:40.390 0x6ba02300 j9trc_aux.1 - [1] sun.misc.Unsafe.freeDBBMemory (Native Method)17:54:40.391 0x6ba02300 j9trc_aux.1 - [2] java.nio.DirectByteBuffer$Deallocator.run (DirectByteBuffer.java:72)17:54:40.392 0x6ba02300 j9trc_aux.1 - [3] sun.misc.Cleaner.clean (Cleaner.java:125)17:54:40.393 0x6ba02300 j9trc_aux.1 - [4] java.lang.ref.ReferenceQueue.enqueue (ReferenceQueue.java:137)17:54:40.393 0x6ba02300 j9trc_aux.1 - [5] java.lang.ref.Reference.enqueueImpl (Reference.java:74)

–Xrunjnichk optionYou can use the -Xrunjnichk option to trace JNI calls that are made by your JNI code or by any JVMcomponents that use JNI. This helps you to identify incorrect uses of JNI libraries from native code andcan help you to diagnose JNI memory leaks.

JNI memory leaks occur when a JNI thread allocates objects and fails to free them. The GarbageCollector does not have enough information about the JNI thread to know when the object is no longerneeded. For more information, see The JNI and the Garbage Collector in the J9 VM reference.

Note that -Xrunjnichk is equivalent to -Xcheck:jni. See Debugging the JNI in the J9 VM reference forinformation on the -Xrunjnichk suboptions.


-Xcheck:memory optionThe -Xcheck:memory option can help you identify memory leaks inside the JVM. The -Xcheck:memoryoption traces the JVM calls to the operating system's malloc() and free() functions, and identifies anyJVM mistakes in memory allocation.

The system property -Dcom.ibm.dbgmalloc=true provides memory allocation information about classlibrary native code. Use this system property with the -Xcheck:memory:callsite=1000 option toobtain detailed information about class library callsites and their allocation sizes. Here is some sampleoutput:

total alloc | total freed | delta alloc | delta freed | high water | largest blocks| bytes | blocks| bytes | blocks| bytes | blocks| bytes | blocks| bytes | bytes | num | callsite-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+------------ 125 16000 0 0 0 0 0 0 125 16000 128 1 dbgwrapper/dbgmalloc.c:434 1 3661 1 3661 0 0 0 0 1 3661 3661 1 java/TimeZone_md.c:294 4144 18121712 4144 18121712 420 1836660 420 1836660 2 8746 4373 1 java/UnixFileSystem_md.c:373 10 124 10 124 0 0 0 0 2 55 51 1 java/jni_util.c:874 2 80797 2 80797 0 0 0 0 1 64413 64413 2 java/io_util.c:102 1 52 1 52 0 0 0 0 1 52 52 1 jli/java.c:2472 2 1872 1 264 0 0 0 0 2 1872 1608 2 net/linux_close.c:135 9 288 9 288 0 0 0 0 2 64 32 1 net/Inet6AddressImpl.c:280 99524 3260992980 99524 3260992980 10514 344503782 10515 344536549 1 32767 32767 1 net/SocketInputStream.c:93 3 24 3 24 0 0 1 8 2 16 8 1 net/linux_close.c:276 201 4824 0 0 0 0 0 0 201 4824 24 1 net/linux_close.c:149 311 1003152 261 496080 0 0 68 142128 119 651040 261360 45 zip/zip_util.c:655 311 31100 261 26100 0 0 68 6800 119 11900 100 1 zip/zip_util.c:230 243 15552 222 14208 0 0 85 5440 160 10240 64 1 zip/Inflater.c:61 1 64 1 64 0 0 0 0 1 64 64 1 zip/Deflater.c:76 146 7592 123 6396 3 156 74 3848 97 5044 52 1 zip/zip_util_md.c:75 3242 1443289 3241 1439991 25 4000 92 252856 71 262264 8192 679 zip/zip_util.c:917 311 125140 261 61724 0 0 68 17856 119 81500 32668 45 zip/zip_util.c:657 146 37376 123 31488 3 768 74 18944 97 24832 256 1 zip/zip_util_md.c:132

For more information about setting -Dcom.ibm.dbgmalloc=true, see “-Dcom.ibm.dbgmalloc” on page327.

For more information about the -Xcheck:memory option, see -Xcheck:memory in the OpenJ9 userdocumentation.

Using Heapdump to debug memory leaksYou can use Heapdump to analyze the Java Heap.

For details about analyzing the Heap, see Using Heapdumps in the J9 VM reference.

Submitting a bug reportIf the data is indicating a memory leak in native JVM code, contact the IBM service team. If the problem isJava heap exhaustion, it is much less likely to be an SDK issue, although it is still possible.

The process for raising a bug is detailed in “Submitting problem reports” on page 99, and the data thatshould be included in the bug report is listed as follows:

• Required:


1. The OutOfMemoryCondition. The error itself with any message or stack trace that accompanied it.2. -verbose:gc output. (Even if the problem is determined to be native heap exhaustion, it can be

useful to see the verbose gc output.)• As appropriate:

1. The svmon snapshot output2. The Heapdump output3. The javacore.txt file

Debugging performance problems on AIXLocating the causes of poor performance is often difficult. Although many factors can affect performance,the overall effect is generally perceived as poor response time or slow execution of your program.

Correcting one performance problem might cause more problems in another area. By finding andcorrecting a bottleneck in one place you might only shift the cause of poor performance to other areas. Toimprove performance, experiment with tuning different parameters, monitoring the effect, and retuninguntil you are satisfied that your system is performing acceptably

Finding the bottleneckThe aspects of the system that you are most interested in measuring are CPU usage and memory usage.

It is possible that even after extensive tuning efforts the CPU is not powerful enough to handle theworkload, in which case a CPU upgrade is required. Similarly, if the program is running in an environmentin which it does not have enough memory after tuning, you must increase memory size.

Given that any performance problem could be caused by any one of several factors, you must look atseveral areas to eliminate each one. First, determine which resource is constraining the system:

• CPU• Memory• Input/Output (I/O)

To do this, use the vmstat command. The vmstat command produces a compact report that details theactivity of these three areas:

> vmstat 1 10

outputs:

kthr memory page faults cpu ----- ----------- ------------------------ ------------ ----------- r b avm fre re pi po fr sr cy in sy cs us sy id wa 0 0 189898 612 0 0 0 3 11 0 178 606 424 6 1 92 1 1 0 189898 611 0 1 0 0 0 0 114 4573 122 96 4 0 0 1 0 189898 611 0 0 0 0 0 0 115 420 102 99 0 0 0 1 0 189898 611 0 0 0 0 0 0 115 425 91 99 0 0 0 1 0 189898 611 0 0 0 0 0 0 114 428 90 99 0 0 0 1 0 189898 610 0 1 0 0 0 0 117 333 102 97 3 0 0 1 0 189898 610 0 0 0 0 0 0 114 433 91 99 1 0 0 1 0 189898 610 0 0 0 0 0 0 114 429 94 99 1 0 0 1 0 189898 610 0 0 0 0 0 0 115 437 94 99 0 0 0 1 0 189898 609 0 1 0 0 0 0 116 340 99 98 2 0 0

The previous example shows a system that is CPU bound. This can be seen as the user (us) plus system(sy) CPU values either equal or are approaching 100. A system that is memory bound shows significantvalues of page in (pi) and page out (po). A system that is disk I/O bound will show an I/O wait percentage(wa) exceeding 10%. More details of vmstat can be found in “AIX debugging commands” on page 108.


CPU bottlenecksIf vmstat has shown that the system is CPU-bound, the next stage is to determine which process is usingthe most CPU time.

The recommended tool is tprof:

> tprof -s -k -x sleep 60

outputs:

Mon Nov 28 12:40:11 2010System: AIX 6.1 Node: voodoo Machine: 00455F1B4C00

Starting Command sleep 60 stopping trace collectionGenerating sleep.prof> cat sleep.profProcess Freq Total Kernel User Shared Other======= ==== ===== ====== ==== ====== =====./java 5 59.39 24.28 0.00 35.11 0.00wait 4 40.33 40.33 0.00 0.00 0.00/usr/bin/tprof 1 0.20 0.02 0.00 0.18 0.00/etc/syncd 3 0.05 0.05 0.00 0.00 0.00/usr/bin/sh 2 0.01 0.00 0.00 0.00 0.00gil 2 0.01 0.01 0.00 0.00 0.00afsd 1 0.00 0.00 0.00 0.00 0.00rpc.lockd 1 0.00 0.00 0.00 0.00 0.00swapper 1 0.00 0.00 0.00 0.00 0.00======= ==== ===== ====== ==== ====== =====Total 20 100.00 64.70 0.00 35.29 0.00

Process PID TID Total Kernel User Shared Other======= === === ===== ====== ==== ====== =====./java 467018 819317 16.68 5.55 0.00 11.13 0.00./java 467018 766019 14.30 6.30 0.00 8.00 0.00./java 467018 725211 14.28 6.24 0.00 8.04 0.00./java 467018 712827 14.11 6.16 0.00 7.94 0.00wait 20490 20491 10.24 10.24 0.00 0.00 0.00wait 8196 8197 10.19 10.19 0.00 0.00 0.00wait 12294 12295 9.98 9.98 0.00 0.00 0.00wait 16392 16393 9.92 9.92 0.00 0.00 0.00/usr/bin/tprof 421984 917717 0.20 0.02 0.00 0.18 0.00/etc/syncd 118882 204949 0.04 0.04 0.00 0.00 0.00./java 467018 843785 0.03 0.02 0.00 0.00 0.00gil 53274 73765 0.00 0.00 0.00 0.00 0.00gil 53274 61471 0.00 0.00 0.00 0.00 0.00/usr/bin/sh 397320 839883 0.00 0.00 0.00 0.00 0.00rpc.lockd 249982 434389 0.00 0.00 0.00 0.00 0.00/usr/bin/sh 397318 839881 0.00 0.00 0.00 0.00 0.00swapper 0 3 0.00 0.00 0.00 0.00 0.00afsd 65776 274495 0.00 0.00 0.00 0.00 0.00/etc/syncd 118882 258175 0.00 0.00 0.00 0.00 0.00/etc/syncd 118882 196839 0.00 0.00 0.00 0.00 0.00======= === === ===== ====== ==== ====== =====Total 100.00 64.70 0.00 35.29 0.00

Total Samples = 24749 Total Elapsed Time = 61.88s

This output shows that the Java process with Process ID (PID) 467018 is using the majority of the CPUtime. You can also see that the CPU time is being shared among four threads inside that process (ThreadIDs 819317, 766019, 725211, and 712827).

By understanding what the columns represent, you can gather an understanding of what these threadsare doing:Total

The total percentage of CPU time used by this thread or process.Kernel

The total percentage of CPU time spent by this thread or process inside Kernel routines (on behalf of arequest by the JVM or other native code).


UserThe total percentage of CPU time spent executing routines inside the executable. Because the Javaexecutable is a thin wrapper that loads the JVM from shared libraries, this CPU time is expected to bevery small or zero.

SharedThe total percentage of CPU time spent executing routines inside shared libraries. Time shown underthis category covers work done by the JVM itself, the act of JIT compiling (but not the running of thesubsequent code), and any other native JNI code.

OtherThe total percentage of CPU time not covered by Kernel, User, and Shared. In the case of a Javaprocess, this CPU time covers the execution of Java bytecodes and JIT-compiled methodsthemselves.

From the previous example, notice the Kernel and Shared values: these account for all of the CPU timeused by this process, indicating that the Java process is spending its time doing work inside the JVM (orsome other native code).

To understand what is being done during the Kernel and Shared times, the relevant sections of the tprofoutput can be analyzed.

The shared library section shows which shared libraries are being invoked:

Shared Object % ============= ======/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9gc26.so 17.42/usr/lib/libc.a[shr.o] 9.38/usr/lib/libpthreads.a[shr_xpg5.o] 6.94/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9thr26.so 1.03/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9prt26.so 0.24/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9vm26.so 0.10/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9ute26.so 0.06/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9jit26.so 0.05/usr/lib/libtrace.a[shr.o] 0.04/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9trc26.so 0.02/work/JDK/inst.images/rios_aix32_8/sdk/jre/bin/libj9hookable26.so 0.01

This section shows that almost all of the time is being spent in one particular shared library, which is partof the JVM installation: libj9gc<vm_version>.so, where <vm_version> is the version of the J9 virtualmachine (check the output of the java -version command to confirm your VM level). By understandingthe functions that the more commonly used JVM libraries carry out, it becomes possible to build a moreaccurate picture of what the threads are doing:libbcv<vm_version>.so

Bytecode Verifierlibdbg<vm_version>.so

Debug Server (used by the Java Debug Interface)libj9gc<vm_version>.so

Garbage Collectionlibj9jextract.so

The dump extractor, used by the jextract commandlibj9jit<vm_version>.so

The Just In Time (JIT) Compilerlibj9jvmti<vm_version>.so

The JVMTI interfacelibj9prt<vm_version>.so

The port layer between the JVM and the Operating Systemlibj9shr<vm_version>.so

The shared classes librarylibj9thr<vm_version>.so

The threading library


libj9ute<vm_version>.soThe trace engine

libj9vm<vm_version>.soThe core Virtual Machine

libj9zlib<vm_version>.soThe compressed file utility library

libjclscar_<vm_version>.soThe Java Class Library (JCL) support routines

In the previous example, the CPU time is being spent inside the garbage collection (GC) implementation,implying either that there is a problem in GC or that GC is running almost continuously.

Again, you can obtain a more accurate understanding of what is occurring inside thelibj9gc<vm_version>.so library during the CPU time by analyzing the relevant section of the tprofoutput:

Profile: /work/JDK/inst.images/rios_aix32_9/sdk/bin/ libj9gc26.so

Total % For All Processes (/work/JDK/inst.images/rios_aix32_9/ sdk/bin/libj9gc26.so) = 17.42

Subroutine % Source ========== ====== ====== Scheme::scanMixedObject(MM_Environment*,J9Object*) 2.67 MarkingScheme.cpp MarkingScheme::scanClass(MM_Environment*,J9Class*) 2.54 MarkingScheme.cpp .GC_ConstantPoolObjectSlotIterator::nextSlot() 1.96 jectSlotIterator.cpplelTask::handleNextWorkUnit(MM_EnvironmentModron*) 1.05 ParallelTask.cpp orkPackets::getPacket(MM_Environment*,MM_Packet**) 0.70 WorkPackets.cpp cheme::fixupRegion(J9Object*,J9Object*,bool,long&) 0.67 CompactScheme.cpp WorkPackets::putPacket(MM_Environment*,MM_Packet*) 0.47 WorkPackets.cpp rkingScheme::scanObject(MM_Environment*,J9Object*) 0.43 MarkingScheme.cpp sweepChunk(MM_Environment*,MM_ParallelSweepChunk*) 0.42 allelSweepScheme.cppment*,J9IndexableObject*,J9Object**,unsigned long) 0.38 MarkingScheme.cpp M_CompactScheme::getForwardingPtr(J9Object*) const 0.36 CompactScheme.cpp ObjectHeapIteratorAddressOrderedList::nextObject() 0.33 dressOrderedList.cppckets::getInputPacketFromOverflow(MM_Environment*) 0.32 WorkPackets.cpp .MM_WorkStack::popNoWait(MM_Environment*) 0.31 WorkStack.cpp WorkPackets::getInputPacketNoWait(MM_Environment*) 0.29 WorkPackets.cpp canReferenceMixedObject(MM_Environment*,J9Object*) 0.29 MarkingScheme.cpp MarkingScheme::markClass(MM_Environment*,J9Class*) 0.27 MarkingScheme.cpp ._ptrgl 0.26 ptrgl.s _MarkingScheme::initializeMarkMap(MM_Environment*) 0.25 MarkingScheme.cpp .MM_HeapVirtualMemory::getHeapBase() 0.23 eapVirtualMemory.cpp

This output shows that the most-used functions are:

MarkingScheme::scanMixedObject(MM_Environment*,J9Object*) 2.67 MarkingScheme.cpp MarkingScheme::scanClass(MM_Environment*,J9Class*) 2.54 MarkingScheme.cppObjectSlotIterator.GC_ConstantPoolObjectSlotIterator::nextSlot() 1.96 ObjectSlotIterator.cppParallelTask::handleNextWorkUnit(MM_EnvironmentModron*) 1.05 ParallelTask.cpp

The values show that the time is being spent during the Mark phase of GC. Because the output alsocontains references to the Compact and Sweep phases, the GC is probably completing but that it isoccurring continuously. You could confirm that likelihood by running with -verbosegc enabled.

The same methodology shown previously can be used for any case where the majority of the CPU time isshown to be in the Kernel and Shared columns. If, however, the CPU time is classed as being Other, adifferent methodology is required because tprof does not contain a section that correctly details whichJava methods are being run.

In the case of CPU time being attributed to Other, you can use a Javadump to determine the stack tracefor the TIDs shown to be taking the CPU time, and therefore provide an idea of the work that it is doing.Map the value of TID shown in the tprof output to the correct thread in the Javadump by taking the


tprof TID, which is stored in decimal, and convert it to hexadecimal. The hexadecimal value is shown asthe native ID in the Javadump.

For the previous example:

Process PID TID Total Kernel User Shared Other======= === === ===== ====== ==== ====== =====./java 7018 819317 16.68 5.55 0.00 11.13 0.00

This thread is the one using the most CPU; the TID in decimal is 819317. This value is C8075 inhexadecimal, which can be seen in the Javadump:

3XMTHREADINFO "main" (TID:0x300E3500, sys_thread_t:0x30010734, state:R, native ID:0x000C8075) prio=54XESTACKTRACE at java/lang/Runtime.gc(Native Method)4XESTACKTRACE at java/lang/System.gc(System.java:274)4XESTACKTRACE at GCTest.main(GCTest.java:5)

These entries show that, in this case, the thread is calling GC, and explains the time spent in thelibj9gc<vm_version>.so shared library.

Memory bottlenecksIf the results of vmstat point to a memory bottleneck, you must find out which processes are using largeamounts of memory, and which, if any, of these are growing.

Use the svmon tool:

> svmon -P -t 5

This command outputs:

------------------------------------------------------------------------------- Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd 38454 java 76454 1404 100413 144805 N Y------------------------------------------------------------------------------- Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd 15552 X 14282 1407 17266 19810 N N------------------------------------------------------------------------------- Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd 14762 dtwm 3991 1403 5054 7628 N N------------------------------------------------------------------------------- Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd 15274 dtsessi 3956 1403 5056 7613 N N------------------------------------------------------------------------------- Pid Command Inuse Pin Pgsp Virtual 64-bit Mthrd 21166 dtpad 3822 1403 4717 7460 N N

This output shows that the highest memory user is Java, and that it is using 144805 pages of virtualstorage (144805 * 4 KB = 565.64 MB). This is not an unreasonable amount of memory for a JVM with alarge Java heap - in this case 512 MB.

If the system is memory-constrained with this level of load, the only remedies available are either toobtain more physical memory or to attempt to tune the amount of paging space that is available by usingthe vmtune command to alter the maxperm and minperm values.

If the Java process continues to increase its memory usage, an eventual memory constraint will becaused by a memory leak.

I/O bottlenecksThis guide does not discuss conditions in which the system is disk-bound or network-bound.

For disk-bound conditions, use filemon to generate more details of which files and disks are in greatestuse. For network conditions, use netstat to determine network traffic. A good resource for these kinds ofproblems is Accelerating AIX by Rudy Chukran (Addison Wesley, 1998).


JIT compilation and performanceWhen deciding whether or not to use JIT compilation, you must make a balance between faster executionand increased processor usage during compilation.

The JIT is another area that can affect the performance of your program. The performance of short-running applications can be improved by using the -Xquickstart command-line parameter. The JIT ison by default, but you can use -Xint to turn it off. You also have considerable flexibility in controlling JITprocessing. For more details about the JIT, see The JIT compiler and Diagnosing a JIT or AOT problem inthe J9 VM reference.

IBM Monitoring and Diagnostic ToolsThe IBM Monitoring and Diagnostic Tools are a set of GUI-based tools for monitoring applications andanalyzing diagnostic data. These tools are designed to make diagnostic tasks as quick and as easy aspossible.

Some tools can be attached to a running Java virtual machine (VM), to monitor application behavior andresource usage. For other tools, you generate dump files from your system or VM, then analyze the file inthe tool. By using the tools, you can diagnose problems such as memory leaks, thread contention issues,and I/O bottlenecks, as well as getting information and recommendations to help you tune the VM andimprove the performance of your application.

For more information about the tools, see “Using the IBM Monitoring and Diagnostic Tools” on page 177.

MustGather information for AIXThe information that is most useful at a point of failure depends, in general, on the type of failure that isexperienced.

The IBM Support Assistant Data Collector is the recommended utility for collecting Java diagnostics filesfor a problem event. The IBM Support Assistant Data Collector collects diagnostic files such as dumpsand log files, and helps you to send the information to IBM, if required. For more information, see “IBMSupport Assistant Data Collector” on page 179.

AIX core fileIf the environment is correctly set up to produce full AIX core files (as detailed in “Setting up andchecking your environment on AIX” on page 106), a core file is generated when the process receives aterminal signal (that is, SIGSEGV, SIGILL, or SIGABORT). The core file is generated into the currentworking directory of the process, or at the location pointed to by the label field specified with -Xdump.

For complete analysis of the core file, the IBM support team needs:

• The core file• A copy of the Java executable file that was running the process• Copies of all the libraries that were in use when the process core dumped

When a core file is generated:

1. Run the jextract utility against the core file, see Dump extractor (jextract). Running thejextract utility generates a file called dumpfilename.zip. This compressed file contains thedump and the required Java executable file and libraries.

Note: The IBM Support Assistant Data Collector runs the jextract utility on system dumps aspart of its collection process.

2. If jextract processing fails, use the snapcore utility to collect the same information. Forexample, snapcore -d /tmp/savedir core.001 /usr/java8/bin/java creates anarchive (snapcore_pid.pax.Z) in the file /tmp/savedir.

You also have the option of looking directly at the core file by using dbx. However, dbx does not havethe advantage of understanding Java frames and the JVM control blocks that the Dump Viewer does.Therefore, you are recommended to use the Dump Viewer in preference to dbx.


Java core file:When a java core file is written, a message (JVMDUMP010I) is written to STDERR telling you the nameand full path of the java core file. In addition, a java core file can be actively generated from a runningJava process by sending the process a SIGQUIT command. The SIGQUIT command can be initiatedby kill -QUIT or Ctrl-\.

JIT dump:A general protection fault (GPF) or abort event generates a small binary dump of JIT diagnostic data.For more information, see JIT dumps.

The Error ReportThe use of errpt -a generates a complete detailed report from the system error log. This report canprovide a stack trace, which might not have been generated elsewhere. The report might also point tothe source of the problem where it is otherwise ambiguous.

Linux problem determinationThis section describes problem determination on Linux.

Use the man command to obtain reference information about many of the commands mentioned in thisset of topics.

Setting up and checking your Linux environmentLinux operating systems undergo a large number of patches and updates.

IBM personnel cannot test the Java VM against every patch. The intention is to test against the mostrecent releases of a few distributions. In general, you should keep systems up-to-date with the latestpatches. To obtain the latest refreshes and view the fixes lists, see the Java SDK developer center.

Working directory

The current working directory of the Java VM process is the default location for the generation of corefiles, Java dumps, heap dumps, and the Java VM trace outputs, including Application Trace and Methodtrace. Enough free disk space must be available for this directory. Also, the Java VM must have writepermission.

Linux system dumps (core files)

When a crash occurs, the most important diagnostic data to obtain is the system dump. To ensure thatthis file is generated, you must check the following settings.

Operating system settings

Operating system settings must be correct. These settings can vary by distribution and Linux version.

To obtain full core files, set the following ulimit options:

ulimit -c unlimited turn on corefiles with unlimited size ulimit -n unlimited allows an unlimited number of open file descriptorsulimit -m unlimited sets the user memory limit to unlimitedulimit -f unlimited sets the file size to unlimited

For more information about ulimit settings, see Setting system resource limits on AIX and Linuxsystems in the J9 VM reference.

From Java 5, the ulimit -c value for the soft limit is ignored and the hard limit value is used to helpensure generation of the core file.

Linux tools such as the Automatic Bug Reporting Tool (ABRT) and Apport tool use settings in theLinux /proc/sys/kernel/core_pattern file to redirect core files to a diagnostic program. Thesetools and the /proc/sys/kernel/core_pattern file settings they use might prevent the JVM from


https://developer.ibm.com/javasdk/

successfully producing system dumps. The tools are enabled by default in some Linux distributions.You might see this error message:

JVMPORT030W "proc/sys/kernel/core_pattern setting ..... specifies that the core dump is to be piped to an external program.Attempting to rename either core or core.<pid>

Review the configuration of these tools or consider disabling the tools if problems occur when youattempt to generate system dumps from the Java VM.

Java Virtual Machine settings

To generate core files when a crash occurs, check that the Java VM is set to do so.

Run java -Xdump:what, which should produce the following output:

-Xdump:system: events=gpf+abort+traceassert+corruptcache, label=/mysdk/sdk//jrebin/core.%Y%m%d.%H%M%S.%pid.dmp, range=1..0, priority=999, request=serial

These values are the default settings. At least events=gpf must be set to generate a core file when acrash occurs. You can change and set options with the command-line option -Xdump:system[:name1=value1,name2=value2 ...]

Available disk space

The available disk space must be large enough for the core file to be written.

The JVM allows the core file to be written to any directory that is specified in the label option. Forexample:

-Xdump:system:label=/mysdk/sdk/jre/bin/core.%Y%m%d.%H%M%S.%pid.dmp

To write the core file to this location, disk space must be sufficient (up to 4 GB might be required for a32-bit process), and the correct permissions for the Java process to write to that location.

ZipException or IOException on Linux

When using a large number of file descriptors to load different instances of classes, you might see anerror message "java.util.zip.ZipException: error in opening .zip file", or some otherform of IOException advising that a file could not be opened. The solution is to increase the provisionfor file descriptors, using the ulimit command. To find the current limit for open files, use the command:

ulimit -a

To allow more open files, use the command:

ulimit -n 8196

Linux on zSeriesIf you are running Java 7 on zLinux under zVM on z10 hardware, you must use zVM Version 5 Release 2 orlater. If you use previous versions of zVM, you do not get the performance benefits available with DFP.

Threading libraries

The distributions supported by the IBM Java VM provide the enhanced Native POSIX Threads Library forLinux (NPTL).

You can discover your glibc version by changing to the /lib directory and running the file libc.so.6. TheLinux command ldd prints information that should help you to work out the shared library dependenciesof your application.


Using CPU Time limits to control runaway tasksBecause real time threads run at high priorities and with FIFO scheduling, failing applications (typicallywith tight CPU-bound loops) can cause a system to become unresponsive. In a development environmentit can be useful to ensure runaway tasks are killed by limiting the amount of CPU that tasks mightconsume. See “Linux system dumps (core files)” on page 136 for a discussion on soft and hard limitsettings.

The command ulimit -t lists the current timeout value in CPU seconds. This value can be reduced witheither soft, for example, ulimit -St 900 to set the soft timeout to 15 minutes or hard values to stoprunaway tasks.

General debugging techniquesThis section provides a guide to the diagnostic tools and Linux commands that can be useful when you arediagnosing problems that occur with the Linux JVM.


• Starting Java dumps, see Using Javadumps in the J9 VM reference.• Starting heap dumps, see Using Heapdumps in the J9 VM reference.• Starting system dumps, see Dump viewer in the OpenJ9 user documentation.

Linux provides various commands and tools that can be useful in diagnosing problems.

Using system dump toolsThe commands objdump and nm are used to investigate and display information about system (core)dumps. If a crash occurs and a system dump is produced, these commands help you analyze the file.

About this task

Run these commands on the same workstation as the one that produced the system dumps to use themost accurate symbol information available. This output (together with the system dump, if smallenough) is used by the IBM support team for Java to diagnose a problem.

objdump

Use this command to disassemble shared objects and libraries. After you have discovered whichlibrary or object has caused the problem, use objdump to locate the method in which the problemoriginates. To start objdump, enter: objdump <option> <filename>

You can see a complete list of options by typing objdump -H. The -d option disassembles contentsof executable sections

nmThis command lists symbol names from object files. These symbol names can be either functions,global variables, or static variables. For each symbol, the value, symbol type, and symbol name aredisplayed. Lowercase symbol types mean the symbol is local, and uppercase means the symbol isglobal or external. To use this tool, type: nm <option> <system dump>.

Examining process informationThe kernel provides useful process and environment information. These commands can be used to viewthis information.

The ps command

On Linux, Java threads are implemented as system threads and might be visible in the process table,depending on the Linux distribution.

Running the ps command gives you a snapshot of the current processes. The ps command gets itsinformation from the /proc file system. Here is an example of using ps:

ps -efwH


UID PID PPID C STIME TTY TIME CMDcass 1234 1231 0 Aug07 ? 00:00:00 /bin/bashcass 1555 1234 0 Aug07 ? 00:00:02 java appcass 1556 1555 0 Aug07 ? 00:00:00 java appcass 1557 1556 0 Aug07 ? 00:00:00 java appcass 1558 1556 0 Aug07 ? 00:00:00 java appcass 1559 1556 0 Aug07 ? 00:00:00 java appcass 1560 1556 0 Aug07 ? 00:00:00 java app

eSpecifies to select all processes.

fEnsures that a full listing is provided.

lDisplays in long format.

mShows threads if they are not shown by default.

wAn output modifier that ensures a wide output.

HUseful when you are interested in Java threads because it displays a hierarchical listing. With ahierarchical display, you can determine which process is the primordial thread, which is the threadmanager, and which are child threads. In the previous example, process 1555 is the primordialthread, while process 1556 is the thread manager. All the child processes have a parent process IDpointing to the thread manager.

The top command

The top command displays the most CPU-intensive or memory-intensive processes in real time. Itprovides an interactive interface for manipulation of processes and allows sorting by different criteria,such as CPU usage or memory usage. Press h while running top to see all the available interactivecommands.

The top command displays several fields of information for each process. The process field shows thetotal number of processes that are running, but breaks down the information into tasks that are running,sleeping, stopped, or undead. In addition to displaying PID, PPID, and UID, the top command displaysinformation about memory usage and swap space. The mem field shows statistics on memory usage,including available memory, free memory, used memory, shared memory, and memory used for buffers.The swap field shows total swap space, available swap space, and used swap space.

The vmstat command

The vmstat command reports virtual storage statistics. It is useful to perform a general health check onyour system because it reports on the system as a whole. Commands such as top can be used to gainmore specific information about the process operation.

When you use it for the first time during a session, the information is reported as averages since the lastreboot. Further usage produces reports that are based on a sampling period that you can specify as anoption. vmstat 3 4 displays values every 3 seconds for a count of four times. It might be useful to startvmstat before the application, have it direct its output to a file and later study the statistics as theapplication started and ran.

The basic output from this command is displayed in these sections:

processesShows how many processes are awaiting run time, blocked, or swapped out.


memoryShows the amount of memory (in kilobytes) swapped, free, buffered, and cached. If the free memoryis going down during certain stages of your applications execution, there might be a memory leak.

swapShows the kilobytes per second of memory swapped in from and swapped out to disk. Memory isswapped out to disk if not enough RAM is available to store it all. Large values here can be a hint thatnot enough RAM is available (although it is normal to get swapping when the application first starts).

ioShows the number of blocks per second of memory sent to and received from block devices.

systemDisplays the interrupts and the context switches per second. There is a performance penaltyassociated with each context switch so a high value for this section might mean that the program doesnot scale well.

cpuShows a breakdown of processor time between user time, system time, and idle time. The idle timefigure shows how busy a processor is, with a low value indicating that the processor is busy. You canuse this knowledge to help you understand which areas of your program are using the CPU the most.

lddThe Linux command ldd prints information that should help you to work out the shared librarydependency of your application.

Tracing toolsTracing is a technique that presents details of the execution of your program. If you are able to follow thepath of execution, you will gain a better insight into how your program runs and interacts with itsenvironment.

Also, you will be able to pinpoint locations where your program starts to deviate from its expectedbehavior.

The tracing tools on Linux are strace and ltrace. The command man strace displays a full set ofavailable options.

straceThe strace tool traces system calls. You can either use it on a process that is already available, or startit with a new process. strace records the system calls made by a program and the signals received bya process. For each system call, the name, arguments, and return value are used. strace allows you totrace a program without requiring the source (no recompilation is required). If you use strace with the-f option, it will trace child processes that have been created as a result of a forked system call. Youcan use strace to investigate plug-in problems or to try to understand why programs do not startproperly.

To use strace with a Java application, type strace java <class-name>.

You can direct the trace output from the strace tool to a file by using the -o option.

ltraceThe ltrace tool is distribution-dependent. It is very similar to strace. This tool intercepts and recordsthe dynamic library calls as called by the executing process. strace does the same for the signalsreceived by the executing process.

To use ltrace with a Java application, type ltrace java <class-name>

Debugging with gdbThe GNU debugger (gdb) allows you to examine the internals of another program while the programexecutes or retrospectively to see what a program was doing at the moment that it crashed.

The gdb allows you to examine and control the execution of code and is useful for evaluating the causesof crashes or general incorrect behavior. gdb does not handle Java processes, so it is of limited use on apure Java program. It is useful for debugging native libraries and the JVM itself.


Running gdb

You can run gdb in three ways:

Starting a programTypically the command: gdb <application> is used to start a program under the control of gdb.However, because of the way that Java is launched, you must start gdb by setting an environmentvariable and then calling Java:

export IBM_JVM_DEBUG_PROG=gdbjava

Then you receive a gdb prompt, and you supply the run command and the Java arguments:

r <java_arguments>

Attaching to a running programIf a Java program is already running, you can control it under gdb. The process ID of the runningprogram is required, and then gdb is started with the Java application as the first argument and theprocess ID as the second argument:

gdb <Java Executable> <PID>

When gdb is attached to a running program, this program is halted and its position in the code isdisplayed for the viewer. The program is then under the control of gdb and you can start to issuecommands to set and view the variables and generally control the execution of the code.

Running on a system dump (corefile)A system dump is typically produced when a program crashes. gdb can be run on this system dump.The system dump contains the state of the program when the crash occurred. Use gdb to examine thevalues of all the variables and registers leading up to a crash. This information helps you discoverwhat caused the crash. To debug a system dump, start gdb with the Java application file as the firstargument and the system dump name as the second argument:

gdb <Java Executable> <system dump>

When you run gdb against a system dump, it initially shows information such as the termination signalthe program received, the function that was executing at the time, and even the line of code thatgenerated the fault.

When a program comes under the control of gdb, a welcome message is displayed followed by a prompt(gdb). The program is now waiting for you to enter instructions. For each instruction, the programcontinues in whichever way you choose.

Setting breakpoints and watchpoints

Breakpoints can be set for a particular line or function using the command:

break linenumber

or

break functionName

After you have set a breakpoint, use the continue command to allow the program to execute until itreaches a breakpoint.

Set breakpoints using conditionals so that the program halts only when the specified condition is reached.For example, using breakpoint 39 if var == value causes the program to halt when it reachesline 39, but only if the variable is equal to the specified value.


If you want to know where as well as when a variable became a certain value you can use a watchpoint.Set the watchpoint when the variable in question is in scope. After doing so, you will be alerted wheneverthis variable attains the specified value. The syntax of the command is: watch var == value.

To see which breakpoints and watchpoints are set, use the info command:

info breakinfo watch

When gdb reaches a breakpoint or watchpoint, it prints out the line of code it is next set to execute.Setting a breakpoint at line 8 will cause the program to halt after completing execution of line 7 butbefore execution of line 8. As well as breakpoints and watchpoints, the program also halts when itreceives certain system signals. By using the following commands, you can stop the debugging toolhalting every time it receives these system signals:

handle sig32 pass nostop noprint handle sigusr2 pass nostop noprint

Examining the code

When the correct position of the code has been reached, there are a number of ways to examine the code.The most useful is backtrace (abbreviated to bt), which shows the call stack. The call stack is thecollection of function frames, where each function frame contains information such as functionparameters and local variables. These function frames are placed on the call stack in the order that theyare executed. This means that the most recently called function is displayed at the top of the call stack.You can follow the trail of execution of a program by examining the call stack. When the call stack isdisplayed, it shows a frame number at the start of the line, followed by the address of the calling function,followed by the function name and the source file for the function. For example:

#6 0x804c4d8 in myFunction () at myApplication.c

To view more detailed information about a function frame, use the frame command along with aparameter specifying the frame number. After you have selected a frame, you can display its variablesusing the command print var.

Use the print command to change the value of a variable; for example, print var = newValue.

The info locals command displays the values of all local variables in the selected function.

To follow the exact sequence of execution of your program, use the step and next commands. Bothcommands take an optional parameter specifying the number of lines to execute. However, next treatsfunction calls as a single line of execution, while step progresses through each line of the called function,one step at a time.

Useful commands

When you have finished debugging your code, the run command causes the program to run through to itsend or its crash point. The quit command is used to exit gdb.

Other useful commands are:

ptypePrints data type of variable.

info sharePrints the names of the shared libraries that are currently loaded.

info functionsPrints all the function prototypes.

listShows the 10 lines of source code around the current line.


helpDisplays a list of subjects, each of which can have the help command called on it, to display detailedhelp on that topic.

Diagnosing crashesMany approaches are possible when you are trying to determine the cause of a crash. The processtypically involves isolating the problem by checking the system setup and trying various diagnosticoptions.

Checking the system environment

The system might have been in a state that has caused the JVM to crash. For example, this could be aresource shortage (such as memory or disk) or a stability problem. Check the Javadump file, whichcontains various system information (as described in Using Javadumps in the J9 VM reference). TheJavadump file tells you how to find disk and memory resource information. The system logs can giveindications of system problems.

Gathering process information

It is useful to find out what exactly was happening leading up to the crash.

Analyze the core file (as described in Dump viewer in the OpenJ9 user documentation) to produce a stacktrace, which will show what was running up to the point of the crash. This could be:

• JNI native code.• JIT or AOT compiled code. If you have a problem with JIT or AOT code, try running without the JIT or

AOT code by using the -Xint option.• JVM code.

Other tracing methods:

• ltrace• strace

Finding out about the Java environment

Use the Javadump to determine what each thread was doing and which Java methods were beingexecuted. Match function addresses against library addresses to determine the source of code executingat various points.

Use the -verbose:gc option to look at the state of the Java heap and determine if:

• There was a shortage of Java heap space and if this could have caused the crash.• The crash occurred during garbage collection, indicating a possible garbage collection fault. See

Garbage collector diagnostic data in the J9 VM reference.• The crash occurred after garbage collection, indicating a possible memory corruption.

For more information about memory management, see Memory management in the J9 VM reference.

Debugging hangsA hang is caused by a wait (also known as a deadlock) or a loop (also known as a livelock). A deadlocksometimes occurs because of a wait on a lock or monitor. A loop can occur similarly or sometimesbecause of an algorithm making little or no progress towards completion.

A wait could either be caused by a timing error leading to a missed notification, or by two threadsdeadlocking on resources.

For an explanation of deadlocks and diagnosing them using a Javadump, see LOCKS .

A loop is caused by a thread failing to exit a loop in a timely manner. The problem might occur becausethe thread calculated the wrong limit value, or missed a flag that was intended to exit the loop. If theproblem occurs only on multiprocessor workstations, the failure can usually be traced to:


• A failure to make the flag volatile.• A failure to access the flag while holding an appropriate monitor.

The following approaches are useful to resolve waits and loops:

• Monitoring process and system state (as described in “MustGather information for Linux” on page 148).• Javadumps give monitor and lock information. You can trigger a Javadump during a hang by using thekill -QUIT <PID> command.

• -verbose:gc information is useful. It indicates:

– Excessive garbage collection, caused by a lack of Java heap space, which makes the system seem tobe in livelock

– Garbage collection causing a hang or memory corruption which later causes hangs

Debugging memory leaksIf dynamically allocated objects are not freed at the end of their lifetime, memory leaks can occur. Whenobjects that should have had their memory released are still holding memory and more objects are beingcreated, the system eventually runs out of memory.

For more details about analyzing the Java Heap, see Using Heapdumps in the J9 VM reference.





























The system property -Dcom.ibm.dbgmalloc=true provides memory allocation information about classlibrary native code. Use this system property with the -Xcheck:memory:callsite=1000 option to


obtain detailed information about class library callsites and their allocation sizes. Here is some sampleoutput:






Debugging performance problems on LinuxLocating the causes of poor performance is often difficult. Although many factors can affect performance,the overall effect is generally perceived as poor response time or slow execution of your program.

Correcting one performance problem might cause more problems in another area. By finding andcorrecting a bottleneck in one place you might only shift the cause of poor performance to other areas. Toimprove performance, experiment with tuning different parameters, monitoring the effect, and retuninguntil you are satisfied that your system is performing acceptably.

Finding the bottleneckGiven that any performance problem could be caused by any one of several factors, you must look atseveral areas to eliminate each one.

Determine which resource is constraining the system:

• CPU


• Memory• Input/Output (I/O)

Several tools are available that enable you to measure system components and establish how they areperforming and under what kind of workload.

The key things to measure are CPU usage and memory usage. If the CPU is not powerful enough to handlethe workload, it will be impossible to tune the system to make much difference to overall performance.You must upgrade the CPU. Similarly, if a program is running in an environment without enough memory,an increase in the memory improves performance far more than any amount of tuning.

CPU usageJava processes consume 100% of processor time when they reach their resource limits. Ensure thatulimit settings are appropriate to the application requirement.

See “Linux system dumps (core files)” on page 136 for more information about ulimit.

The /proc file system provides information about all the processes that are running on your system,including the Linux kernel. See man proc from a Linux shell for official Linux documentation about the /proc file system.

The top command provides real-time information about your system processes. The top command isuseful for getting an overview of the system load. It clearly displays which processes are using the mostresources. Having identified the processes that are probably causing a degraded performance, you cantake further steps to improve the overall efficiency of your program. More information is provided aboutthe top command in “The top command” on page 139.

Memory usageIf a system is performing poorly because of lack of memory resources, it is memory bound. By viewing thecontents of /proc/meminfo, you can view your memory resources and see how they are being used. /proc/swap contains information on your swap file.

Swap space is used as an extension of the systems virtual storage. Therefore, not having enough memoryor swap space causes performance problems. A general guideline is that swap space should be at leasttwice as large as the physical memory.

A swap space can be either a file or disk partition. A disk partition offers better performance than a filedoes. fdisk and cfdisk are the commands that you use to create another swap partition. It is a goodidea to create swap partitions on different disk drives because this distributes the I/O activities and thusreduces the chance of further bottlenecks.

The vmstat tool helps you find where performance problems might be caused. For example, if you seethat high swap rates are occurring, you probably do not have enough physical or swap space. The freecommand displays your memory configuration; swapon -s displays your swap device configuration. Ahigh swap rate (for example, many page faults) means that you probably need to increase your physicalmemory. More information about the vmstat command are provided in “The vmstat command” on page139.

Network problemsAnother area that often affects performance is the network. The more you know about the behavior ofyour program, the easier it is to decide whether the network might be a performance bottleneck.

If you think that your program is likely to be network I/O bound, netstat is a useful tool. The netstatcommand provides information about network routes, active sockets for each network protocol, andstatistics, such as the number of packets that are received and sent.

Use netstat to see how many sockets are in a CLOSE_WAIT or ESTABLISHED state. You can tune theTCP/IP parameters accordingly for better performance of the system. For example, tuning /proc/sys/net/ipv4/tcp_keepalive_time reduces the time for socket waits in TIMED_WAIT statebefore closing a socket.

If you are tuning the /proc/sys/net file system, the changes affect all the applications running on thesystem. To change an individual socket or connection, use Java Socket API calls on the appropriate


socket object. Use netstat -p, or the lsof command, to find the PID of the process that owns aparticular socket. Use the kill -QUIT <pid> command to generate a javacore file that contains detailsof the socket object in the stack trace.

Providing summary statistics that are related to your network is useful for investigating programs thatmight be under-performing because of TCP/IP problems. The more you understand your hardwarecapacity, the easier it is to tune the parameters of system components that improve the performance ofyour application. You can also determine whether tuning the system improves performance or whetheryou require system upgrades.

JIT compilation and performanceThe JIT is another area that can affect the performance of your program. When deciding whether or not touse JIT compilation, you must make a balance between faster execution and increased processor usageduring compilation.

The performance of short-running applications can be improved by using the -Xquickstart command-line parameter. The JIT is switched on by default, but you can use -Xint to turn it off. You also haveconsiderable flexibility in controlling JIT processing. For more details about the JIT, see The JIT compilerand Diagnosing a JIT or AOT problem in the J9 VM reference.




MustGather information for LinuxWhen a problem occurs, the more information known about the state of the system environment, theeasier it is to reach a diagnosis.


The following sections tell you about the data you can collect to help the IBM service team for Java solvethe problem.

Producing system dumps

You can use the -Xdump:system command-line option to obtain system dumps based on a trigger. SeeUsing dump agents for more information.

You can also use a Linux system utility to generate system dumps:

1. Determine the Process ID of your application using the ps command. See “The ps command” on page138.

2. At a shell prompt, type gcore -o <dump file name> <pid>

A system dump file is produced for your application. The application is suspended while the system dumpis written.

Collecting system dumps (core files)


Collect system dumps to help diagnose many types of problem. Process the system dump using thejextract utility to generate a file for service (see Dump extractor (jextract)).

Note: The IBM Support Assistant Data Collector runs the jextract utility on system dumps as part of itscollection process.

Producing Javadumps

In some conditions, like a crash, a Javadump is produced, usually in the current directory.

In other conditions, like a hang, you might need to prompt the JVM to generate a javadump by sending theJVM a SIGQUIT symbol:

1. Determine the Process ID of your application using the ps command. See “The ps command” on page138.

2. At a shell prompt, type kill -QUIT <pid>

For more information about this process, see Using Javadumps in the J9 VM reference.

Producing HeapdumpsThe JVM can generate a Heapdump at the request of the user, for example by callingcom.ibm.jvm.Dump.HeapDump() from inside the application, or by default when the JVM terminatesbecause of an OutOfMemoryError. You can specify finer control of the timing of a Heapdump with the -Xdump:heap option. For example, you can request a heapdump after a certain number of full garbagecollections have occurred. The default heapdump format (phd files) is not human-readable and youprocess it using available tools such as Heaproots. For more information, see Using Heapdumps in the J9VM reference.

Producing Snap tracesUnder default conditions, a running JVM collects a small amount of trace data in a special wraparoundbuffer. This data is dumped to file when the JVM terminates unexpectedly or an OutOfMemoryErroroccurs. You can use the -Xdump:snap option to vary the events that cause a snap trace to be produced.The snap trace is in normal trace file format and requires the use of the supplied standard trace formatterso that you can read it. See Snap traces for more information about the contents and control of snaptraces.

Producing JIT dumpsA general protection fault (GPF) or abort event generates a small binary dump of JIT diagnostic data. Formore information, see JIT dumps.

Using system logs

The kernel logs system messages and warnings. The system log is located in the /var/log/messagesfile. Use it to observe the actions that led to a particular problem or event. The system log can also helpyou determine the state of a system. Other system logs are in the /var/log directory.

Determining the operating environment

This section looks at the commands that can be useful to determine the operating environment of aprocess at various stages of its life cycle.

uname -aDisplays operating system and hardware information.

dfDisplays free disk space on a system.


freeDisplays memory use information.

ps -efDisplays a full process list.

lsofDisplays open file handles.

topDisplays process information (such as processor, memory, states) sorted by default by processorusage.

vmstatDisplays general memory and paging information.

The uname, df, and free output is the most useful. The other commands can be run before and after acrash, or during a hang, to determine the state of a process. These commands can provide usefuldiagnostic information.

Sending information to Java Support

When you have collected the output of the commands listed in the previous section, put that output intofiles.

Compress the files before sending them to Java Support, because the files could be large. You shouldcompress the files at a very high ratio.

The following command builds an archive from files {file1,..,fileN} and compresses them to a file with aname in the format filename.tgz:

tar czf filename.tgz file1 file2...filen

Collecting additional diagnostic data

Depending on the type of problem, the following data can also help you diagnose problems. Theinformation available depends on the way in which Java is started and also the system environment. Ifthese debugging aids are not active, you must change your configuration and restart Java to reproducethe problem.

/proc file system

The /proc file system gives direct access to kernel level information. The /proc/<pid> directorycontains detailed diagnostic information about the process with PID (process ID) <pid>, where <pid> isthe ID of the process.

The command cat /proc/<pid>/maps lists memory segments (including native heap) for a givenprocess.

strace and ltrace

Use the commands strace and ltrace to collect further diagnostic data. See “Tracing tools” on page140.

Windows problem determinationThis section describes problem determination on Windows.


Setting up and checking your Windows environmentThe operation of the Java runtime on Windows is controlled by a number of environment variables.

If you experience initial problems in running the JVM, check the following items:

PATHThe PATH environment variable must point to the directory of your Java installation that contains thefile java.exe. Ensure that PATH includes the \bin directory of your Java installation.

CLASSPATHThe Java runtime uses this environment variable to find the classes it needs when it runs. This isuseful when the class you want to run uses classes that are located in other directories. By default,this is blank. If you install a product that uses the Java runtime, CLASSPATH is automatically set topoint to the .jar files that the product needs.

Windows 32-bit large address aware supportThe 32-bit IBM JVM for Windows includes support for the /LARGEADDRESSAWARE switch, also known asthe /3GB switch. This switch increases the amount of space available to a process, from 2 GB to 3 GB.The switch is a Windows boot parameter, not a command line-option to the JVM.

This switch is useful in the following situations:

• Your application requires a very large number of threads.• Your application requires a large amount of native memory.• Your application has a very large codebase, causing large amounts of JIT compiled code.

To enable large address support, modify your boot.ini file and reboot your computer. See the related linksfor more detailed information.

After enabling the /3GB switch, the JVM gains 1 GB of extra memory space. This extra space does notincrease the theoretical maximum size of the Java heap, but does allow the Java heap to grow closer toits theoretical maximum size (2 GB - 1 bytes), because the extra memory can be used for the native heap.

Related links

• How to Set the /3GB Startup Switch in Windows• Memory Support and Windows Operating Systems• A description of the 4 GB RAM Tuning feature and the Physical Address Extension switch

General debugging techniquesThis section provides a guide to the JVM-provided diagnostic tools that can be useful when you arediagnosing problems that occur with the Windows JVM.



System dumpWhen a JVM crash occurs, the JVM requests the operating system to generate a system dump.

A system dump consists of all the memory that is being used by the JVM; this includes the applicationheap, along with all JVM and user libraries. System dumps allow the IBM service personnel to look at thestate of the JVM at the time of crash, and help them with the problem determination process. Because asystem dump contains all of the memory allocated by the JVM process, system dump files can be verylarge.

You can find the location of the generated system dump in the output that is displayed in the consoleafter the crash. Here is an example of the output:

Unhandled exceptionType=Segmentation error vmState=0x00000000


https://technet.microsoft.com/en-us/library/bb124810.aspx

https://msdn.microsoft.com/en-us/library/windows/hardware/dn613959%28v=vs.85%29.aspx

https://support.microsoft.com/en-us/help/291988/a-description-of-the-4-gb-ram-tuning-feature-and-the-physical-address

Windows_ExceptionCode=c0000005 J9Generic_Signal=00000004 ExceptionAddress=000007FFFF2D90C2 ContextFlags=0010001fHandler1=000007FFFF4EEF80 Handler2=000007FFFF4B2890RDI=00000000003715D0 RSI=0000000000378490 RAX=0000000000000000 RBX=00000000FFFFFFFFRCX=0000000000389E00 RDX=0000000003DB18E8 R8=0000000000000001 R9=0000000000000001R10=0000000001594EF0 R11=0000000003D50540 R12=0000000003D50540 R13=0000000000000001R14=0000000003DB18E8 R15=0000000000389E00RIP=000007FFFF2D90C2 RSP=000000000023F218 RBP=0000000000000001 GS=002BFS=0053 ES=002B DS=002BXMM0 000000000000027f (f: 639.000000, d: 3.157079e-321)XMM1 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM2 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM3 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM4 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM5 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM6 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM7 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM8 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM9 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM10 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM11 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM12 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM13 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM14 0000000000000000 (f: 0.000000, d: 0.000000e+000)XMM15 0000000000000000 (f: 0.000000, d: 0.000000e+000)Module=C:\test\sdk\jre\bin\default\j9trc26.dllModule_base_address=000007FFFF2D0000 Offset_in_DLL=00000000000090c2Target=2_60_20101120_069090 (Windows Server 2008 R2 6.1 build 7600)CPU=amd64 (4 logical CPUs) (0x1bfefb000 RAM)----------- Stack Backtrace --------------------------------------------------JVMDUMP006I Processing dump event "gpf", detail "" - please wait.JVMDUMP032I JVM requested System dump using 'C:\Users\Administrator\core.20101122.101637.7148.0001.dmp' in response to an eventJVMDUMP010I System dump written to C:\Users\Administrator\core.20101122.101637.7148.0001.dmpJVMDUMP032I JVM requested Java dump using 'C:\Users\Administrator\javacore.20101122.101637.7148.0002.txt' in response to an eventJVMDUMP010I Java dump written to C:\Users\Administrator\javacore.20101122.101637.7148.0002.txtJVMDUMP032I JVM requested Snap dump using 'C:\Users\Administrator\Snap.20101122.101637.7148.0003.trc' in response to an eventJVMDUMP010I Snap dump written to C:\Users\Administrator\Snap.20101122.101637.7148.0003.trcJVMDUMP013I Processed dump event "gpf", detail "".

In this example, the JVM has generated the dump in the file D:\core.20040817.131302.2168.dmp.

The JVM attempts to generate the system dump file in one of the following directories (listed in order ofprecedence):

1. Any directory specified on the command line, for example by using the -Xdump:<agent>:file or -Xdump:directory options.

2. The directory pointed to by environment variable IBM_COREDIR.3. The current directory.4. The directory pointed to by the environment variable TMPDIR.5. The C:\Temp directory

Use -Xdump:what to find the current naming convention of all dump files. Use -Xdump:help to learn howto change these settings.

You might want to keep system dumps more private by setting the environment variable IBM_COREDIR,if you are concerned about passwords and other security details that are contained in a system dump.

Diagnosing crashes in WindowsYou generally see a crash either as an unrecoverable exception thrown by Java or as a pop-up windownotifying you of a General Protection Fault (GPF). The pop-up window usually refers to java.exe as theapplication that caused the crash. Crashes can occur because of a fault in the Java runtime, or because ofa fault in native (JNI) code being run in the Java process.


Try to determine whether the application has any JNI code or uses any third-party packages that use JNIcode (for example, JDBC application drivers). If this is not the case, the fault must be in the runtimeenvironment.

Try to re-create the crash with minimal dependencies (in terms of JVM options, JNI applications, orprofiling tools).

In a crash condition, gather as much data as possible for the IBM service team for Java. You should:

• Collect the Javadump. See Using Javadumps in the J9 VM reference for details.• Collect the core dump. See “Setting up and checking your Windows environment” on page 151 for

details.• Collect the snap trace file. See Tracing Java applications in the J9 VM reference for details.• Run with the JIT turned off. See Diagnosing a JIT or AOT problem in the J9 VM reference for details. If

the problem disappears with the JIT turned off, try some JIT compile options to see if the problem canbe narrowed down further.

• Try adjusting the garbage collection parameters. See Memory management in the J9 VM reference fordetails. Make a note of any changes in behavior.

• If your problem is occurring on a multiprocessor system, test your application on a uniprocessorsystem. You can use the BIOS options on your SMP box to reset the processor affinity to 1 to make itbehave like a uniprocessor. If the problem disappears, make a note in your bug report. Otherwise,collect the crash dump.

Collecting system dumps on Windows when -Xrs or -Xrs:sync is setUsing the Dr. Watson tool to enable and collect system dumps on Windows.

About this taskIn some scenarios, you might want to disable the Java runtime signal handler so that any signals receivedare handled by the operating system. The -Xrs and -Xrs:sync command-line options stop the Javaruntime environment from handling exception signals. For some exception signals, a system dump isproduced.

On versions of Windows before Windows Vista and Windows 2008 server, use the Dr Watson tool toenable system dumps.

Windows Vista and Windows 2008 Server do not provide the Dr. Watson tool. The replacement is theProblem Reports and Solutions Control Panel applet. This tool cannot be used to take a fullsystem dump without first uploading the problem report data to Microsoft.

On Windows 7 you can use the Task Manager to create a system dump.

To enable system dumps using the Dr. Watson tool:

Procedure

1. Open the Dr Watson configuration window by clicking Start, selecting Run, and typing drwtsn32 inthe Open field. Click OK.

2. Complete the fields in the configuration window as follows.a) Set the Log File Path field to a location with several hundred MB of free space.b) Set the Crash Dump field to point to a file called user.dmp in the Log File Path.

When an error occurs in JNI code or the Java runtime environment, the dump is stored in this file.c) Set the Number of Instructions field to 20.d) Set the Number of Errors To Save field to 20.e) Set the Crash Dump Type field to NT4 compatible Full or Full, depending on which option is

available.The available options vary depending on the version of Windows in use.

f) Select the remaining option boxes as shown in the screen capture.


g) Click OK to save the settings.3. Install Dr Watson as the default application debugger by clicking Start, selecting Run, and typingdrwtsn32 -i in the Open field. Click OK.A window opens, reporting that Dr. Watson has been installed as the default application debugger.

4. To use Dr. Watson for collecting system dumps, run your application and reproduce the error.When the error occurs, a dialog opens reporting that Java encountered a problem and had to close.Click OK to continue.

5. (Optional) If you set the Visual Notification option in the screen capture, a window opens, reportingthat an error log is being created. Wait until the Cancel button changes to OK. Click OK to continue.

6. The system dump is stored in the location specified in the Crash Dump field. For information aboutanalyzing the system dump file, see Dump viewer.

ResultsDr. Watson has been installed as the default application debugger and used when a system dump iscreated.

Data to send to IBMAt this point, you potentially have several sets of either logs or dumps, or both (for example, one set fornormal running, one set with JIT off, and so on).

Label the files appropriately and make them available to IBM. (See “Submitting problem reports” on page99 for details.) The required files are:

• The JVM-produced Javadump file (Javacore).• The dumpfile.jar file.

Debugging hangsHangs refer to the JVM locking up or refusing to respond.

A hang can occur when:

• Your application entered an infinite loop.• A deadlock has occurred

To determine which of these situations applies, open the Windows Task Manager and select thePerformance tab. If the CPU time is 100% divided by the number of processors and your system isrunning very slowly, the JVM is very likely to have entered an infinite loop. Otherwise, if CPU usage isnormal, you are more likely to have a deadlock situation.

Getting a dump from a hung JVMOn Windows, you can force the JVM to produce a Java dump. Alternatively, you can produce a Java dumpusing Windows utilities.

You can force the JVM to produce a Java dump in response to a SIGBREAK signal, which can be sent byusing the Ctrl-Break key combination. You can also configure the JVM to produce a system dump onSIGBREAK by using the -Xdump:system:events=user option. See Using dump agents for details.

On Windows 7 and Windows Server 2008, you can obtain a system dump by using the Windows TaskManager.

1. Start the Windows Task Manager.2. Select either the Applications or the Processes tab.3. Right-click the application or process, then select the Create Dump File option.

On earlier versions of Windows, you can use the User Mode Process Dumper utility, which is available as adownload from www.microsoft.com. Documentation is provided with the utility. Basic usage is as follows:

userdump -pLists all the processes and their process IDs.


http://www.microsoft.com/

userdump xxxCreates a dump file of a process that has a process ID of xxx. A file named processname.dmp iscreated in the directory where userdump.exe is run.

You can use the dump viewer to examine the system dump produced by the JVM or by the Windowsutilities. For more information, see Using the dump viewer.

Analyzing deadlocksA deadlocked process does not use any CPU time.

For an explanation of deadlocks and how to diagnose them using the information in the Javadump tool,see LOCKS.

Debugging memory leaksThis section begins with a discussion of the Windows memory model and the Java heap to providebackground understanding before going into the details of memory leaks.

The Windows memory modelWindows memory is virtualized. Applications do not have direct access to memory addresses, so allowingWindows to move physical memory and to swap memory in and out of a swapper file (called pagefile.sys).

Allocating memory is usually a two-stage process. Just allocating memory results in an applicationgetting a handle. No physical memory is reserved. There are more handles than physical memory. To usememory, it must be 'committed'. At this stage, a handle references physical memory. This might not be allthe memory you requested.

For example, the stack allocated to a thread is usually given a small amount of actual memory. If thestack overflows, an exception is thrown and the operating system allocates more physical memory so thatthe stack can grow.

Memory manipulation by Windows programmers is hidden inside libraries provided for the chosenprogramming environment. In the C environment, the basic memory manipulation routines are thefamiliar malloc and free functions. Windows APIs sit on top of these libraries and generally provide afurther level of abstraction.

For a programmer, Windows provides a flat memory model, in which addresses run from 0 up to the limitallowed for an application. Applications can choose to segment their memory. In a dump, theprogrammer sees sets of discrete memory addresses.

Classifying leaksYou can classify memory leaks from the usage of Windows memory and the size of the Java heap.

The following scenarios are possible :

• Windows memory usage is increasing and the Java heap is static:

– Memory leak in application native code.– Memory leak in Java runtime native code.– Leak with hybrid Java and native objects (an unlikely occurrence).

• Windows memory usage increases because the Java heap keeps growing:

– Memory leak in application Java code.– Memory leak in Java runtime Java code.










OutOfMemoryError creating a threadThe java.lang.OutOfMemoryError: Failed to create a thread message occurs when thesystem does not have enough resources to create a new thread.

There are two possible causes of the java.lang.OutOfMemoryError: Failed to create athread message:

• There are too many threads running and the system has run out of internal resources to create newthreads.

• The system has run out of native memory to use for the new thread. Threads require a native memoryfor internal JVM structures, a Java stack, and a native stack.

To correct the problem, either:

• Increase the amount of native memory available by decreasing the size of the Java heap using the -Xmxoption.

• Reduce the number of threads in your application.

Debugging performance problems on WindowsLocating the causes of poor performance is often difficult. Although many factors can affect performance,the overall effect is generally perceived as poor response time or slow execution of your program.


Windows systems resource usageThe Windows Task Manager display gives a good general view of system resource usage. You can use thistool to determine which processes are using excessive CPU time and memory. This tool also provides asummary view of network I/O activity.

For a more detailed view of Windows performance data, use the Windows Performance Monitor tool,which is provided as part of the Windows Administrative Tools. This tool provides a comprehensive viewof processor, memory, and I/O device performance metrics.


JIT compilation and performanceThe JIT is another area that can affect the performance of your program. When deciding whether or not touse JIT compilation, you must make a balance between faster execution and increased processor usageduring compilation.

The performance of short-running applications can be improved by using the -Xquickstart command-lineparameter. The JIT is on by default, but you can use -Xint to turn it off. You also have considerableflexibility in controlling JIT processing. For more details about the JIT, see The JIT compiler andDiagnosing a JIT or AOT problem in the J9 VM reference.




MustGather information for WindowsThe more information that you can collect about a problem, the easier it is to diagnose that problem. Alarge set of data can be collected, although some is relevant to particular problems.


The following list describes a typical data set that you can collect to assist IBM service to fix yourproblem.Javadumps

Javadumps can be generated automatically or manually. Automatic dumps are essential for IBMservice. See Using Javadumps in the J9 VM reference.

HeapdumpsIf generated automatically, they are essential. They are also essential if you have a memory orperformance problem. For more information about heapdumps, see Using Heapdumps in the J9 VMreference.

System dumpsSystem dumps are generated by the JVM. See “System dump” on page 151. This type of dumpcontains key information that helps to diagnose the problem.

JIT dumpsJIT dumps are generated in response to a general protection fault (GPF) or abort event, providingdiagnostic data for IBM service. For more information, see JIT dumps.

OtherIf you are working in a WebSphere Application Server environment, the WebSphere Application Serverlogs.Other data, as determined by your particular problem.

z/OS problem determinationThis section describes problem determination on z/OS.


Setting up and checking your z/OS environmentSet up the correct environment for the z/OS VM to run correctly.

MaintenanceThe Java for z/OS Knowledge Center pages have up-to-date information about any changing operatingsystem prerequisites for correct JVM operation.

For more information about Java for z/OS, see: z/OSUser Guide for IBM SDK, Java Technology Edition

LE settingsLanguage Environment (LE) Runtime Options (RTOs) affect operation of C and C++ programs such as theJVM. In general, the options provided by IBM using C #pragma statements in the code must not beoverridden because they are generated as a result of testing to provide the best operation of the JVM.

Environment variablesEnvironment variables that change the operation of the JVM in one release can be deprecated or changemeaning in a following release. Therefore, you should review environment variables that are set for onerelease, to ensure that they still apply after any upgrade.

For information on compatibility between releases, see the SDK for z/OS website at https://www.ibm.com/systems/z/os/zos/tools/java/products/sdk.html.

Private storage usageThe single most common class of failures after a successful installation of the SDK are those related toinsufficient private storage.

As discussed in detail in “Understanding Memory Usage” on page 170, LE provides storage from Subpool2, key 8 for C/C++ programs like the JVM that use C runtime library calls like malloc() to obtain memory.The LE HEAP refers to the areas obtained for all C/C++ programs that run in a process address space andrequest storage.

This area is used for the allocation of the Java heap where instances of Java objects are allocated andmanaged by Garbage Collection. The area is used also for any underlying allocations that the JVM makesduring operations. For example, the JIT compiler obtains work areas for compilation of methods and tostore compiled code.

Because the JVM must preallocate the maximum Java heap size so that it is contiguous, the total privatearea requirement is that of the maximum Java heap size that is set by the -Xmx option (or the 64 MBdefault if this is not set), plus an allowance for underlying allocations. A total private area of 140 MB istherefore a reasonable requirement for an instance of a JVM that has the default maximum heap size.

If the private area is restricted by either a system parameter or user exit, failures to obtain private storageoccur. These failures show as OutOfMemoryErrors or Exceptions, failures to load libraries, or failures tocomplete subcomponent initialization during startup.

Setting up dumpsThe JVM generates a Javadump and System Transaction Dump (SYSTDUMP) when particular eventsoccur.

The JVM, by default, generates the dumps when any of the following conditions occur:

• A SIGQUIT signal is received• The JVM exits because of an error• An unexpected native exception occurs (for example, a SIGSEGV, SIGILL, or SIGFPE signal is received)

You can use the -Xdump option to change the dumps that are produced on the various types of signal andthe naming conventions for the dumps. For more information, see Using dump agents.


https://www.ibm.com/systems/z/os/zos/tools/java/products/sdk.html

https://www.ibm.com/systems/z/os/zos/tools/java/products/sdk.html

Failing transaction dumps (IEATDUMPs)

If a requested IEATDUMP cannot be produced, the JVM issues messages to STDOUT and to the z/OSoperator console. For example:

JVMDUMP025E IEATDUMP failed RC=0x00000008 RSN=0x000000026 for DSN=J9BUILD.JVM.J9BUILD8.D131129.T210839JVMPORT024E IEATDUMP failed because we couldn't allocate the dump data set (check disk space and field permissions)JVMDUMP012E Error in System dump: J9BUILD.JVM.J9BUILD8.D131129.T210839

The return and reason codes in the IEATDUMP messages are documented in z/OS MVS Programming:Authorized Assembler Services Reference EDT-IXG.

Here are some common return and reason codes:

RC=0x00000008 RSN=0x00000022

No dump was written. The dump data set name was too long.

RC=0x00000008 RSN=0x00000026

No dump was written. There was insufficient space to allocate the dump data set.

RC=0x00000004 RSN=0x00000007

A partial dump was written. The system has filled one of the range tables. See APAR OA43509.

If transaction dumps continue to fail, you can trigger a z/OS SVC dump from a JVM console message byusing a SLIP trap. For example:

/SLIP SET,A=SVCD,J=USER*,MSGID=JVMDUMP012E,ID=JAVA,SDATA=(ALLPSA,NUC,SQA,RGN,LPA,TRT,SUMDUMP),END

Multiple transaction dump (IEATDUMP) files

On a 64-bit platform, IEATDUMP files are split into several smaller files if the IEATDUMP exceeds the 2GB file size limit. Each file is given a sequence number.

If you specify a template for the IEATDUMP file name, append the &DS token to enable multiple dumps.The &DS token is replaced by an ordered sequence number, and must be at the end of the file name. Forexample, X&DS generates file names in the form X001, X002, and X003.

If you specify a template without the &DS token, .X&DS is appended automatically to the end of yourtemplate. If your template is too long to append .X&DS, a message is produced. The message advisesthat the template pattern is too long and a default pattern is used instead.

If you do not specify a template, the default template is used. This is the default template:

%uid.JVM.%job.D%y%m%d.T%H%M%S.X&DS

You must merge the sequence of IEATDUMP files before IPCS can process the data. To merge thesequence of IEATDUMP files, use the TSO panel IPCS > Utility > Copy MVS dump data set, or the IPCSCOPYDUMP command. If you copied or moved the IEATDUMP files from MVS™ to the z/OS UNIX SystemServices file system, you can use the cat command to merge the files, for example:

cat JVM.TDUMP.X001 JVM.TDUMP.X002 > JVM.TDUMP.FULL

For more information, see IEATDUMP - Transaction dump request in the z/OS documentation.

Marking failures on z/OSThe Java launcher can mark the z/OS Task Control Block (TCB) with an abend code when the launcherfails to load the VM or is terminated by an uncaught exception. To start TCB marking, set the environmentvariable IBM_JAVA_ABEND_ON_FAILURE=Y.

By default, the Java launcher will not mark the TCB.


http://www-01.ibm.com/support/docview.wss?uid=isg1OA43509

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.2.0/com.ibm.zos.v2r2.ieaa200/tdp.htm

General debugging techniquesA short guide to the diagnostic tools provided by the JVM and the z/OS commands that can be usefulwhen diagnosing problems with the z/OS JVM.

In addition to the information given in this section, you can obtain z/OS publications from the IBMwebsite. Go to https://www.ibm.com/support/publications/us/library/, and then choose thedocumentation link for your platform.



z/OS provides various commands and tools that can be useful in diagnosing problems.

Using IPCS commandsThe Interactive Problem Control System (IPCS) is a tool provided in z/OS to help you diagnose softwarefailures. IPCS provides formatting and analysis support for dumps and traces produced by z/OS.

Here are some sample IPCS commands that you might find useful during your debugging sessions. In thiscase, the address space of interest is ASID(x'7D').ip verbx ledata 'nthreads(*)'

This command provides the stack traces for the TCBs in the dump.ip setd asid(x'007d')

This command is to set the default ASID; for example, to set the default asid to x'007d'.ip verbx ledata 'all,asid(007d),tcb(tttttt)'

In this command, the all report formats out key LE control blocks such as CAA, PCB, ZMCH, CIB. Inparticular, the CIB/ZMCH captures the PSW and GPRs at the time the program check occurred.

ip verbx ledata 'cee,asid(007d),tcb(tttttt)'This command formats out the traceback for one specific thread.

ip summ regs asid(x'007d')This command formats out the TCB/RB structure for the address space. It is rarely useful for JVMdebugging.

ip verbx sumdumpThen issue find 'slip regs sa' to locate the GPRs and PSW at the time a SLIP TRAP is matched.This command is useful for the case where you set a SA (Storage Alter) trap to catch an overlay ofstorage.

ip omvsdata process detail asid(x'007d')This command generates a report for the process showing the thread status from a USS kernelperspective. It requires the USS kernel address space memory to be available in the dump, thereforeit works only for SVC dumps, not TDUMPs.

ip select allThis command generates a list of the address spaces in the system at the time of the dump, so thatyou can tie up the ASID with the JOBNAME.

ip systrace asid(x'007d') time(gmt)This command formats out the system trace entries for all threads in this address space. It is usefulfor diagnosing loops. time(gmt) converts the TOD Clock entries in the system trace to a humanreadable form.

For further information about IPCS, see the z/OS documentation (z/OS V1R7.0 MVS IPCS Commands).

Using dbxThe dbx utility has been improved for z/OS V1R6. You can use dbx to analyze transaction (or system)dumps and to debug a running application.

For information about dbx, see the z/OS documentation; z/OS V1R6.0 UNIX System Services ProgrammingTools at http://publibz.boulder.ibm.com/epubs/pdf/bpxza630.pdf.


https://www.ibm.com/support/publications/us/library/

http://publibz.boulder.ibm.com/epubs/pdf/bpxza630.pdf

Interpreting error message IDsWhile working in the OMVS, if you get an error message and want to understand exactly what the errormessage means there is a website you can go to.

Go to: IBM LookAt and enter the message ID. Then select your OS level and then press enter. The outputwill give a better understanding of the error message. To decode the errno2 values, use the followingcommand:

bpxmtext <reason_code>

Reason_code is specified as 8 hexadecimal characters. Leading zeros can be omitted.

Diagnosing crashesA crash should occur only because of a fault in the JVM, or because of a fault in native (JNI) code that isbeing run inside the Java process. A crash is more strictly defined on z/OS as a program check that ishandled by z/OS UNIX as an unrecoverable signal (for example, SIGSEGV for PIC4; 10, 11, or SIGILL forPIC1).

Documents to gatherWhen a crash takes place, diagnostic data is required to help diagnose the problem.

When one of these unrecoverable signals occurs, the JVM Signal Handler takes control. The default actionof the signal handler is to produce a transaction dump (through the BCP IEATDUMP service), a JVM snaptrace dump, and a formatted Javadump. Output should be written to the message stream that is writtento stderr in the form of:

Unhandled exceptionType=Segmentation error vmState=0x00000000Target=2_30_20060227_05498_bHdSMr (z/OS 01.06.00)CPU=s390 (2 logical CPUs) (0x180000000 RAM)J9Generic_Signal_Number=00000004 Signal_Number=0000000b Error_Value=00000000 Signal_Code=00000035Handler1=115F8590 Handler2=116AFC60gpr0=00000064 gpr1=00000000 gpr2=117A3D70 gpr3=00000000gpr4=114F5280 gpr5=117C0E28 gpr6=117A2A18 gpr7=9167B460gpr8=0000007E gpr9=116AF5E8 gpr10=1146E21C gpr11=0000007Egpr12=1102C7D0 gpr13=11520838 gpr14=115F8590 gpr15=00000000psw0=078D0400 psw1=917A2A2Afpr0=48441040 fpr1=3FFF1999 fpr2=4E800001 fpr3=99999999fpr4=45F42400 fpr5=3FF00000 fpr6=00000000 fpr7=00000000fpr8=00000000 fpr9=00000000 fpr10=00000000 fpr11=00000000fpr12=00000000 fpr13=00000000 fpr14=00000000 fpr15=00000000Program_Unit_Name=Program_Unit_Address=1167B198 Entry_Name=j9sig_protectEntry_Address=1167B198JVMDUMP006I Processing Dump Event "gpf", detail "" - Please Wait.JVMDUMP007I JVM Requesting System Dump using 'CHAMBER.JVM.TDUMP.CHAMBER1.D060309.T144842'IEATDUMP in progress with options SDATA=(LPA,GRSQ,LSQA,NUC,PSA,RGN,SQA,SUM,SWA,TRT) IEATDUMP success for DSN='CHAMBER.JVM.TDUMP.CHAMBER1.D060309.T144842' JVMDUMP010I System Dump written to CHAMBER.JVM.TDUMP.CHAMBER1.D060309.T144842 JVMDUMP007I JVM Requesting Snap Dump using '/u/chamber/test/ras/Snap0001.20060309.144842.196780.trc' JVMDUMP010I Snap Dump written to /u/chamber/test/ras/Snap0002.20060309.144842.196780.trc JVMDUMP007I JVM Requesting Java Dump using '/u/chamber/test/ras/javacore.20060309.144842.196780.txt' JVMDUMP010I Java Dump written to /u/chamber/test/ras/javacore.20060309.144842.196780.txt JVMDUMP013I Processed Dump Event "gpf", detail "".

The output shows the location in HFS into which the Javadump file was written and the name of the MVSdata set to which the transaction dump is written. These locations are configurable and are described inDiagnostic component in the J9 VM reference and -Xdump in the OpenJ9 user documentation.

These documents provide the ability to determine the failing function, and therefore decide which productowns the failing code, be it the JVM, application JNI code, or native libraries acquired from anothervendor (for example native JDBC drivers).

The JVM will display error messages if it is unable to produce the dumps. The IEATDUMP error returncodes, RC=... and RSN=..., are included in the messages. These return codes are fully documented inz/OS V1R7.0 MVS Authorized Assembler Services Reference, 36.1.10 Return and Reason Codes.


https://www.ibm.com/systems/z/os/zos/library/bkserv/lookat/

This example shows the error messages displayed when there is insufficient disk space to write theIEATDUMP:

JVMDUMP007I JVM Requesting System dump using 'J9BUILD.JVM.TDUMP.SSHD1.D080326.T081447'IEATDUMP in progress with options SDATA=(LPA,GRSQ,LSQA,NUC,PSA,RGN,SQA,SUM,SWA,TRT)IEATDUMP failure for DSN='J9BUILD.JVM.TDUMP.SSHD1.D080326.T081447' RC=0x00000008 RSN=0x00000026 JVMDUMP012E Error in System dump: J9BUILD.JVM.TDUMP.SSHD1.D080326.T081447

When an IEATDUMP fails, an error message is also written to the operator console. If the IEATDUMP failsbecause of the 2 GB IEATDUMP size limit, you can use a SLIP trap to trigger an SVC DUMP to ensure allthe required diagnostics information is available. See “Setting up dumps” on page 160 for moreinformation.

z/OS V2R1 MVS Authorized Assembler Services Reference is available at https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieaa300/toc.htm.

Determining the failing functionThe most practical way to find where the exception occurred is to review either the CEEDUMP or theJavadump. Both of these reports show where the exception occurred and the native stack trace for thefailing thread.

The same information can be obtained from the transaction dump by using either the dump viewer (seeDump viewer), the dbx debugger, or the IPCS LEDATA VERB Exit.

The CEEDUMP shows the C-Stack (or native stack, which is separate from the Java stack that is built bythe JVM). The C-stack frames are also known on z/OS as Dynamic Storage Areas (DSAs), because a DSA isthe name of the control block that LE provides as a native stack frame for a C/C++ program. The followingtraceback from a CEEDUMP shows where a failure occurred:


https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieaa300/toc.htm

https://www.ibm.com/support/knowledgecenter/en/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieaa300/toc.htm

Traceback: DSA Entry E Offset Load Mod Program Unit Service Status 00000001 __cdump +00000000 CELQLIB HLE7709 Call 00000002 @@WRAP@MULTHD +00000266 CELQLIB Call 00000003 j9dump_create +0000035C *PATHNAM j040813 Call 00000004 doSystemDump+0000008C *PATHNAM j040813 Call 00000005 triggerDumpAgents +00000270 *PATHNAM j040813 Call 00000006 vmGPHandler +00000C4C *PATHNAM j040813 Call 00000007 gpHandler +000000D4 *PATHNAM j040813 Call 00000008 __zerro +00000BC4 CELQLIB HLE7709 Call 00000009 __zerros +0000016E CELQLIB HLE7709 Call 0000000A CEEHDSP +00003A2C CELQLIB CEEHDSP HLE7709 Call 0000000B CEEOSIGJ +00000956 CELQLIB CEEOSIGJ HLE7709 Call 0000000C CELQHROD +00000256 CELQLIB CELQHROD HLE7709 Call 0000000D CEEOSIGG -08B3FBBC CELQLIB CEEOSIGG HLE7709 Call 0000000E CELQHROD +00000256 CELQLIB CELQHROD HLE7709 Call 0000000F Java_dumpTest_runTest +00000044 *PATHNAM Exception 00000010 RUNCALLINMETHOD -0000F004 *PATHNAM Call 00000011 gpProtectedRunCallInMethod +00000044 *PATHNAM j040813 Call 00000012 j9gp_protect+00000028 *PATHNAM j040813 Call 00000013 gpCheckCallin +00000076 *PATHNAM j040813 Call 00000014 callStaticVoidMethod +00000098 *PATHNAM j040813 Call 00000015 main +000029B2 *PATHNAM j904081 Call 00000016 CELQINIT +00001146 CELQLIB CELQINIT HLE7709 Call

DSA DSA Addr E Addr PU Addr PU Offset Comp Date Attributes 00000001 00000001082F78E0 000000001110EB38 0000000000000000 ******** 20040312 XPLINK EBCDIC POSIX IEEE 00000002 00000001082F7A20 00000000110AF458 0000000000000000 ******** 20040312 XPLINK EBCDIC POSIX Floating Point 00000003 00000001082F7C00 0000000011202988 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000004 00000001082F8100 0000000011213770 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000005 00000001082F8200 0000000011219760 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000006 00000001082F8540 000000007CD4BDA8 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000007 00000001082F9380 00000000111FF190 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000008 00000001082F9480 00000000111121E0 0000000000000000 ******** 20040312 XPLINK EBCDIC POSIX IEEE 00000009 00000001082FA0C0 0000000011112048 0000000000000000 ******** 20040312 XPLINK EBCDIC POSIX IEEE 0000000A 00000001082FA1C0 0000000010DB8EA0 0000000010DB8EA0 00003A2C 20040312 XPLINK EBCDIC POSIX Floating Point 0000000B 00000001082FCAE0 0000000010E3D530 0000000010E3D530 00000956 20040312 XPLINK EBCDIC POSIX Floating Point 0000000C 00000001082FD4E0 0000000010D76778 0000000010D76778 00000256 20040312 XPLINK EBCDIC POSIX Floating Point 0000000D 00000001082FD720 0000000010E36C08 0000000010E36C08 08B3FBB0 20040312 XPLINK EBCDIC POSIX Floating Point 0000000E 00000001082FE540 0000000010D76778 0000000010D76778 00000256 20040312 XPLINK EBCDIC POSIX Floating Point 0000000F 00000001082FE780 00000000122C66B0 0000000000000000 ******** 20040802 XPLINK EBCDIC POSIX IEEE 00000010 00000001082FE880 000000007CD28030 0000000000000000 ******** ^C"^22^04^FF^FDu^58 XPLINK EBCDIC POSIX IEEE 00000011 00000001082FEC80 000000007CD515B8 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000012 00000001082FED80 00000000111FF948 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000013 00000001082FEE80 000000007CD531A8 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE 00000014 00000001082FEF80 000000007CD4F148 0000000000000000 ******** 20040817 XPLINK EBCDIC POSIX IEEE

Note:

1. The stack frame that has a status value of Exception indicates where the crash occurred. In thisexample, the crash occurs in the function Java_dumpTest_runTest.

2. The value under Service for each DSA is the service string. The string is built in the format of jyymmdd,where j is the identifier for the code owner and yymmdd is the build date. A service string with thisformat indicates that the function is part of the JVM. All functions have the same build date, unless youhave been supplied with a dll by IBM Service for diagnostic or temporary fix purposes.

Working with TDUMPs using IPCSA TDUMP or Transaction Dump is generated from the MVS service IEATDUMP by default in the event of aprogram check or exception in the JVM. You can disable the generation of a TDUMP, but it is notrecommended by IBM Service.

A TDUMP can contain multiple Address Spaces. It is important to work with the correct address spaceassociated with the failing java process.

To work with a TDUMP in IPCS, here is a sample set of steps to add the dump file to the IPCS inventory:

1. Browse the dump data set to check the format and to ensure that the dump is correct.


2. In IPCS option 3 (Utility Menu), suboption 4 (Process list of data set names) type in the TSO HLQ (forexample, DUMPHLQ) and press Enter to list data sets. You must ADD (A in the command-line alongsidethe relevant data set) the uncompressed (untersed) data set to the IPCS inventory.

3. You can select this dump as the default one to analyze in two ways:

• In IPCS option 4 (Inventory Menu) type SD to add the selected data set name to the default globals.• In IPCS option 0 (DEFAULTS Menu), change Scope and Source

Scope ==> BOTH (LOCAL, GLOBAL, or BOTH)

Source ==> DSNAME('DUMPHLQ.UNTERSED.SIGSEGV.DUMP') Address Space ==> Message Routing ==> NOPRINT TERMINAL Message Control ==> CONFIRM VERIFY FLAG(WARNING) Display Content ==> NOMACHINE REMARK REQUEST NOSTORAGE SYMBOL

If you change the Source default, IPCS displays the current default address space for the new sourceand ignores any data entered in the address space field.

4. To initialize the dump, select one of the analysis functions, such as IPCS option 2.4 SUMMARY -Address spaces and tasks, which will display something like the following output and give the TCBaddress. (Note that non-zero CMP entries reflect the termination code.)

TCB: 009EC1B0 CMP...... 940C4000 PKF...... 80 LMP...... FF DSP...... 8C TSFLG.... 20 STAB..... 009FD420 NDSP..... 00002000 JSCB..... 009ECCB4 BITS..... 00000000 DAR...... 00 RTWA..... 7F8BEDF0 FBYT1.... 08 Task non-dispatchability flags from TCBFLGS5: Secondary non-dispatchability indicator Task non-dispatchability flags from TCBNDSP2: SVC Dump is executing for another task

SVRB: 009FD9A8 WLIC..... 00000000 OPSW..... 070C0000 81035E40 LINK..... 009D1138

PRB: 009D1138 WLIC..... 00040011 OPSW..... 078D1400 B258B108 LINK..... 009ECBF8 EP....... DFSPCJB0 ENTPT.... 80008EF0

PRB: 009ECBF8 WLIC..... 00020006 OPSW..... 078D1000 800091D6 LINK..... 009ECC80

Useful IPCS commands and some sample outputSome IPCS commands that you can use when diagnosing crashes.

In IPCS option 6 (COMMAND Menu) type in a command and press the Enter key:

ip stProvides a status report.

ip select allShows the Jobname to ASID mapping:

ASID JOBNAME ASCBADDR SELECTION CRITERIA ---- -------- -------- ------------------ 0090 H121790 00EFAB80 ALL 0092 BPXAS 00F2E280 ALL 0093 BWASP01 00F2E400 ALL 0094 BWASP03 00F00900 ALL 0095 BWEBP18 00F2EB80 ALL 0096 BPXAS 00F8A880 ALL

ip systrace all time(local)Shows the system trace:

PR ASID,WU-ADDR- IDENT CD/D PSW----- ADDRESS- UNIQUE-1 UNIQUE-2 UNIQUE-3 UNIQUE-4 UNIQUE-5 UNIQUE-6


09-0094 009DFE88 SVCR 6 078D3400 8DBF7A4E 8AA6C648 0000007A 24AC2408 09-0094 05C04E50 SRB 070C0000 8AA709B8 00000094 02CC90C0 02CC90EC 009DFE88 A0 09-0094 05C04E50 PC ... 0 0AA70A06 0030B 09-0094 00000000 SSRV 132 00000000 0000E602 00002000 7EF16000 00940000

For suspected loops you might need to concentrate on ASID and exclude any branch tracing:

ip systrace asid(x'3c') exclude(br)

ip summ format asid(x'94')To find the list of TCBs, issue a find command for "T C B".

ip verbx ledata 'ceedump asid(94) tcb(009DFE88)'Obtains a traceback for the specified TCB.

ip verbx vsmdata 'summary noglobal'Provides a memory usage report:

LOCAL STORAGE MAP ___________________________ | |80000000 <- Top of Ext. Private | Extended | | LSQA/SWA/229/230 |80000000 <- Max Ext. User Region Address |___________________________|7F4AE000 <- ELSQA Bottom | | | (Free Extended Storage) | |___________________________|127FE000 <- Ext. User Region Top | | | Extended User Region | |___________________________|10D00000 <- Ext. User Region Start : : : Extended Global Storage : =======================================<- 16M Line : Global Storage : :___________________________: A00000 <- Top of Private | | | LSQA/SWA/229/230 | A00000 <- Max User Region Address |___________________________| 9B8000 <- LSQA Bottom | | | (Free Storage) | |___________________________| 7000 <- User Region Top | | | User Region | |___________________________| 6000 <- User Region Start : System Storage : :___________________________: 0

ip verbx ledata 'nthreads(*)'Obtains the tracebacks for all threads.

ip status regsShows the PSW and registers:

CPU STATUS: BLS18058I Warnings regarding STRUCTURE(Psa) at ASID(X'0001') 00: BLS18300I Storage not in dump PSW=00000000 00000000 (Running in PRIMARY key 0 AMODE 24 DAT OFF) DISABLED FOR PER I/O EXT MCH ASCB99 at FA3200 JOB(JAVADV1) for the home ASID ASXB99 at 8FDD00 and TCB99G at 8C90F8 for the home ASID HOME ASID: 0063 PRIMARY ASID: 0063 SECONDARY ASID: 0063 General purpose register values Left halves of all registers contain zeros 0-3 00000000 00000000 00000000 00000000 4-7 00000000 00000000 00000000 00000000 8-11 00000000 00000000 00000000 00000000 12-15 00000000 00000000 00000000 00000000 Access register values 0-3 00000000 00000000 00000000 00000000 4-7 00000000 00000000 00000000 00000000 8-11 00000000 00000000 00000000 00000000 12-15 00000000 00000000 00000000 00000000


Control register values 0-1 00000000_5F04EE50 00000001_FFC3C007 2-3 00000000_5A057800 00000001_00C00063 4-5 00000000_00000063 00000000_048158C0 6-7 00000000_00000000 00000001_FFC3C007 8-9 00000000_00000000 00000000_00000000 10-11 00000000_00000000 00000000_00000000 12-13 00000000_0381829F 00000001_FFC3C007 14-15 00000000_DF884811 00000000_7F5DC138

ip cbf rtctHelps you to find the ASID by looking at the ASTB mapping to see which ASIDs are captured in thedump.

ip verbx vsmdata 'nog summ'Provides a summary of the virtual storage management data areas:

DATA FOR SUBPOOL 2 KEY 8 FOLLOWS:

-- DQE LISTING (VIRTUAL BELOW, REAL ANY64)

DQE: ADDR 12C1D000 SIZE 32000 DQE: ADDR 1305D000 SIZE 800000 DQE: ADDR 14270000 SIZE 200000 DQE: ADDR 14470000 SIZE 10002000 DQE: ADDR 24472000 SIZE 403000 DQE: ADDR 24875000 SIZE 403000 DQE: ADDR 24C78000 SIZE 83000 DQE: ADDR 24CFB000 SIZE 200000 DQE: ADDR 250FD000 SIZE 39B000 FQE: ADDR 25497028 SIZE FD8 DQE: ADDR 25498000 SIZE 735000 FQE: ADDR 25BCC028 SIZE FD8 DQE: ADDR 25D36000 SIZE 200000 DQE: ADDR 29897000 SIZE 200000 DQE: ADDR 2A7F4000 SIZE 200000 DQE: ADDR 2A9F4000 SIZE 200000 DQE: ADDR 2AC2F000 SIZE 735000 FQE: ADDR 2B363028 SIZE FD8 DQE: ADDR 2B383000 SIZE 200000 DQE: ADDR 2B5C7000 SIZE 200000 DQE: ADDR 2B857000 SIZE 1000

***** SUBPOOL 2 KEY 8 TOTAL ALLOC: 132C3000 ( 00000000 BELOW, 132C3000

ip verbx ledata 'all asid(54) tcb(009FD098)'Finds the PSW and registers at time of the exception:

+000348 MCH_EYE:ZMCH+000350 MCH_GPR00:00000000 000003E7 MCH_GPR01:00000000 00000000+000360 MCH_GPR02:00000001 00006160 MCH_GPR03:00000000 00000010+000370 MCH_GPR04:00000001 082FE780 MCH_GPR05:00000000 000000C0+000380 MCH_GPR06:00000000 00000000 MCH_GPR07:00000000 127FC6E8+000390 MCH_GPR08:00000000 00000007 MCH_GPR09:00000000 127FC708+0003A0 MCH_GPR10:00000001 08377D70 MCH_GPR11:00000001 0C83FB78+0003B0 MCH_GPR12:00000001 08300C60 MCH_GPR13:00000001 08377D00+0003C0 MCH_GPR14:00000000 112100D0 MCH_GPR15:00000000 00000000+0003D0 MCH_PSW:07852401 80000000 00000000 127FC6F8 MCH_ILC:0004+0003E2 MCH_IC1:00 MCH_IC2:04 MCH_PFT:00000000 00000000+0003F0 MCH_FLT_0:48410E4F 6C000000 4E800001 31F20A8D+000400 MCH_FLT_2:406F0000 00000000 00000000 00000000+000410 MCH_FLT_4:45800000 00000000 3FF00000 00000000+000420 MCH_FLT_6:00000000 00000000 00000000 00000000+0004B8 MCH_EXT:00000000 00000000

blscddir dsname('DUMPHLQ.ddir')Creates an IPCS DDIR.

runc addr(2657c9b8) link(20:23) chain(9999) le(x'1c') or runc addr(25429108) structure(tcb)Runs a chain of control blocks using the RUNCHAIN command.

addr: the start address of the first blocklink: the link pointer start and end bytes in the block (decimal)


chain: the maximum number of blocks to be searched (default=999)le: the length of data from the start of each block to be displayed (hex)structure: control block type

Debugging hangsA hang refers to a process that is still present, but has become unresponsive.

This lack of response can be caused by any one of these reasons:

• The process has become deadlocked, so no work is being done. Usually, the process is taking up noCPU time.

• The process has become caught in an infinite loop. Usually, the process is taking up high CPU time.• The process is running, but is suffering from very bad performance. This is not an actual hang, but is

often initially mistaken for one.

The process is deadlockedA deadlocked process does not use any CPU time.

You can monitor this condition by using the USS ps command against the Java process:

UID PID PPID C STIME TTY TIME CMDCBAILEY 253 743 - 10:24:19 ttyp0003 2:34 java -classpath .Test2Frame

If the value of TIME increases in a few minutes, the process is still using CPU, and is not deadlocked.

For an explanation of deadlocks and how the Javadump tool is used to diagnose them, see LOCKS.

The process is loopingIf no deadlock exists between threads and the process appears to be hanging but is consuming CPU time,look at the work the threads are doing. To do this, take a console-initiated dump (SVC dump).

Follow these steps to take a console-initiated dump:

1. Use the operating system commands (D OMVS,A=ALL) or SDSF (DA = Display Active) tolocate the ASID of interest.

2. Use the DUMP command to take a console-initiated dump both for hangs and for loops:

DUMP COMM=(Dump for problem 12345) R xx,ASID=(53,d),DSPNAME=('OMVS '.*),CONTR yy,SDATA=(GRSQ,LSQA,RGN,SUM,SWA,TRT,LPA,NUC,SQA)

Prefix all commands on the SDSF panels with a forward slash (/). The console responds to the DUMPcommand with a message requesting additional operands, and provides you with a 2-digit reply ID.You supply the additional operands using the R (reply) command, specifying the reply ID (shown as xxor yy in the previous example). You can use multiple replies for the operands by specifying the CONToperand, as in the previous example.

You can select the process to dump using the z/OS job name instead of the ASID:

R xx,JOBNAME=SSHD9,CONT

When the console dump has been generated, you can view the Systrace in IPCS to identify threads thatare looping. You can do this in IPCS as follows:

ip systrace asid(x'007d') time(gmt)

This command formats out the system trace entries for all threads that are in address space 0x7d. Thetime(gmt) option converts the TOD clock entries, which are in the system trace, to a human readableform.

From the output produced, you can determine which are the looping threads by identifying patterns ofrepeated CLCK and EXT1005 interrupt trace entries, and subsequent redispatch DSP entries. You can


identify the instruction address range of the loop from the PSWs (Program Status Words) that are tracedin these entries.

You can also analyze z/OS console (SVC) dumps using the system dump viewer provided in the SDK, seeDump viewer.

The process is performing badlyIf you have no evidence of a deadlock or an infinite loop, the process is probably suffering from very badperformance. Bad performance can be caused because threads have been placed into explicit sleep calls,or by excessive lock contention, long garbage collection cycles, or for several other reasons. Thiscondition is not a hang and should be handled as a performance problem.

See “Debugging performance problems on z/OS” on page 174 for more information.

Understanding Memory UsageTo debug memory leaks, you need to understand the mechanisms that can cause memory problems, howthe JVM uses the LE HEAP, how the JVM uses z/OS virtual storage, and the possible causes of ajava.lang.OutOfMemoryError exception.

Memory problems can occur in the Java process through the following mechanisms:

• A native (C/C++) memory leak that causes increased usage of the LE HEAP (31-bit VMs only), which canbe seen as excessive usage of Subpool2, Key 8, or storage, and an excessive Working Set Size of theprocess address space

• A Java object leak in the Java-managed heap. The leak is caused by programming errors in theapplication or the middleware. These object leaks cause an increase in the amount of live data thatremains after a garbage collection cycle is completed.

• Incorrect Java heap size. For example, the heap size might be too small for the amount of storage thatis required by the application. However, an excessively large heap size can result in a lack of MVSprivate area storage for other components, such as the native thread stack. Use the -Xmx option tooptimize the heap size for your application and environment.

• Under-allocation of storage areas. For example, if the REGION, MEMLIMIT, or MAXTHREADSparameters are set too low, or if storage areas are in contention with storage areas for other products,such as IBM CICS®.

Allocations to LE HEAPThe Java process makes two distinct allocation types to the LE HEAP.

The first type is the allocation of the Java heap that garbage collection manages (31-bit JVMs only; the64-bit JVM does not use the LE heap for the Java heap). The Java heap is allocated during JVM startup asa contiguous area of memory. Its size is that of the maximum Java heap size parameter. Even if theminimum, initial, heap size is much smaller, you must allocate for the maximum heap size to ensure thatone contiguous area will be available should heap expansion occur.

The second type of allocation to the LE HEAP is that of calls to malloc() by the JVM, or by any native JNIcode that is running under that Java process. This includes application JNI code, and vendor-suppliednative libraries; for example, JDBC drivers.

z/OS virtual storageTo debug these problems, you must understand how C/C++ programs, such as the JVM, use virtualstorage on z/OS. To do this, you need some background understanding of the z/OS Virtual StorageManagement component and LE.

The process address space on 31-bit z/OS has 24-bit addressing that allows the addressing of up 16 MBof virtual storage, and 31-bit addressing that allows the addressing of up to 2 GB of virtual storage. Theprocess address space on 64-bit z/OS additionally has 64-bit addressing that allows the addressing ofover 2 GB of virtual storage. This virtual storage includes areas that are defined as common (addressableby code running in all address spaces) and other areas that are private (addressable by code running inthat address space only).


The size of common areas is defined by several system parameters and the number of load modules thatare loaded into these common areas. On many typical systems, the total 31-bit private area available isabout 1.4 GB. From this area, memory resources required by the JVM and its subcomponents such as theJIT are allocated by calls to malloc(). These resources include: the Java native libraries, the Java heap(if you are using a 31-bit JVM), the Java classes (if you are using a 31-bit JVM or a 64-bit JVM withcompressed references), memory that is required by application JNI code, and third-party nativelibraries.

A Java OutOfMemoryError exception typically occurs when the Java heap is exhausted, but can alsooccur when any of the private storage areas are depleted, for example if there are many threads. Whenlarge numbers of threads are used, native stack storage can often be the largest private storage areabecause LE requires a minimum of 3 MB for each thread in a 64-bit JVM. So 2,000 threads results in theallocation of 6 GB, or more, of storage. For more information about OutOfMemoryError exceptions, see“Receiving OutOfMemoryError exceptions” on page 171. For more information about z/OS storageallocation, see the UNIX System Services z/OS Version 1 Release 7 Implementation Redbooks®

publication.

Related informationSetting Language Environment runtime options (z/OS only) (J9 VM reference)

Receiving OutOfMemoryError exceptionsAn OutOfMemoryError exception can result from running out of space on the Java heap or from runningout of space in any of the MVS private areas.




If an out-of-memory exception occurs and no error message is produced, the Java heap is probablyexhausted. To find the problem, you can try tracing or examining heap dumps. For more information, seeTracing leaks, or Using Heapdumps in the J9 VM reference.

If an OutOfMemoryError exception is thrown due to private storage area exhaustion under the 31-bitJVM, verify if the environment variable _BPX_SHAREAS is set to NO. If _BPX_SHAREAS is set to YESmultiple processes are allowed to share the same virtual storage (address space). The result is a muchquicker depletion of private storage area. For more information on _BPX_SHAREAS, see Setting_BPX_SHAREAS and _BPX_SPAWN_SCRIPT in the z/OS product documentation.

Some BPXPRMxx settings, for example MAXTHREADS and SHRLIBRGNSIZE, can also causeOutOfMemoryError exceptions. For more information, see BPXPRM settings (z/OS only) in the J9 VMreference.

Related informationMemory management (in the J9 VM reference)Setting Language Environment runtime options (z/OS only) (in the J9 VM reference)


http://www.redbooks.ibm.com/abstracts/sg247035.html

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/shbene.htm

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.bpxb200/shbene.htm



















17:54:40.377 0x2dfd00 j9jcl.335 > sun_misc_Unsafe_allocateDBBMemory(0x21d8)17:54:40.378 0x2dfd00 j9trc_aux.0 - jstacktrace:17:54:40.379 0x2dfd00 j9trc_aux.1 - [1] sun.misc.Unsafe.allocateDBBMemory (Native Method)17:54:40.380 0x2dfd00 j9trc_aux.1 - [2] java.nio.DirectByteBuffer.<init> (DirectByteBuffer.java:102)17:54:40.381 0x2dfd00 j9trc_aux.1 - [3] java.nio.ByteBuffer.allocateDirect (ByteBuffer.java:288)17:54:40.382 0x2dfd00 j9trc_aux.1 - [4] test.Test1a.allocatebuf (Test1a.java:10)17:54:40.383 0x2dfd00 j9trc_aux.1 - [5] test.Test1a.main (Test1a.java:14)17:54:40.383 0x2dfd00 j9jcl.337 < sun_misc_Unsafe_allocateDBBMemory result = 6B79D77017:54:40.388*0x6ba02300 j9jcl.338 > sun_misc_Unsafe_freeDBBMemory(6B79D770)17:54:40.389 0x6ba02300 j9trc_aux.0 - jstacktrace:17:54:40.390 0x6ba02300 j9trc_aux.1 - [1] sun.misc.Unsafe.freeDBBMemory (Native Method)17:54:40.391 0x6ba02300 j9trc_aux.1 - [2] java.nio.DirectByteBuffer$Deallocator.run (DirectByteBuffer.java:72)17:54:40.392 0x6ba02300 j9trc_aux.1 - [3] sun.misc.Cleaner.clean (Cleaner.java:125)17:54:40.393 0x6ba02300 j9trc_aux.1 - [4] java.lang.ref.ReferenceQueue.enqueue (ReferenceQueue.java:137)


17:54:40.393 0x6ba02300 j9trc_aux.1 - [5] java.lang.ref.Reference.enqueueImpl (Reference.java:74)












Debugging performance problems on z/OSLocating the causes of poor performance is often difficult. Although many factors can affect performance,the overall effect is generally perceived as poor response time or slow execution of your program.


Finding the bottleneckThe aspects of the system that you are most interested in measuring are CPU usage and memory usage.It is possible that even after extensive tuning efforts the CPU is not powerful enough to handle theworkload, in which case a CPU upgrade is required. Similarly, if the program is running in an environmentin which it does not have enough memory after tuning, you must increase memory size.

Given that any performance problem could be caused by any one of several factors, you must look atseveral areas to eliminate each one. First, determine which resource is constraining the system:

• CPU• Memory• Input/Output (I/O)

z/OS systems resource usageThe z/OS Resource Measurement Facility (RMF) gives a detailed view of z/OS processor, memory, and I/Odevice performance metrics.

JIT compilation and performanceThe JIT is another area that can affect the performance of your program. When deciding whether or not touse JIT compilation, you must make a balance between faster execution and increased processor usageduring compilation .

The performance of short-running applications can be improved by using the -Xquickstart command-lineparameter. The JIT is switched on by default, but you can use -Xint to turn it off. You also haveconsiderable flexibility in controlling JIT processing. For more details about the JIT, see The JIT compilerand Diagnosing a JIT or AOT problem in the J9 VM reference..





MustGather information for z/OSThe more information that you can collect about a problem, the easier it is to diagnose that problem. Alarge set of data can be collected, although some is relevant to particular problems.


The data that is collected from a fault situation in z/OS depends on the problem symptoms, but couldinclude some or all of the following information:

• Transaction dump - an unformatted dump that is requested by the MVS BCP IEATDUMP service. Formore information, see “Setting up dumps” on page 160. This dump can be post-processed with thedump viewer (see Using the dump viewer in the OpenJ9 user documentation), the dbx debugger, orIPCS (Interactive Problem Control System).

• CEEDUMP - formatted application level dump, requested by the cdump system call.• Javadump - formatted internal state data that is produced by the IBM VM.• Binary or formatted trace data from the JVM internal high performance trace. See Using method trace in

the OpenJ9 user documentation and Tracing Java applications in the J9 VM reference.• Debugging messages that are written to stderr. For example, the output from the JVM when switches

like -verbose:gc, -verbose, or -Xtgc are used.• Java stack traces when exceptions are thrown.• JIT dump - a binary file of diagnostic data that is produced by the JVM in response to a GPF or abort

event. For more information, see JIT dumps in the OpenJ9 user documentation.• Other unformatted system dumps obtained from middleware products or components (for example,

SVC dumps requested by WebSphere for z/OS).• SVC dumps obtained by the MVS Console DUMP command (typically for loops or hangs, or when the

IEATDUMP fails).• Trace data from other products or components (for example LE traces or the Component trace for z/OS

UNIX).• Heapdumps, if generated automatically, are required for problem determination. You should also take a

Heapdump if you have a memory or performance problem.

NLS problem determinationThe SDK contains built-in support for different locales. This section provides an overview of locales, withthe main focus on fonts and font management.

Overview of fonts for globalizationWhen you want to show text, either in SDK components (AWT or Swing), on the console or in anyapplication, characters must be mapped to glyphs.

A glyph is an artistic representation of the character, in some typographical style, and is stored in the formof outlines or bitmaps. Glyphs might not correspond one-for-one with characters. For instance, an entirecharacter sequence can be represented as a single glyph. Also, a single character can be represented bymore than one glyph (for example, in Indic scripts).

A font is a set of glyphs. Each glyph is encoded in a particular encoding format, so that the character toglyph mapping can be done using the encoded value. Almost all of the available Java fonts are encoded inUnicode and provide universal mappings for all applications.

The most commonly available font types are TrueType and OpenType fonts.

Font specification properties

Specify fonts according to the following characteristics:


Font familyFont family is a group of several individual fonts that are related in appearance. For example: Times,Arial, and Helvetica.

Font styleFont style specifies that the font is displayed in various faces. For example: Normal, Italic, andOblique

Font variantFont variant determines whether the font is displayed in normal caps or in small caps. A particularfont might contain only normal caps, only small caps, or both types of glyph.

Font weightFont weight describes the boldness or the lightness of the glyph to be used.

Font sizeFont size is used to modify the size of the displayed text.

Fonts installed in the system

On Linux or UNIX platformsTo see the fonts that are either installed in the system or available for an application to use, type thecommand:

xset -q ""

If your PATH also points to the SDK (as expected), a result of running the command:

xset -q

is a list of the fonts that are bundled with the Developer Kit.

To add a font path, use the command:

xset +fp

To remove a font path, use the command:

xset -fp

On Windows platformsMost text processing applications have a drop-down list of the available system fonts, or you can usethe Settings > Control Panel > Fonts application.

Default font

If an application attempts to create a font that cannot be found, the font Dialog Lucida Sans Regular isused as the default font.

Font utilities for globalizationA list of font utilities that are supported for globalization.

Font utilities on AIX, Linux, and z/OSxfd (AIX)

Use the command xfd -fn <physical font name> in AIX to find out about the glyphs and theirrendering capacity. For example: Xfd -fn monotype-sansmonowt-medium-r-normal--*-%d-75-75-m-*-ibm-udcjp brings up a window with all the glyphs that are in that font.

xlsfontsUse xlsfonts to check whether a particular font is installed on the system. For example: xlsfonts |grep ksc will list all the Korean fonts in the system.


iconvUse to convert the character encoding from one encoding to other. Converted text is written tostandard output. For example: iconv -f oldset -t newset [file ...]

Options are:

-f oldsetSpecifies the source codeset (encoding).

-t newsetSpecifies the destination codeset (encoding).

fileThe file that contain the characters to be converted; if no file is specified, standard input is used.

Font utilities on Windows systems

Windows has no built-in utilities similar to those offered by other platforms.

Common globalization problems and possible causesCommon globalization problems with potential solutions.Why do I see a square box or ??? (question marks) in the SDK components?

This effect is caused mainly because Java is not able to find the correct font file to display thecharacter. If a Korean character should be displayed, the system should be using the Korean locale,so that Java can take the correct font file. If you are seeing boxes or queries, check the followingitems:

For Swing components:

1. Check your locale with locale2. To change the locale, export LANG=zh_TW (for example)3. If you know which font you have used in your application, such as serif, try to get the

corresponding physical font by looking in the fontpath. If the font file is missing, try adding it there.

Characters displayed in the console but not in the SDK Components and vice versa (AIX only).Characters that should be displayed in the console are handled by the native operating system. Thus,if the characters are not displayed in the console, in AIX use the xlfd <physical font name>command to check whether the system can recognize the character or not.

Using diagnostic toolsDiagnostic tools are available to help you solve your problems.

Using the IBM Monitoring and Diagnostic ToolsThe IBM Monitoring and Diagnostic Tools are a set of GUI-based tools which you can use to monitor yourapplications, analyze resource usage, and diagnose problems. The tools can help you to optimizeapplication performance, improve application stability, reduce resource usage, and resolve problemsmore quickly.

The tools provide output in various formats, such as tables, charts, graphs, and recommendations. Usethis output to complete the following diagnostic tasks:

• Detect deadlock conditions• Monitor thread activity• See which methods are taking the most time to run• See which objects are using the most memory• Find memory leaks and I/O bottlenecks• Analyze the efficiency of Java collections, such as arrays


• Understand the relationships between application objects• Visualize garbage collection performance• Get recommendations for tuning the Java virtual machine (VM) and improving application performance

The following tools are available:Health Center

Monitor a running VM, with minimal performance overhead. Tuning recommendations are alsoprovided.

Garbage Collection and Memory VisualizerAnalyze the memory usage, garbage collection behavior, and performance of applications, by plottingverbose garbage collection data from dump files. Tuning recommendations are also provided.

Interactive Diagnostic Data ExplorerUse commands to extract information from dump files. This tool is a GUI-based version of thejdmpview command, with extra features.

Memory AnalyzerAnalyze the memory usage and performance of applications, using data from dump files.

The tools are available to download, free of charge, into IBM Support Assistant. Most tools are alsoavailable to download from Eclipse marketplace. The IBM Support Assistant is a free workbench that isdesigned to help you with problem determination. The IBM Monitoring and Diagnostic Tools is just one setof tools that you can install into the IBM Support Assistant.

For more information about the IBM Monitoring and Diagnostic Tools, see the IBM Monitoring andDiagnostic Tools product documentation on IBM Knowledge Center, and theIBM Monitoring andDiagnostic Tools developerWorks page.

Garbage Collection and Memory VisualizerGarbage Collection and Memory Visualizer (GCMV) helps you understand memory use, garbage collectionbehavior, and performance of applications.

GCMV parses and plots data from various types of log, including the following types:

• Verbose garbage collection logs.• Trace garbage collection logs, generated by using the -Xtgc parameter.• Native memory logs, generated by using the ps, svmon, or perfmon system commands.

The tool helps to diagnose problems such as memory leaks, analyze data in various visual formats, andprovides tuning recommendations.

GCMV is available from Eclipse marketplace and as an IBM Support Assistant (ISA) add-on. Forinformation about installing and getting started with the add-on, see this developerWorks GCMV article.

Further information about GCMV is available in IBM Knowledge Center.

Health CenterHealth Center is a diagnostic tool for monitoring the status of a running application.

The tool is provided in two parts:

• The Health Center agent that collects data from a running application.• An Eclipse-based client that connects to the agent. The client interprets the data and provides

recommendations to improve the performance of the monitored application.

Health Center is available from Eclipse marketplace and as an IBM Support Assistant (ISA) add-on. Forinformation about installing and getting started with the add-on, see: https://www.ibm.com/developerworks/java/jdk/tools/healthcenter/.

Further information about Health Center is available in IBM Knowledge Center.


https://www.ibm.com/support/home/product/C100515X13178X21/other_software/ibm_support_assistant

http://marketplace.eclipse.org/

https://www.ibm.com/support/knowledgecenter/SS3KLZ/SS3KLZ/welcome_tools_family.html

https://www.ibm.com/support/knowledgecenter/SS3KLZ/SS3KLZ/welcome_tools_family.html

https://www.ibm.com/developerworks/java/jdk/tools/index.html

https://www.ibm.com/developerworks/java/jdk/tools/index.html

https://www.ibm.com/developerworks/java/jdk/tools/gcmv/

https://www.ibm.com/support/knowledgecenter/SS3KLZ/com.ibm.java.diagnostics.visualizer.doc/homepage/plugin-homepage-gcmv.html

https://www.ibm.com/developerworks/java/jdk/tools/healthcenter/

https://www.ibm.com/developerworks/java/jdk/tools/healthcenter/

https://www.ibm.com/support/knowledgecenter/SS3KLZ/com.ibm.java.diagnostics.healthcenter.doc/homepage/plugin-homepage-hc.html

Interactive Diagnostic Data ExplorerInteractive Diagnostic Data Explorer (IDDE) is a GUI-based alternative to the dump viewer (jdmpviewcommand). IDDE provides the same functionality as the dump viewer, but with extra support such as theability to save command output.

Use IDDE to more easily explore and examine dump files that are produced by your Java virtual machine.Within IDDE, you enter commands in an investigation log, to explore the dump file. The support that isprovided by the investigation log includes the following items:

• Command assistance• Auto-completion of text, and some parameters such as class names• The ability to save commands and output, which you can then send to other people• Highlighted text and flagging of issues• The ability to add your own comments• Support for using the Memory Analyzer from within IDDE

IDDE is available from Eclipse marketplace and as an IBM Support Assistant (ISA) add-on. Forinformation about installing and getting started with the add-on, see IDDE overview on developerWorks.

Further information about IDDE is available in IBM Knowledge Center.

Memory AnalyzerMemory Analyzer helps you analyze Java dump files, Java heap dump files, and system dump files.

This tool can analyze dump files that contain millions of objects, providing the following information:

• The retained sizes of objects.• Processes that are preventing the garbage collector from collecting objects.• A report to automatically extract leak suspects.

This tool is based on the Eclipse Memory Analyzer (MAT) project, and uses the IBM Diagnostic ToolFramework for Java (DTFJ) feature to enable the processing of dump files from IBM virtual machines.

Memory Analyzer is provided as an IBM Support Assistant (ISA) add-on. For information about installingand getting started with the add-on, see: https://developer.ibm.com/javasdk/tools/.

Further information about Memory Analyzer is available in IBM Knowledge Center.

IBM Support Assistant Data CollectorIBM Support Assistant Data Collector helps you to quickly collect diagnostic files, such as dump, log, andconfiguration files. The tool also helps you to send the collected data to IBM, if required. You candownload the tool for free, or use the online version.

The Java runtime environment produces multiple diagnostic files in response to events such as GeneralProtection Faults, out of memory conditions or receiving unexpected operating system signals. Use theIBM Support Assistant Data Collector to collect this diagnostic data together, and send it to IBM ifrequired. For more information about this tool, see IBM Support Assistant.

Using the HPROF ProfilerHPROF is a demonstration profiler shipped with the IBM SDK that uses the JVMTI to collect and recordinformation about Java execution. You can use HPROF to work out which parts of a program are using themost memory or processor time.

Note: For analyzing memory usage, you should use IBM Monitoring and Diagnostic Tools for Java -Memory Analyzer, which is a newer tool. For more information about this tool, see “Using the IBMMonitoring and Diagnostic Tools” on page 177.

To improve the efficiency of your applications, you must know which parts of the code are using largeamounts of memory and processor resources. HPROF is an example JVMTI agent and is started using thefollowing syntax:


https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=5efb4378-ebba-47da-8c0f-8841d669d0cc

https://www.ibm.com/support/knowledgecenter/SS3KLZ/com.ibm.java.diagnostics.idde.doc/homepage/plugin-homepage-idde.html

https://developer.ibm.com/javasdk/tools/

https://www.ibm.com/support/knowledgecenter/SS3KLZ/com.ibm.java.diagnostics.memory.analyzer.doc/homepage/plugin-homepage-ma.html

https://www.ibm.com/support/home/product/C100515X13178X21/other_software/ibm_support_assistant

java -Xrunhprof[:<option>=<value>,...] <classname>

When you run Java with HPROF, a file is created when the program ends. This file is placed in the currentworking directory and is called java.hprof.txt (java.hprof if binary format is used) unless adifferent file name has been given. This file contains a number of different sections, but the exact formatand content depend on the selected options.

If you need more information about HPROF than is contained in this section, see https://docs.oracle.com/javase/8/docs/technotes/samples/hprof.html.

The command java -Xrunhprof:help shows the options available:

heap=dump|sites|allThis option helps in the analysis of memory usage. It tells HPROF to generate stack traces, fromwhich you can see where memory was allocated. If you use the heap=dump option, you get a dumpof all live objects in the heap. With heap=sites, you get a sorted list of sites with the most heavilyallocated objects at the start. The default value all gives both types of output.

cpu=samples|times|oldThe cpu option provides information that is useful in determining where the processor spends most ofits time. If cpu is set to samples, the JVM pauses execution and identifies which method call is active.If the sampling rate is high enough, you get a good picture of where your program spends most of itstime. If cpu is set to times, you receive precise measurements of how many times each method wascalled and how long each execution took. Although this option is more accurate, it slows down theprogram. If cpu is set to old, the profiling data is produced in the old HPROF format.

interval=y|nThe interval option applies only to cpu=samples and controls the time that the sampling threadsleeps between samples of the thread stacks.

monitor=y|nThe monitor option can help you understand how synchronization affects the performance of yourapplication. Monitors implement thread synchronization. Getting information about monitors can tellyou how much time different threads are spending when trying to access resources that are alreadylocked. HPROF also gives you a snapshot of the monitors in use. This information is useful fordetecting deadlocks.

format=a|bThe default for the output file is ASCII format. Set format to 'b' if you want to specify a binary format,which is required for some utilities like the Heap Analysis Tool.

file=<filename>Use the file option to change the name of the output file. The default name for an ASCII file isjava.hprof.txt. The default name for a binary file is java.hprof.

force=y|nTypically, the default (force=y) overwrites any existing information in the output file. So, if you havemultiple JVMs running with HPROF enabled, use force=n, which appends additional characters to theoutput file name as needed.

net=<host>:<port>To send the output over the network rather than to a local file, use the net option.

depth=<size>The depth option indicates the number of method frames to display in a stack trace. The default is 4.

thread=y|nIf you set the thread option to y, the thread ID is printed next to each trace. This option is useful if youcannot see which thread is associated with which trace. This type of problem might occur in a multi-threaded application.

doe=y|nThe default behavior is to collect profile information when an application exits. To collect the profilingdata during execution, set doe (dump on exit) to n.


https://docs.oracle.com/javase/8/docs/technotes/samples/hprof.html

https://docs.oracle.com/javase/8/docs/technotes/samples/hprof.html

msa=y|nThis feature is unsupported on IBM SDK platforms.

cutoff=<value>Many sample entries are produced for a small percentage of the total execution time. By default,HPROF includes all execution paths that represent at least 0.0001 percent of the time spent by theprocessor. You can increase or decrease that cutoff point using this option. For example, to eliminateall entries that represent less than one-fourth of one percent of the total execution time, you specifycutoff=0.0025.

verbose=y|nThis option generates a message when dumps are taken. The default is y.

lineno=y|nEach frame typically includes the line number that was processed, but you can use this option tosuppress the line numbers from the output listing. If enabled, each frame contains the text Unknownline instead of the line number.

TRACE 1056:java/util/Locale.toUpperCase(Locale.java:Unknown line)java/util/Locale.<init>(Locale.java:Unknown line)java/util/Locale.<clinit>(Locale.java:Unknown line)sun/io/CharacterEncoding.aliasName(CharacterEncoding.java:Unknown line)

Explanation of the HPROF output fileThe first section of the file contains general header information such as an explanation of the options,copyright, and disclaimers. A summary of each thread follows.

You can see the output after using HPROF with a simple program, shown as follows. This test programcreates and runs two threads for a short time. From the output, you can see that the two threads calledapples and then oranges were created after the system-generated main thread. Both threads endbefore the main thread. For each thread its address, identifier, name, and thread group name aredisplayed. You can see the order in which threads start and finish.

THREAD START (obj=11199050, id = 1, name="Signal dispatcher", group="system")THREAD START (obj=111a2120, id = 2, name="Reference Handler", group="system")THREAD START (obj=111ad910, id = 3, name="Finalizer", group="system")THREAD START (obj=8b87a0, id = 4, name="main", group="main")THREAD END (id = 4)THREAD START (obj=11262d18, id = 5, name="Thread-0", group="main")THREAD START (obj=112e9250, id = 6, name="apples", group="main")THREAD START (obj=112e9998, id = 7, name="oranges", group="main")THREAD END (id = 6)THREAD END (id = 7)THREAD END (id = 5)

The trace output section contains regular stack trace information. The depth of each trace can be set andeach trace has a unique ID:

TRACE 5: java/util/Locale.toLowerCase(Locale.java:1188) java/util/Locale.convertOldISOCodes(Locale.java:1226) java/util/Locale.<init>(Locale.java:273) java/util/Locale.<clinit>(Locale.java:200)

A trace contains a number of frames, and each frame contains the class name, method name, file name,and line number. In the previous example, you can see that line number 1188 of Locale.java (which isin the toLowerCase method) has been called from the convertOldISOCodes() function in the sameclass. These traces are useful in following the execution path of your program. If you set the monitoroption, a monitor dump is produced that looks like this example:

MONITOR DUMP BEGIN THREAD 8, trace 1, status: R THREAD 4, trace 5, status: CW THREAD 2, trace 6, status: CW THREAD 1, trace 1, status: R MONITOR java/lang/ref/Reference$Lock(811bd50) unowned waiting to be notified: thread 2


MONITOR java/lang/ref/ReferenceQueue$Lock(8134710) unowned waiting to be notified: thread 4 RAW MONITOR "_hprof_dump_lock"(0x806d7d0) owner: thread 8, entry count: 1 RAW MONITOR "Monitor Cache lock"(0x8058c50) owner: thread 8, entry count: 1 RAW MONITOR "Monitor Registry lock"(0x8058d10) owner: thread 8, entry count: 1 RAW MONITOR "Thread queue lock"(0x8058bc8) owner: thread 8, entry count: 1MONITOR DUMP ENDMONITOR TIME BEGIN (total = 0 ms) Thu Aug 29 16:41:59 2002MONITOR TIME END

The first part of the monitor dump contains a list of threads, including the trace entry that identifies thecode the thread executed. There is also a thread status for each thread where:

• R — Runnable (The thread is able to run when given the chance)• S — Suspended (The thread has been suspended by another thread)• CW — Condition Wait (The thread is waiting)• MW — Monitor Wait (The monitor is waiting)

Next is a list of monitors along with their owners and an indication of whether there are any threadswaiting on them.

The Heapdump is the next section. This information contains a list of the different areas of memory, andshows how they are allocated:

CLS 1123edb0 (name=java/lang/StringBuffer, trace=1318) super 111504e8 constant[25] 8abd48 constant[32] 1123edb0 constant[33] 111504e8 constant[34] 8aad38 constant[115] 1118cdc8CLS 111ecff8 (name=java/util/Locale, trace=1130) super 111504e8 constant[2] 1117a5b0 constant[17] 1124d600 constant[24] 111fc338 constant[26] 8abd48 constant[30] 111fc2d0 constant[34] 111fc3a0 constant[59] 111ecff8 constant[74] 111504e8 constant[102] 1124d668 ...CLS 111504e8 (name=java/lang/Object, trace=1) constant[18] 111504e8

CLS tells you that memory is being allocated for a class. The hexadecimal number following it is theaddress where that memory is allocated.

Next is the class name followed by a trace reference. Use this information to cross-reference the traceoutput and see when the class is called. If you refer to that particular trace, you can get the line numberof the instruction that led to the creation of this object. The addresses of the constants in this class arealso displayed and, in the previous example, the address of the class definition for the superclass. Bothclasses are a child of the same superclass (with address 11504e8). Looking further through the output,you can see this class definition and name. It is the Object class (a class that every class inherits from).The JVM loads the entire superclass hierarchy before it can use a subclass. Thus, class definitions for allsuperclasses are always present. There are also entries for Objects (OBJ) and Arrays (ARR):

OBJ 111a9e78 (sz=60, trace=1, class=java/lang/Thread@8b0c38) name 111afbf8 group 111af978 contextClassLoader 1128fa50 inheritedAccessControlContext 111aa2f0 threadLocals 111bea08 inheritableThreadLocals 111bea08ARR 8bb978 (sz=4, trace=2, nelems=0, elem type=java/io/ObjectStreamField@8bac80)


If you set the heap option to sites or all , you get a list of each area of storage allocated by your code. Theparameter all combines dump and sites. This list is ordered starting with the sites that allocate the mostmemory:

SITES BEGIN (ordered by live bytes) Tue Feb 06 10:54:46 2007 percent live alloc'ed stack class rank self accum bytes objs bytes objs trace name 1 20.36% 20.36% 190060 16 190060 16 300000 byte[] 2 14.92% 35.28% 139260 1059 139260 1059 300000 char[] 3 5.27% 40.56% 49192 15 49192 15 300055 byte[] 4 5.26% 45.82% 49112 14 49112 14 300066 byte[] 5 4.32% 50.14% 40308 1226 40308 1226 300000 java.lang.String 6 1.62% 51.75% 15092 438 15092 438 300000 java.util.HashMap$Entry 7 0.79% 52.55% 7392 14 7392 14 300065 byte[] 8 0.47% 53.01% 4360 16 4360 16 300016 char[] 9 0.47% 53.48% 4352 34 4352 34 300032 char[] 10 0.43% 53.90% 3968 32 3968 32 300028 char[] 11 0.40% 54.30% 3716 8 3716 8 300000 java.util.HashMap$Entry[] 12 0.40% 54.70% 3708 11 3708 11 300000 int[] 13 0.31% 55.01% 2860 16 2860 16 300000 java.lang.Object[] 14 0.28% 55.29% 2644 65 2644 65 300000 java.util.Hashtable$Entry 15 0.28% 55.57% 2640 15 2640 15 300069 char[] 16 0.27% 55.84% 2476 17 2476 17 300000 java.util.Hashtable$Entry[] 17 0.25% 56.08% 2312 16 2312 16 300013 char[] 18 0.25% 56.33% 2312 16 2312 16 300015 char[] 19 0.24% 56.57% 2224 10 2224 10 300000 java.lang.Class

In this example, Trace 300055 allocated 5.27% of the total allocated memory. This percentage works outto be 49192 bytes.

The cpu option gives profiling information about the processor. If cpu is set to samples, the outputcontains the results of periodic samples taken during execution of the code. At each sample, the codepath being processed is recorded, and a report is produced similar to:

CPU SAMPLES BEGIN (total = 714) Fri Aug 30 15:37:16 2002rank self accum count trace method1 76.28% 76.28% 501 77 MyThread2.bigMethod2 6.92% 83.20% 47 75 MyThread2.smallMethod...CPU SAMPLES END

You can see that the bigMethod() was responsible for 76.28% of the processor execution time and wasbeing run 501 times out of the 714 samples. If you use the trace IDs, you can see the exact route that ledto this method being called.


Chapter 10. Exploiting data compression devices

• “Enabling hardware compression acceleration (AIX, Linux only)” on page 185• “zEnterprise Data Compression (z/OS only)” on page 188

Enabling hardware compression acceleration (AIX, Linux only)You can use hardware compression acceleration to increase the speed of data compression anddecompression on some Power Systems or IBM Z systems. If your application uses java.util.zipclasses to provide Java compression services, hardware compression can reduce CPU consumption andshorten processing times.

Before you beginHardware compression is done by a PCIe data compression/decompression card, driven by the GenericWork Queue Engine (GenWQE) device driver that is provided in some operating systems. If you want yourJava applications to use hardware compression services, your system must meet the following softwareand hardware requirements:AIX

• AIX 7.1, Technology Level 3, Service Pack 2, or later• GenWQE device driver. The aforementioned operating systems already include this driver.• PCIe3 LP Field Programmable Gate Array (FPGA) Accelerator Adapter

Linux on Power Systems

• One of the following operating systems:

– Red Hat Enterprise Linux 7 for 64-bit Power Systems

– Red Hat Enterprise Linux 7.1 for 64-bit Power Systems (Little Endian)– Red Hat Enterprise Linux 7.3 for 64-bit Power Systems (Little Endian)

• GenWQE device driver. The aforementioned operating systems already include this driver.• PCIe3 LP Field Programmable Gate Array (FPGA) Accelerator Adapter

Linux on IBM Z

• One of the following hardware systems: IBM zEnterprise zEC12 GA2, zBC12, z13, z14, z15 or later . Additional requirements depend on your hardware system:

z15 and laterThere are no hardware or software requirements for z15 or later systems. The IntegratedAccelerator for zEDC solution in these systems provides built-in data acceleration, so a separateadapter is no longer required.

z14 and earlier

• One of the following operating systems:

– SUSE Linux Enterprise Server for System z 12 SP1 or later

– Red Hat Enterprise Linux 7.2 for z Systems• GenWQE device driver. The aforementioned operating systems already include this driver.


• One of the following hardware systems: IBM zEnterprise zEC12 GA2, zBC12, z13, or z14.• zEDC Express adapter, installed in the PCIe I/O drawers of the server.

Note: Hardware compression on z14 and earlier systems uses the zEDC Express adapter, which isnow deprecated.

For more information about installing and using GenWQE, see Generic Work Queue Engine (GenWQE)introduction in the Linux information.

About this taskAccelerated Data Compression is provided as part of the developer kit Zip native library, which you call byusing the java.util.zip application programming interface.

Procedure

1. z14 and earlier only: Set the following environment variables:

export ZLIB_DEFLATE_IMPL=1export ZLIB_INFLATE_IMPL=1

These environment variables specify whether hardware or software compression or decompression isused. By default, both variables are set to 0, which specifies that software compression services areused for both compression and decompression for Java applications.

2. z14 and earlier only: Check that the input buffers for your Java application are sufficiently large.

Some CPU resource is required to send data to the hardware compression accelerator. For smallamounts of data, this resource cost can be greater than the savings that are achieved by usinghardware compression services. You can set a threshold value for the data that is to be sent tohardware compression services, by using the ZLIB_INFLATE_THRESHOLD variable. If the size of thedata is below the threshold (default 16 KB), software compression is used instead.

Here are some methods for determining an application's current buffer size:

• Examine the source code• Examine the behavior of the application by tracing it (see Tracing Java applications in the J9 VM

reference), or monitoring it with Monitoring and Diagnostic Tools3. In your Java application, use the classes and methods in the java.util.zip package to compress

and decompress data.The following example (which excludes imports and try/catch blocks) uses the GZIPOutputStreamclass to read data from one file and write compressed data to another file:

// This 64 KB input buffer exceeds the threshold value set by ZLIB_INFLATE_THRESHOLD, // so is elegible for hardware compression:byte buffer[] = new byte[64 * 1024];byte outputFile[];

input = new FileInputStream(argv[0]);output = new ByteArrayOutputStream();gzStream = new GZIPOutputStream(output, 4096);

for(;;) { // Read data from an uncompressed file: readBytes = input.read(buffer); if(readBytes < 0) { break; } else { // Write data to a compressed file: gzStream.write(buffer, 0, readBytes); }}


https://www.ibm.com/support/knowledgecenter/linuxonibm/liabt/liabtkickoff.htm

https://www.ibm.com/support/knowledgecenter/linuxonibm/liabt/liabtkickoff.htm

https://docs.oracle.com/javase/8/docs/api/java/util/zip/package-summary.html

Results

If your system meets the requirements and conditions that are described, accelerated hardware datacompression is used. Otherwise, software-based compression services are used for data compressionand decompression.

If you want to measure the difference in performance for your Java application with and without hardwarecompression, you can use the following environment variables to temporarily disable hardwareacceleration:

• z15 or later: DFLTCC=0• z14 or earlier: ZLIB_DEFLATE_IMPL=0 for compression and ZLIB_INFLATE_IMPL=0 for

decompression.

If you experience problems, see “Hardware compression acceleration issues on Power Systems and IBMZ systems (AIX, Linux only)” on page 187.

Related informationdeveloperWorks article: Accelerated Data Compressing using the GenWQE Linux Driver and Corsa FPGAPCIe cardzEnterprise Data Compression (zEDC)

Hardware compression acceleration issues on Power Systems and IBM Z systems (AIX,Linux only)

Check that you have the required software and hardware, that environment variables are not set todisable hardware compression, and that your device driver is working correctly, then use the tracefunction to check that your system is using hardware compression services and not software compressionservices. Analyze the trace output to find the point of failure.

Checking hardware and software requirements

You must have specific hardware and software components to use hardware compression services. Youcan read about the prerequisites in “Enabling hardware compression acceleration (AIX, Linux only)” onpage 185.

Checking that environment variables are not set to disable hardware compression

Linux on IBM Z: Check that the following environment variables are not set to 0, which disables hardwareacceleration:

• For IBM z15 or later: DFLTCC• For IBM z14® or earlier: ZLIB_DEFLATE_IMPL for compression and ZLIB_INFLATE_IMPL for

decompression.

Checking that your device driver is working correctly

Linux: Check that your Generic Work Queue Engine (GenWQE) device driver is working correctly. Use thefollowing publications to help:

• For Power Systems: Troubleshooting GenWQE• For IBM Z systems: Device Drivers, Features, and Commands.

Using trace to check that your system is using hardware compression

You can turn on tracing with the environment variable ZLIB_TRACE. Use one of the following values:

• 0x1: provides general information• 0x2: provides hardware information• 0x4: provides software information

Chapter 10. Exploiting data compression devices 187

https://www.ibm.com/developerworks/community/files/form/anonymous/api/library/f57fde24-5f30-4295-91fb-e612c6a7a75a/document/84c8bd13-0402-4540-b2f3-b6362a81e53a/media/GenWQE-GZIP-for-Linux-Doc.pdf

https://www.ibm.com/developerworks/community/files/form/anonymous/api/library/f57fde24-5f30-4295-91fb-e612c6a7a75a/document/84c8bd13-0402-4540-b2f3-b6362a81e53a/media/GenWQE-GZIP-for-Linux-Doc.pdf

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ieac100/zEDC.htm

https://www.ibm.com/support/knowledgecenter/linuxonibm/liabt/liabttrouble.htm

https://www.ibm.com/support/knowledgecenter/linuxonibm/liaaf/lnz_r_dd.html

• 0x8: provides both hardware and software information• 0xf: provides general, hardware, and software information

For example, to turn on trace and obtain general, hardware, and software information, specify thefollowing command at a shell prompt:

export ZLIB_TRACE=0xf

Here is an example of trace output when an application is run in default mode, which uses softwarecompression and decompression:

### _init: BUILD=Feb 6 2014 ZLIB_TRACE=f ZLIB_INFLATE_IMPL=0 ZLIB_DEFLATE_IMPL=0 ### [111def7b0] inflateInit2_: windowBits=-15 version=1.2.7/1.2.7 stream_size=88 impl=0### [111def7b0] inflate: flush=1 next_in=5fe546b8 avail_in=0 next_out=5fe54d60 avail_out=327 total_in=0### [111def7b0] flush=1 next_in=5fe546b8 avail_in=0 next_out=5fe54d60 avail_out=327 total_in=0 rc=-5### [111def7b0] inflate: flush=1 next_in=5fe54b10 avail_in=210 next_out=5fe54d60 avail_out=327 total_in=0### [111def7b0] flush=1 next_in=5fe54be2 avail_in=0 next_out=5fe54ea7 avail_out=0 total_in=210 rc=1### [111def7b0] inflateReset...

The first line in the trace shows that the environment variables ZLIB_INFLATE_IMPL andZLIB_DEFLATE_IMPL are set to 0, which indicates that software compression and decompression modeis enabled. Subsequent lines show that the zlib software APIs, such as inflate, are in use. The traceincludes information on the number of input and output bytes that are available, which can be useful fordebugging problems.

Here is an example of trace output when an application is run in hardware compression anddecompression mode:

### _init: BUILD=Feb 6 2014 ZLIB_TRACE=f ZLIB_INFLATE_IMPL=1 ZLIB_DEFLATE_IMPL=1 ### [111e0f7b0] inflateInit2_: windowBits=-15 version=1.2.7/1.2.7 stream_size=88 impl=1hhh [111e0f7b0] h_inflateInit2_: card_no=-1 ibuf_total=0### [111e0f7b0] inflate: flush=1 next_in=5fe54eb8 avail_in=0 next_out=5fe55560 avail_out=327 total_in=0hhh [111e0f7b0] h_inflate: flush=1 next_in=5fe54eb8 avail_in=0 next_out=5fe55560 avail_out=327hhh [111e0f7b0] flush=1 next_in=5fe54eb8 avail_in=0 next_out=5fe55560 avail_out=327 rc=0### [111e0f7b0] flush=1 next_in=5fe54eb8 avail_in=0 next_out=5fe55560 avail_out=327 total_in=0 rc=0### [111e0f7b0] inflate: flush=1 next_in=5fe55310 avail_in=210 next_out=5fe55560 avail_out=327 total_in=0hhh [111e0f7b0] h_inflate: flush=1 next_in=5fe55310 avail_in=210 next_out=5fe55560 avail_out=327hhh [111e0f7b0] flush=1 next_in=5fe553e2 avail_in=0 next_out=5fe556a7 avail_out=0 rc=1### [111e0f7b0] flush=1 next_in=5fe553e2 avail_in=0 next_out=5fe556a7 avail_out=0 total_in=210 rc=1### [111e0f7b0] inflateResethhh [111e0f7b0] h_inflateReset...

The first line in the trace output shows the environment variables ZLIB_INFLATE_IMPL andZLIB_DEFLATE_IMPL are set to 1, which indicates that hardware compression and decompression modeis enabled. Subsequent lines show that the hardware accelerated data compression APIs, such ash_inflate, are in use. To assist with debugging, the trace includes information on the number of inputand output bytes available.

zEnterprise Data Compression (z/OS only)zEnterprise Data Compression (zEDC) is a hardware/software compression acceleration solution that canincrease the speed of data compression on some z/OS systems. If your application uses Java


compression services extensively, zEDC can provide reduced CPU consumption and shorter processingtimes.

Before you beginYou must have one of the following hardware systems: IBM zEnterprise zEC12 GA2, zBC12, z13 or later.Additional requirements depend on your hardware system:z15 or later

Apply one of the following PTFs, according to your level of z/OS:

• z/OS 2.4: UJ00636• z/OS 2.3: UJ00635• z/OS 2.2: UJ00638

There are no hardware requirements for z15 or later systems. The Integrated Accelerator for zEDCsolution in these systems provides built-in data acceleration, so a separate adapter is no longerrequired.

z14 or earlierYour system must also have the following requirements:

• A zEDC Express® adapter, installed in the PCIe I/O drawers of the hardware system.• The zEDC software capability (an optional, paid-for feature) must be enabled in an IFAPRDxx

parmlib member.

About this task

zEDC supports the DEFLATE compression format. Because this is a standard format, you can transfercompressed or decompressed data to a system other than IBM Z, for decompression or compression.

zEDC is provided by an IBM zlib library within the java.util.zip package. For more information aboutzEDC, see the documentation for your version of z/OS, for example: zEnterprise Data Compression (zEDC).

Procedure

1. z14 and earlier only: Grant READ access to the FPZ.ACCELERATOR.COMPRESSION resource class tothe user ID that will run the Java application.This resource class is a System Authorization Facility (SAF) FACILITY resource class, which regulatesaccess to the zEDC coprocessor. This requirement does not apply to z15 or later processors.

2. Use the z/OS UNIX environment variable, _HZC_COMPRESSION_METHOD, to control whether zEDC isused.By default, zEDC is used. If you set this variable to software, software-based compression servicesare used instead. If you set any other value, zEDC is used.

3. Ensure that the z/OS input buffers for your Java application are sufficiently large.Some CPU resource is required to send data to the zEDC feature for compression or decompression.For small amounts of data, this resource cost can be greater than the savings that are achieved byusing zEDC. You can set threshold values for the data that is compressed and decompressed by zEDC;if the size of the data is below the relevant threshold, zlib software compression is used instead:

z15 and laterUse the environment variables _HZC_DEFLATE_THRESHOLD and _HZC_INFLATE_THRESHOLD tocontrol the threshold for zEDC usage. The valid values are in the range 1-9999999. For example,_HZC_DEFLATE_THRESHOLD=1 forces all deflate requests with an initial input size of 1 byte orlarger to use zEDC. The default value is 1024 for both deflate and inflate.Unlike the DEFMINREQSIZE and INFMINREQSIZE parameters used on z14 or earlier systems, the_HZC_DEFLATE_THRESHOLD and _HZC_INFLATE_THRESHOLD environment variables are


http://www.w3.org/Graphics/PNG/RFC-1951

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ieac100/zEDC.htm

application-specific. You must either add the variables to your /etc/.profile file to make themapply across your system, or set them for each application where you want to override the systemdefault threshold for hardware compression.

z14 and earlierUse the DEFMINREQSIZE and INFMINREQSIZE parameters of the IQPPRMxx parmlib member tocontrol the threshold for zEDC usage. For more information, see the IQPPRMxx section in thedocumentation for your version of z/OS, for example: IQPPRMxx (PCIE related parameters).

Note: On z15 or later processors, the IQPPRMxx parmlib member is allowed in the configurationbut the DEFMINREQSIZE and INFMINREQSIZE values are not accepted.

Here are some methods for determining an application's current buffer size:

• Examine the source code• Examine the behavior of the application by tracing it (see Tracing Java applications in the J9 VM

reference), or monitoring it with IBM Monitoring and Diagnostic Tools4. Optional: z14 and earlier only: Set the amount of storage that is allocated for z/OS I/O buffers.

The zEDC requests that are generated by the zlib library use predefined z/OS I/O buffer pools. Thebuffer pools contain a number of 16 MB storage areas called segments. You can set the size of thebuffer pools by using the MAXSEGMENTS parameter of the IQPPRMxx parmlib member to specify thenumber of segments. The default value is 4 (64 MB). For more information, see the IQPPRMxx sectionin the documentation for your version of z/OS, for example: IQPPRMxx (PCIE related parameters).

Note: On z15 or later processors, these buffers are not required. The IQPPRMxx parmlib member isstill allowed in the configuration, but the values are not accepted.

5. In your Java application, use the classes and methods in the java.util.zip package to compressand decompress data.The following example (which excludes imports and try/catch blocks) uses the GZIPOutputStreamclass to read data from one file and write compressed data to another file:

// This 64 KB input buffer exceeds the threshold value set by DEFMINREQSIZE, so is elegible for compression by zEDC:byte buffer[] = new byte[64 * 1024];byte outputFile[];

input = new FileInputStream(argv[0]);output = new ByteArrayOutputStream();gzStream = new GZIPOutputStream(output, 4096);

for(;;) { // Read data from an uncompressed file: readBytes = input.read(buffer); if(readBytes < 0) { break; } else { // Write data to a compressed file: gzStream.write(buffer, 0, readBytes); }}

ResultsIf your system meets the requirements and conditions described, zEDC is used. Otherwise, software-based compression services are used for data compression and decompression.

What to do nextYou can use the D IQP command to view the current values for the zEDC parameters. The followingexamples show the command output:


https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieae200/IQPPRM.htm

https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.ieae200/IQPPRM.htm

https://docs.oracle.com/javase/8/docs/api/java/util/zip/package-summary.html

z15 or later:

RESPONSE=S5B IQP066I 13.20.46 DISPLAY IQP 826 zEDC Information DEFMINREQSIZE: 1K (STATIC) INFMINREQSIZE: 1K (STATIC) Feature Enablement: Enabled

z14 or earlier:

RESPONSE=CB8B IQP066I 05.55.28 DISPLAY IQP 458 zEDC Information MAXSEGMENTS: 4 (64M) Previous MAXSEGMENTS: N/A Allocated segments: 4 (64M) Used segments: 0 (0M) DEFMINREQSIZE: 4K INFMINREQSIZE: 32K Feature Enablement: Enabled

Related informationz/OS MVSReduce Storage Occupancy and Increase Operations Efficiency with IBM zEnterprise Data Compression


https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.iea/iea.htm

http://www.redbooks.ibm.com/abstracts/sg248259.html?Open

Chapter 11. Exploiting RDMAThe java.net and java.nio application programming interfaces (APIs) enable the development ofJava applications that can use TCP or UDP to communicate over the network. On Linux, extensions areavailable that allow Java applications to communicate over high performance network infrastructure thatsupports Remote Direct Memory Access (RDMA). Existing Java socket applications can take advantage ofRDMA-capable network adapters by using extensions to the Socket and ServerSocket APIs.Alternatively, you can write applications that use APIs in the jVerbs library to communicate directly overRDMA-capable infrastructure.

For any extensions to the java.net and java.nio application programming interfaces, see APIdocumentation.

Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)JSOR provides a mechanism for existing plain and NIO stream Java sockets applications totake advantage of high performance networking infrastructures, such as InfiniBand. Applicationperformance can be improved by reducing network latency and improving network bandwidth betweenJava server and client configurations.

Remote Direct Memory Access (RDMA) is enabled by specifying a runtime configuration file that has asimilar format to a Sockets Direct Protocol (SDP) configuration file. When RDMA is enabled, the traditionalTCP socket transparently switches to an RDMA socket. This connection allows client and server endpoints to communicate over the InfiniBand switch fabric at increased data transfer rates when comparedto traditional Ethernet connections.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related information“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

Comparing JSOR with Java TCP communications (Linux only)The TCP protocol is dependent on the operating system kernel, whereas the RDMA protocol bypasses theoperating system kernel, enabling direct communication between Java applications on different RDMA-enabled host systems. Therefore, RDMA network operations require less processor resources andimprove network throughput.

In the traditional model of Java TCP sockets processing, the host operating system kernel plays a keyrole. Operating system calls are required for all common network operations, for example:

• Creating sockets• Binding to a port• Listening on a well-known address• Connecting to a remote host• Accepting incoming connection requests• Transferring data between connected end points


https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.api.80.doc/api_overview.dita

https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.api.80.doc/api_overview.dita

When Java client and server applications exist on different host systems, transferring data betweensystems involves several copy operations between buffers before the data transfers between networkinterface cards. The following buffers are involved in this process on each system:

• Java application buffer to Java socket buffer• Java socket buffer to operating system socket buffer• Operating system socket buffer to network interface driver buffer

These copy operations use processor cycles before data is transmitted between host systems.

Unlike the TCP protocol, the RDMA protocol is defined on top of high speed switch fabrics, like InfiniBand,which is independent of the operating system kernel. Instead, network processing is offloaded to adedicated RDMA network interface adapter. The RDMA protocol allows a Java application on one host todirectly access the memory of a Java application on a different host. This capability enables the directtransfer of data between Java applications.

The following diagram illustrates the connections that are required between a Java client and serverapplication for TCP/IP communication and RDMA communication:

Compared with TCP processing, RDMA uses less processor resources and can take advantage of highperformance switch fabric to maximize data throughput between RDMA-enabled systems.

Comparing JSOR to Java Sockets Direct Protocol (SDP) communications (Linux only)JSOR uses the R-Sockets protocol API at the native level, allowing Java TCP socket applications to takeadvantage of RDMA-capable hardware without any changes to application code. Although SDP offerssimilar capabilities, specific operating system support is required before Java applications can use RDMAinfrastructure.

The Sockets Direct Protocol (SDP) is a standard protocol that is defined to accelerate TCP stream socketson RDMA capable hardware. However, this protocol has dependencies on the operating system kernel,which must be supported by the underlying host operating system.

As an alternative to SDP, the IBM SDK implements a solution that is based on the R-Sockets protocol. R-Sockets provides the RDMA sockets API at the native level. This API behaves, connects and streams datalike the plain sockets implementation. Tests indicate that this R-Sockets solution performs favorablywhen compared to SDP, and to a pure RDMA native implementation.

JSOR uses R-Sockets as the basis for transparently switching the Java TCP sockets to RDMAcommunication between end points. RDMA communication is based on runtime configuration details.


Java socket and channel -based applications should run without any code changes on theRDMA-enabled infrastructure, which provides improved network performance.

JSOR features and design (Linux only)JSOR provides support for plain and NIO stream socket applications, IPv6, and an optionalmethod for allowing RDMA-enabled servers to accept TCP clients. By intercepting socket stream calls,JSOR manages all control operations and data routing for a Java application.

The following JSOR features are available with this release:

• RMDA-enabled Java plain and NIO stream sockets• Support for IPv6• TCP/IP fall back support for RDMA server sockets• Extensive call tracing at the JSOR native level

TCP socket applications can take advantage of the network performance benefits available with RDMAfabrics, with no changes to application code. Changes to application code are not required becausesocket and channel stream calls are intercepted and routed through the JSOR native library.The ability to intercept socket stream calls is dependent on rules that are specified in a runtimeconfiguration file.

You enable JSOR by specifying a system property when you start your application, which specifies theserver or client configuration file. For more information about enabling JSOR, see “Enabling Java Socketsover Remote Direct Memory Access (JSOR) (Linux only)” on page 203.

JSOR design

The JSOR library uses two routes to interact with the RDMA network interface adapters, as shown in thefollowing diagram:

Chapter 11. Exploiting RDMA 195

Fast data pathThe JSOR library uses the OpenFabrics Software (OFS) userspace verbs module to communicatedirectly with the RDMA network interface adapter. This route is typically used for sending data. Formore information about using userspace verbs, see Userspace verbs access.

Slow control pathThe JSOR library interacts with a device-dependent kernel verbs module for controlling and managingthe RDMA resource objects. This path is used mainly for establishing connections.

JSOR zero copy function (Linux only)By default, JSOR data transfers involve the use of intermediate buffer copy operations. For large datatransfers, you can improve performance by enabling the zero copy function. This function copies datadirectly from Java application memory on one host to Java application memory on a different host,without using the processor on either host.

As shown in the following diagram, the buffer copy process always uses the host operating system,resulting in multiple intermediate copies and computationally expensive context switches between userspace and kernel space. The zero copy process uses the host CPU only when buffers are registered foruse in direct copy operations. After a buffer is registered, the data transfer happens directly.

When application 2, in the diagram, has a buffer available to receive data, the application advertises thatavailability by registering the buffer for direct data placement. When application 1 has data to send, itwrites the data directly into the registered buffer. When the write operation is complete, a writecompletion message is sent by application 1 to the other side. When application 2 receives this messageit can process the transferred data. When the data transfer is complete, application 2 can unregister thereceive buffer.

Because of buffer registration overheads, the expected reduction in CPU cycles is achieved only if thedata transfer sizes are large. For example, for a single connection you might not see a reduction until thedata transfer size exceeds 256 KB. If multiple parallel connections share the same buffer for direct dataplacement, this data threshold can be reduced.

Because the performance gains are achieved only for large data sizes, the zero copy function is notenabled by default. To enable the function, use the -Dcom.ibm.net.rdma.zeroCopy=true property.


https://www.kernel.org/doc/Documentation/infiniband/user_verbs.txt

Restriction: Full duplex communication is not currently supported. When one side sends, the other sidemust receive only.

Restriction: The JSOR zero copy function is not supported for NIO channels.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related information“JSOR environment settings (Linux only)” on page 219Use these environment variables to set and size resources for connection and data transfer by using JavaSockets over Remote Direct Memory Access (JSOR). These environment variables also apply toJSOR NIO client/server scenarios.“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

JSOR native interoperability (Linux only)You can use JSOR to communicate between a Java application and a native application such as a remotedatabase server. There is also limited support for native applications that want to use the fork()function.

You must first ensure that the native application is using the RSockets protocol, by using one of thefollowing methods:

• Preload the existing native application that uses the TCP/IP protocol for communication with the nativeRSockets preloading library

• Write the native application by using RSockets APIs, then link against the RSockets native library.

Dynamic preloading is an operating-system-specific facility where regular TCP/IP socket calls areintercepted and replaced by the equivalent RDMA socket calls for talking to remote applications throughthe RDMA path. This remote application could be a JSOR-enabled Java application. Because JSOR isderived from the RSockets protocol, the protocol matches and communication is seamless. For more


information about using RSockets for native interoperability, see “Enabling JSOR communication betweena Java application and a native application (Linux only)” on page 205.

Support for the fork() function

On a native server system you can enable fork support by setting the environment variableRDMAV_FORK_SAFE=1. When enabled, the RSockets pre-loading library converts a plain socket into anRDMA socket only when the first data transfer call is made. On the client system you must set the systemproperty -Dcom.ibm.net.rdma.nativeForkCompatibility=true. When set, the client connectsand synchronizes with the native server before switching to RDMA mode. For more information about thisproperty, see “-Dcom.ibm.net.rdma.nativeForkCompatibility (Linux only)” on page 225.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related reference“-Dcom.ibm.net.rdma.nativeForkCompatibility (Linux only)” on page 225Specifies whether the Java Sockets over RDMA (JSOR) client should connect and synchronize with thenative RSockets server before establishing an RDMA connection.Related information“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

JSOR system requirements and supported APIs (Linux only)Java client and server applications must have specific hardware and runtime software installed in order touse the JSOR features. JSOR supports a limited set of APIs and classes.

Supported hardware and runtime requirements

The following prerequisites apply:

• This feature is available on the following platforms and Remote Direct Memory Access (RDMA)adapters:

– Linux 32-bit x-86 with either InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)– Linux AMD64/EM64T with IB or RoCE– Linux 32-bit POWER with RoCE– Linux 64-bit POWER with RoCE

– Linux 64-bit POWER8 (Little Endian) with IB

The adapters must be interconnected by a suitable high-performance switch.• You must install OpenFabrics Enterprise Distribution (OFED) v1.5.3 or later, which can be downloaded

from the OpenFabrics Alliance website: https://www.openfabrics.org/index.php/resources/ofed-for-linux-ofed-for-windows/ofed-overview.html. During run time, symbols from the following libraries aredynamically located and loaded: librdmacm.so and libibverbs.so. These libraries are provided bythe OFED run time.

• Users must have adequate permissions to lock memory on both host systems. RDMA socket buffersmust be locked, or pinned, to avoid the operating system swapping out the memory pages during datatransfers.


https://www.openfabrics.org/ofed-for-linux/


Tested environments

• Mellanox MT26428 ConnectX Virtual Protocol Interconnect (VPI) PCI Express (PCIe) hosts, which areinterconnected by a Voltaire 40 GB InfiniBand Switch.

• Mellanox MT25208 InfiniHost III Ex hosts, which are interconnected by a Cisco 4x InfiniBand Switch.• Mellanox MT26448 ConnectX EN PCIe hosts, which are directly interconnected.• Mellanox MT4099 ConnectX-3 VPI hosts, which are directly interconnected.

Supported APIs and classes

Support is limited for the following set of APIs and classes:

• java.net.Socket and java.net.ServerSocket excludes support for the following methods:

– Socket(Proxy proxy)– Socket(SocketImpl impl)– setSocketFactory(SocketImplFactory fac)– setPerformancePreferences(int connectionTime, int latency, int bandwidth).

• java.io.InputStream, includes support for the following methods:

– available()– close()– mark(int readlimit)– markSupported()– read()– read(byte[] b)– read(byte[] b, int off, int len)– reset()– skip()

• java.io.OuputStream includes support for the following methods:

– close()– flush()– write(byte[] b)– write(byte[] b, int off, int len)– write(int b)

• java.net.SocketOptions includes support for the following option:

– SO_TIMEOUT– TCP_NODELAY– SO_LINGER– SO_BINDADDR– SO_REUSEADDR– SO_BROADCAST– SO_SNDBUF– SO_RCVBUF– SO_KEEPALIVE– SO_OOBINLINE

At run time, the following options are acted upon at the RDMA socket level:

– SO_BINDADDR


– SO_REUSEADDR– SO_SNDBUF– SO_RCVBUF

Note: SO_SNDBUF and SO_RCVBUF are effective immediately after socket creation, but before aconnect or bind operation takes place on that socket.

For the remaining socket options, the JSOR run time falls back to the TCP/IP implementation.

For NIO stream socket applications, the following Java classes are supported:

• java.nio.channels.SocketChannel• java.nio.channels.ServerSocketChannel• java.nio.channels.Selector

To manage socket send and receive buffer sizes, use the Java environment variables included withinJSOR. For more information, see “JSOR environment settings (Linux only)” on page 219.

When to choose JSOR (Linux only)Java Sockets over Remote Direct Memory Access (JSOR) is an efficient mechanism for transferring databetween Java applications that exist on separate host systems. However, there are some importantpoints to consider when you are deciding whether your existing Java socket applications can directlybenefit from this network acceleration capability.

• JSOR connection requires more system resources when compared to standard TCP connections.Several complex steps are involved to create and manage the send and receive buffers and channelcompletion queues. These steps involve the transmission of event signals between the server and clientto verify the connection.

• With TCP connections, application buffers are allocated dynamically when needed. However, JSORrequires application send and receive buffers to be set up in advance because the buffers must bepinned, or locked, in memory. This action prevents the operating system swapping out the used bufferregions.

The following types of Java applications can benefit from JSOR:

• Applications that require large data transfers between remote hosts. In these circumstances, thesystem resources that are used to establish a connection might be negligible compared to the amountof data that is being transferred.

• Applications that require connections to be established between remote hosts for a significant length oftime. In these circumstances, the registered send and receive memory buffers can be reusedextensively.

• Applications that require connections between remote hosts where the amount of data that is beingtransferred is known in advance and varies little in size.

These scenarios suit data-center operations such as data streaming, database logging, and databaserecovery.

Java applications that use remote procedure calls (RPC), where message sizes are unpredictable and varysignificantly, might also achieve performance benefits from JSOR if the buffers are correctly tuned.

If you consider that your application can benefit from JSOR, you must follow the steps that are detailed inthe topic “Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.


Related information“JSOR environment settings (Linux only)” on page 219Use these environment variables to set and size resources for connection and data transfer by using JavaSockets over Remote Direct Memory Access (JSOR). These environment variables also apply toJSOR NIO client/server scenarios.“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

JSOR limitations (Linux only)A number of known limitations apply to Java Sockets over Remote Direct Memory Access (RDMA).

The following limitations apply to both the NET and NIO features:

• “The number of long-running parallel clients between two RDMA endpoints is limited” on page 201• “RDMA-enabled Java applications do not close immediately after running” on page 202• “RDMA connections take more time than TCP connections” on page 202• “If the RDMA server chooses the service port dynamically, the corresponding endpoint is not RDMA-

enabled” on page 202

• “JSOR enablement properties” on page 202

The following limitations apply only to the NET feature:

• “An RDMA client connects by using TCP, when the TCP fallback option is not enabled on the RDMAserver” on page 202

The following limitations apply only to the NIO feature:

• “The number of concurrent clients for JSOR NIO channel applications is limited with thedefault Poll selector” on page 202

• “You cannot specify RDMA poll selectors by using the java.nio.channels.spi.SelectorProvidersystem property” on page 202

• “Netty IO framework problems” on page 203

• “Problems encountered with Apache Spark in JSOR mode when the EPoll selector is used” onpage 203

• “Problems encountered with multi-threaded applications in JSOR mode when the EPollselector is used” on page 203

The number of long-running parallel clients between two RDMA endpoints is limited

This behavior is associated with older Mellanox cards and their drivers. The limit is caused by the way thatqueue pairs (linked send and receive queues) are allocated and rehashed by the underlying interfacedriver. Queue pairs are the basis for posting send or receive requests between RDMA endpoints.

For example, first-generation Mellanox card MT25208 limits the number of simultaneous openconnections to approximately 300, and second-generation Mellanox card MT26428 limits the number toapproximately 30.

The queue pair allocation algorithm is improved in the latest Mellanox firmware, so you should not seethis limitation with later drivers. For more information, see the following Mellanox article, which detailshow the bitmap allocator can be optimized: Change bitmap allocator to work in round-robin fashion


https://www.mail-archive.com/[email protected]/msg11654.html

RDMA-enabled Java applications do not close immediately after running

The RDMA runtime environment allocates and manages many resource objects as part of each connectionestablishment. When a connection is closed, these resources are deallocated. The RDMA runtimeenvironment waits for approximately 1 second so that the concurrent connection threads can completebefore the resources are freed. This waiting time is reflected in the closure of an RDMA-enabled Javaapplication.

RDMA connections take more time than TCP connections

The connection establishment process is more complex within RDMA than it is within TCP. The RDMAconnection establishment involves the creation and management of RDMA-specific resource objects andtwo-way event control. This time increase is a widely known side-effect of using RDMA.

If the RDMA server chooses the service port dynamically, the corresponding endpoint is not RDMA-enabled

The JSOR implementation does not support ephemeral ports. The service endpoint must therefore befixed in advance and specified in your configuration file.

JSOR enablement properties

The NET and NIO features are supported by using separate enablement properties:com.ibm.net.rdma.conf and com.ibm.nio.rdma.conf.

An RDMA client connects by using TCP, when the TCP fallback option is not enabled on the RDMAserver

In this unusual scenario, an RDMA client that is listed in the rules of an RDMA-enabled server that isrunning without TCP fallback enabled tries to connect by using TCP.

The RDMA server waits for an indefinite amount of time to try to accept the connection by using RDMA,unless you set an accept timeout. By default, each RDMA endpoint has two parts, one for TCP and one forRDMA. When a connection is established between an RDMA server and an RDMA client, it implicitly opensa TCP connection in the background. The TCP portion is used to listen for incoming connection requests.

When an RDMA client tries to connect by using TCP to an RDMA-enabled server that is running withoutTCP fallback enabled, the TCP part of the connection is progressed on the client. However, the servercontinues to wait to make progress on the RDMA part of its endpoint. To avoid this behavior, set an accepttimeout. Instead of waiting, the RDMA server then cancels, throwing a SocketTimeoutExceptionexception with the message RDMA Accept timed out.

The number of concurrent clients for JSOR NIO channel applications is limited with the default Pollselector

The number of concurrent clients that are supported in Java client and server testing is limited to 200.Beyond this limit, clients might experience connection failure exceptions. However, you can usethe “-Dcom.ibm.nio.rdma.EPollSelectorProvider (Linux only)” on page 225 to increase this limit to 1000clients. For information about the current limitations of this option, see “Problems encountered withApache Spark in JSOR mode when the EPoll selector is used” on page 203 and “Problems encounteredwith multi-threaded applications in JSOR mode when the EPoll selector is used” on page 203.

You cannot specify RDMA poll selectors by using thejava.nio.channels.spi.SelectorProvider system property

Specifying RDMA poll selectors can be achieved only by using the RDMA enablement propertycom.ibm.nio.rdma.conf=<configuration_file> on the Java command line. Specifying RDMA pollselectors by using the system property java.nio.channels.spi.SelectorProvider is notsupported. For example, by using the provider() method in the Java classjava.nio.channels.spi.SelectorProvider.


Netty IO framework problems

For NIO stream socket applications, problems are encountered on the Netty IO framework, https://netty.io/.

Problems encountered with Apache Spark in JSOR mode when the EPoll selector is used

java.io.IOException, unhandled exceptions, and a Java VM dump are observed during the followingApache Spark benchmarks in Java Sockets over Remote Direct Memory Access (JSOR) mode, when the “-Dcom.ibm.nio.rdma.EPollSelectorProvider (Linux only)” on page 225 is set to true:

• Matrix Factorization• Page Rank• Tera Sort

Problems encountered with multi-threaded applications in JSOR mode when the EPoll selector isused

Unhandled exceptions are observed while running multi-threaded Java NIO client/server applications inJava Sockets over Remote Direct Memory Access (JSOR) mode, when the “-Dcom.ibm.nio.rdma.EPollSelectorProvider (Linux only)” on page 225 is set to true.

Unhandled exceptions are also observed when the client side connection is ended before all of the datacan be received from the server.


Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.

Before you beginRead the overview section about “Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)”on page 193, which contains some important considerations. In particular, you should note the followingpoints:


– Linux 32-bit x-86 with either InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)


https://netty.io/

https://netty.io/

– Linux AMD64/EM64T with IB or RoCE– Linux 32-bit POWER with RoCE– Linux 64-bit POWER with RoCE





About this taskJSOR is enabled on the client and server system by specifying a system property on the command line.The system properties are different for plain stream socket applications and NIO channel applications.For detailed information about the construction of the configuration file, config_file, see “-Dcom.ibm.net.rdma.conf (Linux only)” on page 222 or “-Dcom.ibm.nio.rdma.conf (Linux only)” on page228. Support for NIO channel applications is added in this update. To enable JSOR, completethe following steps:

Procedure

1. Create the server configuration file on the server system with an accept rule.2. Create the client configuration file on the client system with a connect rule.3. Start the server, specifying the command-line system property -Dcom.ibm.net.rdma.conf=server_configuration_file or -Dcom.ibm.nio.rdma.conf=server_configuration_file

4. Start the client, specifying the command-line system property -Dcom.ibm.net.rdma.conf=client_configuration_file or -Dcom.ibm.nio.rdma.conf=client_configuration_file

5. Optional: If you want to override the bind address that is used by the system, you must use the -Dcom.ibm.net.rdma.preferredAddress or -Dcom.ibm.nio.rdma.preferredAddresscommand-line system property, with a valid InfiniBand address. For more information, see “-Dcom.ibm.net.rdma.preferredAddress (Linux only)” on page 226 or “-Dcom.ibm.nio.rdma.preferredAddress (Linux only)” on page 232.

6. Optional: If you want your server system to accept connections from TCP clients when RDMAconnections are not possible, specify the system property -Dcom.ibm.net.rdma.tcpFallback=true. For more information about this property, see “-Dcom.ibm.net.rdma.tcpFallback (Linux only)” on page 227.a) Optional: You can enforce a time that an RDMA server must wait for RDMA services before it

switches to TCP communications. For more information, see “-Dcom.ibm.net.rdma.tcpFallbackWaitTime (Linux only)” on page 227.

This option is not supported for NIO channel applications.

Results

The plain or NIO stream sockets connection between the Java application server and client transparentlyswitches to RDMA, providing the rules match at both ends of the connection.

• Server: The switch to an RDMA connection occurs during the bind / accept stage.• Client: The switch to an RDMA connection occurs during the bind / connect stage.




When connected, the server and client endpoints communicate and transfer data by using the R-Socketsprotocol.

If you experience problems when you are trying to establish a connection between RDMA-enabledsystems, you can use the JSOR trace facility to determine where the process is failing. For moreinformation, see “JSOR problem determination (Linux only)” on page 208.

Example

Create file server.conf on the Java application server, host1, with the following configuration rule:

rdma accept host1 1500 host2

All the connections from host2 accepted by host1 on the port 1500 are RDMA connections.

Create file client.conf on the Java application client, host2, with the following configuration rule:

rdma connect host1 1500

All the connections that are made to host1 on port 1500 are RDMA connections.

Start the Java application server in RDMA mode, by specifying the following on the command line:

java -Dcom.ibm.net.rdma.conf=<path>/server.conf Server

Or:

java -Dcom.ibm.nio.rdma.conf=<path>/server.conf NIOServer

Where <path> is the fully qualified path to the configuration file.

Start the Java client application in RDMA mode, by specifying the following on the command line:

java -Dcom.ibm.net.rdma.conf=<path>/client.conf Client

Or:

java -Dcom.ibm.nio.rdma.conf=<path>/client.conf NIOClient

Where <path> is the fully qualified path to the configuration file.

What to do next

To optimize the performance of your RDMA-enabled applications, you should set and size resources forconnection and data transfer. For managing socket send and receive buffers, and queue sizes, JSORincludes a set of Java environment variables. For more information, see “JSOR environment settings(Linux only)” on page 219.

Related information“JSOR environment settings (Linux only)” on page 219Use these environment variables to set and size resources for connection and data transfer by using JavaSockets over Remote Direct Memory Access (JSOR). These environment variables also apply toJSOR NIO client/server scenarios.“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

Enabling JSOR communication between a Java application and a native application (Linux only)To enable Java sockets over Remote Direct Memory Access (JSOR) communication, you must first ensurethat the native application is using the RSockets protocol. The RSockets protocol can be used by


preloading the native RSockets preloading library or by using RSockets APIs to write the nativeapplication. Support for NIO channel applications is added in this update.

Before you beginFor an overview, read “JSOR native interoperability (Linux only)” on page 197.

About this taskThere are two methods for enabling JSOR communications between a Java application and a nativeapplication. You must select the correct system property for your application. For example, plain streamsocket applications (com.ibm.net.rdma.conf) or NIO channel applications(com.ibm.nio.rdma.conf).

Procedure

1. Follow these steps if you want to communicate by preloading the native RSockets preloading library:a) If you are connecting a JSOR client with a native server, type the following command-line

invocation:

java -Dcom.ibm.net.rdma.conf=<client.conf> -cp <classpath> SampleClient <client_args>

LD_PRELOAD=/usr/lib/rsocket/librspreload.so ./SampleServer <server_args>

Or:

java -Dcom.ibm.nio.rdma.conf=<client.conf> -cp <classpath> NIOClient <client_args>

LD_PRELOAD=/usr/lib/rsocket/librspreload.so ./NIOServer <server_args>

Where:

• client.conf is your client RDMA configuration file.• classpath specifies the class path.• client_args are the client application-specific command-line options.• server_args are the native application-specific command-line options.

b) If you are connecting a JSOR server with a native client, type the following command-lineinvocation:

java -Dcom.ibm.net.rdma.conf=<server.conf> -cp <classpath> SampleServer <server_args>

LD_PRELOAD=/usr/lib/rsocket/librspreload.so ./SampleClient <client_args>

Or:

java -Dcom.ibm.nio.rdma.conf=<server.conf> -cp <classpath> NIOServer <server_args>

LD_PRELOAD=/usr/lib/rsocket/librspreload.so ./NIOClient <client_args>

Where:

• server.conf is your server RDMA configuration file.• classpath specifies the class path.• server_args are the server application-specific command-line options.• client_args are the native application-specific command-line options.

2. Follow these steps if your native application is written to use the RSockets APIs to communicate witha JSOR client or server application:


a) If you are connecting a JSOR client with a native server that is written to use the RSockets APIs,type the following command-line invocation:

java -Dcom.ibm.net.rdma.conf=<client.conf> -cp <classpath> SampleClient <client_args>

cc -o SampleServer -lrdmacm

./SampleServer <server_args>

Or:

java -Dcom.ibm.nio.rdma.conf=<client.conf> -cp <classpath> NIOClient <client_args>

cc -o NIOServer -lrdmacm

./NIOServer <server_args>

Where:

• client.conf is your client RDMA configuration file.• classpath specifies the class path.• client_args are the client application-specific command-line options.• server_args are the native application-specific command-line options.

b) If you are connecting a JSOR server with a native client that is written to use the RSockets APIs,type the following command-line invocation:

java -Dcom.ibm.net.rdma.conf=<server.conf> -cp <classpath> SampleServer <server_args>

cc -o SampleClient -lrdmacm

./SampleClient <client_args>

Or:

java -Dcom.ibm.nio.rdma.conf=<server.conf> -cp <classpath> NIOServer <server_args>

cc -o NIOClient -lrdmacm

./NIOClient <client_args>

Where:

• server.conf is your server RDMA configuration file.• classpath specifies the class path.• server_args are the server application-specific command-line options.• client_args are the native application-specific command-line options.

Results

Regular TCP/IP socket calls are intercepted and replaced by the equivalent RDMA socket calls for talkingto remote applications through the RDMA path.

Related concepts“JSOR native interoperability (Linux only)” on page 197


You can use JSOR to communicate between a Java application and a native application such as a remotedatabase server. There is also limited support for native applications that want to use the fork()function.Related information“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

JSOR problem determination (Linux only)Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related information“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

JSOR trace options (Linux only)You can trace Java Sockets over Remote Direct Memory Access (JSOR) runtime calls down to the nativelevel by using the standard trace options, including sending the trace output to a file. Supportfor NIO channel applications is added in this update.

The JSOR component has more than 200 tracepoint identifiers at the native level alone. To trace theentire RDMA stack, use JSOR component tracing with Java method tracing and NET or NIO componenttracing.

RDMA JNI layer tracing includes approximately 85 tracing points that are covered by the NET and NIOtracing components. RDMA Native layer tracing includes approximately 158 tracing points and is coveredby the JSOR tracing component.

Look for the following native methods in the trace output to understand call flow at the library level:

• RDMA_Accept• RDMA_Available• RDMA_Bind• RDMA_Close• RDMA_Connect• RDMA_Destroy• RDMA_GetSockOpt• RDMA_Init• RDMA_Listen• RDMA_Read• RDMA_ReadDirect


• RDMA_Send• RDMA_SendDirect• RDMA_SetSockOpt• RDMA_Shutdown• RDMA_Socket• RDMA_Timeout

• RDMA_Poll

• RDMA_Fcntl

• RDMA_FinishConnect

For more information about tracing, trace components, and tracepoints, see the following topics:

• -Xtrace in the OpenJ9 user documentation• Determining the tracepoint ID of a trace point in the J9 VM reference

Examples

To trace only RDMA Java method calls, use the following command line option:

-Xtrace:methods={java/net/RDMA.*},iprint=mt

To trace RDMA Java method calls and JNI method calls, use the following command line option:

-Xtrace:methods={java/net/RDMA.*},iprint=mt,iprint=NET

To trace RDMA Java method calls, JNI method calls and native method calls, use the following commandline option:

-Xtrace:methods={java/net/RDMA.*},iprint=mt,iprint=NET,iprint=JSOR

Here is some sample trace output from a simple server, which accepts an RDMA connection and receivesa message from the client:

01:49:07.061*0x20d2c100 JSOR.0 > RDMA_Init()01:49:07.061 0x20d2c100 JSOR.39 > initverbs()01:49:07.062 0x20d2c100 JSOR.43 < initverbs(rc=0)01:49:07.062 0x20d2c100 JSOR.46 > initjsor()01:49:07.064 0x20d2c100 JSOR.47 < initjsor(rc=0)01:49:07.064 0x20d2c100 JSOR.3 < RDMA_Init(rc=0)01:49:07.077 0x20d2c100 JSOR.25 > RDMA_Socket(fd=60)01:49:07.077 0x20d2c100 JSOR.27 < RDMA_Socket(rsockp=00007FB690355150, fd=60, state=0x0)01:49:07.078 0x20d2c100 JSOR.28 > RDMA_Bind(rsockp=00007FB690355150, fd=60, my_addr=00007FB6957DE620, state=0x0)01:49:07.078 0x20d2c100 JSOR.50 > create_event_channel(rsockp=00007FB690355150, fd=60, state=0x0)01:49:07.078 0x20d2c100 JSOR.52 < create_event_channel(state=0x0, rc=0)01:49:07.078 0x20d2c100 JSOR.53 > create_id(rsockp=00007FB690355150, fd=60, state=0x0)01:49:07.078 0x20d2c100 JSOR.55 < create_id(state=0x0, rc=0)01:49:07.078 0x20d2c100 JSOR.220 > get_addrinfo_from_sockaddr(address=00007FB6957DE620, len=28)

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related information“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, you


can run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

JSOR messages (Linux only)A comprehensive set of information, warning and exceptions messages are generated during run time.These messages help you understand RDMA operations and troubleshoot points of failure.

Improved message information can help you identify the cause of a failure more quickly. Each exceptionmessage is provided with more detail. For instance, when an RDMA connect operation fails, a messagesimilar to the following is generated:

Exception in thread "main" java.io.IOException: RDMA connection could not be established JSORE: Underlying RDMA connect operation failed Reason: Failed to get successful connection established event)]

For example, if there is a timeout during acceptance of the incoming connection, the accept() methodon an RDMA ServerSocket object throws a SocketTimeoutException exception with the messageRDMA Accept timed out. This message is similar to the Accept timed out message that is thrownby the equivalent TCP/IP scenario.

Exception messages

The following RDMA exception messages might be produced during run time:

Table 11. RDMA exception messages

Exception message Exception type Occurrence stage

Must be a stream socket for RDMA! IOException Socket create

RDMA Socket Closed IOException Socket input / output stream

RDMA Socket input is shutdown IOException Socket input stream

RDMA Socket output is shutdown IOException Socket output stream

RDMA Connection reset SocketException Socket read / write

RDMA Socket closed SocketException Socket read / write

Can't create RDMA Socket IOException Socket create

RDMA socket pointer closed IOException Socket validation

inet address argument null IOException Socket connect / bind

address conversion failed IOException Socket connect / bind / accept

Connection timed out SocketTimeoutException Socket connect

RDMA connection could not beestablished

IOException Socket connect

RDMAconnection could not be establishedto ip_addr/port

IOException Socket connect

RDMA bind failed BindException /SocketException

Socket bind

RDMA listen failed SocketException Socket bind

RDMA server socket pointer closed IOException Socket accept

Accept timed out SocketTimeoutException Socket accept

RDMA accept failed IOException Socket accept


Table 11. RDMA exception messages (continued)

Exception message Exception type Occurrence stage

write failed IOException Socket send urgent data / write

send interrupted InterruptedIOException Socket send urgent data

Invalid option SocketException Socket option

Error setting rdma socket option SocketException Socket option

Error retrieving rdma socket option SocketException Socket option

connection reset ConnectionResetException Socket available

socket already closed SocketException Socket available

operation interrupted InterruptedIOException Socket available

read failed SocketException Socket available / read

Read timed out SocketTimeoutException Socket read

Socket closed SocketException Socket read

select/poll failed SocketException Socket read

operation interrupted InterruptedIOException Socket read or write

Direct Read timed out SocketTimeoutException Socket read direct

Direct Read failed RuntimeException Socket read direct

Direct Write failed RuntimeException Socket write direct

Malformed line xxx RuntimeException Configuration rules processing

Network provider for xxx could notbe loaded

RuntimeException Configuration rules processing

SocketAction xxx not recognized RuntimeException Configuration rules processing

Less than expected number ofarguments xxx


Greater than expected number ofarguments xxx


Malformed port range xxx RuntimeException Configuration rules processing

Malformed prefix xxx RuntimeException Configuration rules processing

Unknown host or malformed IPaddress xxx


Warning messages

RDMA warning messages are prefixed with [JSOR Warning]. The following messages might beproduced during run time:

Table 12. RDMA warning messages

Warning message Occurrence stage

Invalid tcp fallback wait time xxx - defaulting to xxx milliseconds Property validation

Invalid com.ibm.net.rdma.tcpFallbackWaitTime propertyvalue xxx defaulting to xxx milliseconds

Property validation


Table 12. RDMA warning messages (continued)

Warning message Occurrence stage

Invalid timeout parameter xxx - defaulting to zero (infinite timeout) Argument validation

Invalid zero copy threshold xxx - defaulting to xxx KB Property validation

Invalid com.ibm.net.rdma.zeroCopyThreshold property valuexxx defaulting to xxx KB

Property validation

Native error messages

The following RDMA native error messages might be part of the IOException thrown by JSOR. Thesenative failures are prefixed with [JSORE]:

Table 13. JSOR native error messages

JSOR level 1 native error messages Occurrence stage

JSOR operation completed successfully -

Failed to resolve RDMA user verbs library symbols Network initialization

Failed to query RDMA device attributes Network initialization

Failed to initialize key for runtime threads Network initialization

JSOR runtime internal finalization failed Network termination

Failed to free RDMA user verbs shared libraryhandles

Network termination

Failed to allocate memory for new RDMA socket Socket create

Failed to allocate global list entry for created RDMAsocket

Socket create

JSOR runtime shutdown operation in progress Network termination

Failed to create event channel for RDMA socket Socket connect / bind

Failed to create connection manager identifier forRDMA socket

Socket connect / bind

Underlying RDMA connect operation failed Socket connect

Underlying RDMA bind operation failed Socket bind

Inconsistent state for RDMA socket Socket listen / accept

Underlying RDMA listen operation failed Socket listen

Underlying RDMA accept operation failed Socket accept

Underlying RDMA shutdown operation failed Socket shutdown

Socket option not supported for RDMA socket Socket option

RDMA socket's connection manager identifierand/or queue pair invalid

Socket available / read / send

Underlying RDMA poll operation failed Socket timeout

Failed to register direct IO buffer Socket read direct

Failed to send/receive start sync signal for directIO operation

Socket read / send direct


Table 13. JSOR native error messages (continued)


Failed to send/receive end sync signal for direct IOoperation

Socket read / send direct

Failed to transfer data directly to remote endpoint Socket send direct

Underlying RDMA data receive operation failed Socket send

Underlying RDMA data send operation failed Socket send

Invalid JSOR error message code -

Underlying RDMA polloperation failed

Channel select

Invalid arguments to RDMApoll

Channel select

The following RDMA error messages provide further detail and are prefixed with Reason:.

Table 14. JSOR native error messages that provide a reason for failure


JSOR low level operation completed successfully -

Failed to resolve RDMA destination address Socket connect / accept

Failed to retrieve next pending communicationevent

Socket connect

Address resolution failed even after several tries Socket connect

Failed to get successful address resolution event Socket connect

Failed to resolve RDMA route to establishconnection

Socket connect

Route resolution failed even after several tries Socket connect

Failed to get successful route resolution event Socket connect

Failed to create RDMA endpoint Socket connect / accept

Failed to create RDMAendpoint - out of memory

Socket connect / accept

Failed to initiate active connection request Socket connect

Failed to get successful connection establishedevent

Socket connect

RDMA connect state is inconsistent Socket connect

Failed to allocate memory for child RDMA socket Socket accept

Failed to accept a connection request Socket accept

Failed to allocate global list entry for child RDMAsocket

Socket accept

Failed to create connection manager event channelfor child

Socket accept


Table 14. JSOR native error messages that provide a reason for failure (continued)


Failed to migrate child identifier to new eventchannel

Socket accept

A communication event is acknowledged but notreceived before

Socket accept

Timed out while retrieving next communicationevent

Socket accept

Failed to get next connection request event evenafter several retries

Socket accept

Invalid JSOR sub-level error message code -

Information messages

RDMA information messages are generated during run time to confirm JSOR operations that are takingplace.

Table 15. RDMA information messages

Information message Occurrence stage

RDMA socket created Socket create

RDMA socket input stream available Socket input stream

RDMA socket output stream available Socket output stream

RDMA connection established to xxx Socket connect

RDMA socket bound to xxx Socket bind

RDMA socket put in listening mode Socket listen

Accepted RDMA connection request Socket accept

RDMA socket closed Socket close

RDMA socket input/output end closed Socket shutdown

Set RDMA socket option Socket option

Retrieved RDMA socket option Socket option

TCP fallback mode in place Socket accept

RDMA network provider initialized Network initialization

Socket switched to RDMA mode Socket create

If you want to see these messages on the standard terminal, you must enable the system property -Dcom.ibm.net.rdma.debug or -Dcom.ibm.nio.rdma.debug by setting the value totrue. For more information, see “-Dcom.ibm.net.rdma.debug (Linux only)” on page 224 or “-Dcom.ibm.nio.rdma.debug (Linux only)” on page 231.

The format of information messages includes the hash code of the object that is being referredto. Also, the prefix conveys whether the message displayed is a warning, error, or information message.There are separate messages displayed for NET sockets and NIO socket channels.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203


JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related information“JSOR problem determination (Linux only)” on page 208Java Sockets over Remote Direct Memory Access (JSOR) can improve performance by taking advantageof high performance networking infrastructures such as InfiniBand. To investigate JSOR problems, youcan run trace or review the list of common problems. This section also contains a list of exceptions andmessages that you might encounter.

Common JSOR problems (Linux only)Use Java Sockets over Remote Direct Memory Access (JSOR) to take advantage of high performancenetworking infrastructures such as InfiniBand. To use JSOR you must set up, configure, and tune variousresources. If not done correctly, issues can occur.

Use the following list of topics to help you determine the cause of your problem:

• “RDMA socket or thread creation failed” on page 215• “RDMA Network provider initialization failure” on page 216• “RDMA connection failed” on page 216• “RDMA connection reset exceptions” on page 217• “RDMA communication appears to hang” on page 217• “Problems encountered with the zero copy function” on page 218• “Problems encountered with fork compatibility mode” on page 218

RDMA socket or thread creation failedA JSOR problem can occur where a thread or Remote Direct Memory Access (RDMA) socket cannot becreated. This problem can be caused by running concurrent connections over RDMA transport.

Possible causes

• RDMA socket buffers are by default pinned, or memory locked. A restricted memlock setting in yourenvironment can result in a failure to create or register new RDMA sockets.

• When you are running concurrent connections, each RDMA socket implicitly uses a file descriptor forevent tracking. If the maximum user open files limit is too low, socket creation can fail.

• When you are running concurrent connections, thread creation failure can be caused by a maximumuser process limit that is too low. For more information, see the following technote:java.lang.OutOfMemoryError while creating new threads.

Mitigation

• To avoid socket creation failures, check your ulimit -l setting and change your memlock setting toan appropriate value based on the usage of the socket buffers.

• To avoid socket creation failures when you are running concurrent connections, check your ulimit -nsetting and change your nofile setting to an appropriate value based on the scalability requirementsof the application.

• To avoid thread creation failures when you are running concurrent connections, check your ulimit -usetting and change your nproc setting to an appropriate value based on the scalability requirements ofthe application.



RDMA Network provider initialization failureA JSOR problem can occur where the Remote Direct Memory Access (RDMA) network providerinitialization fails on a 64-bit Linux operating system when you are running a 32-bit JVM.

During the RDMA network initialization stage, the JSOR runtime environment checks for the availability ofcompatible OFED runtime libraries. If the runtime environment cannot locate and load thelibrdmacm.so and libibverbs.so 32-bit libraries, you might see this problem. To avoid the problem,install the 32-bit OFED runtime libraries alongside the usual 64-bit libraries on a 64-bit Linux machine.

RDMA connection failedA JSOR problem can occur where a Remote Direct Memory Access (RDMA) client fails to connect to anRDMA server.

Client and server on the same host

If the client and server are on the same host, this behavior is expected because there is currently nosupport for RDMA loop back. For a successful connection, both client and server should be on differenthosts connected by an InfiniBand switch through the RDMA network interface adapters.

If the RDMA NIC has two physical ports, with two InfiniBand interface addresses, you can use theexternal hardware loop back plug (purchased separately) to connect them. Data from one port can thenbe fed back to the other port on the same host. With this arrangement, the RDMA client and server canrun on the same host, each picking up a different InfiniBand address.

Note: This configuration has not been tested in the Java environment.

Client and server on different subnets

The RDMA client and server should be on the same network, connected by a common InfiniBand switchand managed by a single subnet manager. If your RDMA client and server must be on different subnets,ensure that inter-network switching and packet forwarding is enabled at the hardware and softwarelevels.

Client and server on the same subnet

If the client and server are on the same subnet, a connection failure could be caused by incorrect client orserver configuration files, or an incorrect InfiniBand setup on one or both hosts.

Ensure that the rule entries in your configuration files are defined correctly, as described in “-Dcom.ibm.net.rdma.conf (Linux only)” on page 222.

Follow these steps to check your InfiniBand setup:

1. Ensure that each host that is involved in the communication has an appropriate InfiniBand hostchannel adapter or RDMA network interface card with valid InfiniBand addresses (interfaces that beginwith the prefix ib).

2. Ensure that each InfiniBand port is active and that the maximum transfer unit is properly set. To checkthe maximum transfer unit, run one the following OFED runtime commands: ibstat oribv_devinfo.

3. Ensure that the ifconfig command lists all the InfiniBand interfaces, and that each interface has avalid IP address.

4. Choose two valid InfiniBand addresses that are registered with the subnet manager for framing JSORconfiguration rules, then verify that basic RDMA communication is possible between the host andclient machines by running the rping command with your chosen InfiniBand addresses.

5. Similarly, run the ibv_rc_pingpong command.6. Similarly, run the ib_read_bw and ib_write_bw commands.

If all these steps are successful, there is no issue with basic RDMA communication between themachines. For further problem determination, read the configuration section of the README.txt file thatis part of the OFED source distribution: https://www.openfabrics.org/ofed-for-linux/.



RDMA connection reset exceptionsConcurrent Remote Direct Memory Access (RDMA) clients that try to send small chunks of data millions oftimes to a single RDMA server can throw connection reset exceptions.

Java Sockets over Remote Direct Memory Access (JSOR) employs the R-Sockets protocol as the basis forimplementing socket-level APIs on top of RDMA. The R-Sockets protocol uses the send and receivequeue sizes as a basis for implementing data flow and event control between sender and receiver. Whenseveral parallel clients try to send small amounts of data million of times, they might experienceconnection reset exceptions due to insufficient queue sizes. This behavior is because queue sizes dictatethe amount of work that can be queued up on either side.

Because the default queue sizes are large (see “JSOR environment settings (Linux only)” on page 219),the tuning of queue sizes is necessary only in rare cases. You should determine the queue sizes based onthe workload characteristics of your application. The maximum number and frequency of send andreceive operations is particularly important. There is no general formula for determining optimal queuesizes.

RDMA communication appears to hangThe Remote Direct Memory Access (RDMA) communication between client and server appears to hangwhen you are running RPC-based workloads with unpredictable message sizes.

Java Sockets over Remote Direct Memory Access (JSOR) employs the R-Sockets protocol as the basis forimplementing socket-level APIs on top of RDMA. To transfer data properly, the R-Sockets protocolrequires both the sender and receiver to be coordinated. The receiver must be ready with a receive bufferavailable for the sender to put data in. This behavior differs from TCP/IP where buffers are allocateddynamically as required. RDMA receive operations fail if sufficient receive buffers are not available inadvance. For more information, see the flow control section of the IETF draft of Remote Direct MemoryAccess Transport for Remote Procedure Call.

The JSOR implementation by default provides small send and receive buffers, which are less than 50 KBin size. When an RDMA client or server tries to send a large payload, for example 2 MB or 4 MB, in chunksof say 1 KB, in one direction without synchronized data flow between end points, the receive buffers canbe exhausted, resulting in the hung situation. The R-Socket protocol tries to recycle the receive buffers,but if the rate of replenishment is less than the data send rate, progress is impossible. These effects aremore pronounced when hundreds of parallel clients try to do the same operations on the same RDMAtransport, because the clients compete for the same set of physical network resources. The R-Socketsprotocol takes a long time to recover from this situation because it relies on retries and receiver-not-ready negative acknowledgements to make progress. In the worst case scenario, this behavior can resultin a deadlock situation between end points.

Similarly, the size of the send buffer should be sufficient to transfer the data to the corresponding receivebuffer.

Mitigation

For an Java RPC application, tune the buffer sizes before you deploy the application in a productionenvironment. Set the buffer sizes according to the workload characteristics and maximum payload size ofthe application. There is no general formula for determining optimal buffer sizes. For more information,see “JSOR environment settings (Linux only)” on page 219.

Enable application or runtime data transfer time outs that allow the client to cancel and try the datatransfer again, with increased buffer sizes if necessary. See the following APAR for an example: PM52124:OutOfMemoryError errors on eXtreme Scale clients can cause the grid to fail. In this example, a lack ofmemory caused the server thread to get stuck in a socketWrite() method. The suggested resolution isto set the com.ibm.CORBA.SocketWriteTimeout property.


https://www.spinics.net/lists/linux-rdma/msg13083.html

https://www.spinics.net/lists/linux-rdma/msg13083.html

https://tools.ietf.org/html/draft-ietf-nfsv4-rpcrdma-09#page-6

https://tools.ietf.org/html/draft-ietf-nfsv4-rpcrdma-09#page-6

http://www-01.ibm.com/support/docview.wss?uid=swg1PM52124

http://www-01.ibm.com/support/docview.wss?uid=swg1PM52124

Problems encountered with the zero copy function

Java applications hang when the zero copy function is enabled

Due to the internal synchronization that is required between the data source and the data sink when youuse the zero copy function, a client or server application might hang if you enable the zero copy functionfor only one endpoint.

To avoid this problem, take the following actions:

• Avoid using the same socket descriptor for parallel read and write operations when you use the zerocopy function.

• Ensure that the zero copy function is enabled on both endpoints. For more information, see “-Dcom.ibm.net.rdma.zeroCopy (Linux only)” on page 228.

• Ensure that the same zero copy threshold values are set on both endpoints. For more information, see“-Dcom.ibm.net.rdma.zeroCopyThreshold (Linux only)” on page 228.

Java applications are not using the zero copy function

Java applications might not use the zero copy function even after you specify the -Dcom.ibm.net.rdma.zeroCopy=true parameter.

The zero copy function is used only when both the following statements are true:

• You specified the -Dcom.ibm.net.rdma.zeroCopy=true parameter.• The buffer sizes that are passed inside Java read and write calls exceed the value that is specified by

the -Dcom.ibm.net.rdma.zeroCopyThreshold parameter. For more information about thisparameter, see “-Dcom.ibm.net.rdma.zeroCopyThreshold (Linux only)” on page 228.

You can use the standard JSOR tracing mechanism to find out whether the zero copy function is beingused by looking for the following functions in the trace:

• socketRead0Direct• socketWrite0Direct• RDMA_ReadDirect• RDMA_SendDirect

Java applications do not scale

The zero copy function is designed for large data transfers, a few at a time. Due to internalsynchronization, and resource allocation and management overheads, the scalability is restricted by thesize of the data that is transferred.

Ensure that the usage scenario is close to that of file transfer (FTP) type of data transfers in zero copymode.

Problems encountered with fork compatibility modeSeveral problems can be associated with operating in fork compatibility mode between Java clients andnative forked servers.

Native server error message librdmacm: Fatal: unable to open RDMA device

This message relates to a known Open Fabrics Enterprise Distribution (OFED) problem that occurs whenaround 100 client threads repeatedly open a connection and transfer data. This issue is seen on thefollowing system configuration:

• POWER PC systems with a Mellanox RDMA over converged ethernet (RoCE) MT26448 adapter• Redhat Enterprise Linux (RHEL) v6.4• MLNX_OFED_LINUX-2.0-3.0.0


This problem is not seen on systems with a later Mellanox adapter, MT4099, running RHEL v7 beta andOFED v3.5.

If you encounter this issue, upgrade to the latest version of the operating system and OFED software. Ifthe problem persists, consider upgrading to the latest version of the Mellanox RoCE adapter.

Java clients hang

In fork compatibility mode, Java clients can hang when systems connect to native forked servers. Thisproblem is associated with the RSocket preloading library. Internally the library creates a namedsemaphore, /rsocket_fork, when processing fork() support. However, when complete, the R-Socketlibrary does not remove the semaphore, which persists until the system is rebooted. Any stale link orvalue for this named semaphore from a previous invocation blocks the native server from acceptingremote client connections.

To work around this problem, use the rm command to unlink the /rsocket_fork named semaphorebefore fork() preloading begins. On Red Hat Enterprise Linux (RHEL), you can find the namedsemaphores in the directory /dev/shm. These files have a prefix of sem..

Java clients do not scale

The RSockets protocol currently offers fork preloading support only for simple applications that run underideal conditions. While preloading a forked process, the RSockets library uses blocking semantics tomigrate a connection to RDMA..

The current support for the fork() method in the RSocket is therefore inherently non-scalable. Javamultithreaded clients that try to connect to native forked servers by using the native interoperabilityfunction might experience a large number of failed connections. To mitigate this problem, increase theclient connection retry count to more than one.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related information“Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 193JSOR provides a mechanism for existing plain and NIO stream Java sockets applications totake advantage of high performance networking infrastructures, such as InfiniBand. Applicationperformance can be improved by reducing network latency and improving network bandwidth betweenJava server and client configurations.

JSOR environment settings (Linux only)Use these environment variables to set and size resources for connection and data transfer by using JavaSockets over Remote Direct Memory Access (JSOR). These environment variables also apply toJSOR NIO client/server scenarios.

You can improve your Java application network performance by tuning these variables as follows:

• If your application sends small messages, increase the IBM_JAVA_RDMA_INLINE value to reduce thelatency of the messages.

• If your application sends large messages, increase the IBM_JAVA_RDMA_SBUF_SIZE andIBM_JAVA_RDMA_RBUF_SIZE values to significantly reduce network latencies.

• Increasing the IBM_JAVA_RDMA_SQ_SIZE and IBM_JAVA_RDMA_RQ_SIZE values offers only marginalimprovement in network performance.

• Use the IBM_JAVA_RDMA_POLLING_TIME variable to limit the amount of CPU time spent polling forcompletion events.


• Tuning IBM_JAVA_RDMA_UNACK_CQ_EVENTS allows completion queue events to be received in batchmode, which reduces processing time.

• Use the IBM_JAVA_RDMA_COMP_VECTOR variable to spread the completion workload over multipleCPU cores.

Environment variablesIBM_JAVA_RDMA_COMP_VECTOR

This variable is used for tuning completion vectors when creating a new socket completion queue. Thedefault value of this variable is completion vector 0. You can spread completion workload among CPUcores on a system by associating different completion vectors with each connection. The actualmapping of a completion vector to a particular CPU core is decided by the smp_affinity factor thatis set at the system level for the corresponding interrupt request (IRQ) number.

This variable accepts comma-separate values, specified either individually or in a range. For example:

• To specify individual completion vectors, use 2,3,4,5• To specify completion vectors in a range, use 2 - 5

When a new connection is being set up, the next available completion vector is used. On reaching theend of a specified list, the indexer resets to the beginning of the list. This process ensures that all thecompletion vectors are distributed evenly between the connections that are created.

IBM_JAVA_RDMA_SBUF_SIZEIBM_JAVA_RDMA_RBUF_SIZE

These variables specify the RDMA socket send (IBM_JAVA_RDMA_SBUF_SIZE) and receive(IBM_JAVA_RDMA_RBUF_SIZE) buffer sizes, in bytes. If the environment variables are not set, adefault size of 128 KB is used for send and receive buffers.The minimum buffer size is 4096 bytes (4 KB). There is no limit on the upper value of the send buffersize; this limit is determined by the amount of pinned memory that is available on the machine.

The specified value is memory-aligned to 4 KB pages.

If the machine is short of lockable physical memory, the specified send or receive buffer registrationmight fail, resulting in the failure of RDMA socket creation during the accept or connect stage. If thissituation occurs, the API throws an IOException exception that indicates that an accept or connectoperation failed.

IBM_JAVA_RDMA_SQ_SIZEIBM_JAVA_RDMA_RQ_SIZE

These variables specify the RDMA send (IBM_JAVA_RDMA_SQ_SIZE) and receive(IBM_JAVA_RDMA_RQ_SIZE) queue sizes, as integers.

When a send or receive operation is in progress, subsequent send or receive requests are queueduntil the first request is complete. The number of pending requests is limited by the size of the send orreceive queue.

The default queue size and limits are the same for both send and receive queues. In line with RSocketsettings, the default queue size is 384. The minimum queue size is 16. The maximum queue size islimited by the hardware. For example:

• For Mellanox MT26428, MT26448, and MT4099 InfiniBand or RoCE adapters, the send and receivequeue sizes are limited to 16351.

• For Mellanox MT25208 InfiniBand adapters, the send and receive queue sizes are limited to 16384.

If a write operation tries to overfill the send queue, or a read operation tries to take data from anempty receive queue, the associated send or receive operations are blocked until a send slot is vacantor a receive slot is filled.

IBM_JAVA_RDMA_INLINEThis variable specifies the size of message, in bytes, that can be posted inline to a send queue. Aninline message is one that is directly read by the low-level driver instead of the RDMA device. Inline


buffers do not require memory registration and can be reused immediately after the send operationreturns.

The default value is 64 bytes. The minimum value is 64 bytes. The maximum value is 768 bytes

IBM_JAVA_RDMA_POLLING_TIME

This variable specifies the amount of time in microseconds to poll for completion events before therun time is set to blocking mode. Altering this setting affects the application's CPU usage counters.

The default value is 10 microseconds. The minimum value is zero. Although there is no limit on themaximum value you can set, a higher value results in increased CPU usage due to polling.

When a connection request is accepted from the passive side or established from the active side, anRDMA socket is populated with the necessary RDMA resources required for communication. Theseresources include send and receive buffers, and queue pairs for posting work requests. Appropriatesizes for these buffers and queues are set immediately after an RDMA socket is allocated. Thefollowing rules apply:

• On the passive side, when an incoming connection request is accepted, the sizes that are used forall child sockets are inherited from the server socket.

• When creating a new server socket or initiating a new connection on the client side, the sizes are setaccording to the following order of priority:

1. Sizes are specified in the environment variables.2. Sizes are taken from global preferences set by using the socket options property. For more

information, see “-Dcom.ibm.net.rdma.socketOptions (Linux only)” on page 226.3. Sizes are based on hardcoded defaults.

IBM_JAVA_RDMA_UNACK_CQ_EVENTSThis variable is used to acknowledge completion events in batch, instead of individually. This variableaccepts an integer value greater than or equal to 1. The default value is 1. The upper limit of thisvariable is set to the maximum possible completion events in a queue. However, for optimumperformance, set this value to the size of a completion queue, which is equal to the sum of send andreceive queue pair sizes. Each acknowledgment involves acquiring and releasing a shared lock. Byenabling batch processing, the overhead of many lock and unlock cycles is minimized.


RDMA system property command-line optionsUse the system property command-line options to set up your system.-D<name>=<value>



-Dcom.ibm.net.rdma.conf (Linux only)You can enable Java Sockets over RDMA (JSOR) on Java application server and client systems byspecifying this system property on the command line. Each host system requires a valid configuration file.

-Dcom.ibm.net.rdma.conf=<path><config_file>Where:

• <path> is an absolute path to the configuration file, or a relative path from the directory in which theJava process is started.

• <config_file> is a configuration file that specifies one or more rules.

Configuration file

The JSOR configuration file must be a plain text file that contains one rule per line. Comments must startwith the # character.

The following syntax applies to a rule:<net-spec><sp>(<connect-entry> | <accept-entry> | <bind-entry>)

Where:

• <net-spec> = rdma• <sp>=1*LWSP-char• <connect-entry> = connect <host-spec><sp><port-spec>• <accept-entry> = accept <host-spec><sp><port-spec><sp>(*| any | all |<client-spec>[<sp><client-spec>])

• <bind-entry> = bind <host-spec><sp><port-spec>

These suboptions apply to <connect-entry>, <accept-entry>, or <bind-entry>:

• <host-spec> = (hostname | ipaddress [/ prefix])• <port-spec> = (* | port)[ - (* | port) ]• <client-spec> = (hostname | ipaddress [/ prefix])

The following notes apply to syntax:

• Any number of linear white space characters (1*LWSP-char), such as tabs or spaces, can separate the<options>.

• Brackets, [], indicate optional text.• The vertical bar character (|) within parentheses, (), indicates a choice of values. You must select only

one.

Server configuration details

Rules that apply to a server configuration file:

• A server configuration file can have <accept-entry> and <bind-entry> parameters. Each<accept-entry> implicitly generates a <bind-entry> as well.

• Each hostname or ipaddress specified must be a valid InfiniBand interface address on that host.• If hostname is specified, there must be an appropriate hostname to InfiniBand interface address

mapping available, otherwise the default domain name resolution maps to an ethernet address ratherthan an InfiniBand address.

• <accept-entry>:

– The <host-spec> and <port-spec> values must be the local host.– All <client-spec> values must be the local host.– The local hostname or ipaddress can be either NULL or LOOPBACK.

• <bind-entry>:


– The <host-spec> and <port-spec> values must be the local host.– The hostname or ipaddress values can be either NULL or LOOPBACK.

• NULL or LOOPBACK addresses are replaced by an InfiniBand interface address during the bind process.

– A NULL address in the configuration can be 0, 0.0, 0.0.0, 0.0.0.0, or ::.– A LOOPBACK IP address must be 127.0.0.1.

The system selects an interface from the available InfiniBand interfaces. If you want to override thedefault address that is selected by the system, specify the -Dcom.ibm.net.rdma.preferredAddress system property.

Client configuration details

Rules that apply to a client configuration file:

• A client configuration file can have <connect-entry> and <bind-entry> parameters.• Each hostname or ipaddress specified must be a valid InfiniBand interface address on that host.• If hostname is specified, there must be an appropriate hostname to InfiniBand interface address


• <connect-entry>:

– The <host-spec> and <port-spec> values must be the remote host.– The <port-spec> value must not be NULL or LOCAL.– The <host-spec> value can be either NULL or LOCAL. This value is replaced by your preferred

RDMA-capable address during connection, which allows a JSOR client to connect to a JSOR server onthe same host.

• <bind-entry>:

– The <host-spec> and <port-spec> values must be the local host.– The hostname or ipaddress values can be either NULL or LOOPBACK.– NULL or LOOPBACK addresses are replaced by an InfiniBand interface address during the bind

process.

- A NULL address in the configuration can be 0, 0.0, 0.0.0, 0.0.0.0, or ::.- A LOOPBACK IP address must be 127.0.0.1.

The system selects an interface from the available InfiniBand interfaces. If you want to override thedefault address that is selected by the system, specify the -Dcom.ibm.net.rdma.preferredAddress system property.

Example: Server configuration

This example shows a server-side configuration entry on host1:

# My server configurationrdma accept host1 2000-3000 host2 host3

This rule configures connections that are accepted by host1 from host2 and host3 on server socketsthat are listening on ports 2000 - 3000 (inclusive) as RDMA connections.

In this case, for every accept rule a corresponding bind rule is created internally that forces a specific bindoperation for any sockets that match the rule. Consequently, a bind rule is not needed on the server, andan accept rule is not needed for a client.


Example: Client configuration

This example shows a client-side configuration entry on host2:

# My client configurationrdma connect host1 2435

This rule configures a connection that originates from host2 to host1 on port 2435 to be treated as anRDMA connection.

Example: Binding to NULL, LOCAL, or LOOPBACK address

This example shows a bind entry with the NULL, LOCAL, or LOOPBACK address:

rdma bind 0 *rdma bind :: *rdma bind 127.0.0.1 *

These rules configure all bind connections to the local address to pick up and bind to an RDMA-enabledaddress. The system selects an interface from the available IB interfaces. If you want to override thedefault address that is selected by the system, specify the -Dcom.ibm.net.rdma.preferredAddresssystem property.

Use the :: format to override the local ipv6 address.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related reference“-Dcom.ibm.net.rdma.preferredAddress (Linux only)” on page 226Use this property to set an RDMA-capable InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)interface address when the system default bind address is set to NULL, LOOPBACK, or LOCAL.

-Dcom.ibm.net.rdma.debug (Linux only)Specifies whether Java Sockets over RDMA (JSOR) debug messages are sent to the standard terminal.These messages are information messages.

-Dcom.ibm.net.rdma.debug=[true|false]

When you specify the -Dcom.ibm.net.rdma.debug=true property, debug messages are sent tothe standard terminal when major RDMA processing steps, such as when a socket is switched toRDMA or bound to an address, are completed. The default value is false.

Server example

The following output is generated from the command java -Dcom.ibm.net.rdma.debug=true -Dcom.ibm.net.rdma.conf=server.conf SampleServer6 7.7.12.10 1058 1 1000000:

[JSOR Info] RDMA network provider inialized[JSOR Info] Socket switched to RDMA mode[JSOR Info] RDMA socket created[JSOR Info] RDMA socket bound to /7.7.12.10:1058[JSOR Info] RDMA socket put in listening modeServer Ready>[JSOR Info] Socket switched to RDMA mode[JSOR Info] Accepted RDMA connection request[JSOR Info] Retrieved RDMA socket optionLocal: /7.7.12.10:1058 Remote: /7.7.12.9:55498[JSOR Info] Retrieved RDMA socket option[JSOR Info] Retrieved RDMA socket optionSBuf: 131072 bytes RBuf: 131072 bytes[JSOR Info] RDMA socket input stream available[JSOR Info] RDMA socket output stream available


Received/Sent 1000000 bytes[JSOR Info] RDMA socket closed[JSOR Info] RDMA socket closed

Client example

The following output is generated from the command java -Dcom.ibm.net.rdma.debug=true -Dcom.ibm.net.rdma.conf=client.conf SampleClient6 7.7.12.10 1058 1 1000000:

[JSOR Info] RDMA network provider inialized[JSOR Info] Socket switched to RDMA mode[JSOR Info] RDMA socket created[JSOR Info] RDMA connection established to /7.7.12.10:1058[JSOR Info] RDMA socket input stream available[JSOR Info] RDMA socket output stream availableClient Ready>[JSOR Info] Retrieved RDMA socket optionLocal: /7.7.12.9:55498 Remote: /7.7.12.10:1058[JSOR Info] Retrieved RDMA socket option[JSOR Info] Retrieved RDMA socket optionSBuf: 131072 bytes RBuf: 131072 bytesRound trip time of 1000000 bytes: 2430 usec[JSOR Info] RDMA socket closed


-Dcom.ibm.nio.rdma.EPollSelectorProvider (Linux only)Use the EPoll selector when enabling Java Sockets over RDMA (JSOR) to increase the number ofconcurrent clients that are supported in Java client and server testing from 200 to 1000. This selectoralso reduces latency in the channel selection process.

-Dcom.ibm.nio.rdma.EPollSelectorProvider=[true|false]

When you are enabling JSOR for Java NIO client or server applications, you can specify the -Dcom.ibm.nio.rdma.EPollSelectorProvider=true property to use the EPoll selector. Thedefault Poll selector will be used if the property value is false. See “JSOR limitations (Linux only)” onpage 201 for more information about the limitations of the Poll and EPoll selectors.

To use this property, you must also set the -Dcom.ibm.nio.rdma.conf property. See “-Dcom.ibm.nio.rdma.conf (Linux only)” on page 228 for more information about this property.

-Dcom.ibm.net.rdma.nativeForkCompatibility (Linux only)Specifies whether the Java Sockets over RDMA (JSOR) client should connect and synchronize with thenative RSockets server before establishing an RDMA connection.

-Dcom.ibm.net.rdma.nativeForkCompatibility=[true|false]

The -Dcom.ibm.net.rdma.nativeForkCompatibility=true property results in the samebehavior as the RDMAV_FORK_SAFE environment variable that is supported by the native RSsocketinterface. Use this property when you interact with native applications that export theRDMAV_FORK_SAFE environment variable. The default value is false.

The following examples show the native server and Java client invocations that enable fork compatibility:

• Server command-line invocation:

$ export RDMAV_FORK_SAFE=1

$ LD_PRELOAD=/usr/lib/rsocket/librspreload.so SampleNativeServer <server_args>


where <server_args> are the native application-specific command-line options.

• Client command-line invocation:

$ java -Dcom.ibm.net.rdma.conf=<client.conf> -Dcom.ibm.net.rdma.nativeForkCompatibility=true -cp <classpath> SampleClient <client_args>

where:

– <client.conf> is your client RDMA configuration file.– <classpath> specifies your class path.– <client_args> are the Java application-specific command-line options.


-Dcom.ibm.net.rdma.preferredAddress (Linux only)Use this property to set an RDMA-capable InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)interface address when the system default bind address is set to NULL, LOOPBACK, or LOCAL.

RDMA can be enabled only when a socket binds to an RDMA-capable InfiniBand or RoCE interfaceaddress. If a socket bind address is the NULL, LOOPBACK, or LOCAL address, you can override the defaultRDMA address that is chosen by the system by specifying this property. For RoCE adapters, if a preferredaddress is not specified, the default value for the address is NULL.-Dcom.ibm.net.rdma.preferredAddress=<interface_address>

where:

• <interface_address> is your chosen interface address in ipv4 or ipv6 format.

If there is no IB or RoCE interface address available, or the bind rule is not specified, the socket that bindsto NULL, LOOPBACK, or LOCAL address is the TCP connection.

For more information about using RDMA configuration rules, see “-Dcom.ibm.net.rdma.conf (Linux only)”on page 222.


-Dcom.ibm.net.rdma.socketOptions (Linux only)Use this property to specify a list of socket options for Java Sockets over RDMA (JSOR).

-Dcom.ibm.net.rdma.socketOptions=filename

List the socket options as key-value pairs in a plain text file, then supply the filename as theparameter for the -Dcom.ibm.net.rdma.socketOptions property. The file path must be eitherabsolute or relative to the location of the VM. The following socket options are supported:

• SendBufferSize=integer_value_in_bytes• ReceiveBufferSize=integer_value_in_bytes• SendQueueSize=integer_value• ReceiveQueueSize=integer_value• SendInlineSize=integer_value


Other properties are ignored.

You can also specify these options by using the following environment variables:

• IBM_JAVA_RDMA_SBUF_SIZE• IBM_JAVA_RDMA_RBUF_SIZE• IBM_JAVA_RDMA_SQ_SIZE• IBM_JAVA_RDMA_RQ_SIZE• IBM_JAVA_RDMA_INLINE

These environment variables take precedence over socket options that you specify by using the -Dcom.ibm.net.rdma.socketOptions property.


-Dcom.ibm.net.rdma.tcpFallback (Linux only)RDMA-enabled Java application servers are intended to connect RDMA-enabled clients. However, youcan use this option to allow an RDMA-enabled Java application server to accept a TCP connection from aclient.

The client must be specified in the JSOR configuration file on the server host system.

Use this system property with the following syntax:-Dcom.ibm.net.rdma.tcpFallback=[true | false]

The default setting for this property is false.You can configure the time that a Java application server must wait before the server accepts TCPconnections. For more information, see “-Dcom.ibm.net.rdma.tcpFallbackWaitTime (Linux only)” on page227.


-Dcom.ibm.net.rdma.tcpFallbackWaitTime (Linux only)Use this system property to configure the time period that an RDMA-enabled Java application server mustwait before the server allows a remote TCP client to connect.

This system property must be used with -Dcom.ibm.net.rdma.tcpFallback, which enables TCPcommunication on an RDMA server. If -Dcom.ibm.net.rdma.tcpFallback is not set to true, thissystem property is ignored.

Specify the time to wait in milliseconds, by using the following syntax:-Dcom.ibm.net.rdma.tcpFallback=<milliseconds>

The time that is specified must be between 20 milliseconds and 10 seconds. If the value specified isoutside of this range, a warning message is issued and the value is reset to the lower or upper limit.

If the value specified is not valid, a warning message is issued and the default value is set.

If a value is not provided, the default value is set.

The default value is 100 milliseconds.


For more information about enabling TCP communications on an RDMA system, see “-Dcom.ibm.net.rdma.tcpFallback (Linux only)” on page 227.


-Dcom.ibm.net.rdma.zeroCopy (Linux only)Specifies whether the zero copy function is enabled for Java Sockets over RDMA (JSOR). Enable thisfunction to reduce data transfer time for large payloads.

-Dcom.ibm.net.rdma.zeroCopy=[true|false]

When you enable the zero copy function, data is copied directly from Java application memory on onehost to Java application memory on another host without using the processor on either host.Intermediate buffer copy operations are avoided, which reduces data transfer time for large datatransfers. The default value is false. Use this property with the “-Dcom.ibm.net.rdma.zeroCopyThreshold (Linux only)” on page 228 property, which specifies aminimum size for the data transfer. These properties are ignored if RDMA is not enabled.

For more information about the zero copy function, see “JSOR zero copy function (Linux only)” onpage 196.


-Dcom.ibm.net.rdma.zeroCopyThreshold (Linux only)Specifies the minimum data transfer size for the zero copy function of Java Sockets over RDMA (JSOR).

-Dcom.ibm.net.rdma.zeroCopyThreshold=<size>When you set the “-Dcom.ibm.net.rdma.zeroCopy (Linux only)” on page 228 property to true, data iscopied between hosts without using the processor on either host. This function reduces data transfertime, but only for large data transfers. Use the -Dcom.ibm.net.rdma.zeroCopyThreshold=<size> property to set the minimum size, in kilobytes,of the data that you want to be transferred by using the zero copy function. The default value is 256and the specified value should be between 64 and 16384.


-Dcom.ibm.nio.rdma.conf (Linux only)You can enable Java Sockets over RDMA (JSOR) on Java NIO application server and client systems byspecifying this system property on the command line. Each host system requires a valid configuration file.

-Dcom.ibm.nio.rdma.conf=<path><config_file>Where:

• <path> is an absolute path to the configuration file, or a relative path from the directory in which theJava process is started.

• <config_file> is a configuration file that specifies one or more rules.


Configuration file

The JSOR configuration file must be a plain text file that contains one rule per line. Comments must startwith the # character.

The following syntax applies to a rule:<net-spec><sp>(<connect-entry> | <accept-entry> | <bind-entry>)

Where:

• <net-spec> = rdma• <sp>=1*LWSP-char• <connect-entry> = connect <host-spec><sp><port-spec>• <accept-entry> = accept <host-spec><sp><port-spec><sp>(*| any | all |<client-spec>[<sp><client-spec>])

• <bind-entry> = bind <host-spec><sp><port-spec>

These suboptions apply to <connect-entry>, <accept-entry>, or <bind-entry>:

• <host-spec> = (hostname | ipaddress [/ prefix])• <port-spec> = (* | port)[ - (* | port) ]• <client-spec> = (hostname | ipaddress [/ prefix])

The following notes apply to syntax:

• Any number of linear white space characters (1*LWSP-char), such as tabs or spaces, can separate the<options>.

• Brackets, [], indicate optional text.• The vertical bar character (|) within parentheses, (), indicates a choice of values. You must select only

one.

Server configuration details

Rules that apply to a server configuration file:

• A server configuration file can have <accept-entry> and <bind-entry> parameters. Each<accept-entry> implicitly generates a <bind-entry> as well.

• Each hostname or ipaddress specified must be a valid InfiniBand interface address on that host.• If hostname is specified, there must be an appropriate hostname to InfiniBand interface address


• <accept-entry>:

– The <host-spec> and <port-spec> values must be the local host.– All <client-spec> values must be the local host.– The local hostname or ipaddress can be either NULL or LOOPBACK.

• <bind-entry>:

– The <host-spec> and <port-spec> values must be the local host.– The hostname or ipaddress values can be either NULL or LOOPBACK.

• NULL or LOOPBACK addresses are replaced by an InfiniBand interface address during the bind process.

– A NULL address in the configuration can be 0, 0.0, 0.0.0, 0.0.0.0, or ::.– A LOOPBACK IP address must be 127.0.0.1.

The system selects an interface from the available InfiniBand interfaces. If you want to override thedefault address that is selected by the system, specify the -Dcom.ibm.nio.rdma.preferredAddress system property.


Client configuration details

Rules that apply to a client configuration file:

• A client configuration file can have <connect-entry> and <bind-entry> parameters.• Each hostname or ipaddress specified must be a valid InfiniBand interface address on that host.• If hostname is specified, there must be an appropriate hostname to InfiniBand interface address


• <connect-entry>:

– The <host-spec> and <port-spec> values must be the remote host.– The <host-spec> value can be NULL or LOCAL. This address is replaced by the preferred RDMA-

capable address during connection. Therefore, the JSOR client can connect to the JSOR server on thesame host.

– The <port-spec> value must not be NULL or LOCAL.• <bind-entry>:

– The <host-spec> and <port-spec> values must be the local host.– The hostname or ipaddress values can be either NULL or LOOPBACK.– NULL or LOOPBACK addresses are replaced by an InfiniBand interface address during the bind

process.

- A NULL address in the configuration can be 0, 0.0, 0.0.0, 0.0.0.0, or ::.- A LOOPBACK IP address must be 127.0.0.1.

The system selects an interface from the available InfiniBand interfaces. If you want to override thedefault address that is selected by the system, specify the -Dcom.ibm.nio.rdma.preferredAddress system property.

Example: Server configuration

This example shows a server-side configuration entry on host1:

# My server configurationrdma accept host1 2000-3000 host2 host3

This rule configures connections that are accepted by host1 from host2 and host3 on server socketsthat are listening on ports 2000 - 3000 (inclusive) as RDMA connections.

In this case, for every accept rule a corresponding bind rule is created internally that forces a specific bindoperation for any sockets that match the rule. Consequently, a bind rule is not needed on the server, andan accept rule is not needed for a client.

Example: Client configuration

This example shows a client-side configuration entry on host2:

# My client configurationrdma connect host1 2435

This rule configures a connection that originates from host2 to host1 on port 2435 to be treated as anRDMA connection.

Example: Binding to NULL, LOCAL, or LOOPBACK address

This example shows a bind entry with the NULL, LOCAL, or LOOPBACK address:

rdma bind 0 *rdma bind :: *rdma bind 127.0.0.1 *


These rules configure all bind connections to the local address to pick up and bind to an RDMA-enabledaddress. The system selects an interface from the available IB interfaces. If you want to override thedefault address that is selected by the system, specify the -Dcom.ibm.nio.rdma.preferredAddresssystem property.

Use the :: format to override the local ipv6 address.

Related tasks“Enabling Java Sockets over Remote Direct Memory Access (JSOR) (Linux only)” on page 203JSOR is enabled by specifying a command line system property when you start your Java application. Avalid configuration file must exist on both the Java application server and client systems, which specifiesthe RDMA rules for connection. If RDMA services are not available, you can optionally configure yourserver to receive TCP connections for plain sockets.Related reference“-Dcom.ibm.net.rdma.preferredAddress (Linux only)” on page 226Use this property to set an RDMA-capable InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)interface address when the system default bind address is set to NULL, LOOPBACK, or LOCAL.

-Dcom.ibm.nio.rdma.debug (Linux only)Specifies whether Java Sockets over RDMA (JSOR) debug messages are sent to the standard terminal.These messages are information messages.

-Dcom.ibm.nio.rdma.debug=[true|false]

When you specify the -Dcom.ibm.nio.rdma.debug=true property, debug messages are sent tothe standard terminal when major RDMA processing steps, such as when a socket is switched toRDMA or bound to an address, are completed. The default value is false.

Server example

The following output is generated from the command java -Dcom.ibm.nio.rdma.debug=true -Dcom.ibm.nio.rdma.conf=server.conf SampleServer6 7.7.12.10 1058 1 1000000:

[JSOR Info] RDMA network provider inialized[JSOR Info] Socket switched to RDMA mode[JSOR Info] RDMA socket created[JSOR Info] RDMA socket bound to /7.7.12.10:1058[JSOR Info] RDMA socket put in listening modeServer Ready>[JSOR Info] Socket switched to RDMA mode[JSOR Info] Accepted RDMA connection request[JSOR Info] Retrieved RDMA socket optionLocal: /7.7.12.10:1058 Remote: /7.7.12.9:55498[JSOR Info] Retrieved RDMA socket option[JSOR Info] Retrieved RDMA socket optionSBuf: 131072 bytes RBuf: 131072 bytes[JSOR Info] RDMA socket input stream available[JSOR Info] RDMA socket output stream availableReceived/Sent 1000000 bytes[JSOR Info] RDMA socket closed[JSOR Info] RDMA socket closed

Client example

The following output is generated from the command java -Dcom.ibm.nio.rdma.debug=true -Dcom.ibm.nio.rdma.conf=client.conf SampleClient6 7.7.12.10 1058 1 1000000:

[JSOR Info] RDMA network provider inialized[JSOR Info] Socket switched to RDMA mode[JSOR Info] RDMA socket created[JSOR Info] RDMA connection established to /7.7.12.10:1058[JSOR Info] RDMA socket input stream available[JSOR Info] RDMA socket output stream availableClient Ready>


[JSOR Info] Retrieved RDMA socket optionLocal: /7.7.12.9:55498 Remote: /7.7.12.10:1058[JSOR Info] Retrieved RDMA socket option[JSOR Info] Retrieved RDMA socket optionSBuf: 131072 bytes RBuf: 131072 bytesRound trip time of 1000000 bytes: 2430 usec[JSOR Info] RDMA socket closed


-Dcom.ibm.nio.rdma.preferredAddress (Linux only)Use this property to set an RDMA-capable InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)interface address when the system default bind or connect address is set to NULL, LOOPBACK, or LOCAL.

RDMA can be enabled only when a socket binds to an RDMA-capable InfiniBand or RoCE interfaceaddress. If a socket bind address is the NULL, LOOPBACK, or LOCAL address, you can override the defaultRDMA address that is chosen by the system by specifying this property. For RoCE adapters, if a preferredaddress is not specified, the default value for the address is NULL.-Dcom.ibm.nio.rdma.preferredAddress=<interface_address>

where:

• <interface_address> is your chosen interface address in ipv4 or ipv6 format.

If there is no IB or RoCE interface address available, or the bind/connect rule is not specified, the socketthat binds to NULL, LOOPBACK, or LOCAL address is the TCP connection.

For more information about using RDMA configuration rules, see “-Dcom.ibm.net.rdma.conf (Linux only)”on page 222.


The jVerbs library (Linux only)The jVerbs library contains a verbs API and an endpoint API that enable the development of Javaapplications that use high performance networking infrastructures, such as InfiniBand, iWARP, or RoCE.The verbs interface is an alternative networking API to the sockets interface. The verbs interfaceprovides send and receive communications, and the endpoint interface is a simplified API that providesan abstraction of a jVerbs endpoint.

jVerbs is implemented as a Java library that is based on the Open Fabrics Enterprise Distribution (OFED)RDMA user libraries. jVerbs uses a thin JNI layer to bridge between Java code and the OFED userlibraries. To avoid any performance impacts that are associated with passing complex RDMA parametersand arrays through the JNI interface, the jVerbs library implements a concept called stateful verbsmethod (SVM). With this approach, each JNI serialization state for a verb call is cached in the context ofan SVM object and can be reused many times.

The following diagram illustrates the high-level design for implementing RDMA communications by usingthe jVerbs library.


The slow control path is used for RDMA operations such as registering memory and creating queue pairsfor communications. The fast data path is used for the transfer of data.

verbs API

The purpose of the verbs interface is to separate data and control. By pre-allocating communicationresources, such as pinning memory for Direct Memory Access (DMA), data is transferred without involvingthe operating system or the JVM. This principle improves the performance of data transfer operations, akey factor in achieving low latency and high bandwidth over RDMA-capable network infrastructures.

The verbs interface provides APIs for the following functions:RDMA send and receive types of communication

RDMA send and receive communications are two-sided operations. The sender sends a message,while the receiver creates an application buffer and indicates where to receive the data. Thismechanism is similar to traditional TCP socket-based communications.

RDMA operationsRDMA operations are one-sided operations in which only one peer reads, writes, or manipulatesremote application buffers.

For all functions, data transfer is efficient because the network hardware accesses the data buffersdirectly by using DMA. Application data buffers must be registered with the RDMA subsystem by usingspecific verbs API calls. As a consequence, the RDMA subsystem ensures that the memory is pinned andcannot be swapped out.

endpoint API

The endpoint interface is simpler than the verbs interface. You can create an endpoint and a connectionin a similar way to TCP socket communications, by using bind, connect, and disconnect operations.However, when an endpoint is connected it represents a simple RDMA queue pair, which can be used topost one-sided or two-sided operations.

For more information about programming with these APIs, see “Writing Java applications that use thejVerbs library (Linux only)” on page 235.


jVerbs application system and runtime requirements (Linux only)Java applications that are written by using the jVerbs library depend on specific hardware and softwarerequirements. However, there are no specific runtime configuration requirements for a jVerbsapplication.

The following prerequisites apply:


– Linux 32-bit x-86 with either InfiniBand (IB) or RDMA over Converged Ethernet (RoCE)– Linux AMD64/EM64T with IB or RoCE– Linux 32-bit POWER with RoCE– Linux 64-bit POWER with RoCE





Running a jVerbs application is the same as running any other Java application; no additional properties orenvironment variables are required. You do not need to set the class path because the jverbs.jar file isloaded automatically by the extension class loader. For example:

JAVA_HOME/jre/bin/java MyClientApplication.java arguments

Note: Running a jVerbs application on a non-RDMA computer results in an IOException exceptionduring initialization.

Related information“jVerbs problem determination (Linux only)” on page 249You use the jVerbs API to develop Java applications that use high-speed network infrastructures such asInfiniBand. To investigate jVerbs problems, you can run trace or review the list of common problems. Thissection also contains a list of exceptions and messages that you might encounter.

jVerbs limitations (Linux only)The following known limitations apply to the jVerbs library.

• Direct byte buffers are required for all data transfers. If you try to use a different resource for datatransfer, an exception is generated.

• The IPv6 address format is not supported. You must pass the InfiniBand address in IPv4 format. Hostnames are also not supported.

• The loopback and wildcard addresses are not supported by bindAddress() or resolveAddress().• The CompletionChannel.getCQEvent() method does not indicate which CompletionQueue

object has the event, only that a new completion event is available in one of the CompletionQueueobjects that are attached to the CompletionChannel object. You must poll all the CompletionQueueobjects, by using the CompletionQueue.pollCQ() method, to find and retrieve the completionevent.

• The jVerbs library has been tested with a maximum of 20 parallel Connection IDs doing read and writeoperations. You can exceed this limit as long as you work within the system hardware limit and ensure




that resources are properly released when complete. If you exceed the limits for the system, anIOException exception is generated. If it is ignored, this exception results in a hang or crash.

• Not all jVerbs APIs handle, or know about, abrupt terminations at the other end. Some calls, such as theconnect() method, indicate an abrupt termination by using a rejected event type, but other callsmight block and wait forever without knowing that the other end terminated. To avoid this issue inapplications that use the jVerbs APIs, add code to recognize an abrupt termination, then end theapplication gracefully.

• Interoperability between the verbs and endpoint interface is not supported.


Writing Java applications that use the jVerbs library (Linux only)On Linux systems, you can use the jVerbs library to write applications that communicate between clientand server systems directly over RDMA-capable infrastructure, bypassing the operating system. There aretwo interfaces. The verbs interface is an alternative networking interface to sockets; it provides sendand receive communications, and Remote Direct Memory Access (RDMA) operations. The endpointinterface is a simplified API that provides an abstraction of a jVerbs endpoint.

For a high level overview of the jVerbs software architecture and the application programminginterfaces, see “jVerbs problem determination (Linux only)” on page 249.

RDMA client and server applications can be written directly by using the verbs package classes or byusing the endpoint package classes. The topics that follow describe the interfaces and the artifacts thatare required to implement RDMA communications. Examples are provided for client and serverimplementations.

Related information“jVerbs problem determination (Linux only)” on page 249You use the jVerbs API to develop Java applications that use high-speed network infrastructures such asInfiniBand. To investigate jVerbs problems, you can run trace or review the list of common problems. Thissection also contains a list of exceptions and messages that you might encounter.jVerbs API Reference

jVerbs programming terms and artifacts (Linux only)Developing applications that use Remote Direct Memory Access (RDMA) communications requires someunderstanding of RDMA artifacts and common terminology. Explanations are provided for RDMAresources such as protection domains, queue pairs, completion queues, and event channels. Thisinformation supplements the application programming interface (API) reference for the jVerbs library.

The common terms are described in the following list. For more information, see the jVerbs APIreference.

Completion channelAll completion events for send or receive posts are placed on a completion channel. You can use theCompletionChannel.getCQEvent() method to check when an event is placed on the completionchannel. If the return is not null, a completion event is placed on a queue that is associated with thechannel. You can retrieve the completion event by using the CompletionQueue.pollCQ() method.The CompletionChannel.getCQEvent() method does not indicate which completion queue topoll, therefore you must poll all the queues that are associated with the channel to retrieve thecompletion event.

Completion queueWork completion events for send and receive posts are placed on a completion queue. Queues can becreated for each connection ID, or queues can be shared among multiple connection IDs. Whencompletion queues are shared, the work completion queue pair number uniquely identifies theconnection ID that the work belongs to. When you create a completion queue, you can define the


maximum number of completion events that can be held. A completion queue can be polled directly,or you can request notifications on an event channel and poll the completion queue afterward. If youpoll the completion queue, you must poll at regular intervals to avoid missing any work completionevents that might overrun.

Connection eventConnection management events are generated for different connection management calls. Here aresome examples of common event types:Connection request event: RDMA_CM_CONNECT_REQUEST

This event type is generated when a ConnectionID.connect() call is made from the activeclient side to the server side.

Established event: RDMA_CM_EVENT_ESTABLISEDThis event type is generated when a connection is established on both sides.

Disconnection event: RDMA_CM_EVENT_DISCONNECTEDThis event type is generated when a ConnectionID.destroy() call is made to the other side.

Address resolved event: RDMA_CM_EVENT_ADDRESS_RESOLVEDThis event type is generated when a ConnectionID.resolveAdress() call is made from theactive client side.

Route resolved event: RDMA_CM_EVENT_ROUTE_RESOLVEDThis event type is generated when a ConnectionID.resolveRoute() call is made from theactive client side.

For a complete list of event types, see the ConnectionEvent.EventType class in the APIreference.

Connection IDA connection ID is a unique identifier that identifies a connection between two RDMA systems. Youcreate a connection ID by using the ConnectionID.create() method, passing the event channelas an argument to associate the connection ID with the channel. A connection event for a connectionID is received through an event channel.

Device contextThe verbsContext class is specific to InfiniBand devices and describes the context in whichresources can operate. Each InfiniBand device has one context; all the connection IDs that areassociated with that device share the same context. Protection domains and completion channels arecreated by using device context.

Event channelsEvent channels are used to receive all connection events for a connection ID. You can create an eventchannel by using the static method EventChannel.createEventChannel(). To get an event thatwas received on a channel, use the EventChannel.getConnectionEvent() method. Toacknowledge an event, use the EventChannel.ackConnectionEvent() method.

Post send or receive requestA work request is posted to a queue pair that is associated with a connection ID. The work requestmight relate to a send or receive operation.

Protection domainsA protection domain controls the interaction between an RDMA adapter and host memory, byassociating a queue pair and memory region. Components within a protection domain can interactonly with each other.

Queue pairEach connection ID must be associated with a queue pair to transfer data by using theConnectionID.createQueuePair() method. All send or receive work requests that are generatedby a connection ID are posted to that queue pair. Separate queue pairs can be associated either witha single completion queue, or with a shared completion queue.

ScatterGatherElementA work request is made up of a list of ScatterGatherElement elements. Each element consists ofthe following information:


• A starting address of an allocated direct byte buffer that is to be sent, or the address location whereremote data needs to be placed.

• The length of the buffer.• A local key. The local key value corresponds to the local key value for the MemoryRegion instance

that is returned by the registerMemoryRegion() method for that buffer.

Register and unregister memoryAny data buffers that are sent or received must first be registered to pin the memory for RDMAtransfer. The buffers must also be unregistered after usage to unpin the memory. These tasks use theVerbsContext.registerMemoryRegion() and VerbsContext.deregisterMemoryRegion()API calls.

Work completion eventA work completion event is received on the completion queue for every send or receive work request.You can query the following details:

• Success or failure• Number of bytes (read or write)• Work request ID• Queue pair number

When completion queues are shared between connection IDs, querying the queue pair numberindicates which connection ID the work completion event is for.

Work requestThere are two types of work requests:

• Send work request: This type of request is generated by a QueuePair.postSend() call. Therequest consists of an element, which is known as a ScatterGatherElement, a send flag, and anoperation code. The ScatterGatherElement describes a local buffer.

• Receive work request: This type of request is generated by a QueuePair.postReceive() call.The request consists of a list of ScatterGatherElement elements.

You can post a list of work requests by using the ConnectionID.postSend() orConnectionID.postReceive() methods.

A work completion event is received for each work request that is made.

Related informationjVerbs API Reference

Implementing client and server communications with the verbs interface (Linux only)Developing applications that use the verbs interface requires a number of steps to create artifacts thatare used in Remote Direct Memory Access (RDMA) connections between server and client. An example isprovided to guide developers through the process on both the client and server sides of the connection.

The verbs API enables you to control how RDMA resources are created and used. Before you start anydevelopment work, you should have a good understanding of RDMA communications and the client andserver environment for your Java application. The following types of RDMA resources are required:

• Protection domains• Connection IDs• Queue pairs• Completion queues

You must determine how these resources should be associated with each other. For example, separatequeue pairs can be associated either with a single completion queue, or with a shared completion queue.You must also determine how RDMA resources should be used for networking. For example, a completionqueue can be polled directly, or you can request notifications on an event channel and poll the completionqueue afterward.


The following diagram shows an example of a client and server implementation that uses the verbs API.Certain steps that are common to both the client and server processes are expanded in later diagrams.For a detailed description of the terms that are used in these communication flows, see “jVerbsprogramming terms and artifacts (Linux only)” on page 235.


The following diagram expands the programming steps that are required when you allocate RDMAstructures. This process is shown in the first diagram as the single step labeled "Allocate RDMAstructures", which is marked with the number 1.

The following diagram expands the programming steps that are required when you remove RDMAstructures. This process is shown in the first diagram as the single step labeled "Destroy allocatedstructures", which is marked with the number 2.

The following sections provide an explanation of the server and client communication flows that areillustrated in the diagrams.


Server flow

The following events are established on the server side of the RDMA connection:

1. An event channel is created.2. A connection ID is created and associated with the event channel. Any number of connection IDs can

be associated with the event channel.3. The server listens for connection requests from clients.4. When a client connection request is received, the request is acknowledged. The event type for the

request is RDMA_CM_EVENT_CONNECT_REQUEST.5. For each request received from a client the following steps occur:

a. The server obtains the client connection ID.b. The necessary RDMA structures are allocated before the connection between the server and client

is established. The following steps are required to create the RDMA structures:

• The context for the device is obtained, which can be used to query the device, port, or globalunique identifier (GUID).

• A protection domain is allocated.• A completion channel is created for posting completion events.• A completion queue is created.• A work request is made for a completion queue notification.• A queue pair is created.• A direct byte buffer is allocated and registered for the data transfer.

c. Optionally, a completion queue processing thread can be started. For more information about theevents that take place, see “Completion queue processing” on page 242.

d. When the RDMA structures are ready, a receive work request is posted by the server.e. When the work request is accepted, an event is sent to the client to confirm that the connection is

established and ready to receive RDMA send or receive requests. The event type isRDMA_CM_EVENT_ESTABLISHED.

f. A send or receive request is posted, which initiates data transfer between the server and clientsystems.

g. When the work request is complete, the connection is disconnected. The event typeRDMA_CM_EVENT_DISCONNECTED is generated by the server.

h. The RDMA structures that were created for the data transfer are removed in the following order:

1) The buffers are cleaned and unregistered.2) The completion queue is removed.3) The completion channel is removed.4) The queue pair is removed.

6. To disconnect the server from further RDMA operations with client systems, the connection ID isremoved.

7. The event channel is removed. The event channel cannot be removed until all acknowledgments arereceived.

Client flow

The following events occur on the client side of the RDMA connection:

1. An event channel is created.2. A connection ID is created and associated with the event channel. Any number of connection IDs can

be associated with the event channel.


3. The client queries the address of the server system by using theConnectionID.ResolveAddress() method. When the event typeRDMA_CM_EVENT_ADDRESS_RESOLVED is received, the client sends an acknowledgment.

4. The client queries the route for the server system by using the ConnectionID.ResolveRoute()method. When the event type RDMA_CM_EVENT_ROUTE_RESOLVED is received, the client sends anacknowledgment.

5. The necessary RDMA structures are allocated before the connection between the client and server isestablished. The following steps are required to create the RDMA structures:

• The context for the device is obtained, which can be used to query the device, port, or global uniqueidentifier (GUID).

• A protection domain is allocated.• A completion channel is created for posting completion events.• A completion queue is created.• A work request is made for a completion queue notification.• A queue pair is created.• A direct byte buffer is allocated and registered for the data transfer.

6. Optionally, a completion queue processing thread can be started. For more information about theevents that take place, see “Completion queue processing” on page 242.

7. A post receive request is made to the server.8. A connection request is made to the server. The event type RDMA_CM_CONNECT_REQUEST is

generated and sent to the server.9. The client waits until the event type RDMA_CM_EVENT_ESTABLISHED is received from the server.

This event indicates that the connection is established and data transfer is ready to take place.10. A send or receive work request is posted, which initiates data transfer between the server and client

systems.11. When the work request is complete, the connection is disconnected. The event type

RDMA_CM_EVENT_DISCONNECTED is generated by the client.12. The RDMA structures that were created for the data transfer are removed in the following order:

a. The buffers are cleaned and unregistered.b. The completion queue is removed.c. The completion channel is removed.d. The queue pair is removed.

13. To disconnect the client from further RDMA operations with the server, the connection ID is removed.14. The event channel is removed.

Completion queue processing

The following diagram expands the programming steps that are required when optionally processingcompletion queues. This process is shown in the first diagram as the single step labeled "Completionqueue processing", which is marked with the number 3.


The following steps are shown in the diagram:

1. The client or server uses the getCQEvent() and pollCQEvent() methods to retrieve the event oftype RDMA_CM_EVENT ESTABLISHED from the event queue channel, which triggers processing.

2. Work completion is processed.3. An acknowledgment is sent to the completion queue to confirm work completion.4. A request is made for a completion queue notification to ensure that the completion queue received

the acknowledgement.


Programming tips for the verbs interface (Linux only)Developing applications that use the jVerbs verbs interface is a complex process. Some tips and bestpractices are provided to assist developers.

Creating a stateful verbs method (SVM) object

Stateful operations avoid the performance impact of passing complex structures through the Java NativeInterface (JNI) for fast-path data operations such as postSend() or postReceive(). You create thestateful method object only once but you can use the object multiple times. For example, you can sendthe same data again or receive data on the same buffers. The SVM object allocates direct byte buffers tohold the parameters that must be passed through the JNI. When an SVM object is no longer needed, youmust free the SVM object by using the free() method so that the buffer can be marked for garbagecollection. To find out whether the last operation was successful, use the IsSuccess() method.

Sharing completion queues

When completion queues are shared among multiple connection IDs, make sure that the completionqueue entry is large enough for all send and receive operations. The limit is set by passing an argumentwhen you create the queue by using the createCompletionQueue() method. If there are too manycompletion entries, an IOException exception occurs when the device limit is reached, and theremaining completions are missed.


The WorkCompletion.getQueuePairNum() method uniquely identifies the queue pair number thatthe work completion entry belongs to. Therefore, the work completion event can be dispatched to thecorresponding connection ID to proceed with the operation.

Requesting notification

You must call the CompletionQueue.requestNotifyCQ() method to notify the application threadwhen the completion queue is waiting for a CompletionChannel.getCQEvent() call. If you do notrequest notification by using the CompletionQueue.requestNotifyCQ() method, a notification is notsent when a completion event is received on the completion queue. However, completion events areplaced on the completion queue, which you can poll by using the pollCQ() method.

When a notification is received from a getCQEvent() method, you must call the requestNotifyCQ()method again for the next getCQEvent() method. You cannot call theCompletionQueue.requestNotifyCQ() method multiple times to queue requests; only onenotification request is registered for the next getCQEvent() method.

The CompletionQueue.requestNotifyCQ() method accepts a Boolean data type that determineswhether a notification is required on completion in the completion queue for solicited events, or for allevents. If you want to mark an event as solicited, you can set the IBV_SEND_SOLICITED flag in the workrequest.

Creating queue pairs

A queue pair is required for posting send and receive requests. When you create a new queue pair, youmust consider other active queue pairs that exist on the system. Choose a queue pair size that fits thenumber of work requests that are posted for send or receive at any point in time. Exceeding the devicelimit for a queue pair causes an IOException exception. Although you can set a queue pair size whenthe queue pair is created, the system can choose a more appropriate size that is based on existing queuepairs and available resource. To determine the actual size of a queue pair after creation, use theQueuePair.getQueuePairLimit() method.

Posting send or receive buffers

RDMA operations are asynchronous. Posting a send or receive buffer does not mean that the work isactually sent or received. The client or server that posted the send or receive buffer should wait for workcompletion to determine whether the send or receive operation was successful. You can query workcompletion status by using the WorkCompletion.getStatus() method to determine success orfailure. You can also use the WorkCompletion.getOpcode() method to check for send or receiveoperation completion. If the work is complete, you can reuse the send or receive buffer. If the postedoperation is not complete, reusing the same registered buffer can lead to a crash or memory corruption.

Buffers must be in place before you connect from the client side, and before you accept on the serverside, to avoid missing any data transfer when the connection is established. The buffer position is notaltered when data is received because the RDMA operation pins the buffer and copies the content. Theapplication must handle changing the buffer position by determining the number of bytes that werewritten. Use the WorkCompletion.getByteLength() method to retrieve information about thenumber of bytes that were successfully sent or received. This data is applicable only when the completionstatus is successful.

Using the PollCQEvent() and getCQEvent() methods

The getCQEvent() method notifies the calling code when an event is received on the channel on whichthe method is called. You must call the PollCQEvent() method to retrieve the event from the channel.By pairing a getCQEvent() method with a pollCQEvent() method, you can check that an event isreceived then retrieve that event. Alternatively, you can use the pollCQEvent() method independentlybecause a poll count of zero is returned if there is no event to retrieve. However, unlike thegetCQEvent() method, the pollCQEvent() method occupies the processor, and uses processorcycles. Applications can choose to use the getCQEvent() and pollCQEvent() methods together, orjust the pollCQEvent() method.


Removing resources

Destroying or removing resources must be carried out in a particular order to avoid any exceptions. Forexample:

• When you are ready to end communication, either the server or the client must initiate disconnection.Disconnection flushes out any outstanding events or requests before resources are removed.Disconnection generates an event of type RDMA_CM_EVENT_DISCONNECTED, which is sent to the otherside of the connection. That side must then initiate removal of its resources. You do not have to call thedisconnect() method again.

• Before you remove a connection ID, you must remove the associated queue pair by using thedestroyQueuePair() method.

• A completion queue must be removed before a completion channel.• A completion channel cannot be removed without an acknowledgment for all completion queuenotification requests. Therefore, each successful getCQEvent() call must be paired with anackCQEvent() call.

• An event channel cannot be removed without an acknowledgment for all connection requests.Therefore, each successful getConnectionEvent() call must be paired with anackConnectionEvent() call.


Classes and methods for the verbs interface (Linux only)

The following diagram illustrates the classes and methods that are involved in creating an RDMAconnection by using the verbs interface. C and E indicate the type of the class or method. C signifies aClass type, and E signifies an Enum (enumeration) type.


For more information about these classes and methods, see the jVerbs API reference.


Implementing server and client communications with the endpoint interface (Linux only)If you develop applications that use the endpoint interface, fewer steps are required for Remote DirectMemory Access (RDMA) connections between server and client than an equivalent process that uses theverbs interface. An example is provided to guide developers through the process on both the server andclient sides of the connection.

The endpoint API is simpler than the verbs API. You can create an endpoint and a connection in asimilar way to TCP socket communications, by using bind, connect, and disconnect operations. However,after they are connected, endpoints register memory, post send and receive requests, and unregistermemory in a similar way to RDMA connection IDs.

Endpoints belong to an endpoint group; endpoint groups contain endpoints that share common propertiesor infrastructure. For example, basic endpoint groups can define the following processes:Connection management

Common event processing and dispatching for endpoints.


RDMA resourcesCommon associations between RDMA resources, such as queue pairs and completion queues.

RDMA operationsCommon requirements for how RDMA resources are used.

You must choose the type of group that meets the requirement for an application. Alternatively you cancustomize and extend a group to meet specific requirements.

An extension of the basic endpoint group is defined by the RdmaActiveEndpointGroup class. Theactive endpoint group creates the following threads:

• A thread for processing connection management events on an event channel• A thread for processing completion events on a completion channel

An endpoint group shares the same completion queue, which can hold up to 500 work completion events.If the limit is reached, accepting new connections or creating new endpoints in the endpoint group resultsin an IOException exception.

The following diagram shows an example of a server and client implementation that uses the endpointAPI.

The following sections provide an explanation of the server and client implementation that is illustrated inthe diagram.

Server flow

The following steps take place on the server side to implement the RDMA communication flow by usingthe RdmaActiveEndpointGroup() method:


1. The RDMA endpoint group is created by using the RdmaActiveEndpointGroup() method.2. The RDMA server endpoint is created by using theRdmaActiveEndpointGroup.createServerEndpoint() method.

3. A bind takes place.4. The connection is accepted.5. For each client request, the following steps take place:

• The client RDMA endpoint connection is opened.• A send or receive work request is posted. The completion of the post is notified to an endpoint by

calling the dispatchCQEvent() method.• The connection with the client RDMA endpoint is closed.

6. The RDMA server endpoint is closed.7. The RDMA endpoint group is closed.

Client flow

The following steps take place on the client side to implement the RDMA communication flow:

1. The RDMA endpoint group is created by using the RdmaActiveEndpointGroup() method.2. The RDMA client endpoint is created by using theRdmaActiveEndpointGroup.createEndpoint() method.

3. A connect request is made to the server.4. A send or receive work request is posted.5. The RDMA client endpoint is closed.6. The RDMA endpoint group is closed.


Extending the RdmaActiveEndpoint class to add customized steps (Linux only)You can extend the RdmaActiveEndpoint class to provide custom implementations for client andserver communications, which allows you to perform additional steps on either side of the connection.

If you want to provide a custom implementation for the abstract method dispatchCQEvent(), you canextend the RdmaActiveEndpoint class for both the server and client. For example:dispatchCQEvent()

Use this method for any processing after a completion event is received for a posted request, such asnotifying an endpoint that a post is completed.

To create a customized endpoint, you must extend the RdmaEndpointFactory class by overriding thecreateEndpoint() method in that class.

Related information“jVerbs problem determination (Linux only)” on page 249


You use the jVerbs API to develop Java applications that use high-speed network infrastructures such asInfiniBand. To investigate jVerbs problems, you can run trace or review the list of common problems. Thissection also contains a list of exceptions and messages that you might encounter.

Classes and methods for the endpoint interface (Linux only)

The following diagram illustrates the classes and methods that are involved in creating RDMAcommunications by using the endpoint interface. C and I indicate the type of the class or method. Csignifies a Class type, and I signifies an Interface type.

For more information about these classes and methods, see the jVerbs API reference.


jVerbs problem determination (Linux only)You use the jVerbs API to develop Java applications that use high-speed network infrastructures such asInfiniBand. To investigate jVerbs problems, you can run trace or review the list of common problems. Thissection also contains a list of exceptions and messages that you might encounter.Related information“jVerbs problem determination (Linux only)” on page 249You use the jVerbs API to develop Java applications that use high-speed network infrastructures such asInfiniBand. To investigate jVerbs problems, you can run trace or review the list of common problems. Thissection also contains a list of exceptions and messages that you might encounter.

jVerbs trace options (Linux only)You can trace jVerbs runtime calls down to the native level by using the standard trace options, includingsending the trace output to a file.

A native implementation of the jVerbs interface is provided. Each Java call from your application makes anative call to the rdmacm or ibverbs libraries, to do remote direct memory access (RDMA) operations byusing the Java Native Interface (JNI). The Java calls are routed to the native layer by internal, nativedispatcher classes.

You can trace Java method calls and native method calls.


Tracing Java method calls

The jVerbs interface contains the following Java packages:com.ibm.net.rdma.jverbs.cm

Connection management classes that access the rdmacm library.com.ibm.net.rdma.jverbs.verbs

Verbs classes that access the ibverbs library.com.ibm.net.rdma.jverbs.endpoints

An endpoint abstraction class that uses classes from the cm and verbs packages.You can trace the classes in these packages by using the standard -Xtrace option on the Java commandline. For example, to trace all jVerbs Java methods, use the following command-line option:

-Xtrace:methods={com.ibm.net.rdma.jverbs.*},print=mt

Use a more specific pattern to trace classes at the level that you require. For example, to trace methodsfrom all connection management native classes, use the following command-line option:

-Xtrace:methods={com.ibm.net.rdma.jverbs.cm.Native*},print=mt

Tracing native method calls

Use the JVERBS trace point component to trace native method calls within the runtime environment. Youcan trace native method entry, parameters, normal exit, and abnormal exit with error numbers. Forexample:

-Xtrace:print=JVERBS

This command-line option produces output similar to the following text:

06:22:48.672 0x21b21100 JVERBS.4 > NativeRdmaCM_createEventChannel()06:22:48.674 0x21b21100 JVERBS.5 < NativeRdmaCM_createEventChannel(channel->fd=41, channel=00007F9A643427A0) event channel created06:22:48.675 0x21b21100 JVERBS.7 > NativeRdmaCM_createId(channel->fd=41, rdma_ps=262)06:22:48.675 0x21b21100 JVERBS.8 - NativeRdmaCM_createId(channel=00007F9A643427A0, rdma_ps=262) Calling rdma_create_id06:22:48.675 0x21b21100 JVERBS.9 < NativeRdmaCM_createId(listen_id=00007F9A6433CB20) listen id created06:22:48.685 0x21b21100 JVERBS.18 > NativeRdmaCM_bindAddr(id=00007F9A6433CB20, address=00007F9A643415E0)06:22:48.685 0x21b21100 JVERBS.19 - NativeRdmaCM_bindAddr(cm_listen_id=00007F9A6433CB20) Calling rdma_bind_addr06:22:48.685 0x21b21100 JVERBS.20 < NativeRdmaCM_bindAddr() Passed06:22:48.685 0x21b21100 JVERBS.23 > NativeRdmaCM_listen(id=1681115936, backlog=10)06:22:48.685 0x21b21100 JVERBS.24 - NativeRdmaCM_listen(cm_listen_id=00007F9A6433CB20) Calling rdma_listen06:22:48.685 0x21b21100 JVERBS.25 < NativeRdmaCM_listen() Passed06:22:48.685 0x21b21100 JVERBS.38 > NativeRdmaCM_getCmEvent(channel=41, event=00007F9A643414D0, listen_id=00007F9A643414D4, client_id=00007F9A643414DC)06:22:48.685 0x21b21100 JVERBS.39 - NativeRdmaCM_getCmEvent(cm_channel=00007F9A643427A0) Calling rdma_get_cm_event06:23:32.329 0x21b21100 JVERBS.40 < NativeRdmaCM_getCmEvent(_event=4, _client_id=00007F9A64342930, _listen_id=00007F9A6433CB20, cm_event->id->verbs->cmd_fd=39, cm_event->id->verbs=00007F9A6433D090, cm_event=00007F9A643427C0) Passed06:23:32.330 0x21b21100 JVERBS.92 > NativeRdmaCM_getContext(id=00007F9A6433CB20)06:23:32.330 0x21b21100 JVERBS.93 - NativeRdmaCM_getContext(cm_listen_id=00007F9A6433CB20)06:23:32.330 0x21b21100 JVERBS.94 < NativeRdmaCM_getContext(context=00007F9A6433D090, context->cmd_fd=39) Passed

You can combine Java and native method tracing as shown by the following example:

-Xtrace:methods={com.ibm.net.rdma.jverbs.*},print=mt,print=JVERBS


For more information about tracing, trace components, and trace points, see the following topics:

• -Xtrace in the OpenJ9 user documentation• Determining the tracepoint ID of a trace point in the J9 VM reference


jVerbs exceptions (Linux only)The jVerbs interface can produce IOException and IllegalArgumentException exceptions.

An IOException exception is thrown when there is a failure in the native code, or when a device limit forresource creation is exceeded. If you enable trace, you can see error numbers that are associated withnative calls in the trace output. This output can help you to identify the cause of the failure. For example,the following output shows an error number of 98 and an IOException, in this case caused by anothersocket being bound to the same port:

06:37:58.023 0x2208b100 JVERBS.7 > NativeRdmaCM_createId(channel->fd=41, rdma_ps=262)06:37:58.023 0x2208b100 JVERBS.8 - NativeRdmaCM_createId(channel=00007EFFD8258BC0, rdma_ps=262) Calling rdma_create_id06:37:58.023 0x2208b100 JVERBS.9 < NativeRdmaCM_createId(listen_id=00007EFFD833C090) listen id created06:37:58.034 0x2208b100 JVERBS.18 > NativeRdmaCM_bindAddr(id=00007EFFD833C090, address=00007EFFD8340B50)06:37:58.034 0x2208b100 JVERBS.19 - NativeRdmaCM_bindAddr(cm_listen_id=00007EFFD833C090) Calling rdma_bind_addr06:37:58.034 0x2208b100 JVERBS.21 < NativeRdmaCM_bindAddr(errno=98) rdma_bind_addr FailedException in thread "main" java.io.IOException: Binding socket address failed at com.ibm.net.rdma.jverbs.cm.NativeRdmaCM.bindAddress(NativeRdmaCM.java:190) at com.ibm.net.rdma.jverbs.cm.ConnectionId.bindAddress(ConnectionId.java:124)

An IllegalArgumentException exception is thrown when the parameter that you passed is notexpected. For example, this exception is thrown when the port space is not a supported type. The jVerbsinterface supports only the TCP port space, so parameters other than PortSpace.RDMA_PS_TCP resultin an exception, as follows:

Exception in thread "main" java.lang.IllegalArgumentException: Unsupported RDMA port space at com.ibm.net.rdma.jverbs.cm.NativeRdmaCM.createConnectionId(NativeRdmaCM.java:71) at com.ibm.net.rdma.jverbs.cm.ConnectionId.create(ConnectionId.java:262) at tests.com.ibm.jtc.rdma.jverbs.zurich.JVerbsSendRecvServer.run(JVerbsSendRecvServer.java:38) at tests.com.ibm.jtc.rdma.jverbs.zurich.JVerbsSendRecvServer.launch(JVerbsSendRecvServer.java:281) at tests.com.ibm.jtc.rdma.jverbs.zurich.JVerbsSendRecvServer.main(JVerbsSendRecvServer.java:286)


Common jVerbs problems (Linux only)You use the jVerbs interface to develop Java applications that use high-speed network infrastructuressuch as InfiniBand. You might see the following problems when you are using the jVerbs interface.

• “Connection event RDMA_CM_EVENT_REJECTED generated while trying to connect” on page 252• “Queue pair error with operation code IBV_WC_WR_FLUSH_ERR” on page 252• “Work completion event received with operation code IBV_WC_RETRY_EXC_ERR” on page 252• “Native OutOfMemory exception occurred” on page 252• “Memory corruption” on page 252• “getConnectionEvent(-1) or getCompletionEvent(-1) methods block forever” on page 252


Connection event RDMA_CM_EVENT_REJECTED generated while trying to connectThis event is generated on the client when there is no server running, or when the server is busy doingother processing.

To avoid this issue, ensure that the server is running on the intended port. You should also write yourapplication to try connecting again if a failure occurs.

Queue pair error with operation code IBV_WC_WR_FLUSH_ERRIf the send and receive buffer sizes do not match, a send or receive request can result in a queue pairerror that cannot be recovered. You can add steps to the communication process to avoid this problem.

This problem can occur if the size of the receive buffer does not match the size of the send buffer. Thesend operation fails with the operation code IBV_WC_LOC_LEN_ERR on the receiver side andIBV_WC_REM_INV_REQ_ERR on the sender side. Such an error causes the queue pair to move to an errorstate and further send or receive requests result in the operation code IBV_WC_WR_FLUSH_ERR. Thequeue pair cannot be recovered.

To avoid this problem, ensure that the length of the posted receive buffer is large enough to hold the sendrequest. If the length is not known, you can program your application to communicate the required lengthbefore the send. On the other side, a buffer can be prepared with the appropriate size to receive.

Work completion event received with operation code IBV_WC_RETRY_EXC_ERRThe client or server did not respond to a posted request (either send or receive).

This issue is common when one side completes a send request but the receive buffer is not yet posted. Inthis situation, the sending side receives this work completion event.

To avoid this issue, ensure that the buffer is posted for receiving data before the data is sent. If you aresending data multiple times, ensure that the receiving side posts enough buffers to hold all the parallelsend requests.

Native OutOfMemory exception occurredThe jVerbs interface uses direct byte buffers for transferring data, and internally for stateful verbs methodoperations and for passing complex data structures to native code. You might therefore receive nativeOutOfMemory exceptions on computers that do not meet the memory requirements of your application.

One of the following solutions might help you to avoid this issue:

• Mark the used buffer as eligible for garbage collection by using the DBB.cleaner().clean() method.• Consider reusing buffers if they are no longer in use, for example by a post that is not yet complete.• Use the -XX:MaxDirectMemorySize=<size> command-line option to trigger garbage collection

when the memory allocation reaches the specified size.• Create a stateful verb method once, then call it multiple times, if the parameters are same. After you

call the method, use the free() method of the StatefulVerbMethod object to mark the memorythat was allocated as eligible for garbage collection.

Memory corruptionMemory corruption is possible if a buffer is used for a different operation while remote reading, writing, orreceiving is in progress using that buffer.

Ensure that a completion event is received for the operation that is posted for the buffer before you reusethe buffer.

getConnectionEvent(-1) or getCompletionEvent(-1) methods block foreverIf you pass -1 as a parameter to the getConnectionEvent(int timeout) orgetCompletionEvent(int timeout) event methods, to indicate no timeout, the methods blockforever even if the channel on which they are waiting for an event is destroyed.

This issue is a known problem with the underlying OFED implementation. To avoid this issue, use thesemethods with the -1 parameter only when you know that an event will be received. Alternatively, specify atimeout value or use the pollCQEvent() method.



Shared Memory Communications via Remote Direct Memory Access (z/OSonly)

You can improve the performance of communication flow between peers by configuring Shared MemoryCommunications via Remote Direct Memory Access (SMC-R) on your SMC-R enabled environment. Virtualservers that support RDMA over Converged Ethernet (RoCE) can dynamically and transparently switchfrom TCP network flows to more optimized direct memory access flows that use RDMA.

Before you beginYour system must meet the following hardware and software requirements:

• IBM zEnterprise EC12 or later, with one or more IBM Z RoCE adapters• 10GbE RoCE Express feature

About this taskSMC-R is a protocol solution that is based on sockets over RDMA. SMC-R enables TCP socketsapplications to transparently use RDMA, which enables direct, high-speed, low-latency, memory-to-memory (peer-to-peer) communications. You do not need to change any Java settings to enable SMC-Ron z/OS. However, you must complete certain configuration tasks on your SMC-R enabled environment.

Procedure

SMC-R is enabled by specifying one or more Peripheral Component Interconnect Express (PCIe) functionID (PFID) values on the SMCR parameter of the GLOBALCONFIG statement in the TCP/IP profile data set.For more information about these configuration steps, see z/OS Communication Server IP ConfigurationGuide, V2.1 and z/OS Communication Server IP Configuration Reference, V2.1 in the z/OS productdocumentation.

ResultsIf your system meets the requirements, and is correctly configured, TCP network flows take advantage ofthe available direct memory flows. This seamless transfer improves the speed of communication for yourTCP sockets applications.


https://www.ibm.com/support/knowledgecenter/SSLTBW_2.1.0/com.ibm.zos.v2r1.halz002/toc.htm



Chapter 12. Java Plug-in, Applet Viewer, and WebStart (AIX, Linux, and Windows only)

The Java plug-in is used to run Java applications in the browser. The appletviewer is used to testapplications designed to be run in a browser. Java Web Start is used to deploy desktop Java applicationsover a network, and provides a mechanism for keeping them up-to-date. Note: Java Plug-in and WebStart are available only on AIX, Linux, and Windows systems, not on z/OS.

Using the Java plug-in (AIX, Linux 32-bit, and Windows only)The Java plug-in is a web browser plug-in that you use to run applets in a browser on AIX, Linux (32-bitonly), and Windows systems.

Note: The following Java plug-in capabilities are not supported for Windows on the AMD64 architecture:

• Java Kernel• JQS• DeployTK• Patch in Place• Online installer• Java auto download• Java auto update

Allow enough time for applets to finish loading, otherwise your browser might seem to stop. For example,if you click Back and then click Forward while an applet is loading, the HTML pages might be unable toload.

For more information about the Java plug-in, see: https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/applet_dev_guide.html.

Note: The Classic plug-in, sometimes referred to as the First-generation plug-in, was deprecated in IBMSDK, Java Technology Edition, Version 7. This plug-in is not supported in this release. Instead, use theNext-generation plug-in to run applets in the browser.

Supported browsers for the Java plug-in (AIX, Linux, and Windows only)The Java plug-in supports Mozilla Firefox and also Internet Explorer on Windows systems.

Table 16. Browsers supported by the Java plug-in on Windowssystems

Browser Supported versions

Internet Explorer 7.0, 8.0, 9.0, 10.0

Firefox 3.6, 4.0, 5.0, 6.0, and later releases

Note: Internet Explorer V10.0 is the default browser on Windows 8 classic edition.

Later minor releases of these browsers are also supported.

Table 17. Browsers supported by the Java plug-in on Linux IA32 systems

Browser Supported versions

Firefox 3.6, 4.0, 5.0, 6.0, and later releases

Later minor releases of these browsers are also supported.


https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/applet_dev_guide.html

https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/applet_dev_guide.html

Table 18. Browsers supported by the Java plug-in on 64-bit AIX systems

Browser Supported Versions

Firefox 3.6.25.2. Available at https://www.ibm.com/marketing/iwm/iwm/web/pickUrxNew.do?source=firefox.

Related informationAIX Firefox Browser unsupported on many HTTPS sites

Installing the Java plug-in by using the Java control panel on WindowsOn Windows systems, you can use the Java control panel to install the Java plug-in for Internet Explorerand Mozilla Firefox.

Before you beginThe IBM SDK for Java must be installed before using this method.

About this taskIf the Java plug-in was not installed when the SDK was installed, follow these steps to install the plug-in,using the Java control panel:

Procedure

1. Open the Windows Control Panel.2. Double-click IBM Control Panel for Java.3. On the Advanced tab, select Default Java for Browsers.4. To install the Java plug-in for specific browsers, select the corresponding check box. To remove the

Java plug-in from specific browsers, clear the corresponding check box. On Windows 7, the check boxto associate with Internet Explorer is disabled by default. You cannot change this selection. By default,the Next-Generation plug-in is enabled. If you want to switch between a Next-Generation and a First-Generation, or Classic plug-in, follow these steps:a) Open the IBM Control Panel for Java.b) On the Advanced tab, select Java Plug-in. Select or clearEnable the next-generation Java Plug-

in. This action changes the association between old style and Next-Generation plug-ins.

What to do next

Note: The Classic plug-in, sometimes referred to as the First-generation plug-in, was deprecated in Java7. This plug-in is not supported in this release. Instead, use the Next-generation plug-in to run applets inthe browser.

Installing the Java plug-in on AIX and LinuxTo install the Java plug-in on AIX and Linux systems, symbolically link it to the plug-in directory for yourbrowser.

The Java plug-in is based on the Mozilla Open JVM Integration initiative, which is used with most Mozillaproducts and derivatives, including Firefox.

You must symbolically link the plug-in, rather than copy it, so that the browser and plug-in can locate theJVM.

Complete these steps to make the Java plug-in available to Mozilla Firefox users:

1. Log in as root user.2. Change to the Firefox plug-in directory.

cd /usr/local/mozilla-firefox/plugins/


https://www.ibm.com/marketing/iwm/iwm/web/pickUrxNew.do?source=firefox

https://www.ibm.com/marketing/iwm/iwm/web/pickUrxNew.do?source=firefox


https://www-archive.mozilla.org/oji/

Note: The directory name is different for different Linux distributions.3. Create a symbolic link to the plug-in. For Firefox 3.x, use the command:

ln -s /opt/ibm/java-<arch>-80/jre/lib/<arch>/libnpjp2.so .

Making the Java plug-in available to Firefox users (Linux only)Use this procedure on Linux systems to make the Java plug-in available to Mozilla Firefox users. You mustsymbolically link the plug-in, rather than copy it, so that it can locate the JVM.

Procedure

1. Log in as root.2. Change to your Firefox plug-ins directory (which differs, depending on the Linux distributions).

cd /usr/local/mozilla-firefox/plugins/

3. Create a symbolic link to the plug-in.To link with a First-generation, or Classic plug-in:

ln -s install_dir/jre/plugin/<arch>/ns7/libjavaplugin_oji.so .

To link with a Next-Generation plug-in, which is available only with IA32:

ln -s install_dir/jre/lib/<arch>/libnpjp2.so .

where <arch> is the architecture of your system.

Changing the properties of the Java Plug-in (AIX only)On AIX systems, you can change the properties of the Java Plug-in from the control panel, which can berun as a stand-alone Java application.

Procedure

To start this Java application, run the following script:

install_dir/bin/ControlPanel

Java plug-in environment variables (AIX and Linux only)On AIX and Linux, environment variables are available to configure the Java plug-in.

On AIX, to configure the path to the Java plug-in, use the following environment variable:

PLUGIN_HOME=<path>

where <path> is the full directory path to the Java plug-in.

On Linux systems, to specify the version of Mozilla to use for the Java plug-in, set the followingenvironment variable:

JAVA_PLUGIN_AGENT=<version>

Where <version> is the Mozilla version on your system.

Common Document Object Model (DOM) support (AIX, Linux, and Windows only)Because of limitations in particular browsers, you might not be able to implement all the functions of theorg.w3c.dom.html package.

One of the following errors is thrown:

• sun.plugin.dom.exception.InvalidStateException• sun.plugin.dom.exception.NotSupportedException

Chapter 12. Java Plug-in, Applet Viewer, and Web Start (AIX, Linux, and Windows only) 257

Using DBCS parameters (AIX, Linux, and Windows only)The Java plug-in supports double-byte characters (for example, Chinese Traditional BIG-5, Korean, andJapanese) as parameters for the tags <APPLET>, <OBJECT>, and <EMBED>. You must select the correctcharacter encoding for your HTML document so that the Java plug-in can parse the parameter.

About this task

Specify character encoding for your HTML document by using the <META> tag in the <HEAD> section likethis:

<meta http-equiv="Content-Type" content="text/html; charset=big5">

This example tells the browser to use the Chinese BIG-5 character encoding to parse the HTML file.

Working with applets (AIX, Linux, and Windows only)With the Applet Viewer, you can run one or more applets that are called by reference in a web page (HTMLfile) by using the <APPLET> tag. The Applet Viewer finds the <APPLET> tags in the HTML file and runs theapplets, 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 manyHTML tags. It parses only the <APPLET> tags and no other HTML on the web page.

Running and debugging applets with the Applet Viewer (AIX, Linux, and Windows only)Use the following commands to run and debug an applet with the Applet Viewer.

Procedure

• To run an applet with the Applet Viewer, enter the following command: appletviewer <name>,where <name> is one of the following options:

– The file name of an HTML file that calls an applet– The URL of a web page that calls an applet

For example, to start the Applet Viewer on an HTML file that calls an applet:

On AIX and Linux systems, type at a shell prompt:

appletviewer $HOME/<filename>.html

where filename is the name of the HTML file.

On Windows systems, type at a shell or command prompt:

appletviewer <demo>\GraphLayout\example1.html

where <demo> is the full path into which you extracted the compressed demo package.• To start the Applet Viewer on a web page, type at a shell or command prompt:

appletviewer http://mywebpage.com/demo/applets/MyApplet/example1.html

The Applet Viewer does not recognize the charset option of the <META> tag. If the file that theApplet Viewer loads is not encoded as the system default, an I/O exception might occur. To avoid theexception, use the -encoding option when you run appletviewer. For example:

appletviewer -encoding JISAutoDetect sample.html

• To debug an applet with the Applet Viewer, use the debug parameter with the appletviewercommand.For example:


>cd demo\applets\TicTacToe..\..\..\bin\appletviewer -debug example1.html

Unique CLSIDs (Windows only)A unique set of CLSIDs have been added to the IBM JVM from Version 7.

The CLSIDs that have been added are as follows:

1ACECAFE-0016-0000-0000-ABCDEFFEDCBA1ACECAFE-0016-0000-0000-ABCDEFFEDCBB1ACECAFE-0016-0000-0000-ABCDEFFEDCBC

You can refer to these CLSIDs in the OBJECT tag for your applet.

In addition, the following existing CLSIDs are also supported for compatibility purposes:

CAFEEFAC-0016-0000-0000-ABCDEFFEDCBACAFEEFAC-0016-0000-0000-ABCDEFFEDCBBCAFEEFAC-0016-0000-0000-ABCDEFFEDCBC

Java Applet Viewer and the classpath (AIX only)On AIX systems, if you use the Applet Viewer to run an applet that is in CLASSPATH, you might get anAccessControlException in Swing. Because CLASSPATH implicitly contains the current directory, ".",this exception might occur if you run the Java Plug-in in the same directory that the applet class itself isin.

To work around this problem, ensure that:

• No CLASSPATH references exist to the applet that you are attempting to run in the Java Plug-in or theappletviewer.

• You are not running the applet from the same directory that the class is in.

Using Web Start (AIX, Linux, and Windows only)Java Web Start is used for Java application deployment. Web Start can be used on AIX, Linux (IA 32-bit,PPC32, and PPC64), and Windows systems.

With Web Start, you can start and manage applications directly from the web. Applications are cached tominimize installation times. Applications are automatically upgraded when new versions becomeavailable.

Web Start supports these command-line arguments documented at https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/developersguide/syntax.html#resources:

• -verbose• -version• -showversion• -help• -X• -ea• -enableassertions• -da• -disableassertions• -esa• -enablesystemassertions

Chapter 12. Java Plug-in, Applet Viewer, and Web Start (AIX, Linux, and Windows only) 259

https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/developersguide/syntax.html#resources

https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/developersguide/syntax.html#resources

• -dsa• -disablesystemassertions• -Xint• -Xnoclassgc• -Xdebug• -Xfuture• -Xrs• -Xms• -Xmx• -Xss

Web Start also supports -Xgcpolicy to set the garbage collection policy.

The Autodownload option in the Java Control Panel is set to Always by default. This option enables a userwithout administration privileges to download the runtime environment from the location specified in theJNLP file.

For more information about Web Start, see:

• https://www.oracle.com/technetwork/java/javase/tech/index-jsp-136112.html• https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/index.html

For more information about deploying applications, see:

• https://docs.oracle.com/javase/8/docs/technotes/guides/jweb/index.html

Running Web Start (AIX, Linux, and Windows only)Web Start can be run from a web page or the command line. Web Start applications are stored in the JavaApplication Cache. Web Start can be used on AIX, Linux (IA 32-bit, PPC32, and PPC64), and Windowssystems.

Procedure

You can start Web Start in a number of different ways.• Select a link on a Web page that refers to a .jnlp file.

If your browser does not have the correct association to run Web Start applications, select theinstall_dir/jre/bin/javaws command from the Open/Save window to start the Web Startapplication.

• At a shell or command prompt, type:

javaws <URL>

Where <URL> is the location of a .jnlp file.• If you have used Java Web Start to open the application in the past, use the Java Application Cache

Viewer.At a shell or command prompt, type:

install_dir/jre/bin/javaws -viewer

All Java Web Start applications are stored in the Java Application Cache. An application is downloadedonly if the latest version is not in the cache.



https://docs.oracle.com/javase/8/docs/technotes/guides/javaws/index.html

https://docs.oracle.com/javase/8/docs/technotes/guides/jweb/index.html

Chapter 13. Using XMLThe IBM SDK contains the XML4J and XL XP-J parsers, the XL TXE-J 1.0 XSLT compiler, and the XSLT4JXSLT interpreter. These tools allow you to parse, validate, transform, and serialize XML documentsindependently from any given XML processing implementation.

Use factory finders to locate implementations of the abstract factory classes, as described in “Selectingan XML processor” on page 261. By using factory finders, you can select a different XML library withoutchanging your Java code.

Available XML libraries

The IBM SDK contains the following XML libraries:

XML4J 4.5

XML4J is a validating parser providing support for the following standards:

• XML 1.0 (4th edition)• Namespaces in XML 1.0 (2nd edition)• XML 1.1 (2nd edition)• Namespaces in XML 1.1 (2nd edition)• W3C XML Schema 1.0 (2nd Edition)• XInclude 1.0 (2nd Edition)• OASIS XML Catalogs 1.0• SAX 2.0.2• DOM Level 3 Core, Load and Save• DOM Level 2 Core, Events, Traversal and Range• JAXP 1.6

XML4J 4.5 is based on Apache Xerces-J 2.9.0. See http://xerces.apache.org/xerces2-j/ for moreinformation.

XL XP-J 1.1

XL XP-J 1.1 is a high-performance non-validating parser that provides support for StAX 1.0 (JSR 173).StAX is a bidirectional API for pull-parsing and streaming serialization of XML 1.0 and XML 1.1documents. See the “XL XP-J reference information” on page 265 section for more details about whatis supported by XL XP-J 1.1.

XL TXE-J 1.0

For Version 6 and later, the IBM SDK for Java includes XL TXE-J. XL TXE-J includes the XSLT4J 2.7.8interpreter and a new XSLT compiler. The new compiler is used by default. The XSLT4J compiler is nolonger included with the IBM SDK for Java. See “Migrating to the XL-TXE-J” on page 263 forinformation about migrating to XL TXE-J.

XL TXE-J provides support for the following standards:

• XSLT 1.0• XPath 1.0• JAXP 1.6

Selecting an XML processor

XML processor selection is performed using service providers. When using a factory finder, Java looks inthe following places, in this order, to see which service provider to use:


http://xerces.apache.org/xerces2-j/

1. The system property with the same name as the service provider.2. The service provider specified in a properties file.

• For XMLEventFactory, XMLInputFactory, and XMLOutputFactory only. The value of theservice provider in the following file:

– AIX: /etc/java8[_64]/jre/lib/stax.properties– Linux: /opt/ibm/java-<arch>-80/jre/lib/stax.properties– Windows: C:\Program Files\IBM\Java80\jre\lib\stax.properties– z/OS: /usr/lpp/java/J8.0[_64]/jre/lib/stax.properties

.• For other factories. The value of the service provider in the following file:

– AIX: /etc/java8[_64]/jre/lib/jaxp.properties– Linux: /opt/ibm/java-<arch>-80/jre/lib/jaxp.properties– Windows: C:\Program Files\IBM\Java80\jre\lib\jaxp.properties– z/OS: /usr/lpp/java/J8.0[_64]/jre/lib/jaxp.properties

3. The contents of the META-INF/services/<service.provider> file.4. The default service provider.

The following service providers control the XML processing libraries used by Java:javax.xml.parsers.SAXParserFactory

Selects the SAX parser. By default, org.apache.xerces.jaxp.SAXParserFactoryImpl from theXML4J library is used.

javax.xml.parsers.DocumentBuilderFactorySelects the document builder. By default,org.apache.xerces.jaxp.DocumentBuilderFactoryImpl from the XML4J library is used.

javax.xml.datatype.DatatypeFactorySelects the datatype factory. By default,org.apache.xerces.jaxp.datatype.DatatypeFactoryImpl from the XML4J library is used.

javax.xml.stream.XMLEventFactorySelects the StAX event factory. By default,com.ibm.xml.xlxp.api.stax.XMLEventFactoryImpl from the XL XP-J library is used.

javax.xml.stream.XMLInputFactorySelects the StAX parser. By default, com.ibm.xml.xlxp.api.stax.XMLInputFactoryImpl fromthe XL XP-J library is used.

javax.xml.stream.XMLOutputFactorySelects the StAX serializer. By default, com.ibm.xml.xlxp.api.stax.XMLOutputFactoryImplfrom the XL XP-J library is used.

javax.xml.transform.TransformerFactorySelects the XSLT processor. Possible values are:com.ibm.xtq.xslt.jaxp.compiler.TransformerFactoryImpl

Use the XL TXE-J compiler. This value is the default.org.apache.xalan.processor.TransformerFactoryImpl

Use the XSLT4J interpreter.javax.xml.validation.SchemaFactory:http://www.w3.org/2001/XMLSchema

Selects the schema factory for the W3C XML Schema language. By default,org.apache.xerces.jaxp.validation.XMLSchemaFactory from the XML4J library is used.

javax.xml.xpath.XPathFactorySelects the XPath processor. By default, org.apache.xpath.jaxp.XPathFactoryImpl from theXSLT4J library is used.



Migrating to the XL-TXE-JFrom Version 6, the XL TXE-J compiler replaces the XSLT4J interpreter as the default XSLT processor. Ifyou are migrating applications from older versions of Java, follow these steps to prepare your applicationfor the new library.

About this task

The XL TXE-J compiler is faster than the XSLT4J interpreter when you are applying the sametransformation more than once. If you perform each individual transformation only once, the XL TXE-Jcompiler is slower than the XSLT4J interpreter because compilation and optimization reduceperformance.

To continue using the XSLT4J interpreter as your XSLT processor, set thejavax.xml.transform.TransformerFactory service provider toorg.apache.xalan.processor.TransformerFactoryImpl.

To migrate to the XL-TXE-J compiler, follow the instructions in this task.


Procedure

1. Use com.ibm.xtq.xslt.jaxp.compiler.TransformerFactoryImpl when setting thejavax.xml.transform.TransformerFactory service provider.

2. Regenerate class files generated by the XSLT4J compiler. XL TXE-J cannot execute class filesgenerated by the XSLT4J compiler.

3. Some methods generated by the compiler might exceed the JVM method size limit, in which case thecompiler attempts to split these methods into smaller methods.

• If the compiler splits the method successfully, you receive the following warning:

Some generated functions exceeded the JVM method size limit and wereautomatically split into smaller functions. You might get betterperformance by manually splitting very large templates into smallertemplates, by using the 'splitlimit' option to the Process or Compilecommand, or by setting the 'https://www.ibm.com/xmlns/prod/xltxe-j/split-limit' transformer factory attribute.

You can use the compiled classes, but you might get better performance by controlling the splitlimit manually.

• If the compiler does not split the method successfully, you receive one of the following exceptions:

com.ibm.xtq.bcel.generic.ClassGenException: Branch target offset too largefor short

or

bytecode array size > 65535 at offset=#####

Try setting the split limit manually, or decreasing the split limit.

To set the split limit, use the -SPLITLIMIT option when using the Process or Compile commands,or the https://www.ibm.com/xmlns/prod/xltxe-j/split-limit transformer factory attributewhen using the transformer factory. The split limit can be between 100 and 2000. When setting thesplit limit manually, use the highest split limit possible for best performance.

4. XL TXE-J might need more memory than the XSLT4J compiler. If you are running out of memory orperformance seems slow, increase the size of the heap using the -Xmx option.

Chapter 13. Using XML 263

5. Migrate your application to use the new attribute keys. The old transformer factory attribute keys aredeprecated. The old names are accepted with a warning.

Table 19. Changes to attribute keys from the XSL4J compiler to the XL TXE-J compiler

XSL4J compiler attribute XL TXE-J compiler attribute

translet-name https://www.ibm.com/xmlns/prod/xltxe-j/translet-name

destination-directory https://www.ibm.com/xmlns/prod/xltxe-j/destination-directory

package-name https://www.ibm.com/xmlns/prod/xltxe-j/package-name

jar-name https://www.ibm.com/xmlns/prod/xltxe-j/jar-name

generate-translet https://www.ibm.com/xmlns/prod/xltxe-j/generate-translet

auto-translet https://www.ibm.com/xmlns/prod/xltxe-j/auto-translet

use-classpath https://www.ibm.com/xmlns/prod/xltxe-j/use-classpath

debug https://www.ibm.com/xmlns/prod/xltxe-j/debug

indent-number https://www.ibm.com/xmlns/prod/xltxe-j/indent-number

enable-inlining Obsolete in new compiler

6. Optional: For best performance, ensure that you are not recompiling XSLT transformations that can bereused.Use one of the following methods to reuse compiled transformations:

• If your stylesheet does not change at run time, compile the stylesheet as part of your build processand put the compiled classes on your classpath. Use theorg.apache.xalan.xsltc.cmdline.Compile command to compile the stylesheet and set thehttps://www.ibm.com/xmlns/prod/xltxe-j/use-classpath transformer factory attributeto true to load the classes from the classpath.

• If your application will use the same stylesheet during multiple runs, set the https://www.ibm.com/xmlns/prod/xltxe-j/auto-translet transformer factory attribute to true toautomatically save the compiled stylesheet to disk for reuse. The compiler will use a compiledstylesheet if it is available, and compile the stylesheet if it is not available or is out-of-date. Use thehttps://www.ibm.com/xmlns/prod/xltxe-j/destination-directory transformerfactory attribute to set the directory used to store compiled stylesheets. By default, compiledstylesheets are stored in the same directory as the stylesheet.

• If your application is a long-running application that reuses the same stylesheet, use thetransformer factory to compile the stylesheet and create a Templates object. You can use theTemplates object to create Transformer objects without recompiling the stylesheet. TheTransformer objects can also be reused but are not thread-safe.

• If your application uses each stylesheet just once or a very small number of times, or you areunable to make any of the other changes listed in this step, you might want to continue to use theXSLT4J interpreter by setting the javax.xml.transform.TransformerFactory serviceprovider to org.apache.xalan.processor.TransformerFactoryImpl.


Securing Java API for XML processing (JAXP) against malformed inputIf your application takes untrusted XML, XSD or XSL files as input, you can enforce specific limits duringJAXP processing to protect your application from malformed data. If you specify limits, you must overridethe default XML parser configuration with a custom configuration.

About this task

To protect your application from malformed data, you can enforce specific limits during JAXP processing.These limits can be set in your jaxp.properties file, or by specifying various system properties on thecommand line. However, for these limits to take effect you must also override the default XML parserconfiguration with a custom configuration that allows these secure processing limits.


Procedure

1. Select the limits that you want to set for your application.

• To limit the number of entity expansions in an XML document, see “-Djdk.xml.entityExpansionLimit” on page 271.

• To limit the maximum size of a general entity, see “-Djdk.xml.maxGeneralEntitySizeLimit” on page272.

• To limit the maximum size of a parameter entity, see “-Djdk.xml.maxParameterEntitySizeLimit” onpage 273.

• To limit the length of XML names in XML documents, see “-Djdk.xml.maxXMLNameLimit”on page 274.

• To limit the total size of all entities that include general and parameter entities, see “-Djdk.xml.totalEntitySizeLimit” on page 275.

• To define the maximum number of content model nodes that can be created in a grammar, see “-Djdk.xml.maxOccur” on page 272.

• To control whether external entities are resolved in an XML document, see “-Djdk.xml.resolveExternalEntities” on page 274.

2. To override the default XML parser configuration, set the custom configuration by specifying thefollowing system property on the command line: -Dorg.apache.xerces.xni.parser.XMLParserConfiguration=config_file, where config_file isorg.apache.xerces.parsers.SecureProcessingConfiguration. For more information aboutthe full override mechanism, see http://xerces.apache.org/xerces2-j/faq-xni.html#faq-2.

XML reference informationThe XL XP-J and XL TXE-J XML libraries are new for Version 6 of the SDK. This reference informationdescribes the features supported by these libraries.

XL XP-J reference informationXL XP-J 1.1 is a high-performance non-validating parser that provides support for StAX 1.0 (JSR 173).StAX is a bidirectional API for pull-parsing and streaming serialization of XML 1.0 and XML 1.1documents.

Unsupported features

The following optional StAX features are not supported by XL XP-J:


http://xerces.apache.org/xerces2-j/faq-xni.html#faq-2

• DTD validation when using an XMLStreamReader or XMLEventReader. The XL XP-J parser is non-validating.

• When using an XMLStreamReader to read from a character stream (java.io.Reader), theLocation.getCharaterOffset() method always returns -1. TheLocation.getCharaterOffset() returns the byte offset of a Location when using anXMLStreamReader to read from a byte stream (java.io.InputStream).

XMLInputFactory reference

The javax.xml.stream.XMLInputFactory implementation supports the following properties, asdescribed in the XMLInputFactory Javadoc information: https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLInputFactory.html.

Property name Supported?

javax.xml.stream.isValidating No. The XL XP-J scanner does not support validation.

javax.xml.stream.isNamespaceAware Yes, supports true and false. For XMLStreamReaderscreated from DOMSources, namespace processingdepends on the methods that were used to create theDOM tree, and this value has no effect.

javax.xml.stream.isCoalescing Yes

javax.xml.stream.isReplacingEntityReferences

Yes. For XMLStreamReaders created fromDOMSources, if entities have already been replaced inthe DOM tree, setting this parameter has no effect.

javax.xml.stream.isSupportingExternalEntities

Yes

javax.xml.stream.supportDTD True is always supported. Setting the value to falseworks only if thecom.ibm.xml.xlxp.support.dtd.compat.modesystem property is also set to false.

When both properties are set to false, parsers createdby the factory throw an XMLStreamException whenthey encounter an entity reference that requiresexpansion. This setting is useful for protecting againstDenial of Service (DoS) attacks involving entitiesdeclared in the DTD.

javax.xml.stream.reporter Yes

javax.xml.stream.resolver Yes

XL XP-J also supports the optional methodcreateXMLStreamReader(javax.xml.transform.Source), which allows StAX readers to becreated from DOM and SAX sources.

XL XP-J also supports the javax.xml.stream.isSupportingLocationCoordinates property. Ifyou set this property to true, XMLStreamReaders created by the factory return accurate line, column,and character information using Location objects. If you set this property to false, line, column, andcharacter information is not available. By default, this property is set to false for performance reasons.

XMLStreamReader reference

The javax.xml.stream.XMLStreamReader implementation supports the following properties, asdescribed in the XMLStreamReader Javadoc: https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamReader.html.


https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLInputFactory.html

https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLInputFactory.html

https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamReader.html

https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamReader.html


javax.xml.stream.entities Yes

javax.xml.stream.notations Yes

XL XP-J also supports the javax.xml.stream.isInterning property. This property returns a booleanvalue indicating whether or not XML names and namespace URIs returned by the API calls have beeninterned by the parser. This property is read-only.

XMLOutputFactory reference

The javax.xml.stream.XMLOutputFactory implementation supports the following properties, asdescribed in the XMLOutputFactory Javadoc: https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLOutputFactory.html.


javax.xml.stream.isRepairingNamespaces Yes

XL XP-J also supports thejavax.xml.stream.XMLOutputFactory.recycleWritersOnEndDocument property. If you set thisproperty to true, XMLStreamWriters created by this factory are recycled when writeEndDocument()is called. After recycling, some XMLStreamWriter methods, such as getNamespaceContext(), mustnot be called. By default, XMLStreamWriters are recycled when close() is called. You must call theXMLStreamWriter.close() method when you have finished with an XMLStreamWriter, even if thisproperty is set to true.

XMLStreamWriter reference

The javax.xml.stream.XMLStreamWriter implementation supports the following properties, asdescribed in the XMLStreamWriter Javadoc: https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamWriter.html.


javax.xml.stream.isRepairingNamespaces Yes

Properties on XMLStreamWriter objects are read-only.

XL XP-J also supports thejavax.xml.stream.XMLStreamWriter.isSetPrefixBeforeStartElement property. Thisproperty returns a Boolean indicating whether calls to setPrefix() and setDefaultNamespace()should occur before calls to writeStartElement() or writeEmptyElement() to put a namespaceprefix in scope for that element. XL XP-J always returns false; calls to setPrefix() andsetDefaultNamespace() should occur after writeStartElement() or writeEmptyElement().



https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLOutputFactory.html

https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLOutputFactory.html

https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamWriter.html

https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamWriter.html

XL TXE-J reference informationXL TXE-J is an XSLT library containing the XSLT4J 2.7.8 interpreter and a XSLT compiler.

Feature comparison table

Table 20. Comparison of the features in the XSLT4J interpreter, the XSLT4J compiler, and the XL TXE-J compiler.

Feature

XSLT4Jinterpreter(included)

XSLT4J compiler(not included)

XL TXE-Jcompiler(included)

http://javax.xml.transform.stream.StreamSource/feature feature

Yes Yes Yes

http://javax.xml.transform.stream.StreamResult/feature feature

Yes Yes Yes

http://javax.xml.transform.dom.DOMSource/feature feature

Yes Yes Yes

http://javax.xml.transform.dom.DOMResult/feature feature

Yes Yes Yes

http://javax.xml.transform.sax.SAXSource/featurefeature

Yes Yes Yes

http://javax.xml.transform.sax.SAXResult/featurefeature

Yes Yes Yes

http://javax.xml.transform.stax.StAXSource/feature feature

Yes No Yes

http://javax.xml.transform.stax.StAXResult/feature feature

Yes No Yes

http://javax.xml.transform.sax.SAXTransformerFactory/feature feature

Yes Yes Yes

http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter feature

Yes Yes Yes

http://javax.xml.XMLConstants/feature/secure-processing feature

Yes Yes Yes

http://xml.apache.org/xalan/features/incrementalattribute

Yes No No

http://xml.apache.org/xalan/features/optimizeattribute

Yes No No

http://xml.apache.org/xalan/properties/source-location attribute

Yes No No

translet-name attribute N/A Yes Yes (with newname)

destination-directory attribute N/A Yes Yes (with newname)

package-name attribute N/A Yes Yes (with newname)


Table 20. Comparison of the features in the XSLT4J interpreter, the XSLT4J compiler, and the XL TXE-J compiler.(continued)

Feature

XSLT4Jinterpreter(included)

XSLT4J compiler(not included)

XL TXE-Jcompiler(included)

jar-name attribute N/A Yes Yes (with newname)

generate-translet attribute N/A Yes Yes (with newname)

auto-translet attribute N/A Yes Yes (with newname)

use-classpath attribute N/A Yes Yes (with newname)

enable-inlining attribute No Yes No (obsolete in TLTXE-J)

indent-number attribute No Yes Yes (with newname)

debug attribute No Yes Yes (with newname)

Java extensions Yes Yes (abbreviatedsyntax only,xalan:component/xalan:scriptconstructs notsupported)

Yes (abbreviatedsyntax only,xalan:component/xalan:scriptconstructs notsupported)

JavaScript extensions Yes No No

Extension elements Yes No No

EXSLT extension functions Yes Yes (excludingdynamic)

Yes (excludingdynamic)

redirect extension Yes Yes (excludingredirect:open andredirect:close)

Yes

output extension No Yes Yes

nodeset extension Yes Yes Yes

NodeInfo extension functions Yes No No

SQL library extension Yes No No

pipeDocument extension Yes No No

evaluate extension Yes No No

tokenize extension Yes No No

XML 1.1 Yes Yes Yes

Notes

1. With the Process command, use -FLAVOR sr2sw to transform using StAX stream processing, and -FLAVOR er2ew for StAX event processing.


2. The new compiler does not look for the org.apache.xalan.xsltc.dom.XSLTCDTMManagerservice provider. Instead, if StreamSource is used, the compiler switches to a high-performance XMLparser.

3. Inlining is obsolete in XL TXE-J.

• The -XN option to the Process command is silently ignored.• The -n option to the Compile command is silently ignored.• The enable-inlining transformer factory attribute is silently ignored.

4. The org.apache.xalan.xsltc.trax.SmartTransformerFactoryImpl class is no longersupported.


Using an older version of Xerces or XalanIf you are using an older version of Xerces (before 2.0) or Xalan (before 2.3) in the endorsed override, youmight get a NullPointerException when you start your application. This exception occurs becausethese older versions do not handle the jaxp.properties file correctly.

To avoid this situation, use one of the following workarounds:

• Upgrade to a newer version of the application that implements the latest Java API for XML Programming(JAXP) specification (https://jaxp.dev.java.net/).

• Remove the jaxp.properties file.• On AIX, copy the jaxp.properties.sample file to jaxp.properties in /etc/java8[_64]/jre/lib. Uncomment the entries in the jaxp.properties file. Create a symbolic link to thejaxp.properties file from the /etc/java8[_64]/jre/lib directory.

• Set the system property for javax.xml.parsers.SAXParserFactory,javax.xml.parsers.DocumentBuilderFactory, orjavax.xml.transform.TransformerFactory using the -D command-line option.

• Set the system property for javax.xml.parsers.SAXParserFactory,javax.xml.parsers.DocumentBuilderFactory, orjavax.xml.transform.TransformerFactory in your application. For an example, see the JAXP1.6 specification.

• Explicitly set the SAX parser, Document builder, or Transformer factory using the IBM_JAVA_OPTIONSor OPENJ9_JAVA_OPTIONS environment variable. For example, on a UNIX-based system:

export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.SAXParserFactory= org.apache.xerces.jaxp.SAXParserFactoryImpl

or

export IBM_JAVA_OPTIONS=-Djavax.xml.parsers.DocumentBuilderFactory= org.apache.xerces.jaxp.DocumentBuilderFactoryImpl

or

export IBM_JAVA_OPTIONS=-Djavax.xml.transform.TransformerFactory= org.apache.xalan.processor.TransformerFactoryImpl

On Windows, use the set command instead of export.

Note: The IBM_JAVA_OPTIONS environment variable is deprecated and replaced by theOPENJ9_JAVA_OPTIONS environment variable.



XML system property command-line optionsUse the system property command-line options to set up your system.-D<name>=<value>


-Dcom.ibm.xtq.processor.overrideSecureProcessingThis system property affects the XSLT processing of extension functions or extension elements whenJava security is enabled.

Purpose

The use of extension functions or extension elements is no longer allowed when Java security is enabled.The system property can be used to revert to the behavior in earlier releases.

Parameterscom.ibm.xtq.processor.overrideSecureProcessing=true

To revert to the behavior in earlier releases of the IBM SDK, set this system property to true.

-Djdk.xml.entityExpansionLimitThis option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.

-Djdk.xml.entityExpansionLimit=value

where value is a positive integer. The default value is 64,000.

A value of 0 or a negative number sets no limit.

You can also set this limit by adding the following line to your jaxp.properties file:

jdk.xml.entityExpansionLimit=value


Related reference“-Djdk.xml.maxGeneralEntitySizeLimit” on page 272This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.“-Djdk.xml.maxOccur” on page 272This option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.“-Djdk.xml.maxParameterEntitySizeLimit” on page 273This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.“-Djdk.xml.maxXMLNameLimit” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.“-Djdk.xml.totalEntitySizeLimit” on page 275This option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.“-Djdk.xml.resolveExternalEntities” on page 274


This option provides limits for Java API for XML processing (JAXP). Use this option to control whetherexternal entities are resolved in an XML document.

-Djdk.xml.maxGeneralEntitySizeLimitThis option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.

To protect an application from malformed XML, set this value to the minimum size possible.-Djdk.xml.maxGeneralEntitySizeLimit=value

Where value is the maximum size that is allowed for a general entity. The default value is 0.

A value of 0 or a negative number sets no limits.


jdk.xml.maxGeneralEntitySizeLimit=value


Related reference“-Djdk.xml.entityExpansionLimit” on page 271This option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.“-Djdk.xml.maxOccur” on page 272This option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.“-Djdk.xml.maxParameterEntitySizeLimit” on page 273This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.“-Djdk.xml.maxXMLNameLimit” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.“-Djdk.xml.totalEntitySizeLimit” on page 275This option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.“-Djdk.xml.resolveExternalEntities” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to control whetherexternal entities are resolved in an XML document.

-Djdk.xml.maxOccurThis option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.

When building a grammar for a W3C XML schema, use this option to limit the number of content modelnodes that can be created when the schema defines attributes that can occur multiple times.

-Djdk.xml.maxOccur=value

Where value is a positive integer. The default value is 5,000.



jdk.xml.maxoccur=value



Related reference“-Djdk.xml.entityExpansionLimit” on page 271This option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.“-Djdk.xml.maxGeneralEntitySizeLimit” on page 272This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.“-Djdk.xml.maxParameterEntitySizeLimit” on page 273This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.“-Djdk.xml.maxXMLNameLimit” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.“-Djdk.xml.totalEntitySizeLimit” on page 275This option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.“-Djdk.xml.resolveExternalEntities” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to control whetherexternal entities are resolved in an XML document.

-Djdk.xml.maxParameterEntitySizeLimitThis option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.

To protect an application from malformed XML, set this value to the minimum size possible.-Djdk.xml.maxParameterEntitySizeLimit=value

Where value is the maximum size that is allowed for a parameter entity. The default value is 0.



jdk.xml.maxParameterEntitySizeLimit=value


Related reference“-Djdk.xml.entityExpansionLimit” on page 271This option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.“-Djdk.xml.maxGeneralEntitySizeLimit” on page 272This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.“-Djdk.xml.maxOccur” on page 272This option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.“-Djdk.xml.maxXMLNameLimit” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.“-Djdk.xml.totalEntitySizeLimit” on page 275This option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.“-Djdk.xml.resolveExternalEntities” on page 274



-Djdk.xml.maxXMLNameLimitThis option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.

-Djdk.xml.maxXMLNameLimit=value

Where value is a positive integer.

A value of 0 or a negative number sets no limits. The default value is 0.


jdk.xml.maxXMLNameLimit=value


Related reference“-Djdk.xml.entityExpansionLimit” on page 271This option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.“-Djdk.xml.maxGeneralEntitySizeLimit” on page 272This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.“-Djdk.xml.maxOccur” on page 272This option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.“-Djdk.xml.maxParameterEntitySizeLimit” on page 273This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.“-Djdk.xml.resolveExternalEntities” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to control whetherexternal entities are resolved in an XML document.“-Djdk.xml.totalEntitySizeLimit” on page 275This option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.

-Djdk.xml.resolveExternalEntitiesThis option provides limits for Java API for XML processing (JAXP). Use this option to control whetherexternal entities are resolved in an XML document.

-Djdk.xml.resolveExternalEntities=value

Where value is boolean. The default value is true.

A value of false turns off the resolution of XML external entities.


jdk.xml.resolveExternalEntities=value



Related reference“-Djdk.xml.entityExpansionLimit” on page 271This option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.“-Djdk.xml.maxGeneralEntitySizeLimit” on page 272This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.“-Djdk.xml.maxOccur” on page 272This option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.“-Djdk.xml.maxXMLNameLimit” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.“-Djdk.xml.totalEntitySizeLimit” on page 275This option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.“-Djdk.xml.maxParameterEntitySizeLimit” on page 273This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.

-Djdk.xml.totalEntitySizeLimitThis option provides limits for Java API for XML processing (JAXP). Use this option to limit the total size ofall entities, including general and parameter entities.

-Djdk.xml.totalEntitySizeLimit=value

Where value is the collective size of all entities. The default value is 5x10^7 (50 000 000).



jdk.xml.totalEntitySizeLimit=value


Related reference“-Djdk.xml.entityExpansionLimit” on page 271This option provides limits for Java API for XML processing (JAXP). Use this option to limit the number ofentity expansions in an XML document.“-Djdk.xml.maxGeneralEntitySizeLimit” on page 272This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a general entity.“-Djdk.xml.maxOccur” on page 272This option provides limits for Java API for XML processing (JAXP). This option defines the maximumnumber of content model nodes that can be created in a grammar.“-Djdk.xml.maxParameterEntitySizeLimit” on page 273This option provides limits for Java API for XML processing (JAXP). Use this option to limit the maximumsize of a parameter entity.“-Djdk.xml.maxXMLNameLimit” on page 274This option provides limits for Java API for XML processing (JAXP). Use this option to limit the length ofXML names in XML documents.“-Djdk.xml.resolveExternalEntities” on page 274



Known issues and limitationsKnown issues or limitations that you might encounter in specific system environments, or configurations.

The problems described in this topic might not be limitations with the release. Instructions are providedto work around problems, where possible.

These known issues and limitations also apply to earlier releases:

Unexpected XSLT error on extension elements or extension functions when security is enabled

Any attempt to use extension elements or extension functions when security is enabled, results in ajavax.xml.transform.TransformerException error during XSLT processing.

The following XSLT message is generated when extension functions are used: Use of the extensionfunction '<method name>' is not allowed when Java security is enabled. Tooverride this, set the com.ibm.xtq.processor.overrideSecureProcessing propertyto true. This override only affects XSLT processing.

The following XSLT message is generated when extension elements are used: Use of the extensionelement '<element name>' is not allowed when Java security is enabled. Tooverride this, set the com.ibm.xtq.processor.overrideSecureProcessing propertyto true. This override only affects XSLT processing.

To allow extensions when security is enabled, set thecom.ibm.xtq.processor.overrideSecureProcessing system property to true. For moreinformation about this system property, see “-Dcom.ibm.xtq.processor.overrideSecureProcessing” onpage 271.


Chapter 14. The ORBThis description of the Object Request Broker (ORB) provides background information to help youunderstand how the ORB works.

The IBM ORB that is provided with this release is used by WebSphere Application Server. It is one of theenterprise features of the Java Standard Edition. The ORB is both a tool and a runtime component. Itprovides distributed computing through the CORBA Internet Inter-Orb Protocol (IIOP) communicationprotocol. The protocol is defined by the Object Management Group (OMG). The ORB runtime environmentconsists of a Java implementation of a CORBA ORB. The ORB toolkit provides APIs and tools for both theRemote Method Invocation (RMI) programming model and the Interface Definition Language (IDL)programming model.

CORBAThe Common Object Request Broker Architecture (CORBA) is an open, vendor-independent specificationfor distributed computing. It is published by the Object Management Group (OMG).

Most applications need different objects on various platforms and operating systems to communicatewith each other across networks. CORBA enables objects to interoperate in this way, using the InternetInter-ORB Protocol (IIOP). To help objects understand the operations available, and the syntax requiredto invoke them, an Interface Definition Language (IDL) is used. The IDL is programming-languageindependent, to increase the interoperability between objects.

When an application developer defines an object, they also define other aspects. The aspects include theposition of the object in an overall hierarchy, object attributes, and possible operations. Next, the aspectsare all described in the IDL. The description is then converted into an implementation by using an IDLcompiler. For example, IDLJ is an IDL compiler for the Java language, and converts an IDL descriptioninto a Java source code. The benefit of this is that the object implementation is encapsulated by the IDLdefinition. Any other objects wanting to interoperate can do so using mechanisms defined using theshared IDL.

Developers enable this interoperability by defining the hierarchy, attributes, and operations of objectsusing IDL. They then use an IDL compiler (such as IDLJ for Java) to map the definition onto animplementation in a programming language. The implementation of an object is encapsulated. Clients ofthe object can see only its external IDL interface. The OMG has produced specifications for mappingsfrom IDL to many common programming languages, including C, C++, and Java

An essential part of the CORBA specification is the Object Request Broker (ORB). The ORB routesrequests from a client object to a remote object. The ORB then returns any responses to the requireddestinations. Java contains an implementation of the ORB that communicates by using IIOP.

RMI and RMI-IIOPThis description compares the two types of remote communication in Java; Remote Method Invocation(RMI) and RMI-IIOP.

RMI is Java's traditional form of remote communication. It is an object-oriented version of RemoteProcedure Call (RPC). It uses the nonstandardized Java Remote Method Protocol (JRMP) to communicatebetween Java objects. This provides an easy way to distribute objects, but does not allow forinteroperability between programming languages.

RMI-IIOP is an extension of traditional Java RMI that uses the IIOP protocol. This protocol allows RMIobjects to communicate with CORBA objects. Java programs can therefore interoperate transparentlywith objects that are written in other programming languages, provided that those objects are CORBA-compliant. Objects can still be exported to traditional RMI (JRMP) and the two protocols cancommunicate.


A terminology difference exists between the two protocols. In RMI (JRMP), the server objects are calledskeletons; in RMI-IIOP, they are called ties. Client objects are called stubs in both protocols.

Java IDL or RMI-IIOP?There are circumstances in which you might choose to use RMI-IIOP and others in which you mightchoose to use Java IDL.

RMI-IIOP is the method that is chosen by Java programmers who want to use the RMI interfaces, but useIIOP as the transport. RMI-IIOP requires that all remote interfaces are defined as Java RMI interfaces.Java IDL is an alternative solution, intended for CORBA programmers who want to program in Java toimplement objects that are defined in IDL. The general rule that is suggested by Oracle is to use Java IDLwhen you are using Java to access existing CORBA resources, and RMI-IIOP to export RMI resources toCORBA.

RMI-IIOP limitationsYou must understand the limitations of RMI-IIOP when you develop an RMI-IIOP application, and whenyou deploy an existing CORBA application in a Java-IIOP environment.

In a Java-only application, RMI (JRMP) is more lightweight and efficient than RMI-IIOP, but less scalable.Because it has to conform to the CORBA specification for interoperability, RMI-IIOP is a more complexprotocol. Developing an RMI-IIOP application is much more similar to CORBA than it is to RMI (JRMP).

You must take care if you try to deploy an existing CORBA application in a Java RMI-IIOP environment. AnRMI-IIOP client cannot necessarily access every existing CORBA object. The semantics of CORBA objectsthat are defined in IDL are a superset of those of RMI-IIOP objects. That is why the IDL of an existingCORBA object cannot always be mapped into an RMI-IIOP Java interface. It is only when the semantics ofa specific CORBA object are designed to relate to those of RMI-IIOP that an RMI-IIOP client can call aCORBA object.

Examples of client–server applicationsCORBA, RMI (JRMP), and RMI-IIOP approaches are used to present three client-server exampleapplications. All the applications use the RMI-IIOP IBM ORB.

InterfacesThe interfaces to be implemented are CORBA IDL and Java RMI.

The two interfaces are:

• CORBA IDL Interface (Sample.idl):

interface Sample { string message(); };

• Java RMI Interface (Sample.java):

public interface Sample extends java.rmi.Remote{ public String message() throws java.rmi.RemoteException; }

These two interfaces define the characteristics of the remote object. The remote object implements amethod, named message. The method does not need any parameter, and it returns a string. For furtherinformation about IDL and its mapping to Java, see the OMG specifications (https://www.omg.org).


https://www.omg.org

Remote object implementation (or servant)This description shows possible implementations of the object.

The possible RMI(JRMP) and RMI-IIOP implementations (SampleImpl.java) of this object could be:

public class SampleImpl extends javax.rmi.PortableRemoteObject implements Sample { public SampleImpl() throws java.rmi.RemoteException { super(); } public String message() { return "Hello World!"; } }

You can use the class PortableRemoteObject for both RMI over JRMP and IIOP. The effect is to makedevelopment of the remote object effectively independent of the protocol that is used. The objectimplementation does not need to extend PortableRemoteObject, especially if it already extendsanother class (single-class inheritance). Instead, the remote object instance must be exported in theserver implementation. Exporting a remote object makes the object available to accept incoming remotemethod requests. When you extend javax.rmi.PortableRemoteObject, your class is exportedautomatically on creation.

The CORBA or Java IDL implementation of the remote object (servant) is:

public class SampleImpl extends _SamplePOA { public String message() { return "Hello World"; } }

The POA is the Portable Object Adapter, described in “Portable object adapter” on page 289.

The implementation conforms to the Inheritance model, in which the servant extends directly the IDL-generated skeleton SamplePOA. You might want to use the Tie or Delegate model instead of the typicalInheritance model if your implementation must inherit from some other implementation. In the Tiemodel, the servant implements the IDL-generated operations interface (such as SampleOperations).The Tie model introduces a level of indirection, so that one extra method call occurs when you invoke amethod. The server code describes the extra work that is required in the Tie model, so that you candecide whether to use the Tie or the Delegate model. In RMI-IIOP, you can use only the Tie or Delegatemodel.

Stubs and ties generationThe RMI-IIOP code provides the tools to generate stubs and ties for whatever implementation exists ofthe client and server.

The following table shows what command to run to get the stubs and ties (or skeletons) for each of thethree techniques:

CORBA RMI(JRMP) RMI-IIOP

idlj Sample.idl rmic SampleImpl rmic -iiop Sample

Compilation generates the files that are shown in the following table. To keep the intermediate .javafiles, run the rmic command with the -keep option.


Sample.java SampleImpl_Skel.class _SampleImpl_Tie.class

SampleHolder.java SampleImpl_Stub.class _Sample_Stub.class

SampleHelper.java Sample.class (Sample.javapresent)

Sample.class (Sample.javapresent)

SampleOperations.java SampleImpl.class (onlycompiled)

SampleImpl.class (onlycompiled)

_SampleStub.java

Chapter 14. The ORB 279


SamplePOA.java (-fserver, -fall, -fserverTie, -fallTie)

SamplePOATie.java (-fserverTie, -fallTie)

_SampleImplBase.java (-oldImplBase)

Since the Java v1.4 ORB, the default object adapter (see the OMG CORBA specification v.2.3) is thePortable Object Adapter (POA). Therefore, the default skeletons and ties that the IDL compiler generatescan be used by a server that is using the POA model and interfaces. By using the idlj -oldImplBaseoption, you can generate older versions of the server-side skeletons that are compatible with servers thatare written in Java v1.3 and earlier.

Server codeThe server application has to create an instance of the remote object and publish it in a naming service.The Java Naming and Directory Interface (JNDI) defines a set of standard interfaces. The interfaces areused to query a naming service, or to bind an object to that service.

The implementation of the naming service can be a CosNaming service in the Common Object RequestBroker Architecture (CORBA) environment. A CosNaming service is a collection of naming services, andimplemented as a set of interfaces defined by CORBA. Alternatively, the naming service can beimplemented using a Remote Method Invocation (RMI) registry for an RMI(JRMP) application. You canuse JNDI in CORBA and in RMI cases. The effect is to make the server implementation independent of thenaming service that is used. For example, you could use the following code to obtain a naming service andbind an object reference in it:

Context ctx = new InitialContext(...); // get hold of the initial context ctx.bind("sample", sampleReference); // bind the reference to the name "sample" Object obj = ctx.lookup("sample"); // obtain the reference

To tell the application which naming implementation is in use, you must set one of the following Javaproperties:java.naming.factory.initial

Defined also as javax.naming.Context.INITIAL_CONTEXT_FACTORY, this property specifies theclass name of the initial context factory for the naming service provider. For RMI registry, the classname is com.sun.jndi.rmi.registry.RegistryContextFactory. For the CosNaming Service,the class name is com.sun.jndi.cosnaming.CNCtxFactory.

java.naming.provider.urlThis property configures the root naming context, the Object Request Broker (ORB), or both. It is usedwhen the naming service is stored in a different host, and it can take several URI schemes:

• rmi• corbaname• corbaloc• IOR• iiop• iiopname

For example:

rmi://[<host>[:<port>]][/<initial_context>] for RMI registry iiop://[<host>[:<port>]][/<cosnaming_name>] for COSNaming

To get the previous properties in the environment, you could code:


Hashtable env = new Hashtable(); Env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.cosnaming.CNCtxFactory");

and pass the hash table as an argument to the constructor of InitialContext.

For example, with RMI(JRMP), you create an instance of the servant then follow the previous steps tobind this reference in the naming service.

With CORBA (Java IDL), however, you must do some extra work because you have to create an ORB. TheORB has to make the servant reference available for remote calls. This mechanism is typically controlledby the object adapter of the ORB.

public class Server { public static void main (String args []) { try { ORB orb = ORB.init(args, null); // Get reference to the root poa & activate the POAManager POA poa = (POA)orb.resolve_initial_references("RootPOA"); poa.the_POAManager().activate(); // Create a servant and register with the ORB SampleImpl sample = new SampleImpl(); sample.setORB(orb);

// TIE model ONLY // create a tie, with servant being the delegate and // obtain the reference ref for the tie SamplePOATie tie = new SamplePOATie(sample, poa); Sample ref = tie._this(orb);

// Inheritance model ONLY // get object reference from the servant org.omg.CORBA.Object ref = poa.servant_to_reference(sample); Sample ref = SampleHelper.narrow(ref);

// bind the object reference ref to the naming service using JNDI ..........(see previous code) ..... orb.run(); } catch(Exception e) {} }}

For RMI-IIOP:

public class Server { public static void main (String args []) { try { ORB orb = ORB.init(args, null); // Get reference to the root poa & activate the POAManager POA poa = (POA)orb.resolve_initial_references("RootPOA"); poa.the_POAManager().activate();

// Create servant and its tie SampleImpl sample = new SampleImpl(); _SampleImpl_Tie tie = (_SampleImpl_Tie)Util.getTie(sample); // get an usable object reference org.omg.CORBA.Object ref = poa.servant_to_reference((Servant)tie);

// bind the object reference ref to the naming service using JNDI ..........(see previous code) ..... } catch(Exception e) {} }}

To use the previous Portable Object Adapter (POA) server code, you must use the -iiop -poa optionstogether to enable rmic to generate the tie. If you do not use the POA, the RMI(IIOP) server code can bereduced to instantiating the servant (SampleImpl sample = new SampleImpl()). You then bind theservant to a naming service as is typically done in the RMI(JRMP) environment. In this case, you need use


only the -iiop option to enable rmic to generate the RMI-IIOP tie. If you omit -iiop, the RMI(JRMP)skeleton is generated.

When you export an RMI-IIOP object on your server, you do not necessarily have to choose betweenJRMP and IIOP. If you need a single server object to support JRMP and IIOP clients, you can export yourRMI-IIOP object to JRMP and to IIOP simultaneously. In RMI-IIOP terminology, this action is called dualexport.

RMI Client example:

public class SampleClient { public static void main(String [] args) { try{ Sample sampleref //Look-up the naming service using JNDI and get the reference ......... // Invoke method System.out.println(sampleRef.message()); } catch(Exception e) {} } }

CORBA Client example:

public class SampleClient { public static void main (String [] args) { try { ORB orb = ORB.init(args, null); // Look up the naming service using JNDI ...... // Narrowing the reference to the correct class Sample sampleRef = SampleHelper.narrow(o); // Method Invocation System.out.println(sampleRef.message()); } catch(Exception e) {} }}

RMI-IIOP Client example:

public class SampleClient { public static void main (String [] args) { try{ ORB orb = ORB.init(args, null); // Retrieving reference from naming service ........ // Narrowing the reference to the correct class Sample sampleRef = (Sample)PortableRemoteObject.narrow(o, Sample.class); // Method Invocation System.out.println(sampleRef.message()); } catch(Exception e) {} }}

How the ORB worksThis description tells you how the ORB works, by explaining what the ORB does transparently for theclient. An important part of the work is performed by the server side of the ORB.

This section describes a basic, typical RMI-IIOP session in which a client accesses a remote object on aserver. The access is made possible through an interface named Sample. The client calls a simplemethod provided through the interface. The method is called message(). The method returns a HelloWorld string. For further examples, see “Examples of client–server applications” on page 278.

The client sideThere are several steps to perform in order to enable an application client to use the ORB.


Stub creationFor any distributed application, the client must know what object it is going to contact, and which methodof this object it must call. Because the ORB is a general framework, you must give it general informationabout the method that you want to call.

You provide the connection information by implementing a Java interface, for example Sample. Theinterface contains basic information about the methods that can be called in the remote object.

The client relies on the existence of a server containing an object that implements the Sample interface.You create a proxy object that is available on the client side for the client application to use. The proxyobject is called a stub. The stub that acts as an interface between the client application and the ORB.

To create the stub, run the RMIC compiler on the Java interface:

rmic -iiop Sample

This command generates a file and object named _Sample_Stub.class.

The presence of a stub is not always mandatory for a client application to operate. When you useparticular CORBA features such as the Dynamic Invocation Interface (DII), you do not require a stub. Thereason is that the proxy code is implemented directly by the client application. You can also upload a stubfrom the server to which you are trying to connect. See the CORBA specification for further details.

ORB initializationIn a stand-alone Java application, the client must create an instance of the ORB.

The ORB instance is created by calling the static method init(...). For example:

ORB orb = ORB.init(args,props);

The parameters that are passed to the method are:

• A string array containing property-value pairs.• A Java Properties object.

A similar method is used for an applet. The difference is that a Java Applet is passed instead of the stringarray.

The first step of ORB initialization is to process the ORB properties.

The properties are found by searching in the following sequence:

1. First, check in the applet parameter, or application string array.2. Check in the properties parameter, if the parameter exists.3. Check in the system properties.4. Check in any orb.properties file that is found in the <user-home> directory.


5. Check in any orb.properties file that is found in the <java-home>/lib directory.6. Finally, use hardcoded default behavior.

From service refresh 3, fix pack 10, the order of precedence is changed.

The properties are found by searching in the following sequence:

1. First, check in the applet parameter, or application string array.2. Check in the properties parameter, if the parameter exists.3. Check in the system properties.4. Check in any orb.properties file under the directory that is specified by the JVM propertycom.ibm.CORBA.ORBPropertyFilePath.

5. Check in any orb.properties file that is found in the <user-home> directory.6. Check in any orb.properties file that is found in the <java-home>/lib directory.7. Check in any orb.properties file that is found in the CLASSPATH (including JAR files).8. Finally, use hardcoded default behavior.

For more information about the property com.ibm.CORBA.ORBPropertyFilePath, see “-Dcom.ibm.CORBA.ORBPropertyFilePath” on page 311.

Two important properties are ORBClass and ORBSingletonClass. These properties determine whichORB class is created and initialized, or instantiated.

After the ORB is instantiated, it starts and initializes the TCP transport layer. If the ListenerPortproperty was set, the ORB also opens a server socket to listen for incoming requests. The ListenerPortproperty is used by a server-side ORB. At the end of the initialization process that is run by the init()method, the ORB is fully functional and ready to support the client application.

Obtaining the remote objectSeveral methods exist by which the client can get a reference for the remote object.

Typically, this reference is a string, called an Interoperable Object Reference (IOR). For example:

IOR:000000000000001d524d493a5......

This reference contains all the information required to find the remote object. It also contains somedetails of the server settings to which the object belongs.

The client ORB does not have to understand the details of the IOR. The IOR is used as a reference to theremote object, like a key. However, when client and server are both using an IBM ORB, extra features arecoded in the IOR. For example, the IBM ORB adds a proprietary field into the IOR, calledIBM_PARTNER_VERSION. This field holds a value like the following example:

49424d0a 00000008 00000000 1400 0005

In the example:

• The first three bytes are the ASCII code for IBM• The next byte is 0x0A, which specifies that the following bytes provide information about the partner

version.• The next 4 bytes encode the length of the remaining data. In this example, the remaining data is 8 bytes

long.• The next 4 null bytes are reserved for future use.• The next 2 bytes are for the Partner Version Major field. In this example, the value is 0x1400, which

means that release 1.4.0 of the ORB is being used.• The final 2 bytes in this example have the value 0x0005 and represent the Minor field. This field is used

to distinguish maintenance updates within the same release. The updates contain changes that affectcompatibility with earlier versions.


The final step is called the bootstrap process. This step is where the client application tells the ORB wherethe remote object reference is located. The step is necessary for two reasons:

• The IOR is not visible to application-level ORB programmers.• The client ORB does not know where to look for the IOR.

A typical example of the bootstrap process takes place when you use a naming service. First, the clientcalls the ORB method resolve_initial_references("NameService"). The method which returnsa reference to the name server. The reference is in the form of a NamingContext object. The ORB thenlooks for a corresponding name server in the local system at the default port 2809. If no name serverexists, or the name server cannot be found because it is listening on another port, the ORB returns anexception. The client application can specify a different host, a different port, or both, by using the -ORBInitRef and -ORBInitPort options.

Using the NamingContext and the name with which the Remote Object has been bound in the nameservice, the client can retrieve a reference to the remote object. The reference to the remote object thatthe client holds is always an instance of a Stub object; for example _Sample_Stub.

Using ORB.resolve_initial_references() causes much system activity. The ORB starts bycreating a remote communication with the name server. This communication might include severalrequests and replies. Typically, the client ORB first checks whether a name server is listening. Next, theclient ORB asks for the specified remote reference. In an application where performance is important,caching the remote reference is preferable to repetitive use of the naming service. However, because thenaming service implementation is a transient type, the validity of the cached reference is limited to thetime in which the naming service is running.

The IBM ORB implements an Interoperable Naming Service as described in the CORBA 2.3 specification.This service includes a new string format that can be passed as a parameter to the ORB methodsstring_to_object() and resolve_initial_references(). The methods are called with a stringparameter that has a corbaloc (or corbaname) format. For example:

corbaloc:iiop:[email protected]:1050/AService

In this example, the client ORB uses GIOP 1.0 to send a request with a simple object key of AService toport 1050 at host aserver.aworld.aorg. There, the client ORB expects to find a server for therequested Aservice. The server replies by returning a reference to itself. You can then use this referenceto look for the remote object.

This naming service is transient. It means that the validity of the contained references expires when thename service or the server for the remote object is stopped.

Remote method invocationThe client holds a reference to the remote object that is an instance of the stub class. The next step is tocall the method on that reference. The stub implements the Sample interface and therefore contains themessage() method that the client has called.

First, the stub code determines whether the implementation of the remote object is located on the sameORB instance. If so, the object can be accessed without using the Internet.

If the implementation of the remote object is located on the same ORB instance, the performanceimprovement can be significant because a direct call to the object implementation is done. If no localservant can be found, the stub first asks the ORB to create a request by calling the _request() method,specifying the name of the method to call and whether a reply is expected or not.

The CORBA specification imposes an extra layer of indirection between the ORB code and the stub. Thislayer is commonly known as delegation. CORBA imposes the layer using an interface named Delegate.This interface specifies a portable API for ORB-vendor-specific implementation of theorg.omg.CORBA.Object methods. Each stub contains a delegate object, to which allorg.omg.CORBA.Object method invocations are forwarded. Using the delegate object means that astub generated by the ORB from one vendor is able to work with the delegate from the ORB of anothervendor.


When creating a request, the ORB first checks whether the enableLocateRequest property is set totrue, in which case, a LocateRequest is created. The steps of creating this request are like the fullRequest case.

The ORB obtains the IOR of the remote object (the one that was retrieved by a naming service, forexample) and passes the information that is contained in the IOR (Profile object) to the transport layer.

The transport layer uses the information that is in the IOR (IP address, port number, and object key) tocreate a connection if it does not exist. The ORB TCP/IP transport has an implementation of a table ofcached connections for improving performances, because the creation of a new connection is a time-consuming process. The connection is not an open communication channel to the server host. It is only anobject that has the potential to create and deliver a TCP/IP message to a location on the Internet.Typically, that involves the creation of a Java socket and a reader thread that is ready to intercept theserver reply. The ORB.connect() method is called as part of this process.

When the ORB has the connection, it proceeds to create the Request message. The message containsthe header and the body of the request. The CORBA 2.3 specification specifies the exact format. Theheader contains these items:

• Local IP address• Local port• Remote IP address• Remote port• Message size• Version of the CORBA stream format• Byte sequence convention• Request types• IDs

See “ORB problem determination ” on page 293 for a detailed description and example.

The body of the request contains several service contexts and the name and parameters of the methodinvocation. Parameters are typically serialized.

A service context is some extra information that the ORB includes in the request or reply, to add severalother functions. CORBA defines a few service contexts, such as the codebase and the codeset servicecontexts. The first is used for the callback feature which is described in the CORBA specification. Thesecond context is used to specify the encoding of strings.

In the next step, the stub calls _invoke(). The effect is to run the delegate invoke() method. The ORBin this chain of events calls the send() method on the connection that writes the request to the socketbuffer and then flushes it away. The delegate invoke() method waits for a reply to arrive. The readerthread that was spun during the connection creation gets the reply message, processes it, and returns thecorrect object.

Handling request retriesWhen a CORBA request results in a response of type org.omg.CORBA.SystemException, the IBM ORBretries a request under certain conditions. You can control the number of retries and the time delaybetween retries by using system properties.

When a CORBA request results in a response of type org.omg.CORBA.SystemException, the IBM ORBretries a request when the following two conditions are met:

1. The org.omg.CORBA.SystemException is one of the following types:

• org.omg.CORBA.COMM_FAILURE• org.omg.CORBA.TRANSIENT• org.omg.CORBA.NO_RESOURCE

2. The completion status of the org.omg.CORBA.SystemException isorg.omg.CORBA.CompletionStatus.COMPLETED_NO.


The following properties govern ORB retry behavior:com.ibm.CORBA.requestRetriesCount

This property governs the number of retries that are attempted.com.ibm.CORBA.requestRetriesDelay

This property determines the time delay in milliseconds (ms) between retries.For more information about these properties, see “-Dcom.ibm.CORBA.requestRetriesCount” on page 311and “-Dcom.ibm.CORBA.requestRetriesDelay” on page 311.

The overall time delay before the client receives an org.omg.CORBA.SystemException response if allretry attempts fail, is based on the property values for these two properties. Note: IBM ORB does notretry a request when a completion status that contains COMPLETED_MAYBE or COMPLETED_YES isreturned.

The Interoperable Object References (IOR) also play a role in the retry logic. The ORB deals with twodifferent IORs when CORBA requests are sent, which are the “indirect” (or "initial") IOR and “direct” (or"forwarded") IOR. The “initial” IOR is the bootstrap IOR with which a client starts the initial request,which is essentially an IOR used to contact the NameService on the bootstrap port. Subsequentrequests are made by using the “forwarded” IOR, which is a “direct” IOR to a specific server’s ORB port.If an org.omg.CORBA.SystemException exception is thrown of one of the specified types, the ORBfalls back to the “initial” IOR and sends the retry request by using the “initial” IOR. This behavior allowsthe ORB to obtain a new “direct” IOR to a server to attempt to complete the request. The IOR-relatedlogic is separate from the property settings that are made by usingcom.ibm.CORBA.requestRetriesCount.

Important: The retry behavior of the two IOR types is not configurable, is internal to IBM ORB, and mightbe changed without any prior notification.

The server sideIn ORB terminology, a server is an application that makes one of its implemented objects availablethrough an ORB instance.

Servant implementationThe implementations of the remote object can either inherit fromjavax.rmi.PortableRemoteObject, or implement a remote interface and use the exportObject()method to register themselves as a servant object. In both cases, the servant has to implement theSample interface. Here, the first case is described. From now, the servant is called SampleImpl.

Tie generationYou must put an interfacing layer between the servant and the ORB code. In the old RMI (JRMP) namingconvention, skeleton was the name given to the proxy that was used on the server side between ORB andthe object implementation. In the RMI-IIOP convention, the proxy is called a Tie.

You generate the RMI-IIOP tie class at the same time as the stub, by calling the rmic compiler. Theseclasses are generated from the compiled Java programming language classes that contain remote objectimplementations. For example, the command:

rmic -iiop SampleImpl

generates the stub _Sample_Stub.class and the tie _Sample_Tie.class.

Servant bindingThe steps required to bind the servant are described.

The server implementation is required to do the following tasks:

1. Create an ORB instance; that is, ORB.init(...)2. Create a servant instance; that is, new SampleImpl(...)3. Create a Tie instance from the servant instance; that is, Util.getTie(...)4. Export the servant by binding it to a naming service


As described for the client side, you must create the ORB instance by calling the ORB static methodinit(...). The typical steps performed by the init(...) method are:

1. Retrieve properties2. Get the system class loader3. Load and instantiate the ORB class as specified in the ORBClass property4. Initialize the ORB as determined by the properties

Next, the server must create an instance of the servant class SampleImpl.class. Something more thanthe creation of an instance of a class happens under the cover. Remember that the servant SampleImplextends the PortableRemoteObject class, so the constructor of PortableRemoteObject is called.This constructor calls the static method exportObject(...) with the parameter that is the sameservant instance that you try to instantiate. If the servant does not inherit fromPortableRemoteObject, the application must call exportObject() directly.

The exportObject() method first tries to load an RMI-IIOP tie. The ORB implements a cache of classesof ties for improving performance. If a tie class is not already cached, the ORB loads a tie class for theservant. If it cannot find one, it goes up the inheritance tree, trying to load the parent class ties. The ORBstops if it finds a PortableRemoteObject class or the java.lang.Object, and returns a null value.Otherwise, it returns an instance of that tie from a hashtable that pairs a tie with its servant. If the ORBcannot find the tie, it assumes that an RMI (JRMP) skeleton might be present and calls theexportObject() method of the UnicastRemoteObject class. A null tie is registered in the cacheand an exception is thrown. The servant is now ready to receive remote methods invocations. However, itis not yet reachable.

In the next step, the server code must find the tie itself (assuming the ORB has already got hold of the tie)to be able to export it to a naming service. To do that, the server passes the newly created instance of theservant into the static method javax.rmi.CORBA.Util.getTie(). This method, in turn, gets the tiethat is in the hashtable that the ORB created. The tie contains the pair of tie-servant classes.

When in possession of the tie, the server must get hold of a reference for the naming service and bind thetie to it. As in the client side, the server calls the ORB methodresolve_initial_references("NameService"). The server then creates a NameComponent,which is a directory tree object identifying the path and the name of the remote object reference in thenaming service. The server binds the NameComponent together with the tie. The naming service thenmakes the IOR for the servant available to anyone requesting. During this process, the server code sendsa LocateRequest to get hold of the naming server address. It also sends a Request that requires arebind operation to the naming server.

Processing a requestThe server ORB uses a single listener thread, and a reader thread for each connection or client, to processan incoming message.

During the ORB initialization, a listener thread was created. The listener thread is listening on a defaultport (the next available port at the time the thread was created). You can specify the listener port by usingthe com.ibm.CORBA.ListenerPort property. When a request comes in through that port, the listenerthread first creates a connection with the client side. In this case, it is the TCP transport layer that takescare of the details of the connection. The ORB caches all the connections that it creates.

By using the connection, the listener thread creates a reader thread to process the incoming message.When dealing with multiple clients, the server ORB has a single listener thread and one reader thread foreach connection or client.

The reader thread does not fully read the request message, but instead creates an input stream for themessage to be piped into. Then, the reader thread picks up one of the worker threads in the implementedpool, or creates one if none is present. The work thread is given the task of reading the message. Theworker thread reads all the fields in the message and dispatches them to the tie. The tie identifies anyparameters, then calls the remote method.


The service contexts are then created and written to the response output stream with the return value.The reply is sent back with a similar mechanism, as described in the client side. Finally, the connection isremoved from the reader thread which stops.

Additional features of the ORBPortable object adapter, fragmentation, portable interceptors, and Interoperable Naming Service aredescribed.

This section describes:

• “Portable object adapter” on page 289• “Interoperable Naming Service (INS)” on page 290

Portable object adapterAn object adapter is the primary way for an object to access ORB services such as object referencegeneration. A portable object adapter exports standard interfaces to the object.

The main responsibilities of an object adapter are:

• Generation and interpretation of object references.• Enabling method calling.• Object and implementation activation and deactivation.• Mapping object references to the corresponding object implementations.

For CORBA 2.1 and earlier, all ORB vendors implemented an object adapter, which was known as thebasic object adapter. A basic object adapter could not be specified with a standard CORBA IDL. Therefore,vendors implemented the adapters in many different ways. The result was that programmers were notable to write server implementations that were truly portable between different ORB products. A firstattempt to define a standard object adapter interface was done in CORBA 2.1. With CORBA v.2.3, theOMG group released the final corrected version of a standard interface for the object adapter. Thisadapter is known as the Portable Object Adapter (POA).

Some of the main features of the POA specification are to:

• Allow programmers to construct object and server implementations that are portable between differentORB products.

• Provide support for persistent objects. The support enables objects to persist across several serverlifetimes.

• Support transparent activation of objects.• Associate policy information with objects.• Allow multiple distinct instances of the POA to exist in one ORB.

For more details of the POA, see the CORBA v.2.3 (formal/99-10-07) specification.


The IBM ORB supports both the POA specification and the previous proprietary basic object adapter. Bydefault, the RMI compiler, when used with the -iiop option, generates RMI-IIOP ties for servers. Theseties are based on the basic object adapter. When a server implementation uses the POA interface, youmust add the -poa option to the rmic compiler to generate the relevant ties.

To implement an object using the POA, the server application must obtain a POA object. When the serverapplication calls the ORB method resolve_initial_reference("RootPOA"), the ORB returns thereference to the main POA object that contains default policies. For a list of all the POA policies, see theCORBA specification. You can create new POAs as child objects of the RootPOA. These child objects cancontain different policies. This structure allows you to manage different sets of objects separately, and topartition the namespace of objects IDs.

Ultimately, a POA handles Object IDs and active servants. An active servant is a programming object thatexists in memory. The servant is registered with the POA because one or more associated objectidentities was used. The ORB and POA cooperate to determine which servant starts the operationrequested by the client. By using the POA APIs, you can create a reference for the object, associate anobject ID, and activate the servant for that object. A map of object IDs and active servants is stored insidethe POA. A POA also provides a default servant that is used when no active servant has been registered.You can register a particular implementation of this default servant. You can also register a servantmanager, which is an object for managing the association of an object ID with a particular servant.

The POA manager is an object that encapsulates the processing state of one or more POAs. You cancontrol and change the state of all POAs by using operations on the POA manager.

The adapter activator is an object that an application developer uses to activate child POAs.

Interoperable Naming Service (INS)The CORBA CosNaming Service follows the Object Management Group (OMG) Interoperable NamingService specification (INS, CORBA 2.3 specification). CosNaming stands for Common Object ServicesNaming.

The name service maps names to CORBA object references. Object references are stored in thenamespace by name and each object reference-name pair is called a name binding. Name bindings canbe organized under naming contexts. Naming contexts are themselves name bindings, and serve the sameorganizational function as a file system subdirectory does. All bindings are stored under the initial namingcontext. The initial naming context is the only persistent binding in the namespace.


This implementation includes string formats that can be passed as a parameter to the ORB methodsstring_to_object() and resolve_initial_references(). The formats are corbaname andcorbaloc.

Corbaloc URIs allow you to specify object references that can be contacted by IIOP or found throughORB::resolve_initial_references(). This format is easier to manipulate than IOR. To specify anIIOP object reference, use a URI of the form:

corbaloc:iiop:<host>:<port>/<object key>

Note: See the CORBA 2.4.2 specification for the full syntax of this format.

For example, the following corbaloc URI specifies an object with key MyObjectKey that is in a processthat is running on myHost.myOrg.com, listening on port 2809:

corbaloc:iiop:myHost.myOrg.com:2809/MyObjectKey

Corbaname URIs cause the string_to_object() method to look up a name in a CORBA namingservice. The URIs are an extension of the corbaloc syntax:

corbaname:<corbaloc location>/<object key>#<stringified name>

Note: See the CORBA 2.4.2 specification for the full syntax of this format.

An example corbaname URI is:

corbaname::myOrg.com:2050#Personal/schedule

In this example, the portion of the reference up to the number sign character (#) is the URL that returnsthe root naming context. The second part of the example, after the number sign character (#), is theargument that is used to resolve the object on the NamingContext.

The INS specified two standard command-line arguments that provide a portable way of configuringORB::resolve_initial_references():

• -ORBInitRef takes an argument of the form <ObjectId>=<ObjectURI>. For example, you can usethe following command-line arguments:

-ORBInitRef NameService=corbaname::myhost.example.com

In this example, resolve_initial_references("NameService") returns a reference to theobject with key NameService available on myhost.example.com, port 2809.

• -ORBDefaultInitRef provides a prefix string that is used to resolve otherwise unknown names.When resolve_initial_references() cannot resolve a name that has been configured with -ORBInitRef, it constructs a string that consists of the default prefix, a forward slash character (/), andthe name requested. The string is then supplied to string_to_object(). For example, with acommand line of:

-ORBDefaultInitRef corbaloc::myhost.example.com

a call to resolve_initial_references("MyService") returns the object reference that isdenoted by corbaloc::myhost.example.com/MyService.

Using the ORBTo use the Object Request Broker (ORB) effectively, you must understand the properties that control thebehavior of the ORB.

The following table lists the property values that you can use to customize the behavior of the ORB. Allproperty values are specified as strings. Click on the links for more information about each property.


Table 21. IBM ORB system properties

System property Usage

“-Dcom.ibm.CORBA.AcceptTimeout” on page 306 Set a timeout value for an accept() call.

“-Dcom.ibm.CORBA.AllowUserInterrupt” on page 306 Allow an interrupt to a remote method call.

“-Dcom.ibm.CORBA.BufferSize” on page 307 Set the number of bytes to read of a GIOP message.

“-Dcom.ibm.CORBA.ConnectionMultiplicity” on page307

Manage the number of concurrent socket connections.

“-Dcom.ibm.CORBA.ConnectTimeout” on page 307 Set a timeout value for opening a remote ORBconnection.

“-Dcom.ibm.CORBA.enableLocateRequest” on page309

Configure ORB to send a LocateRequest before aRequest

“-Dcom.ibm.CORBA.FragmentSize” on page 309 Control GIOP 1.2 fragmentation.

“-Dcom.ibm.CORBA.FragmentTimeout” on page 309 Set a timeout value for receiving GIOP messagefragments.

“-Dcom.ibm.CORBA.GIOPAddressingDisposition” onpage 310

Set the GIOP address disposition.

“-Dcom.ibm.CORBA.InitialReferencesURL” on page310

Configure ORB to use a server based URL instead ofthe bootstrap approach.

Note: This property is deprecated.

“-Dcom.ibm.CORBA.ListenerPort” on page 310 Set the server listening port.

“-Dcom.ibm.CORBA.LocalHost” on page 310 Set the hostname of the system on which the ORB isrunning.

“-Dcom.ibm.CORBA.LocateRequestTimeout” on page310

Set a timeout value for LocateRequest messages.

“-Dcom.ibm.CORBA.MaxOpenConnections” on page310

Set the maximum number of in-use connections in theconnection cache table.

“-Dcom.ibm.CORBA.MinOpenConnections” on page310

Set the minimum number of in-use connections in theconnection cache table.

“-Dcom.ibm.CORBA.NoLocalInterceptors” on page311

Define whether local portable interceptors are used.

“-Dcom.ibm.CORBA.ORBCharEncoding” on page 311 Specify the native encoding set.

“-Dcom.ibm.CORBA.ORBWCharDefault” on page 311 Specify the wchar code set.

“-Dcom.ibm.CORBA.requestRetriesCount” on page311

Specify the number of retries when certain exceptionsare received.

“-Dcom.ibm.CORBA.requestRetriesDelay” on page311

Specify the delay between retries.

“-Dcom.ibm.CORBA.RequestTimeout” on page 311 Set the timeout value for a Request message.

“-Dcom.ibm.CORBA.SendingContextRunTimeSupported” on page 312

Control the CodeBase SendingContext RunTimeservice.

“-Dcom.ibm.CORBA.SendVersionIdentifier” on page312

Determine the partner version of ORB.


Table 21. IBM ORB system properties (continued)

System property Usage

“-Dcom.ibm.CORBA.ServerSocketQueueDepth” onpage 312

Set the maximum queue length for incomingconnection requests.

“-Dcom.ibm.CORBA.ShortExceptionDetails” on page312

Control the output from a SystemException reply.

“-Dcom.ibm.tools.rmic.iiop.Debug” on page 312 Set the rmic tool to map fully qualified class names toshort names.

“-Dcom.ibm.tools.rmic.iiop.SkipImports” on page 312 Set the rmic tool to generate classes with fullyqualified names only.

“-Dorg.omg.CORBA.ORBid” on page 312 Set a unique identifier for the ORB.

“-Dorg.omg.CORBA.ORBListenEndpoints” on page312

Identify the set of endpoints on which the ORB listensfor requests.

“-Dorg.omg.CORBA.ORBServerId” on page 313 Set the same value for all ORB instances that arerunning in the same server.

com.ibm.CORBA.BootstrapHost This property is deprecated. It is replaced by -ORBInitRef and -ORBDefaultInitRef.

com.ibm.CORBA.BootstrapPort This property is deprecated. It is replaced by -ORBInitRef and -ORBDefaultInitRef.

This table shows the Java properties defined by Oracle Corporation that are now deprecated, and the IBMproperties that have replaced them. These properties are not OMG standard properties, despite theirnames:

Oracle Corporation property IBM property

com.sun.CORBA.ORBServerHost com.ibm.CORBA.LocalHost

com.sun.CORBA.ORBServerPort com.ibm.CORBA.ListenerPort

org.omg.CORBA.ORBInitialHost com.ibm.CORBA.BootstrapHost

org.omg.CORBA.ORBInitialPort com.ibm.CORBA.BootstrapPort

org.omg.CORBA.ORBInitialServices com.ibm.CORBA.InitialReferencesURL

ORB problem determinationOne of your first tasks when debugging an ORB problem is to determine whether the problem is in theclient-side or in the server-side of the distributed application. Think of a typical RMI-IIOP session as asimple, synchronous communication between a client that is requesting access to an object, and a serverthat is providing it.

During this communication, a problem might occur in the execution of one of the following steps:

1. The client writes and sends a request to the server.2. The server receives and reads the request.3. The server executes the task in the request.4. The server writes and sends a reply back.5. The client receives and reads the reply.

It is not always easy to identify where the problem occurred. Often, the information that the applicationreturns, in the form of stack traces or error messages, is not enough for you to make a decision. Also,


because the client and server communicate through their ORBs, if a problem occurs, both sides willprobably record an exception or unusual behavior.

This section describes all the clues that you can use to find the source of the ORB problem. It alsodescribes a few common problems that occur more frequently.

Identifying an ORB problemA background of the constituents of the IBM ORB component.

What the ORB component contains

The ORB component contains the following items:

• Java ORB from IBM and rmi-iiop runtime environment (com.ibm.rmi.*, com.ibm.CORBA.*)• RMI-IIOP API (javax.rmi.CORBA.*,org.omg.CORBA.*)• IDL to Java implementation (org.omg.* and IBM versions com.ibm.org.omg.*)• Transient name server (com.ibm.CosNaming.*, org.omg.CosNaming.*) - tnameserv• -iiop and -idl generators (com.ibm.tools.rmi.rmic.*) for the rmic compiler - rmic• idlj compiler (com.ibm.idl.*)

What the ORB component does not contain

The ORB component does not contain:

• RMI-JRMP (also known as Standard RMI)• JNDI and its plug-ins

Therefore, if the problem is in java.rmi.* or sun.rmi.* , it is not an ORB problem. Similarly, if the problem isin com.sun.jndi.*, it is not an ORB problem.

Platform dependent problems

If possible, run the test case on more than one platform. All the ORB code is shared. You can nearlyalways reproduce genuine ORB problems on any platform. If you have a platform-specific problem, it islikely to be in some other component.

JIT problem

JIT bugs are very difficult to find. They might show themselves as ORB problems. When you aredebugging or testing an ORB application, it is always safer to switch off the JIT by setting the option -Xint.

Fragmentation

Disable fragmentation when you are debugging the ORB. Although fragmentation does not addcomplications to the ORB's functioning, a fragmentation bug can be difficult to detect because it will mostlikely show as a general marshalling problem. The way to disable fragmentation is to set the ORB propertycom.ibm.CORBA.FragmentSize=0. You must do this on the client side and on the server side.

ORB versions

The ORB component carries a few version properties that you can display by calling the main method ofthe following classes:

1. com.ibm.CORBA.iiop.Version (ORB runtime version)


2. com.ibm.tools.rmic.iiop.Version (for tools; for example, idlj and rmic)3. rmic -iiop -version (run the command line for rmic)

Limitation with bidirectional GIOP

Bidirectional GIOP is not supported.

Debug propertiesProperties to use to enable ORB traces.

Attention: Do not enable tracing for normal operation, because it might cause a performancedegradation. First Failure Data Capture (FFDC) still works when tracing is turned off, which meansthat serious errors are reported. If a debug file is produced, examine it for issues. For example, theserver might have stopped without performing an ORB.shutdown().

You can use the following properties to enable the ORB traces:

• com.ibm.CORBA.Debug:

Table 22. Debug property values

Property value Trace output information

false [default] Tracing is disabled, so no information is recorded.

true Tracing is enabled. The output contains messages and traces for theentire ORB code flow

Note: If you use this property without specifying a value, tracing is enabled.• com.ibm.CORBA.Debug.Component: This property generates trace output only for specific Object

Request Broker (ORB) subcomponents. The following subcomponents can be specified:

– DISPATCH– MARSHAL– TRANSPORT– CLASSLOADER– ALL

When you want to trace more than one of these subcomponents, each subcomponent must beseparated by a comma.

Here is an example of common usage:

java -Dcom.ibm.CORBA.Debug=true -Dcom.ibm.CORBA.Debug.Output=trace.log -Dcom.ibm.CORBA.Debug.Component=DISPATCH-Dcom.ibm.CORBA.CommTrace=true <classname>

Note: The example provided is a single line, entered on the command line.• com.ibm.CORBA.Debug.Output: This property redirects traces to a file, which is known as a trace log.

When this property is not specified, or it is set to an empty string, the file name defaults to the formatorbtrc.DDMMYYYY.HHmm.SS.txt, where D=Day; M=Month; Y=Year; H=Hour (24 hour format);m=Minutes; S=Seconds. If the application (or Applet) does not have the privilege that it requires towrite to a file, the trace entries go to stderr.

• com.ibm.CORBA.CommTrace: This property turns on wire tracing, also known as Comm tracing. Everyincoming and outgoing GIOP message is sent to the trace log. You can set this property independentlyfrom Debug. This property is useful if you want to look only at the flow of information, and you are notinterested in debugging the internals. The only two values that this property can have are true andfalse. The default is false.

• Here is an example of common usage:


java -Dcom.ibm.CORBA.Debug=true -Dcom.ibm.CORBA.Debug.Output=trace.log-Dcom.ibm.CORBA.Debug.Component=DISPATCH-Dcom.ibm.CORBA.CommTrace=true <classname>

Note: The example provided is a single line, entered on the command line.

For rmic -iiop or rmic -idl, the following diagnostic tools are available:

• -J-Djavac.dump.stack=1: This tool ensures that all exceptions are caught.• -Xtrace: This tool traces the progress of the parse step.

If you are working with an IBM SDK, you can obtain CommTrace for the transient name server(tnameserv) by using the standard environment variable IBM_JAVA_OPTIONS. In a separate commandsession to the server or client SDKs, you can use:

export IBM_JAVA_OPTIONS=-Dcom.ibm.CORBA.CommTrace=true -Dcom.ibm.CORBA.Debug=true

or the equivalent platform-specific command.

Note: The IBM_JAVA_OPTIONS environment variable is deprecated and will be removed froma future release of the Eclipse OpenJ9 VM. Use the OPENJ9_JAVA_OPTIONS environment variableinstead.

The setting of this environment variable affects each Java process that is started, so use this variablecarefully. Alternatively, you can use the -J option to pass the properties through the tnameserv wrapper,as follows:

tnameserv -J-Dcom.ibm.CORBA.Debug=true

Related reference“-Dcom.ibm.CORBA.Debug” on page 307This system property enables debugging for the Object Request Broker (ORB) and includes tracingoptions that control how much information is recorded.“-Dcom.ibm.CORBA.Debug.Component” on page 308This system property can be used with -Dcom.ibm.CORBA.Debug=true to generate trace output forspecific Object Request Broker (ORB) subcomponents such as MARSHAL or DISPATCH. This finer level oftracing helps you debug problems with ORB operations.“-Dcom.ibm.CORBA.Debug.Output” on page 309This system property redirects Object Request Broker (ORB) trace output to a file, which is known as atrace log.“-Dcom.ibm.CORBA.CommTrace” on page 307This system property turns on wire tracing for the Object Request Broker (ORB), which is also known asComm tracing.

ORB exceptionsThe exceptions that can be thrown are split into user and system categories.

If your problem is related to the ORB, unless your application is doing nothing or giving you the wrongresult, your log file or terminal is probably full of exceptions that include the words CORBA and rmi manytimes. All unusual behavior that occurs in a good application is highlighted by an exception. This principlealso applies for the ORB with its CORBA exceptions. Similarly to Java, CORBA divides its exceptions intouser exceptions and system exceptions.

User exceptions

User exceptions are IDL defined and inherit from org.omg.CORBA.UserException. These exceptions aremapped to checked exceptions in Java; that is, if a remote method raises one of them, the applicationthat called that method must catch the exception. User exceptions are usually not unrecoverableexceptions and should always be handled by the application. Therefore, if you get one of these user


exceptions, you know where the problem is, because the application developer had to make allowancefor such an exception to occur. In most of these cases, the ORB is not the source of the problem.

System exceptions

System exceptions are thrown transparently to the application and represent an unusual condition inwhich the ORB cannot recover gracefully, such as when a connection is dropped. The CORBA 2.6specification defines 31 system exceptions and their mapping to Java. They all belong to theorg.omg.CORBA package. The CORBA specification defines the meaning of these exceptions anddescribes the conditions in which they are thrown.

The most common system exceptions are:

• BAD_OPERATION: This exception is thrown when an object reference denotes an existing object, butthe object does not support the operation that was called.

• BAD_PARAM: This exception is thrown when a parameter that is passed to a call is out of range orotherwise considered not valid. An ORB might raise this exception if null values or null pointers arepassed to an operation.

• COMM_FAILURE: This exception is raised if communication is lost while an operation is in progress,after the request was sent by the client, but before the reply from the server has been returned to theclient.

• DATA_CONVERSION: This exception is raised if an ORB cannot convert the marshaled representationof data into its native representation, or cannot convert the native representation of data into itsmarshaled representation. For example, this exception can be raised if wide character codesetconversion fails, or if an ORB cannot convert floating point values between different representations.

• MARSHAL: This exception indicates that the request or reply from the network is structurally not valid.This error typically indicates a bug in either the client-side or server-side run time. For example, if areply from the server indicates that the message contains 1000 bytes, but the actual message is shorteror longer than 1000 bytes, the ORB raises this exception.

• NO_IMPLEMENT: This exception indicates that although the operation that was called exists (it has anIDL definition), no implementation exists for that operation.

• UNKNOWN: This exception is raised if an implementation throws a non-CORBA exception, such as anexception that is specific to the implementation's programming language. It is also raised if the serverreturns a system exception that is unknown to the client. If the server uses a later version of CORBAthan the version that the client is using, and new system exceptions have been added to the laterversion this exception can happen.

Completion status and minor codesTwo pieces of data are associated with each system exception, these are described in this section.

• A completion status, which is an enumerated type that has three values: COMPLETED_YES,COMPLETED_NO and COMPLETED_MAYBE. These values indicate either that the operation wasexecuted in full, that the operation was not executed, or that the execution state cannot be determined.

• A long integer, called minor code, that can be set to some ORB vendor-specific value. CORBA alsospecifies the value of many minor codes.

Usually the completion status is not very useful. However, the minor code can be essential when thestack trace is missing. In many cases, the minor code identifies the exact location of the ORB code wherethe exception is thrown and can be used by the vendor's service team to localize the problem quickly.However, for standard CORBA minor codes, this is not always possible. For example:

org.omg.CORBA.OBJECT_NOT_EXIST: SERVANT_NOT_FOUND minor code: 4942FC11 completed: No

Minor codes are usually expressed in hexadecimal notation (except for Oracle's minor codes, which are indecimal notation) that represents four bytes. The OMG organization has assigned to each vendor a range


of 4096 minor codes. The IBM vendor-specific minor code range is 0x4942F000 through 0x4942FFFF.“CORBA minor codes” on page 313 gives diagnostic information for common minor codes.

System exceptions might also contain a string that describes the exception and other useful information.You will see this string when you interpret the stack trace.

The ORB tends to map all Java exceptions to CORBA exceptions. A runtime exception is mapped to aCORBA system exception, while a checked exception is mapped to a CORBA user exception.

More exceptions other than the CORBA exceptions could be generated by the ORB component in a codebug. All the Java unchecked exceptions and errors and others that are related to the ORB tools rmic andidlj must be considered. In this case, the only way to determine whether the problem is in the ORB, is tolook at the generated stack trace and see whether the objects involved belong to ORB packages.

Java security permissions for the ORBWhen running with a Java SecurityManager, invocation of some methods in the CORBA API classes mightcause permission checks to be made that could result in a SecurityException.

The following table shows 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.SocketPermissionconnect

org.omg.CORBA.portable.ObjectImpl

_is_a java.net.SocketPermissionconnect


_non_existent java.net.SocketPermissionconnect


OutputStream _request (String,boolean)

java.net.SocketPermissionconnect


_get_interface_def java.net.SocketPermissionconnect

org.omg.CORBA.Request

invoke java.net.SocketPermissionconnect


send_deferred java.net.SocketPermissionconnect


send_oneway java.net.SocketPermissionconnect

javax.rmi.PortableRemoteObject

narrow java.net.SocketPermissionconnect

If your program uses any of these methods, ensure that it is granted the necessary permissions.


Interpreting the stack traceWhether the ORB is part of a middleware application or you are using a Java stand-alone application (oreven an applet), you must retrieve the stack trace that is generated at the moment of failure. It could bein a log file, or in your terminal or browser window, and it could consist of several chunks of stack traces.

The following example describes a stack trace that was generated by a server ORB running in theWebSphere Application Server:

org.omg.CORBA.MARSHAL: com.ibm.ws.pmi.server.DataDescriptor; IllegalAccessException minor code: 4942F23E completed: No at com.ibm.rmi.io.ValueHandlerImpl.readValue(ValueHandlerImpl.java:199) at com.ibm.rmi.iiop.CDRInputStream.read_value(CDRInputStream.java:1429) at com.ibm.rmi.io.ValueHandlerImpl.read_Array(ValueHandlerImpl.java:625) at com.ibm.rmi.io.ValueHandlerImpl.readValueInternal(ValueHandlerImpl.java:273) at com.ibm.rmi.io.ValueHandlerImpl.readValue(ValueHandlerImpl.java:189) at com.ibm.rmi.iiop.CDRInputStream.read_value(CDRInputStream.java:1429) at com.ibm.ejs.sm.beans._EJSRemoteStatelessPmiService_Tie._invoke(_EJSRemoteStatelessPmiService_Tie.java:613) at com.ibm.CORBA.iiop.ExtendedServerDelegate.dispatch(ExtendedServerDelegate.java:515) at com.ibm.CORBA.iiop.ORB.process(ORB.java:2377) at com.ibm.CORBA.iiop.OrbWorker.run(OrbWorker.java:186) at com.ibm.ejs.oa.pool.ThreadPool$PooledWorker.run(ThreadPool.java:104) at com.ibm.ws.util.CachedThread.run(ThreadPool.java:137)

In the example, the ORB mapped a Java exception to a CORBA exception. This exception is sent back tothe client later as part of a reply message. The client ORB reads this exception from the reply. It maps itto a Java exception (java.rmi.RemoteException according to the CORBA specification) and throws thisnew exception back to the client application.

Along this chain of events, often the original exception becomes hidden or lost, as does its stack trace. Onearly versions of the ORB (for example, 1.2.x, 1.3.0) the only way to get the original exception stack tracewas to set some ORB debugging properties. Newer versions have built-in mechanisms by which all thenested stack traces are either recorded or copied around in a message string. When dealing with an oldORB release (1.3.0 and earlier), it is a good idea to test the problem on newer versions. Either theproblem is not reproducible (known bug already solved) or the debugging information that you obtain ismuch more useful.

Description stringThe example stack trace shows that the application has caught a CORBA org.omg.CORBA.MARSHALsystem exception. After the MARSHAL exception, some extra information is provided in the form of astring. This string should specify minor code, completion status, and other information that is related tothe problem. Because CORBA system exceptions are alarm bells for an unusual condition, they also hideinside what the real exception was.

Usually, the type of the exception is written in the message string of the CORBA exception. The traceshows that the application was reading a value (read_value()) when an IllegalAccessException occurredthat was associated to class com.ibm.ws.pmi.server.DataDescriptor. This information is an indication ofthe real problem and should be investigated first.

Interpreting ORB tracesThe ORB trace file contains messages, trace points, and wire tracing. This section describes the varioustypes of trace.

ORB trace messageAn example of an ORB trace message.

Here is a simple example of a message:

19:12:36.306 com.ibm.rmi.util.Version logVersions:110 P=754534:O=0:CT ORBRas[default] IBM Java ORB build orbdev-20050927

This message records the time, the package, and the method name that was called. In this case,logVersions() prints out, to the log file, the version of the running ORB.


After the first colon in the example message, the line number in the source code where that methodinvocation is done is written (110 in this case). Next follows the letter P that is associated with theprocess number that was running at that moment. This number is related (by a hash) to the time at whichthe ORB class was loaded in that process. It is unlikely that two different processes load their ORBs at thesame time.

The following O=0 (alphabetic O = numeric 0) indicates that the current instance of the ORB is the firstone (number 0). CT specifies that this is the main (control) thread. Other values are: LT for listener thread,RT for reader thread, and WT for worker thread.

The ORBRas field shows which RAS implementation the ORB is running. It is possible that when the ORBruns inside another application (such as a WebSphere application), the ORB RAS default code is replacedby an external implementation.

The remaining information is specific to the method that has been logged while executing. In this case,the method is a utility method that logs the version of the ORB.

This example of a possible message shows the logging of entry or exit point of methods, such as:

14:54:14.848 com.ibm.rmi.iiop.Connection <init>:504 LT=0:P=650241:O=0:port=1360 ORBRas[default] Entry ..... 14:54:14.857 com.ibm.rmi.iiop.Connection <init>:539 LT=0:P=650241:O=0:port=1360 ORBRas[default] Exit

In this case, the constructor (that is, <init>) of the class Connection is called. The tracing records when itstarted and when it finished. For operations that include the java.net package, the ORBRas logger printsalso the number of the local port that was involved.

Comm tracesAn example of comm (wire) tracing.

Here is an example of comm tracing:

// Summary of the message containing name-value pairs for the principal fields OUT GOING: Request Message // It is an out going request, therefore we are dealing with a clientDate: 31 January 2003 16:17:34 GMT Thread Info: P=852270:O=0:CT Local Port: 4899 (0x1323) Local IP: 9.20.178.136 Remote Port: 4893 (0x131D) Remote IP: 9.20.178.136 GIOP Version: 1.2 Byte order: big endian

Fragment to follow: No // This is the last fragment of the request Message size: 276 (0x114) --

Request ID: 5 // Request Ids are in ascending sequence Response Flag: WITH_TARGET // it means we are expecting a reply to this request Target Address: 0Object Key: length = 26 (0x1A) // the object key is created by the server when exporting // the servant and retrieved in the IOR using a naming service 4C4D4249 00000010 14F94CA4 00100000 00080000 00000000 0000 Operation: message // That is the name of the method that the client invokes on the servant Service Context: length = 3 (0x3) // There are three service contextsContext ID: 1229081874 (0x49424D12) // Partner version service context. IBM only Context data: length = 8 (0x8) 00000000 14000005

Context ID: 1 (0x1) // Codeset CORBA service context Context data: length = 12 (0xC) 00000000 00010001 00010100

Context ID: 6 (0x6) // Codebase CORBA service context Context data: length = 168 (0xA8) 00000000 00000028 49444C3A 6F6D672E 6F72672F 53656E64 696E6743 6F6E7465 78742F43 6F646542 6173653A 312E3000 00000001 00000000 0000006C 00010200 0000000D 392E3230 2E313738 2E313336


00001324 0000001A 4C4D4249 00000010 15074A96 00100000 00080000 00000000 00000000 00000002 00000001 00000018 00000000 00010001 00000001 00010020 00010100 00000000 49424D0A 00000008 00000000 14000005 Data Offset: 11c // raw data that goes in the wire in numbered rows of 16 bytes and the corresponding ASCII decoding 0000: 47494F50 01020000 00000114 00000005 GIOP............ 0010: 03000000 00000000 0000001A 4C4D4249 ............LMBI 0020: 00000010 14F94CA4 00100000 00080000 ......L......... 0030: 00000000 00000000 00000008 6D657373 ............mess 0040: 61676500 00000003 49424D12 00000008 age.....IBM..... 0050: 00000000 14000005 00000001 0000000C ................ 0060: 00000000 00010001 00010100 00000006 ................ 0070: 000000A8 00000000 00000028 49444C3A ...........(IDL: 0080: 6F6D672E 6F72672F 53656E64 696E6743 omg.org/SendingC 0090: 6F6E7465 78742F43 6F646542 6173653A ontext/CodeBase: 00A0: 312E3000 00000001 00000000 0000006C 1.0............l 00B0: 00010200 0000000D 392E3230 2E313738 ........9.20.178 00C0: 2E313336 00001324 0000001A 4C4D4249 .136...$....LMBI 00D0: 00000010 15074A96 00100000 00080000 ......J......... 00E0: 00000000 00000000 00000002 00000001 ................ 00F0: 00000018 00000000 00010001 00000001 ................ 0100: 00010020 00010100 00000000 49424D0A ... ........IBM. 0110: 00000008 00000000 14000005 00000000 ................

Note: The italic comments that start with a double slash have been added for clarity; they are not part ofthe traces.

In this example trace, you can see a summary of the principal fields that are contained in the message,followed by the message itself as it goes in the wire. In the summary are several field name-value pairs.Each number is in hexadecimal notation.

For details of the structure of a GIOP message, see the CORBA specification, chapters 13 and 15: https://www.omg.org/cgi-bin/doc?formal/99-10-07.

Client or serverFrom the first line of the summary of the message, you can identify whether the host to which this tracebelongs is acting as a server or as a client. OUT GOING means that the message has been generated onthe workstation where the trace was taken and is sent to the wire.

In a distributed-object application, a server is defined as the provider of the implementation of theremote object to which the client connects. In this work, however, the convention is that a client sends arequest while the server sends back a reply. In this way, the same ORB can be client and server indifferent moments of the rmi-iiop session.

The trace shows that the message is an outgoing request. Therefore, this trace is a client trace, or at leastpart of the trace where the application acts as a client.

Time information and host names are reported in the header of the message.

The Request ID and the Operation (message in this case) fields can be very helpful when multiple threadsand clients destroy the logical sequence of the traces.

The GIOP version field can be checked if different ORBs are deployed. If two different ORBs supportdifferent versions of GIOP, the ORB that is using the more recent version of GIOP should fall back to acommon level. By checking that field, however, you can easily check whether the two ORBs speak thesame language.

Service contextsThe header also records three service contexts, each consisting of a context ID and context data.

A service context is extra information that is attached to the message for purposes that can be vendor-specific such as the IBM Partner version that is described in the IOR in Chapter 14, “The ORB,” on page277.


https://www.omg.org/cgi-bin/doc?formal/99-10-07


Usually, a security implementation makes extensive use of these service contexts. Information about anaccess list, an authorization, encrypted IDs, and passwords could travel with the request inside a servicecontext.

Some CORBA-defined service contexts are available. One of these is the Codeset.

In the example, the codeset context has ID 1 and data 00000000 00010001 00010100. Bytes 5through 8 specify that characters that are used in the message are encoded in ASCII (00010001 is thecode for ASCII). Bytes 9 through 12 instead are related to wide characters.

The default codeset is UTF8 as defined in the CORBA specification, although almost all Windows andUNIX platforms typically communicate through ASCII. i5/OS and mainframes such as IBM Z are based onthe IBM EBCDIC encoding.

The other CORBA service context, which is present in the example, is the Codebase service context. Itstores information about how to call back to the client to access resources in the client such as stubs, andclass implementations of parameter objects that are serialized with the request.

Common problemsThis section describes some of the problems that you might find.

ORB application hangsOne of the worst conditions is when the client, or server, or both, hang. If a hang occurs, the most likelycondition (and most difficult to solve) is a deadlock of threads. In this condition, it is important to knowwhether the workstation on which you are running has more than one CPU, and whether your CPU is usingSimultaneous Multithreading (SMT).

A simple test that you can do is to keep only one CPU running, disable SMT, and see whether the problemdisappears. If it does, you know that you must have a synchronization problem in the application.

Also, you must understand what the application is doing while it hangs. Is it waiting (low CPU usage), or itis looping forever (almost 100% CPU usage)? Most of the cases are a waiting problem.

You can, however, still identify two cases:

• Typical deadlock• Standby condition while the application waits for a resource to arrive

An example of a standby condition is where the client sends a request to the server and stops whilewaiting for the reply. The default behavior of the ORB is to wait indefinitely.

You can set a couple of properties to avoid this condition:

• com.ibm.CORBA.LocateRequestTimeout• com.ibm.CORBA.RequestTimeout

When the property com.ibm.CORBA.enableLocateRequest is set to true (the default is false), theORB first sends a short message to the server to find the object that it needs to access. This first contactis the Locate Request. You must now set the LocateRequestTimeout to a value other than 0 (which isequivalent to infinity). A good value could be something around 5000 ms.

Also, set the RequestTimeout to a value other than 0. Because a reply to a request is often large, allowmore time for the reply, such as 10,000 ms. These values are suggestions and might be too low for slowconnections. When a request runs out of time, the client receives an explanatory CORBA exception.

When an application hangs, consider also another property that is calledcom.ibm.CORBA.FragmentTimeout. This property was introduced in IBM ORB 1.3.1, when the concept offragmentation was implemented to increase performance. You can now split long messages into smallchunks or fragments and send one after the other over the net. The ORB waits for 30 seconds (defaultvalue) for the next fragment before it throws an exception. If you set this property, you disable thistimeout, and problems of waiting threads might occur.

If the problem seems to be a deadlock or hang, capture the Javadump information. After capturing theinformation, wait for a minute or so, and do it again. A comparison of the two snapshots shows whether


any threads have changed state. For information about how to do this operation, see Using Javadumps inthe J9 VM reference.

In general, stop the application, enable the orb traces and restart the application. When the hang isreproduced, the partial traces that can be retrieved can be used by the IBM ORB service team to helpunderstand where the problem is.

Starting the client before the server is runningIf the client is started before the server is running, an error occurs when you run the client.

An example of the error messages that are generated from this process.

This operation outputs:

(org.omg.CORBA.COMM_FAILURE)Hello Client exception: org.omg.CORBA.COMM_FAILURE:minor code:1 completed:No at com.ibm.rmi.iiop.ConnectionTable.get(ConnectionTable.java:145) at com.ibm.rmi.iiop.ConnectionTable.get(ConnectionTable.java:77) at com.ibm.rmi.iiop.GIOPImpl.createRequest(GIOPImpl.java:98) at com.ibm.rmi.iiop.GIOPImpl.createRequest(GIOPImpl.java:75) at com.ibm.rmi.corba.ClientDelegate.createRequest(ClientDelegate.java:440) at com.ibm.rmi.corba.ClientDelegate.is_a(ClientDelegate.java:571) at org.omg.CORBA.portable.ObjectImpl._is_a(ObjectImpl.java:74) at org.omg.CosNaming.NamingContextHelper.narrow(NamingContextHelper.java:58) com.sun.jndi.cosnaming.CNCtx.callResolve(CNCtx.java:327)

Client and server are running, but not naming serviceAn example of the error messages that are generated from this process.

The output is:

Hello Client exception:Cannot connect to ORBJavax.naming.CommunicationException: Cannot connect to ORB.Root exception is org.omg.CORBA.COMM_FAILURE minor code:1 completed:No at com.ibm.rmi.iiop.ConnectionTable.get(ConnectionTable.java:145) at com.ibm.rmi.iiop.ConnectionTable.get(ConnectionTable.java:77) at com.ibm.rmi.iiop.GIOPImpl.createRequest(GIOPImpl.java:98) at com.ibm.rmi.iiop.GIOPImpl.createRequest(GIOPImpl.java:75) at com.ibm.rmi.corba.ClientDelegate.createRequest(ClientDelegate.java:440) at com.ibm.rmi.corba.InitialNamingClient.resolve(InitialNamingClient.java:197) at com.ibm.rmi.corba.InitialNamingClient.cachedInitialReferences(InitialNamingClient.j at com.ibm.rmi.corba.InitialNamingClient.resolve_initial_references(InitialNamingClien at com.ibm.rmi.corba.ORB.resolve_initial_references(ORB.java:1269) .........

You must start the Java IDL name server before an application or applet starts that uses its namingservice. Installation of the Java IDL product creates a script (Solaris: tnameserv) or executable file thatstarts the Java IDL name server.

Start the name server so that it runs in the background. If you do not specify otherwise, the name serverlistens on port 2809 for the bootstrap protocol that is used to implement the ORBresolve_initial_references() and list_initial_references() methods.

Specify a different port, for example, 1050, as follows:

tnameserv -ORBInitialPort 1050

Clients of the name server must be made aware of the new port number. Do this by setting theorg.omg.CORBA.ORBInitialPort property to the new port number when you create the ORB object.

Running the client with MACHINE2 (client) unplugged from the networkAn example of the error messages that are generated when the client has been unplugged form thenetwork.

Your output is:

(org.omg.CORBA.TRANSIENT CONNECT_FAILURE)

Hello Client exception:Problem contacting address:corbaloc:iiop:machine2:2809/NameService


javax.naming.CommunicationException:Problem contacting address:corbaloc:iiop:machine2:2809/N is org.omg.CORBA.TRANSIENT:CONNECT_FAILURE (1)minor code:4942F301 completed:No at com.ibm.CORBA.transport.TransportConnectionBase.connect(TransportConnectionBase.jav at com.ibm.rmi.transport.TCPTransport.getConnection(TCPTransport.java:178) at com.ibm.rmi.iiop.TransportManager.get(TransportManager.java:79) at com.ibm.rmi.iiop.GIOPImpl.createRequest(GIOPImpl.java:131) at com.ibm.rmi.iiop.GIOPImpl.createRequest(GIOPImpl.java:98) at com.ibm.CORBA.iiop.ClientDelegate._createRequest(ClientDelegate.java:2096) at com.ibm.CORBA.iiop.ClientDelegate.createRequest(ClientDelegate.java:1264) at com.ibm.CORBA.iiop.ClientDelegate.createRequest(ClientDelegate.java:1177) at com.ibm.rmi.corba.InitialNamingClient.resolve(InitialNamingClient.java:252) at com.ibm.rmi.corba.InitialNamingClient.cachedInitialReferences(InitialNamingClient.j at com.ibm.rmi.corba.InitialNamingClient.resolve_initial_references(InitialNamingClien at com.ibm.rmi.corba.InitialReferenceClient.resolve_initial_references(InitialReferenc at com.ibm.rmi.corba.ORB.resolve_initial_references(ORB.java:3211) at com.ibm.rmi.iiop.ORB.resolve_initial_references(ORB.java:523) at com.ibm.CORBA.iiop.ORB.resolve_initial_references(ORB.java:2898) ..........

Autonomic connection management issues

The ORB automatically manages the number of concurrent connections to the server endpoint (targethost-port). The following problems might be seen:

• Because many connections can be created between the client and the server ORBs, you might receive aConnectException error and a message to indicate that the connection is refused. This problem canoccur when the queue depth for the server socket is exhausted. You can increase the queue depth byusing the system property com.ibm.CORBA.ServerSocketQueueDepth. The default value for thisproperty is 50.

• You might observe an OutofMemory error when a client ORB talks to multiple server ORBs and theclient ORB receives a high number of concurrent requests. This problem can be caused by autonomicconnection management because of the increase in the number of connections that the client ORBcreates.

You can control the number of concurrent connections by using thecom.ibm.CORBA.ConnectionMultiplicity system property. For more information about thisproperty, see “Using the ORB” on page 291.

IBM ORB service: collecting dataThis section describes how to collect data about ORB problems.

If after all these verifications, the problem is still present, collect at all nodes of the problem the followinginformation:

• Operating system name and version.• Output of java -version.• Output of java com.ibm.CORBA.iiop.Version.• Output of rmic -iiop -version, if rmic is involved.• ASV build number (WebSphere Application Server only).• If you think that the problem is a regression, include the version information for the most recent known

working build and for the failing build.• If this is a runtime problem, collect debug and communication traces of the failure from each node in

the system (as explained earlier in this section).• If the problem is in rmic -iiop or rmic -idl, set the options: -J-Djavac.dump.stack=1 -Xtrace, and capture the output.

• Typically this step is not necessary. If it looks like the problem is in the buffer fragmentation code, IBMservice will return the defect asking for an additional set of traces, which you can produce by executingwith -Dcom.ibm.CORBA.FragmentSize=0.

A testcase is not essential, initially. However, a working testcase that demonstrates the problem by usingonly the Java SDK classes will speed up the resolution time for the problem.


Preliminary testsThe ORB is affected by problems with the underlying network, hardware, and JVM.

When a problem occurs, the ORB can throw an org.omg.CORBA.* exception, some text that describes thereason, a minor code, and a completion status. Before you assume that the ORB is the cause of problem,do the following checks:

• Check that the scenario can be reproduced in a similar configuration.• Check that the JIT is disabled (see Diagnosing a JIT or AOT problem in the J9 VM reference).

Also:

• Disable additional CPUs.• Disable Simultaneous Multithreading (SMT) where possible.• Eliminate memory dependencies with the client or server. The lack of physical memory can be the

cause of slow performance, apparent hangs, or crashes. To remove these problems, ensure that youhave a reasonable headroom of memory.

• Check physical network problems (firewalls, comm links, routers, DNS name servers, and so on). Theseare the major causes of CORBA COMM_FAILURE exceptions. As a test, ping your own workstationname.

• If the application is using a database such as DB2, switch to the most reliable driver. For example, toisolate DB2 AppDriver, switch to Net Driver, which is slower and uses sockets, but is more reliable.

CORBA supportThe Java Platform, Standard Edition (JSE) supports, at a minimum, the specifications that are defined inthe compliance document from Oracle. In some cases, the IBM JSE ORB supports more recent versionsof the specifications.

The minimum specifications supported are defined in the Official Specifications for CORBA support inJava SE 6: https://docs.oracle.com/javase/8/docs/api/org/omg/CORBA/doc-files/compliance.html.

Support for GIOP 1.2This SDK supports all versions of GIOP, as defined by chapters 13 and 15 of the CORBA 2.3.1specification, OMG document formal/99-10-07.


Bidirectional GIOP is not supported.

Support for Portable Interceptors

This SDK supports Portable Interceptors, as defined by the OMG in the document ptc/01–03–04, whichyou can obtain from:

https://www.omg.org/cgi-bin/doc?ptc/01–03-04

Portable Interceptors are hooks into the ORB that ORB services can use to intercept the normal flow ofexecution of the ORB.

Support for Interoperable Naming Service

This SDK supports the Interoperable Naming Service, as defined by the OMG in the document ptc/00-08-07, which you can obtain from:

https://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 noORBInitialPort parameter is given, has changed from 900 to 2809, which is the port number that isregistered with the IANA (Internet Assigned Number Authority) for a CORBA Naming Service. Programsthat depend on this default might have to be updated to work with this version.


https://docs.oracle.com/javase/8/docs/api/org/omg/CORBA/doc-files/compliance.html




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

The ORB supports the -ORBInitRef and -ORBDefaultInitRef parameters that are defined by theInteroperable Naming Service specification, and the ORB::string_to_object operation now supportsthe ObjectURL string formats (corbaloc: and corbaname:) that are defined by the InteroperableNaming Service specification.

The OMG specifies a method ORB::register_initial_reference to register a service with theInteroperable Naming Service. However, this method is not available in the Oracle Java Core API at thisrelease. Programs that have to register a service in the current version must invoke this method on theIBM 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(), andserviceRef is a CORBA Object, which is connected to the ORB. This mechanism is an interim one, and isnot compatible with future versions or portable to non-IBM ORBs.

ORB implementation classesA list of the 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 theimplementation classes directly. For portability, make references only to the CORBA API classes, and notto the implementation. These values might be changed in future releases.

CORBA system property command-line optionsUse the system property command-line options to set up your system.-D<name>=<value>


-Dcom.ibm.CORBA.AcceptTimeoutThis system property controls the amount of time that a ServerSocket waits in a call to accept().

-Dcom.ibm.CORBA.AcceptTimeout=<ms>Where <ms> is the wait time in milliseconds. The acceptable range is 0 - 5000. If this property is notset, a default value of 0 is used, which prevents a timeout. If the property is set but the value that isprovided is not valid, a value of 5000 is used.

-Dcom.ibm.CORBA.AllowUserInterruptWhen this property is set to true, remote method calls can be interrupted with a Thread.interrupt()call.

-Dcom.ibm.CORBA.AllowUserInterrupt=trueWhen set, the thread that is waiting for the call to return is stopped. Interrupting a call in this waycauses a RemoteException to be thrown, containing a CORBA.NO_RESPONSE runtime exceptionwith the RESPONSE_INTERRUPTED minor code. If this property is not set, the default behavior is toignore any Thread.interrupt() calls that are received while the ORB waits for the call to finish.


-Dcom.ibm.CORBA.BufferSizeThis system property sets the number of bytes of a General Inter-ORB Protocol (GIOP) message that isread from a socket on the first attempt.

-Dcom.ibm.CORBA.BufferSize=<bytes>Where <bytes> is in the range is 0 - 2147483647. The default size is 2048. A larger buffer sizeincreases the probability of reading the whole message in one attempt. Such an action might improveperformance. The minimum size that can be used is 24 bytes.

-Dcom.ibm.CORBA.CommTraceThis system property turns on wire tracing for the Object Request Broker (ORB), which is also known asComm tracing.

-Dcom.ibm.CORBA.CommTrace=true|falseWhen you set this option to true, every incoming and outgoing GIOP message is sent to the trace log.You can set this property independently from -Dcom.ibm.CORBA.Debug. Use this property if youwant to look only at the flow of information, and you do not want to debug the internal information.The default value for this property is false.

Related reference“-Dcom.ibm.CORBA.Debug” on page 307This system property enables debugging for the Object Request Broker (ORB) and includes tracingoptions that control how much information is recorded.“-Dcom.ibm.CORBA.Debug.Component” on page 308This system property can be used with -Dcom.ibm.CORBA.Debug=true to generate trace output forspecific Object Request Broker (ORB) subcomponents such as MARSHAL or DISPATCH. This finer level oftracing helps you debug problems with ORB operations.“-Dcom.ibm.CORBA.Debug.Output” on page 309This system property redirects Object Request Broker (ORB) trace output to a file, which is known as atrace log.

-Dcom.ibm.CORBA.ConnectionMultiplicityThis system property sets the number of concurrent connections to the server endpoint (target host-port).

-Dcom.ibm.CORBA.ConnectionMultiplicity=<n>Where <n> is in the range 0 - 2147483647. Setting this value to a number <n> greater than onecauses a client ORB to multiplex communications to each server ORB. There can be no more than <n>concurrent sockets to each server ORB at any one time. This value might increase throughput undercertain circumstances, particularly when a long-running, multithreaded process is acting as a client.If this property is not set, autonomic connection management is turned on and the ORB automaticallymanages the number of concurrent connections to the server endpoint (target host-port).

Read the following article for best practices on tuning this property: https://www.ibm.com/support/docview.wss?uid=swg21669697

-Dcom.ibm.CORBA.ConnectTimeoutThis system property controls the maximum amount of time that the ORB waits when a connection isopened to another ORB.

-Dcom.ibm.CORBA.AcceptTimeout=<s>Where <s> is the wait time in seconds. The acceptable range is 0 - 300. By default, a timeout is notspecified.

-Dcom.ibm.CORBA.DebugThis system property enables debugging for the Object Request Broker (ORB) and includes tracingoptions that control how much information is recorded.

-Dcom.ibm.CORBA.Debug=valueWhere value is one of the following options:




falseNo output is produced. This option is the default value.

trueMessages and traces for the entire ORB code flow

Note: If you use this property without specifying a value, tracing is enabled.

If you want to limit tracing to specific subcomponents of ORB, you can also specify the -Dcom.ibm.CORBA.Debug.Component system property.Related reference“-Dcom.ibm.CORBA.Debug.Component” on page 308This system property can be used with -Dcom.ibm.CORBA.Debug=true to generate trace output forspecific Object Request Broker (ORB) subcomponents such as MARSHAL or DISPATCH. This finer level oftracing helps you debug problems with ORB operations.“-Dcom.ibm.CORBA.Debug.Output” on page 309This system property redirects Object Request Broker (ORB) trace output to a file, which is known as atrace log.“-Dcom.ibm.CORBA.CommTrace” on page 307This system property turns on wire tracing for the Object Request Broker (ORB), which is also known asComm tracing.

-Dcom.ibm.CORBA.Debug.ComponentThis system property can be used with -Dcom.ibm.CORBA.Debug=true to generate trace output forspecific Object Request Broker (ORB) subcomponents such as MARSHAL or DISPATCH. This finer level oftracing helps you debug problems with ORB operations.

-Dcom.ibm.CORBA.Debug.Component=nameWhere name can be one of the following ORB subcomponents:

• DISPATCH• MARSHAL• TRANSPORT• CLASSLOADER• ALL

When you want to trace more than one of these subcomponents, each subcomponent must beseparated by a comma. The default value is ALL.

Note: This option has no effect unless it is used with the system property -Dcom.ibm.CORBA.Debug=true.

The following setting enables tracing for the DISPATCH, TRANSPORT, and CLASSLOADER components:

-Dcom.ibm.CORBA.Debug=true -Dcom.ibm.CORBA.Debug.Component=DISPATCH,TRANSPORT,CLASSLOADER

Related reference“-Dcom.ibm.CORBA.Debug” on page 307This system property enables debugging for the Object Request Broker (ORB) and includes tracingoptions that control how much information is recorded.“-Dcom.ibm.CORBA.Debug.Output” on page 309This system property redirects Object Request Broker (ORB) trace output to a file, which is known as atrace log.“-Dcom.ibm.CORBA.CommTrace” on page 307


This system property turns on wire tracing for the Object Request Broker (ORB), which is also known asComm tracing.

-Dcom.ibm.CORBA.Debug.OutputThis system property redirects Object Request Broker (ORB) trace output to a file, which is known as atrace log.

-Dcom.ibm.CORBA.Debug.Output=filenameWhere filename is the name you want to specify for your trace log. If this property is not specified orthe value of filename is empty, the file name defaults to the following format:

orbtrc.DDMMYYYY.HHmm.SS.txt

Where:

• D = day• M = month• Y = year• H = hour (24 hour format)• M = minutes• S = seconds

If the application does not have the privilege that it requires to write to a file, the trace entries go tostderr.

Related reference“-Dcom.ibm.CORBA.Debug” on page 307This system property enables debugging for the Object Request Broker (ORB) and includes tracingoptions that control how much information is recorded.“-Dcom.ibm.CORBA.Debug.Component” on page 308This system property can be used with -Dcom.ibm.CORBA.Debug=true to generate trace output forspecific Object Request Broker (ORB) subcomponents such as MARSHAL or DISPATCH. This finer level oftracing helps you debug problems with ORB operations.“-Dcom.ibm.CORBA.CommTrace” on page 307This system property turns on wire tracing for the Object Request Broker (ORB), which is also known asComm tracing.

-Dcom.ibm.CORBA.enableLocateRequestSetting this system property causes the ORB to send a LocateRequest before the actual Request.

-Dcom.ibm.CORBA.enableLocateRequest=[true|false]The default for this option is false.

-Dcom.ibm.CORBA.FragmentSizeThis system property controls General Inter-ORB Protocol (GIOP) 1.2 fragmentation.

-Dcom.ibm.CORBA.FragmentSize=<bytes>Where <bytes> is in the range is 0 - 2147483647. The default size is 4096 bytes. The size that isspecified is rounded down to the nearest multiple of 8, with a minimum size of 64 bytes. To turn offmessage fragmentation, set the value to 0.

-Dcom.ibm.CORBA.FragmentTimeoutThis system property controls the maximum length of time for which the ORB waits for second andsubsequent message fragments before the ORB times out.

-Dcom.ibm.CORBA.FragmentTimeout=<ms>Where <ms> is milliseconds in the range 0 - 600000. The default time is 300000 milliseconds. Set thevalue to 0 if a timeout is not required.


-Dcom.ibm.CORBA.GIOPAddressingDispositionThis system property sets the addressing disposition for a General Inter-ORB Protocol (GIOP) 1.2Request, LocateRequest, Reply, or LocateReply.

-Dcom.ibm.CORBA.GIOPAddressingDisposition=[0|1|2]Where the following options apply:

• 0 = Object Key• 1 = GIOP Profile• 2 = Full IOR

If this property is not set or is passed a value that is not valid, a default of 0 is used.

-Dcom.ibm.CORBA.InitialReferencesURLUse this property if you do not have a bootstrap server and want to have a file on the web server thatserves the purpose.

-Dcom.ibm.CORBA.InitialReferencesURL=<url>Where <url> is a correctly formed URL, for example, http://w3.mycorp.com/InitRefs.file.The InitRefs.file file contains a name and value pair such asNameService=<stringified_IOR>. If you specify this property, the ORB does not attempt thebootstrap approach.

Note: This property is deprecated.

-Dcom.ibm.CORBA.ListenerPortThis system property sets the port on which the server listens for incoming requests.

-Dcom.ibm.CORBA.ListenerPort=<port>Where <port> is in the range is 0 - 2147483647. By default, the next available port is selected. If thisproperty is set, the ORB starts listening as soon as it is initialized. Otherwise, the ORB starts listeningonly when required.

-Dcom.ibm.CORBA.LocalHostThis system property sets the host name or IP address of the system on which the ORB is running.

-Dcom.ibm.CORBA.LocalHost=<host>Where <host> is an IP address or a host name. If this property is not set, retrieve the local host bycalling InetAddress.getLocalHost().getHostAddress(). The local host name is used by theserver-side ORB to place the host name of the server into the IOR of a remote-able object.

-Dcom.ibm.CORBA.LocateRequestTimeoutThis system property defines the number of seconds to wait before the ORB times out on aLocateRequest message.

-Dcom.ibm.CORBA.LocateRequestTimeout=<s>Where <s> is seconds in the range 0 - 2147483647. The default time is 0, which prevents timing out.

-Dcom.ibm.CORBA.MaxOpenConnectionsThis system property determines the maximum number of in-use connections that are to be kept in theconnection cache table at any one time.

-Dcom.ibm.CORBA.MaxOpenConnections=<number>Where <number> is the number of connections in the range 0 - 2147483647. The default value is240.

-Dcom.ibm.CORBA.MinOpenConnectionsThis system property determines the desired minimum number of in-use connections that are to be keptin the connection cache table at any one time.

-Dcom.ibm.CORBA.MinOpenConnections=<number>Where <number> is the number of connections in the range 0 - 2147483647. The default value is100.


Note: The ORB cleans up only connections that are not busy from the connection cache table, if thesize is of the table is larger than <number>.

-Dcom.ibm.CORBA.NoLocalInterceptorsThis system property can be used to prevent the use of local portable interceptors.

-Dcom.ibm.CORBA.NoLocalInterceptors=[true|false]The default value is false. The expected result is improved performance if interceptors are notrequired when the ORB connects to a co-located object.

-Dcom.ibm.CORBA.ORBCharEncodingThis system property sets the native encoding set for the ORB.

-Dcom.ibm.CORBA.ORBCharEncoding=<encoding>Where <encoding> is a native encoding set. The default value is ISO8859_1.

-Dcom.ibm.CORBA.ORBPropertyFilePathUse this system property to set the location of the ORB properties file.

-Dcom.ibm.CORBA.ORBPropertyFilePath=<ORB.properties_file_path>The value of <ORB.properties_file_path> must be the absolute path to the properties file.

-Dcom.ibm.CORBA.ORBWCharDefaultThis system property indicates the wchar code set that should be used with other ORBs that do notpublish a wchar code set.

-Dcom.ibm.CORBA.ORBWCharDefault=<code_set>Where <code_set> is a wchar code set. The default value is UCS2.

-Dcom.ibm.CORBA.requestRetriesCountThis system property governs the number of request retries that are attempted.

-Dcom.ibm.CORBA.requestRetriesCount=<value>Where <value> is in the range 1 - 10. The default value is 1.Use this property with the -Dcom.ibm.CORBA.requestRetriesDelay system property to controlORB retry behavior.

Related reference“-Dcom.ibm.CORBA.requestRetriesDelay” on page 311This property determines the time delay in milliseconds (ms) between two retries.

-Dcom.ibm.CORBA.requestRetriesDelayThis property determines the time delay in milliseconds (ms) between two retries.

-Dcom.ibm.CORBA.requestRetriesDelay=<ms>Where <ms> is in the range 0 - 60000 milliseconds. The default value is 0.Use this property with the -Dcom.ibm.CORBA.requestRetriesCount system property to controlORB retry behavior.

Related reference“-Dcom.ibm.CORBA.requestRetriesCount” on page 311This system property governs the number of request retries that are attempted.

-Dcom.ibm.CORBA.RequestTimeoutThis system property defines the number of seconds to wait before the ORB times out on a Requestmessage.

-Dcom.ibm.CORBA.RequestTimeout=<s>Where <s> is seconds in the range 0 - 2147483647. The default value is 0, which prevents timing out.


-Dcom.ibm.CORBA.SendingContextRunTimeSupportedThis system property determines whether the CodeBaseSendingContextRunTime service is operating.

-Dcom.ibm.CORBA.SendingContextRunTimeSupported=[true|false]The default value is true. When set to false, the ORB does not attach a SendingContextRuntimeservice context to outgoing messages.

-Dcom.ibm.CORBA.SendVersionIdentifierThis system property causes the ORB to send an initial dummy request in order to determine, from theresponse, the partner version of the remote ORB server.

-Dcom.ibm.CORBA.SendVersionIdentifier=[true|false]The default value is false.

-Dcom.ibm.CORBA.ServerSocketQueueDepthThis system property controls the maximum queue length for incoming connection requests.

-Dcom.ibm.CORBA.ServerSocketQueueDepth=<length>Where <length> is in the range is 50 - 2147483647. If a connection request arrives when the queue isfull, the connection is refused. If the property is not set, a default length of 0 is used. If the property isnot valid, 50 is used.

-Dcom.ibm.CORBA.ShortExceptionDetailsThis system property controls the method by which information is returned following a CORBA systemexception.

-Dcom.ibm.CORBA.ShortExceptionDetails=[false | true]When a CORBA SystemException reply is created, the ORB includes, by default, the Java stacktrace of the exception in an associated ExceptionDetailMessage service context. If you set thisproperty to any value, the ORB includes a toString of the Exception instead. The default value forthis property is false.

-Dcom.ibm.tools.rmic.iiop.DebugThis system property causes the rmic compiler to report the mappings of fully qualified class names toshort names, which is useful for debugging purposes.

-Dcom.ibm.tools.rmic.iiop.Debug=[true | false]The rmic compiler automatically creates import statements in the classes that it generates. If set totrue, this property causes rmic to report the mappings of fully qualified class names to short names.The default value is false.

-Dcom.ibm.tools.rmic.iiop.SkipImportsThis system property causes the rmic compiler to generate classes only with fully qualified names.

-Dcom.ibm.tools.rmic.iiop.Debug=[true | false]The default value is false.

-Dorg.omg.CORBA.ORBidThis system property uniquely identifies an ORB in its address space.

-Dorg.omg.CORBA.ORBid=<string>Where string is a unique identifier. The default value is a randomly generated number that is unique inthe JVM to the ORB.

-Dorg.omg.CORBA.ORBListenEndpointsThis system property identifies the set of endpoints on which the ORB listens for requests. Endpointsconsist of a hostname or IP address, and optionally a port.

-Dorg.omg.CORBA.ORBListenEndpoints=<value>Where value is a string of the form hostname:portnumber, where the :portnumber component isoptional. IPv6 addresses must be surrounded by brackets (for example, [::1]:1020). Specifymultiple endpoints in a comma-separated list.


Note: Some versions of the ORB support only the first endpoint in a multiple endpoint list.

If this property is not set, the port number is set to 0 and the host address is retrieved by callingInetAddress.getLocalHost().getHostAddress(). If you specify only the host address, theport number is set to 0. If you want to set only the port number, you must also specify the host. Youcan specify the host name as the default host name of the ORB. The default host name is localhost.

-Dorg.omg.CORBA.ORBServerIdThis system property identifies the ORB server. Assign the same value for this property to all ORBscontained in the same server. It is included in all Interoperable Object References (IORs) exported by theserver.

-Dorg.omg.CORBA.ORBServerId=<value>Where value is in the range 0 - 2147483647.

CORBA minor codesThis appendix gives definitions of the most common OMG- and IBM-defined CORBA system exceptionminor codes that the Java ORB from IBM uses.

See “Completion status and minor codes” on page 297 for more information about minor codes.

When an error occurs, you might find additional details in the ORB FFDC log. By default, the Java ORBfrom IBM creates an FFDC log with a filename in the format of orbtrc.DDMMYYY.HHmm.SS.txt. If theORB is operating in the WebSphere Application Server or other IBM product, see the publications for thatproduct to determine the location of the FFDC log.

org.omg.CORBA.BAD_OPERATIONA method was called on an object that does not support that method.

For example, this exception is thrown if the extract() method is called on an IBM ORB-generatedHelper class, but the type of the provided Any object does not match the type that is expected by theHelper class.

For example, consider the following interface definition language (IDL) definition:

struct StructuredEvent { string header; any remainder_of_body; };

struct ExpectedRemainderOfBody { string desc1; string desc2 };

typedef string UnexpectedActualRemainderOfBody;

Assuming the server is designed to return a StructuredEvent object as a result of an operation that iscalled by the client, the type of the remainder_of_body field should be anExpectedRemainderOfBody object. The client side then calls theExpectedRemainderOfBodyHelper.extract() method by passing the remainder_of_body field.

If the server does not behave as designed but instead puts an UnexpectedActualRemainderOfBodyobject in the remainder_of_body field, this exception is thrown when the client calls theExpectedRemainderOfBodyHelper.extract() method.

org.omg.CORBA.BAD_PARAMAn invalid parameter was passed. For example, the parameter is out of range, or is a null values orpointer.

4942f216 NULL_PI_NAME

Explanation

One of the following methods has been called:


org.omg.PortableInterceptor.ORBInitInfoOperations.add_ior_interceptor

org.omg.PortableInterceptor.ORBInitInfoOperations.add_client_request_interceptor

org.omg.PortableInterceptor.ORBInitInfoOperations.add_server_request_interceptor

The name() method of the interceptor input parameter returned a null string.

User response

Change the interceptor implementation so that the name() method returns a non-null string. The name attributecan be an empty string if the interceptor is anonymous, but it cannot be null.

org.omg.CORBA.COMM_FAILUREA communication failure occurred during an operation. This exception is raised after the client sends arequest, but before the server returns a reply.

4942f308 CONN_CLOSE_REBIND

Explanation

An attempt has been made to write to a TCP/IPconnection that is closing.

User response

Ensure that the completion status that is associatedwith the minor code is NO, then reissue the request.

4942f306 CONN_PURGE_ABORT

Explanation

An unrecoverable error occurred on a TCP/IPconnection. All outstanding requests are cancelled.Errors include:

• A GIOP MessageError or unknown message type• An IOException that is received while data is being

read from the socket• An unexpected error or exception that occurs during

message processing

User response

Investigate each request and reissue if necessary. Ifthe problem occurs again, enable ORB, networktracing, or both, to determine the cause of the failure.

org.omg.CORBA.INTERNALAn internal ORB failure, such as corruption of internal data structures, occurred.

4942f584 CREATE_LISTENER_FAILED

Explanation

An exception occurred while a TCP/IP listener wasbeing created.

User response

The details of the caught exception are written to theFFDC log. Review the details of the exception, and takeany further action that is necessary.

4942f5a9 TRANS_NC_LIST_GOT_EXC

Explanation

An exception was caught in the NameService while theNamingContext.List() method was executing.

User response

The details of the caught exception are written to theFFDC log. Review the details of the original exception,and any further action that is necessary.

org.omg.CORBA.MARSHALA request or reply is structurally invalid. For example, if method parameters are supplied that do notmatch the parameters defined for the method in the CORBA interface definition language (IDL), or if amessage is a different size from the size listed within the message.

4942f89a UNSPECIFIED_MARSHAL_25


Explanation

This error can occur at the server side while the server is reading a request, or at the client side while the clientis reading a reply. Possible causes are that the data on the wire is corrupted, or the server and client ORB are notcommunicating correctly. Communication problems can caused when one of the ORBs has an incompatibility orbug that prevents it from conforming to specifications.

User response

Check whether the IIOP levels and CORBA versions of the client and server are compatible. Try disablingfragmentation (set com.ibm.CORBA.FragmentationSize to zero) to determine whether it is a fragmentationproblem. In this case, analysis of CommTraces (com.ibm.CORBA.CommTrace) might give extra information.

org.omg.CORBA.NO_RESPONSENo response was received from the server. For example, this exception is thrown when a deferredasynchronous call is made, and the client attempts to get a result before the response is available.

4942fb03 RESPONSE_INTERRUPTED

Explanation

The client has enabled the AllowUserInterrupt property and has called for an interrupt on a thread currentlywaiting for a reply from a remote method call.

User response

None.

org.omg.CORBA.OBJ_ADAPTERAn object adapter detected a failure, such as a failed server registration due to the use of an existingregistration name.

4942fb90 ORB_CONNECT_ERROR_6

Explanation

A servant failed to connect to a server-side ORB.

User response

See the FFDC log for the cause of the problem, then try restarting the application.

org.omg.CORBA.OBJECT_NOT_EXISTThe referenced object does not exist. If the object existed at some point, it has now been deleted. Anyremaining references to the object, for example references in code that receives the exception or proxyobjects within an interoperability bridge, may also be deleted.

4942fc01 LOCATE_UNKNOWN_OBJECT

Explanation

The server has no knowledge of the object for which the client has asked in a locate request.

User response

Ensure that the remote object that is requested resides in the specified server and that the remote reference isup-to-date.


org.omg.CORBA.TRANSIENTAn object could not be reached. The object might or might not exist. For example, a connection cannot beestablished because the server is inactive.

4942fe02 CONNECT_FAILURE_1

Explanation

The client attempted to open a connection with theserver, but failed. The reasons for the failure can bemany; for example, the server might not be up or itmight not be listening on that port. If a BindExceptionis caught, it shows that the client could not open asocket locally (that is, the local port was in use or theclient has no local address).

User response

As with all TRANSIENT exceptions, trying again orrestarting the client or server might solve the problem.Ensure that the port and server host names arecorrect, and that the server is running and allowingconnections. Also ensure that no firewall is blockingthe connection, and that a route is available betweenclient and server.

4942FE07 CONNECT_FAILURE_5

Explanation

An attempt to connect to a server failed with both thedirect and indirect IORs. Every client side handle to aserver object (managed by the ClientDelegatereference) is set up with two IORs (object references)to reach the servant on the server. The first IOR is thedirect IOR, which holds details of the server hostingthe object. The second IOR is the indirect IOR, whichholds a reference to a naming server that can bequeried if the direct IOR fails.

Note: The two IORs might be the same at times.

For any remote request, the ORB tries to reach theservant object using the direct IOR and then theindirect IOR. The CONNECT_FAILURE_5 exception isthrown when the ORB failed with both IORs.

User response

The cause of failure is typically connection-related, forexample because of "connection refused" exceptions.Other CORBA exceptions such as NO_IMPLEMENT orOBJECT_NOT_EXIST might also be the root cause ofthe (E07) CORBA.TRANSIENT exception. An abstractof the root exception is logged in the description of the(E07) CORBA.TRANSIENT exception. Review thedetails of the exception, and take any further actionthat is necessary.

4f4d0001 POA_DISCARDING

Explanation

The POA Manager at the server is in the discardingstate. When a POA manager is in the discarding state,the associated POAs discard all incoming requests (forwhich processing has not yet begun). For more details,see the section that describes the POAManagerInterface in the https://www.omg.org/cgi-bin/doc?formal/99-10-07.

User response

Put the POA Manager into the active state if you wantrequests to be processed.

org.omg.CORBA.UNKNOWNAn unknown exception was raised. Examples of unknown exceptions include: user exceptions that are notspecified in the raises clause of a method, non-CORBA exceptions, and CORBA exceptions from a laterversion of CORBA than is being used by this server or client.

4942fe85 UNEXPECTED_CHECKED_EXCEPTION

Explanation

An unexpected checked exception was caught during the servant_preinvoke method. This method is calledbefore a locally optimized operation call is made to an object of type class. This exception does not occur if theORB and any Portable Interceptor implementations are correctly installed. It might occur if, for example, achecked exception is added to the Request interceptor operations and these higher level interceptors are calledfrom a back level ORB.

User response

The details of the caught exception are written to the FFDC log. Check whether the class from which it wasthrown is at the expected level.




Chapter 15. RMI, IIOP, and RMI-IIOPThe basic concepts behind RMI-IIOP and other similar technologies.

RMI

With RMI, you can write distributed programs in the Java programming language. RMI is easy to use, youdo not need to learn a separate interface definition language (IDL), and you get Java's inherent "writeonce, run anywhere" benefit. Clients, remote interfaces, and servers are written entirely in Java. RMI usesthe Java Remote Method Protocol (JRMP) for remote Java object communication. For a quick introductionto writing RMI programs, see the RMI tutorial Web page: https://docs.oracle.com/javase/tutorial/rmi/,which describes writing a simple "Hello World" RMI program.

RMI lacks interoperability with other languages, and, because it uses a non-standard communicationprotocol, cannot communicate with CORBA objects.

IIOP, CORBA, and Java IDL

IIOP is CORBA's communication protocol. It defines the way bits are sent over a wire between CORBAclients and servers. CORBA is a standard distributed object architecture developed by the ObjectManagement Group (OMG). Interfaces to remote objects are described in a platform-neutral interfacedefinition language (IDL). Mappings from IDL to specific programming languages are implemented,binding the language to CORBA/IIOP.

The Java Standard Edition CORBA/IIOP implementation is known as Java IDL. Along with the IDL to Java(idlj) compiler, Java IDL can be used to define, implement, and access CORBA objects from the Javaprogramming language.

The Java IDL Web page: Java IDL (CORBA), gives you a good, Java-centric view of CORBA/IIOPprogramming. To get a quick introduction to writing Java IDL programs, see the Getting Started: HelloWorld Web page: Getting Started with Java IDL.

RMI-IIOP

Previously, Java programmers had to choose between RMI and CORBA/IIOP (Java IDL) for distributedprogramming solutions. Now, by adhering to a few restrictions (see “Restrictions when running RMIprograms over IIOP” on page 323), RMI server objects can use the IIOP protocol, and communicate withCORBA client objects written in any language. This solution is known as RMI-IIOP. RMI-IIOP combinesRMI ease of use with CORBA cross-language interoperability.

Background reading

Here are some sites to help you with this technology:

• The Java RMI home page contains links to RMI documentation, examples, specification, and more:https://www.oracle.com/technetwork/java/javase/tech/index-jsp-136424.html

• The RMI trail in the Java Tutorial: https://docs.oracle.com/javase/tutorial/rmi/• The RMI API Javadoc HTML contains the most up-to-date RMI API documentation: https://

docs.oracle.com/javase/8/docs/api/java/rmi/package-summary.html• The Java IDL Web page will familiarize you with Oracle's CORBA/IIOP implementation: https://

docs.oracle.com/javase/8/docs/technotes/guides/idl/index.html• The Java IDL Trail in the Java Tutorial: https://docs.oracle.com/javase/8/docs/technotes/guides/idl/

GShome.html


https://docs.oracle.com/javase/tutorial/rmi/

https://docs.oracle.com/javase/8/docs/technotes/guides/idl/

https://docs.oracle.com/javase/8/docs/technotes/guides/idl/GShome.html


https://docs.oracle.com/javase/tutorial/rmi/

https://docs.oracle.com/javase/8/docs/api/java/rmi/package-summary.html

https://docs.oracle.com/javase/8/docs/api/java/rmi/package-summary.html

https://docs.oracle.com/javase/8/docs/technotes/guides/idl/index.html

https://docs.oracle.com/javase/8/docs/technotes/guides/idl/index.html



The RMI implementationThe RMI implementation consists of three abstraction layers.

These abstraction layers are:

1. The Stub and Skeleton layer, which intercepts method calls made by the client to the interfacereference variable and redirects these calls to a remote RMI service.

2. The Remote Reference layer understands how to interpret and manage references made from clientsto the remote service objects.

3. The bottom layer is the Transport layer, which is based on TCP/IP connections between machines in anetwork. It provides basic connectivity, as well as some firewall penetration strategies.

On top of the TCP/IP layer, RMI uses a wire-level protocol called Java Remote Method Protocol (JRMP),which works like this:

1. Objects that require remote behavior should extend the RemoteObject class, typically through theUnicastRemoteObject subclass.

a. The UnicastRemoteObject subclass exports the remote object to make it available for servicingincoming RMI calls.

b. Exporting the remote object creates a new server socket, which is bound to a port number.c. A thread is also created that listens for connections on that socket. The server is registered with a

registry.d. A client obtains details of connecting to the server from the registry.e. Using the information from the registry, which includes the hostname and the port details of the

server's listening socket, the client connects to the server.2. When the client issues a remote method invocation to the server, it creates a TCPConnection object,

which opens a socket to the server on the port specified and sends the RMI header information andthe marshalled arguments through this connection using the StreamRemoteCall class.

3. On the server side:

a. When a client connects to the server socket, a new thread is assigned to deal with the incomingcall. The original thread can continue listening to the original socket so that additional calls fromother clients can be made.

b. The server reads the header information and creates a RemoteCall object of its own to deal withunmarshalling the RMI arguments from the socket.

c. The serviceCall() method of the Transport class services the incoming call by dispatching itd. The dispatch() method calls the appropriate method on the object and pushes the result back

down the wire.


e. If the server object throws an exception, the server catches it and marshals it down the wireinstead of the return value.

4. Back on the client side:

a. The return value of the RMI is unmarshalled and returned from the stub back to the client codeitself.

b. If an exception is thrown from the server, that is unmarshalled and thrown from the stub.

Using RMI-IIOPThis section describes how to use the IBM RMI-IIOP implementation.

The rmic compilerReference information about the rmic compiler.

PurposeThe rmic compiler generates IIOP stubs and ties, and emits IDL, in accordance with the Java Languageto OMG IDL Language Mapping Specification: https://www.omg.org/cgi-bin/doc?formal/01-06-07.

Parameters-iiop

Generates stub and tie classes. A stub class is a local proxy for a remote object. Clients use stubclasses to send calls to a server. Each remote interface requires a stub class, which implements thatremote interface. The remote object reference used by a client is a reference to a stub. Tie classes areused on the server side to process incoming calls, and dispatch the calls to the correctimplementation class. Each implementation class requires a tie class.

Stub classes are also generated for abstract interfaces. An abstract interface is an interface that doesnot extend java.rmi.Remote, but has methods that throw either java.rmi.RemoteException ora superclass of java.rmi.RemoteException. Interfaces that do not extend java.rmi.Remoteand have no methods are also abstract interfaces.

-poa

Changes the inheritance from org.omg.CORBA_2_3.portable.ObjectImpl toorg.omg.PortableServer.Servant. This type of mapping is nonstandard and is not specified bythe Java Language to OMG IDL Mapping Specification: https://www.omg.org/cgi-bin/doc?formal/01-06-07.

The PortableServer module for the Portable Object Adapter (POA) defines the native Servant type.In the Java programming language, the Servant type is mapped to the Javaorg.omg.PortableServer.Servant class. The class serves as the base class for all POA servantimplementations. It provides a number of methods that can be called by the application programmer,as well as methods that are called by the POA itself and might be overridden by the user to controlaspects of servant behavior.

Valid only when the -iiop option is present.

-idl

Generates OMG IDL for the classes specified and any classes referenced. This option is required onlyif you have a CORBA client written in another language that needs to talk to a Java RMI-IIOP server.

Tip: After the OMG IDL is generated using rmic -idl, use the generated IDL with an IDL-to-C++ orother language compiler, but not with the IDL-to-Java language compiler. Round tripping is notrecommended and should not be necessary. The IDL generation facility is intended to be used withother languages. Java clients or servers can use the original RMI-IIOP types.

Chapter 15. RMI, IIOP, and RMI-IIOP 319




IDL provides a purely declarative means of specifying the API for an object. IDL is independent of theprogramming language used. The IDL is used as a specification for methods and data that can bewritten in and called from any language that provides CORBA bindings. Java and C++ are suchlanguages. For a complete description, see the Java Language to OMG IDL Mapping Specification:https://www.omg.org/cgi-bin/doc?formal/01-06-07.

Restriction: The generated IDL can be compiled using only an IDL compiler that supports the CORBA2.3 extensions to IDL.

-alwaysForces regeneration even when existing stubs, ties, or IDL are newer than the input class. Valid onlywhen -iiop or -idl options are present.

-noValueMethods

Ensures that methods and initializers are not included in valuetypes emitted during IDL Generation.Methods and initializers are optional for valuetypes and are otherwise omitted.

Only valid when used with -idl option.

-idlModule <fromJavaPackage[.class]> <toIDLModule>

Specifies IDLEntity package mapping. For example: -idlModule sample.barmy::real::idlmod.


-idlFile <fromJavaPackage[.class]> <toIDLModule>

Specifies IDLEntity file mapping. For example: -idlFile test.pkg.X TEST16.idl.


More Information

For more detailed information about the rmic compiler, see the RMIC tool page:

• Solaris, Linux, AIX, and z/OS version: rmic• Windows version: rmic

The idlj compilerReference information for the idlj compiler.

PurposeThe idlj compiler generates Java bindings from an IDL file. This compiler supports the CORBA ObjectsBy Value feature, which is required for inter-operation with RMI-IIOP. It is written in Java, and so can runon any platform.

More Information

To learn more about using the idlj compiler, see:

• idlj - The IDL-to-Java Compiler (on AIX, Linux, and z/OS)• idlj - The IDL-to-Java Compiler (on Windows)

.

Making RMI programs use IIOPA general guide to converting an RMI application to use RMI-IIOP.

Before you beginTo use these instructions, your application must already use RMI.



https://docs.oracle.com/javase/8/docs/technotes/tools/unix/rmic.html

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/rmic.html

https://docs.oracle.com/javase/8/docs/technotes/tools/unix/idlj.html

https://docs.oracle.com/javase/8/docs/technotes/tools/windows/idlj.html

Procedure

1. If you are using the RMI registry for naming services, you must switch to CosNaming:a) In both your client and server code, create an InitialContext for JNDI.

For a Java application use the following code:

import javax.naming.*;...Context ic = new InitialContext();

For an applet, use this alternative code:

import java.util.*;import javax.naming.*;...Hashtable env = new Hashtable();env.put("java.naming.applet", this);Context ic = new InitialContext(env);

b) Modify all uses of RMI registry lookup(), bind(), and rebind() to use JNDI lookup(),bind(), and rebind() instead.Instead of:

import java.rmi.*;...Naming.rebind("MyObject", myObj);

use:

import javax.naming.*;...ic.rebind("MyObject", myObj);

2. If you are not using the RMI registry for naming services, you must have some other way ofbootstrapping your initial remote object reference. For example, your server code might be using Javaserialization to write an RMI object reference to an ObjectOutputStream and passing this to yourclient code for deserializing into an RMI stub. When doing this in RMI-IIOP, you must also ensure thatobject references are connected to an ORB before serialization and after deserialization.a) On the server side, use the PortableRemoteObject.toStub() call to obtain a stub, then usewriteObject() to serialize this stub to an ObjectOutputStream. If necessary, useStub.connect() to connect the stub to an ORB before serializing it.For example:

org.omg.CORBA.ORB myORB = org.omg.CORBA.ORB.init(new String[0], null);Wombat myWombat = new WombatImpl();javax.rmi.CORBA.Stub myStub = (javax.rmi.CORBA.Stub)PortableRemoteObject.toStub(myWombat);myStub.connect(myORB);// myWombat is now connected to myORB. To connect other objects to the// same ORB, use PortableRemoteObject.connect(nextWombat, myWombat);FileOutputStream myFile = new FileOutputStream("t.tmp");ObjectOutputStream myStream = new ObjectOutputStream(myFile);myStream.writeObject(myStub);

b) On the client side, use readObject() to deserialize a remote reference to the object from anObjectInputStream. Before using the deserialized stub to call remote methods, it must beconnected to an ORB.For example:

FileInputStream myFile = new FileInputStream("t.tmp");ObjectInputStream myStream = new ObjectInputStream(myFile);Wombat myWombat = (Wombat)myStream.readObject();org.omg.CORBA.ORB myORB = org.omg.CORBA.ORB.init(new String[0], null);((javax.rmi.CORBA.Stub)myWombat).connect(myORB);// myWombat is now connected to myORB. To connect other objects to the// same ORB, use PortableRemoteObject.connect(nextWombat, myWombat);

The JNDI approach is much simpler, so it is preferable to use it whenever possible.


3. Either change your remote implementation classes to inherit fromjavax.rmi.PortableRemoteObject, or explicitly to export implementation objects after creationby calling PortableRemoteObject.exportObject(). For more discussion on this topic, read“Connecting IIOP stubs to the ORB” on page 322.

4. Change all the places in your code where there is a Java cast of a remote interface to usejavax.rmi.PortableRemoteObject.narrow().

5. Do not depend on distributed garbage collection (DGC) or use any of the RMI DGC facilities. UsePortableRemoteObject.unexportObject() to make the ORB release its references to anexported object that is no longer in use.

6. Regenerate the RMI stubs and ties using the rmic command with the -iiop option.This will produce stub and tie files with the following names:

_<implementationName>_Tie.class_<interfaceName>_Stub.class

7. Before starting the server, start the CosNaming server (in its own process) using the tnameservcommandThe CosNaming server uses the default port number of 2809. If you want to use a different portnumber, use the -ORBInitialPort parameter.

8. When starting client and server applications, you must specify some system properties.When running an application, you can specify properties on the command line:

java -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory -Djava.naming.provider.url=iiop://<hostname>:2809 <appl_class>

9. If the client is an applet, you must specify some properties in the applet tag.For example:

java.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactoryjava.naming.provider.url=iiop://<hostname>:2809

This example uses the default name service port number of 2809. If you specify a different port in theprevious step, you need to use the same port number in the provider URL here.The <hostname> in the provider URL is the host name that was used to start the CosNaming server.

ResultsYour application can now communicate with CORBA objects using RMI-IIOP.

Connecting IIOP stubs to the ORBWhen your application uses IIOP stubs, as opposed to JRMP stubs, you must properly connect the IIOPstubs with the ORB before starting operations on the IIOP stubs (this is not necessary with JRMP stubs).This section discusses the extra 'connect' step required for the IIOP stub case.

The PortableRemoteObject.exportObject() call only creates a Tie object and caches it for futureusage. The created tie does not have a delegate or an ORB associated. This is known as explicitinvocation.

The PortableRemoteObject.exportObject() happens automatically when the servant instance iscreated. The servant instance is created when a PortableRemoteObject constructor is called as a baseclass. This is known as implicit invocation.

Later, when the application calls PortableRemoteObject.toStub(), the ORB creates thecorresponding Stub object and associates it with the cached Tie object. But because the Tie is notconnected and does not have a delegate, the newly created Stub also does not have a delegate or ORB.

The delegate is set for the stub only when the application calls Stub.connect(orb). Thus, anyoperations on the stub made before the ORB connection is made will fail.

The Java Language to OMG IDL Mapping Specification (https://www.omg.org/cgi-bin/doc?formal/01-06-07) says this about the Stub.connect() method:




"The connect method makes the stub ready for remote communication using the specified ORBobject orb. Connection normally happens implicitly when the stub is received or sent as anargument on a remote method call, but it is sometimes useful to do this by making an explicitcall (e.g., following deserialization). If the stub is already connected to orb (has a delegate setfor orb), then connect takes no action. If the stub is connected to some other ORB, then aRemoteException is thrown. Otherwise, a delegate is created for this stub and the ORB objectorb."

For servants that are not POA-activated, Stub.connect(orb) is necessary as a required setup.

Thread pooling for RMI connection handlersWhen a client connects to the server socket, a new thread is forked to deal with the incoming call. TheIBM SDK implements thread pooling in the sun.rmi.transport.tcp.TCPTransport class.

Thread pooling is not enabled by default. Enable it with this command-line setting:

-Dsun.rmi.transport.tcp.connectionPool=true

Alternatively, you could use a non-null value instead of true.

With the connectionPool enabled, threads are created only if there is no thread in the pool that can bereused. In the current implementation of the connection Pool, the RMI connectionHandler threads areadded to a pool and are never removed. Enabling thread pooling is not recommended for applications thathave only limited RMI usage. Such applications have to live with these threads during the RMI off-peaktimes as well. Applications that are mostly RMI intensive can benefit by enabling the thread poolingbecause the connection handlers will be reused, avoiding the additional memory usage when creatingthese threads for every RMI call.

Understanding distributed garbage collectionThe RMI subsystem implements reference counting based Distributed Garbage Collection (DGC) toprovide automatic memory management facilities for remote server objects.

When the client creates (unmarshalls) a remote reference, it calls dirty() on the server-side DGC. Afterthe client has finished with the remote reference, it calls the corresponding clean() method.

A reference to a remote object is leased for a time by the client holding the reference. The lease periodstarts when the dirty() call is received. The client must renew the leases by making additionaldirty() calls on the remote references it holds before such leases expire. If the client does not renewthe lease before it expires, the distributed garbage collector assumes that the remote object is no longerreferenced by that client.

DGCClient implements the client side of the RMI distributed garbage collection system. The externalinterface to DGCClient is the registerRefs() method. When a LiveRef to a remote object enters theJVM, it must be registered with the DGCClient to participate in distributed garbage collection. When thefirst LiveRef to a particular remote object is registered, a dirty() call is made to the server-side DGC forthe remote object. The call returns a lease guaranteeing that the server-side DGC will not collect theremote object for a certain time. While LiveRef instances to remote objects on a particular server exist,the DGCClient periodically sends more dirty calls to renew its lease. The DGCClient tracks the localavailability of registered LiveRef instances using phantom references. When the LiveRef instance for aparticular remote object is garbage collected locally, a clean() call is made to the server-side DGC. Thecall indicates that the server does not need to keep the remote object alive for this client. TheRenewCleanThread handles the asynchronous client-side DGC activity by renewing the leases andmaking clean calls. So this thread waits until the next lease renewal or until any phantom reference isqueued for generating clean requests as necessary.

Restrictions when running RMI programs over IIOPA list of limitations when running RMI programs over IIOP.

To make existing RMI programs run over IIOP, observe the following restrictions.


• Make sure all constant definitions in remote interfaces are of primitive types or String and evaluated atcompile time.

• Do not use Java names that conflict with IDL mangled names generated by the Java-to-IDL mappingrules. See section 28.3.2 of the Java Language to OMG IDL Mapping Specification for more information:https://www.omg.org/cgi-bin/doc?formal/01-06-07

• Do not inherit the same method name into a remote interface more than once from different baseremote interfaces.

• Be careful when using names that are identical other than their case. The use of a type name and avariable of that type with a name that differs from the type name in case only is supported. Most othercombinations of names that are identical other than their case are not supported.

• Do not depend on run time sharing of object references to be preserved exactly when transmittingobject references to IIOP. Runtime sharing of other objects is preserved correctly.

• Do not use the following features of RMI, which do not work in RMI-IIOP:

– RMISocketFactory– UnicastRemoteObject– Unreferenced– The Distributed Garbage Collector (DGC) interfaces

Debugging applications involving RMIWhen debugging applications involving RMI you need information on exceptions and properties settings,solutions to common problems, answers to frequently asked questions, and useful tools.

The list of exceptions that can occur when using RMI and their context is included in the RMI Specificationdocument at:https://docs.oracle.com/javase/8/docs/platform/rmi/spec/rmi-exceptions.html#3601

Properties settings that are useful for tuning, logging, or tracing RMI servers and clients can be foundat:https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/javarmiproperties.html

Solutions to some common problems and answers to frequently asked questions related to RMI andobject serialization can be found at:https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/faq.html

Network monitoring tools like netstat and tcpdump are useful for debugging RMI problems because theyenable you to see the traffic at the network level.

Issues and limitationsInformation about thread safety, working with other ORBs, the difference betweenUnicastRemoteObject and PortableRemoteObject, and known limitations.

Servers must be thread safe

Because remote method invocations on the same remote object might run concurrently, a remote objectimplementation must be thread-safe.

Interoperating with other ORBs

RMI-IIOP should interoperate with other ORBs that support the CORBA 2.3 specification. RMI-IIOP doesnot interoperate with older ORBs, because older ORBs cannot handle the IIOP encodings for ObjectsBy Value. This support is needed to send RMI value classes, including strings, over IIOP.

Note: Although ORBs written in different languages should be able to interoperate, the Java ORB has notbeen fully tested with other vendors' ORBs.



https://docs.oracle.com/javase/8/docs/platform/rmi/spec/rmi-exceptions.html#3601

https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/javarmiproperties.html

https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/faq.html

https://docs.oracle.com/javase/8/docs/technotes/guides/rmi/faq.html

When do I use UnicastRemoteObject vs PortableRemoteObject?

Use UnicastRemoteObject as the superclass for the object implementation in RMI programming. UsePortableRemoteObject in RMI-IIOP programming. If PortableRemoteObject is used, you canswitch the transport protocol to either JRMP or IIOP during run time.

Known limitations

• JNDI 1.1 does not support java.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactoryas an Applet parameter. Instead, it must be explicitly passed as a property to the InitialContextconstructor. This capability is supported in JNDI 1.2.

• When running the Naming Service on Unix based platforms, you must use a port number greater than1024. The default port is 2809, so this should not be a problem.


Chapter 16. Miscellaneous system propertycommand-line options

Use the system property command-line options to set up your system.-D<name>=<value>


Many system properties are associated with components of the SDK. Information about these systemproperties can be found at the following links:

• GPU system property command-line options• “RDMA system property command-line options” on page 221• “XML system property command-line options” on page 271• “CORBA system property command-line options” on page 306• “Bidirectional system property command-line options” on page 87• OpenJ9 VM system property command-line options

-Dcom.ibm.dbgmallocThis option provides memory allocation diagnostic information for class library native code.

-Dcom.ibm.dbgmalloc=trueWhen an application is started with this option, a Java dump records the amount of memory allocatedby the class library components. You can use this option together with the -Xcheck:memory optionto obtain information about class library call sites and their allocation sizes. Enabling this option hasan impact on throughput performance. For sample Java dump output, see .https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/openj9/dump_javadump/index.html#nativememinfo

-Dcom.ibm.mappedByteBufferForceSetting this value to true forces data to be committed to disk during system failure.

-Dcom.ibm.mappedByteBufferForce=[true | false]During system failure, the MappedByteBuffer.force API does not commit data to disk, whichprevents data integrity issues. Setting this value to true forces data to be committed to disk duringsystem failure. Because this setting can cause performance degradation, this switch is not enabled bydefault.

-Dcom.ibm.rational.mvfs.checking (Windows only)Use this property to improve the performance of Multi Version File System (MVFS) file systems.

-Dcom.ibm.rational.mvfs.checking=[true | false]The WinNTFilesystem methods getModifiedTime and getBooleanAttributes use thewindows methods API_wstati64() and _wfindfirsti64() instead of the defaults. This propertyis not enabled by default because it can cause performance degradation on local file systems. Theproperty also causes degradation on remote Windows shares where there is no Windows directorycache for the remote file system.


https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/openj9/dump_javadump/index.html#nativememinfo

https://www.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/openj9/dump_javadump/index.html#nativememinfo

-Dcom.ibm.signalhandling.ignoreLogoff (Windows only)This property controls the way the JVM handles a CTRL_LOGOFF_EVENT signal when the JVM is runningas an interactive Windows service. In service refresh 6, fix pack 10, the IBM signal handlingimplementation was replaced with the OpenJDK implementation, so this property became redundant andis now ignored.

-Dcom.ibm.signalhandling.ignoreLogoff=[true|false]Windows issues a CTRL_LOGOFF_EVENT when a user logs out of an interactive Windows service. Bydefault, the JVM ends when this signal is received. Setting this property to true (the default is false)prevents the JVM ending when a CTRL_LOGOFF_EVENT signal is received. From servicerefresh 6, fix pack 10, this property no longer has any effect. To achieve the same result, you can usethe -Xrs command-line option to disable the handling of hardware exceptions by the VM. However,you should use the -Xrs option with care because it affects more than just the CTRL_LOGOFF_EVENTsignal. For more information, see -Xrs.

-Dcom.ibm.zipfile.closeinputstreamsThe Java.util.zip.ZipFile class allows you to create InputStreams on files held in a compressedarchive.

-Dcom.ibm.zipfile.closeinputstreams=trueUnder some conditions, using ZipFile.close() to close all InputStreams that have been openedon the compressed archive might result in a 56-byte-per-InputStream native memory leak. Settingthe -Dcom.ibm.zipfile.closeinputstreams=true forces the JVM to track and closeInputStreams without the memory impact caused by retaining native-backed objects. Native-backed objects are objects that are stored in native memory, rather than the Java heap. By default,the value of this system property is not enabled.

-Dibm.awt.mediumColor (AIX only)This property reverts behavior to an earlier release.

-Dibm.awt.mediumColor=trueFrom IBM SDK, Java Technology Edition, Version 8, the default SystemColor settings of AbstractWindows Toolkit (AWT) components are changed. To revert to the original color palette settings, setthis property on the command line.This property is not enabled by default.

-Dil8n.vsThis system property enables awareness of Unicode Ideographic Variation Sequence (IVS) to drawcharacters, except in peered components.

-Dil8n.vs=[true]The behavior depends on the font specified. If the font supports IVS, and has a glyph based on thecombination of a base character and a variation selector character, an accurate glyph can be pickedup. If not, the base character is displayed and the variation selector character is ignored. Because thisoption changes the behavior of the font drawing engine, the option is disabled by default. Whendisabled, a variation selector is displayed as an undefined character. This option is supported only forJapanese.


-Dsun.rmi.transport.tcp.connectionPoolEnables thread pooling for the RMI ConnectionHandlers in the TCP transport layer implementation.

-Dsun.rmi.transport.tcp.connectionPool=valval is either true or a value that is not null.

Chapter 16. Miscellaneous system property command-line options 329

Notices

This information was developed for products and services offered in the US. This material might beavailable from IBM in other languages. However, you may be required to own a copy of the product orproduct version in that language in order to access it.

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 inyour area. Any reference to an IBM product, program, or service is not intended to state or imply that onlythat IBM product, program, or service may be used. Any functionally equivalent product, program, orservice that does not infringe any IBM intellectual property right may be used instead. However, it is theuser'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 described in thisdocument. The furnishing of this document does not grant you any license to these patents. You can sendlicense inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785US

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

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

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 APARTICULAR PURPOSE. Some jurisdictions do not allow disclaimer of express or implied warranties incertain transactions, therefore, this statement may not apply to you.

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

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

IBM may use or distribute any of the information you provide in any way it believes appropriate withoutincurring any obligation to you.

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

IBM Director of LicensingIBM CorporationNorth Castle Drive, MD-NC119Armonk, NY 10504-1785US


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 byIBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or anyequivalent agreement between us.

The performance data discussed herein is presented as derived under specific operating conditions.Actual results may vary.

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

Statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,and represent goals and objectives only.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work must include a copyright noticeas follows:

© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names might betrademarks of IBM or other companies. A current list of IBM trademarks is available on the web at"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

Intel, Intel logo, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, IntelSpeedStep, Itanium, and Pentium are trademarks of Intel Corporation in the United States, othercountries, or both.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/orits affiliates.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT and the Windows logo are trademarks of Microsoft Corporation in theUnited States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Terms and conditions for product documentationPermissions for the use of these publications are granted subject to the following terms and conditions.

332 Notices

https://www.ibm.com/legal/us/en/copytrade.shtml

Applicability

These terms and conditions are in addition to any terms of use for the IBM website.

Personal use

You may reproduce these publications for your personal, noncommercial use provided that all proprietarynotices are preserved. You may not distribute, display or make derivative work of these publications, orany portion thereof, without the express consent of IBM.

Commercial use

You may reproduce, distribute and display these publications solely within your enterprise provided thatall proprietary notices are preserved. You may not make derivative works of these publications, orreproduce, distribute or display these publications or any portion thereof outside your enterprise, withoutthe express consent of IBM.

Rights

Except as expressly granted in this permission, no other permissions, licenses or rights are granted, eitherexpress or implied, to the publications or any information, data, software or other intellectual propertycontained therein.

IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use ofthe publications is detrimental to its interest or, as determined by IBM, the above instructions are notbeing properly followed.

You may not download, export or re-export this information except in full compliance with all applicablelaws and regulations, including all United States export laws and regulations.

IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS AREPROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.

IBM Online Privacy StatementIBM Software products, including software as a service solutions, (“Software Offerings”) may use cookiesor other technologies to collect product usage information, to help improve the end user experience, totailor interactions with the end user or for other purposes. In many cases no personally identifiableinformation is collected by the Software Offerings. Some of our Software Offerings can help enable you tocollect personally identifiable information. If this Software Offering uses cookies to collect personallyidentifiable information, specific information about this offering’s use of cookies is set forth below.

This Software Offering does not use cookies or other technologies to collect personally identifiableinformation.

If the configurations deployed for this Software Offering provide you as customer the ability to collectpersonally identifiable information from end users via cookies and other technologies, you should seekyour own legal advice about any laws applicable to such data collection, including any requirements fornotice and consent.

For more information about the use of various technologies, including cookies, for these purposes, see: (i)IBM’s Privacy Policy at https://www.ibm.com/privacy ; (ii) IBM’s Online Privacy Statement at https://www.ibm.com/privacy/details (in particular, the section entitled “Cookies, Web Beacons and OtherTechnologies”); and (iii) the “IBM Software Products and Software-as-a-Service Privacy Statement” athttps://www.ibm.com/software/info/product-privacy.

Notices 333

https://www.ibm.com/privacy

https://www.ibm.com/privacy/details

https://www.ibm.com/privacy/details

https://www.ibm.com/software/info/product-privacy

Version 8 IBM SDK, Java Technology Edition · 2020-05-01 · Version 8 IBM SDK, Java Technology...

Documents

Transcript of Version 8 IBM SDK, Java Technology Edition · 2020-05-01 · Version 8 IBM SDK, Java Technology...