IBM Distributed Debugger and Object Level Trace
Version 9.1
RELEASE NOTES

Table of Contents

1.0 INTRODUCTION
2.0 INSTALLATION
2.1 General remarks
2.2 Installation on Windows®
2.3 Installation on Linux and Linux/390
2.4 Installation on AIX
2.5 Installation on Solaris
2.6 Installation on OS/2
2.7 Installation on OS/390
2.8 Installation on HP-UX
2.9 Installation for use with WebSphere Application Server v3.5 (Fixpack 3 or higher)
3.0 UNINSTALLING
3.1 Uninstalling on Windows
3.2 Uninstalling on Linux
3.3 Uninstalling on HP-UX
4.0 DEBUGGER ISSUES AND LIMITATIONS
4.1 Debugging applets in a browser
     4.1.1 Internet Explorer for Windows
     4.1.2 Netscape for Windows
4.2 General issues
     4.2.1 TCP/IP considerations
     4.2.2 Windows-specific issues
     4.2.3 AIX-specific issues
     4.2.4 AS/400-specific issues
     4.2.5 Solaris-specific issues
     4.2.6 Usage tips, limitations, and known issues
     4.2.7 Generating Business Object code for tracing and debugging in Object Builder
4.3 Limitations for Java (interpreted only)
     4.3.1 General issues
     4.3.2 JDK and CLASSPATH issues
     4.3.3 Interpreted Java
     4.3.4 JavaServer Pages (JSPs)
4.4 Limitations for all compiled languages
     4.4.1 General issues
     4.4.2 AIX-specific limitations
     4.4.3 OS/390-specific issues
5.0 OBJECT LEVEL TRACE KNOWN ISSUES AND LIMITATIONS
5.1 OLT online documentation issues
5.2 NL- and GUI-related limitations and considerations

1.0 INTRODUCTION

The IBM Distributed Debugger and Object Level Trace support debugging and tracing on AIX, OS/2, Solaris, Windows NT and 2000, OS/390, HP-UX and various distributions of Linux. The debugger can debug both interpreted and compiled Java, as well as other compiled languages, such as C++. Please see the chart below for further details.

National Language Support has been provided for Group 1 (Gr1) languages, which are Brazilian Portuguese, English, French, German, Italian, Japanese, Korean, Simplified Chinese, Spanish, and Traditional Chinese.

The S/390 server series and the OS/390 operating system are now called the IBM eServer zSeries and zOS respectively. However, for the purpose of this document, all reference made to the server and operating system will be by their former names, S/390 and OS/390.

The AS/400 server series is now referred to as the IBM eServer iSeries or IBM eServer iSeries 400. However, for the purpose of this document, all reference made to the server will be by its former name, AS/400.

The following table presents a summary by platform of Debugger and OLT functionality on supported platforms, and the languages for which National Language Support has been provided. For the earliest supported operating system level, please refer to product installation information.

Platform AIX OS/2 Solaris Windows NT/2000 OS/390 OS/400 Linux Linux390 HP-UX
Debugger User Interface (idebug) X     X X** X+      
Debugger Engine Interpreted Languages (irmtdbgj) X X X X X   X X X
Debugger Engine Compiled Languages (irmtdbgc) X X X X          
National Language Support Gr1 Gr1 Gr1 Gr1 * Gr1 Gr1 * Gr1
OLT X     X          
OLT Java runtime X   X X X X X X X
OLT C++ runtime X   X X X        

* English and Japanese on host; Group 1 on client.

** For OS/390 remote debugging, use the idebug command on the workstation to start a Debugger user interface daemon that will connect to Debug Tool or the Java debug engine on the host (OS/390).

+ For AS/400 remote debugging, use the idebug -a command on the workstation to start the Debugger user interface and ensure that the STRDBGSVR command was issued on the AS/400 server.

The following table lists the platforms that supports debugging interpreted Java programs using JDI (Java Debug Interface) and the corresponding JDK levels.

Platform
AIX
OS/2
Solaris
Windows NT/2000
OS/390
OS/400
Linux
Linux390
HP-UX
JDK level 1.2.2 SR11 or later

and

1.3.0 SR6 or later
  1.2.2_007* or later

and

1.3.0 or later
1.2.2 SR9 or later

and

1.3.0 SR5 or later
1.3 SR6 or later 1.1.8 or 1.2 or 1.3 1.2.2 SR9 or later

and

1.3.0 SR5 or later
1.2.2 SR9 or later 1.3.0 or later

* JPDA support must be installed separately for JDK 1.2.2_007 or later. JPDA is available from Sun Microsystems at http://java.sun.com/products/jpda/download.html.

2.0 INSTALLATION

2.1 General remarks about installation

The following remarks regarding installation and prerequisites are applicable to all platforms for the installation of the IBM Distributed Debugger and Object Level Trace tools. Additional prerequisites and platform-specific installation issues are mentioned in the subsections for each platform.

General prerequisites:

Netscape Navigator, Version 4.5 or later is recommended for displaying Debugger and OLT online help. Using an earlier version may give you a browser exception if you reopen a help window multiple times.

For interpreted debugging, the following additional prerequisites apply:

2.2 Installation on Windows®

Prerequisites:

For standalone debugging, the location of the Java executable specified in the PATH environment variable must be from the JDK \bin directory. For example, if, on Windows NT, the PATH environment variable points to the java.exe file in the \WINNT\SYSTEM32 directory, the Debugger cannot debug the application. To avoid this problem, insert the full path to java.exe in the JDK \bin directory to the start of the PATH environment variable.

If you are using remote stored procedure debugging on DB2, you must add the \IBMDebug\lib\dertrjrt.jar file to your system CLASSPATH.

Installation:

Installing the Distributed Debugger on Windows is automatic and does not require you to manually issue any commands or move any files.

Any beta version of the IBM Distributed Debugger must be uninstalled before installing the current version that accompanies this product. See Section 3.1, Uninstalling on Windows.

The Debugger will not function if installed in a directory whose name contains spaces or DBCS characters.

2.3 Installation on Linux and Linux/390

The Distributed Debugger ships a Java debug engine for Linux/390. Linux/390 images are of the form DERJPICL-9-0.s390.rpm, whereas the standard Linux/Intel images are of the form DERJPICL-9-0.i386.rpm. These images are not interchangeable between platforms, but install and operate in a similar manner.

Installation:

  1. Download the zip archive that contains the Debugger.
  2. From a command prompt, change directory (by issuing the cd command) to your download directory.
  3. If you have not already done so, issue the su command to become root.
  4. Issue the rpm -Uvh DER* command to install the Debugger.

2.4 Installation on AIX

Prerequisites:

If you are using remote stored procedure debugging on DB2, you must add the /usr/lpp/idebug/lib/dertrjrt.jar file to your system CLASSPATH.

Before you can run OLT on AIX, you must execute OLT.profile from within your .profile script.

Installation:

Search for the install image of the Distributed Debugger. Copy the install file(s) to the machine on which the Debugger is to be installed. Use installp or smitty install_latest.

2.5 Installation on Solaris

Prerequisites:

If you are using remote stored procedure debugging on DB2, you must add the /opt/IBMdebug/lib/dertrjrt.jar file to your system CLASSPATH.

If you are using a locale other than en_US, you must add /opt/IBMdebug/msg/%L/%N to the NLSPATH environment variable.

Installation:

  1. Download the Solaris oltdbg.zip image.
  2. Unzip the image.
  3. From a command prompt, change directory (by issuing the cd command) to the location where you have unzipped the image.
  4. If you have not done so already, use the su command to become root.
  5. Issue the ./dbgsetup idebug.pkg command.

If you are using JDK 1.2.2 for debugging applications on Solaris, you need to do the following:

  1. Download the jpda1_0-solsparc.zip file from http://java.sun.com/products/jpda/download.html.
  2. Unzip the file.
  3. Add the location of the jpda.jar (jpda_home) to your library path by issuing the following command:
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<jpda_home>/lib/sparc

2.6 Installation on OS/2

Prerequisites:

Interpreted Java debugging is supported only for Java programs developed for JDK 1.1.8 or lower.

Installation:

Search for the install image of the Distributed Debugger. The following copies the install file(s) to the machine on which the Debugger is to be installed. You will also need to set environment variables.

To install on OS/2:

  1. Choose a drive on which to install the Debugger Engine.
  2. Create a directory called \IBMDebug.
  3. Change directory (by issuing the cd command) to \IBMDebug.
  4. Unzip the Debugger zip file.

Setting Environment Variables for OS/2:

  1. Add d:\IBMDebug\bin to the PATH environment variable, where d is the drive on which the Debugger resides.
  2. Add d:\IBMDebug\dll to the LIBPATH environment variable or to the BEGINLIBPATH environment variable.
  3. Add d:\IBMDebug\help to the DPATH environment variable.
  4. Add d:\IBMDebug\msg\%L\%N to the NLSPATH environment variable.
  5. Add d:\IBMDebug\locale to the LOCPATH environment variable.

Note: To make these changes permanent, modify the environment variable settings in the CONFIG.SYS file.

2.7 Installation on OS/390

Prerequisites:

These prerequisites require you to know the version number of the Distributed Debugger (for use as a client) you are using. To obtain the version number, issue the idebug command at a Windows command prompt and examine the Command Prompt window to see the copyright and version message.

If you install the VisualAge for Java PTF for OS/390, you must ensure that you are running the Distributed Debugger user interface, version 8.4.3 or later. Version 8.4.3 can be downloaded from IBM VisualAge Developer's Domain at http://www.ibm.com/vadd.

The IBM JDK 1.3 SR6 (Service Release 6) is a prerequisite for interpreted debugging on this platform. You can download this JDK from http://www-1.ibm.com/servers/eserver/zseries/software/java/.

Version 8.4.3 or later of the Distributed Debugger user interface requires either of the following Debug Tool PTFs:

Installation:

To install the Distributed Debugger on your OS/390 server, do the following:

  1. Create the following directory structure:
    /usr
    /usr/lpp
    /usr/lpp/IBMDebug
    /usr/lpp/IBMDebug/lib
    /usr/lpp/IBMDebug/bin
  2. Once the directories are created, use ftp to copy the following binaries from the machine on which you have installed the Distributed Debugger user interface to their corresponding locations on the OS/390 server:
    Copy /extras/390/bin/irmtdbgj to /usr/lpp/IBMDebug/bin/irmtdbgj
    chmod +x irmtdbgj
    Copy /extras/390/lib/derdebug.jar to /usr/lpp/IBMDebug/lib/derdebug.jar
  3. Prepend /usr/lpp/IBMDebug/bin to your system path.

The Debugger engine can then be started using the irmtdbgj command.

2.8 Installation on HP-UX

Prerequisites:

Java Version 1.3 is required for installation and Java debugging.

Installation:

To install the Distributed Debugger, do the following:

  1. In the HP-UX archive, there will be an install.class file.
  2. Issue the java install command.

2.9 Installation for use with WebSphere v3.5 (Fixpack 3 or higher)

This section applies to installation of the IBM Distributed Debugger and Object Level Trace for use with WebSphere Application Server, Advanced Edition Version 3.5.3 or higher, but not Version 4.0 or higher. To install, do the following:

  1. Install v9.1 or v9.1.x of the Debugger on your workstation.
  2. Install v9.1 or v9.1.x of the Debugger on the machine running the WebSphere Application Server, if the application server is on a machine other than your workstation. On the machine running the application server, copy dertrjrt.jar from IBMDebug\lib to WebSphere\AppServer\lib.
  3. Open the WebSphere Administrator's Console.
  4. Add the following parameters to the command line arguments for your AppServer when you want to debug your application server:
    -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777 -Xnoagent -Dcom.ibm.debug.jdwpport=7777 -Djava.compiler=NONE -Xbootclasspath/a:%JAVA_HOME%\lib\tools.jar;

If the application server is running on Solaris, do the following:

3.0 UNINSTALLING

The parent products of the IBM Distributed Debugger may depend on it being installed. For most platforms, the IBM Distributed Debugger uninstalls along with the uninstall of the product it accompanied. This is the recommended uninstall procedure.

The manual procedure for uninstalling the Debugger is provided for removal of beta versions on the Windows platform.

The following sections discuss platform-specific uninstall issues.

3.1 Uninstalling on Windows

The Add/Remove Programs utility in the Control Panel will not uninstall only the Distributed Debugger while keeping the parent product. On the Windows platform, the Debugger can only be uninstalled by uninstalling the parent product.

VisualAge for Java, Version 3.0 only:

If you installed the Distributed Debugger along with this product, you must uninstall the Debugger before attempting to uninstall the product. If you uninstalled VisualAge for Java, Version 3.0 without removing the Debugger first, you can still uninstall the Debugger by manually deleting the registry key that contains the name of the product: HKEY_LOCAL_MACHINE\SOFTWARE\IBM\IBM Distributed Debugger\CurrentVersion\Install\ParentProducts\VisualAge for Java for Windows.

Note: Any deletions from the Windows registry other than those identified may render your system unstable or unusable.

Removing installed beta versions of the Distributed Debugger:

The following procedures are provided to allow you to remove the Debugger from your system by manually editing the Windows registry.

To remove the IBM Distributed Debugger, do the following:

  1. Run regedit.exe.
  2. Backup your registry file by exporting your registry file.
  3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\IBM\IBM Distributed Debugger\CurrentVersion\Install.
  4. The RefCount entry indicates the number of Debugger instances on the system. Decrement the RefCount value data by 1.
  5. Click on the Uninstaller icon of the newer (non-beta) version of the Debugger. This should uninstall the icons and files (if there are no other IBM products installed on your machine that make use of the IBM Distributed Debugger).
  6. If the RefCount value data is equal to one, remove the HKEY_LOCAL_MACHINE\SOFTWARE\IBM\IBM Distributed Debugger registry key, if it exists. If the RefCount value is less than one, set it equal to one and re-try the uninstall.

    The uninstall process is complete if the RefCount entry is not equal to one.

To reinstall the IBM Distributed Debugger, use the product CD to install it with the parent product.

3.2 Uninstalling on Linux

To uninstall the IBM Distributed Debugger, do the following:

  1. Find out which Debugger packages are installed on your system by issuing the following command:
    rpm -qa | grep DER
  2. For each Debugger package on your system, issue the following command from a command prompt, with the appropriate modifications for the release level in the last two digits:
    rpm -ev DERJPICL-9-1

3.3 Uninstalling on HP-UX

To uninstall the IBM Distributed Debugger, issue the following command:

juninst <Destination Directory>/UnInst

where <Destination Directory> is the root of the debugger install tree. For example, juninst /opt/ibm/debugger/UnInst.

4.0 DEBUGGER ISSUES AND LIMITATIONS

4.1 Debugging applets in a browser

Changes to the JDK necessitated the following browser configurations in order to debug applets in a browser.

4.1.1 Internet Explorer for Windows

  1. Close all browsers.
  2. Start the Java Plug-in Properties panel.
  3. Click the Advanced tab.
  4. Click the Enable Debug checkbox.
  5. Select a port (default is 2502).
  6. Set the Java Run Time Environment to point to your JDK install directory (you cannot use the plug-in's JRE).
  7. Click Apply.
  8. Start the applet in your browser.
  9. A dialog box will appear with the agent password. Make note of this password and click OK.
  10. From a command line, set your CLASSPATH to include the applet's class/source files. Issue the following commands on OS/2, AIX, or Windows: 

    irmtdbgj -quiport=<port> -qhost=<hostname> -password=<agent password>

    The Debugger will attach to the applet running inside the browser.

4.1.2 Netscape for Windows

4.2 General issues

4.2.1 TCP/IP considerations

The Debugger (and many other Java products) requires TCP/IP to be functioning and that you be able to ping your own machine hostname (or the localhost hostname), even while disconnected from a LAN.

4.2.2 Windows-specific issues

4.2.3 AIX-specific issues

4.2.4 AS/400-specific issues

4.2.5 Solaris-specific issues

4.2.6 Usage tips, limitations, and known issues

4.2.7 Generating Business Object code for tracing and debugging in Object Builder

By default, the wrapper code that is code-generated in Object Builder is compiled with debugging flags turned on. This causes the Distributed Debugger to interpret it as debuggable. To limit debugging to business logic only, follow these steps:

  1. Build with IVB_UNOPTIMIZE=1, ensuring that there are no make options for any of the individual build configuration units. By default, this should create non-optimized, non-debug-enabled binaries in the NOOPT subdirectory.
  2. Touch any Object Builder-generated files for which you wish to have debug information compiled.
  3. In the build configuration unit's SmartGuide, add the make option, IVB_TRACE_DEBUG=1, and regenerate the all.mak makefile from the build configuration main folder.
  4. Build with IVB_UNOPTIMIZE=1 again as in Step 1 above. This will build the touched file(s) with trace and debug information and link these binaries with the non-optimized, non-debug versions created in Step 1. The results will be in the NOOPT subdirectory.

4.3 Limitations for Java (interpreted only)

4.3.1 General issues

The Debugger provides two different ways of stepping into a method when debugging interpreted Java:

  1. Step Into, which will step into the specified method regardless of the package the method is in.
  2. Step Debug, which will only step into methods which are not in the following default filtered packages:

    java.*
    javax.*
    sun.*
    com.sun.*
    com.ibm.*
    org.omg.*
    org.xml.*
    org.w3c.*

    In order to change the list of filtered packages, you can pass the option -qfilter=filteredPackageList to irmtdbgj or irmtdbgc, where filteredPackageList is the name of the file that includes the list of packages not to be debugged by the users of your application.

4.3.2 JDK and CLASSPATH issues

The product install does not check for the prerequisite JDK. You should ensure it is installed and configured (PATH and CLASSPATH are set correctly) so that the java command works from the command line.

If you do not have an installed JDK and you attempt to debug an interpreted Java application either locally or remotely, you may get an error message from the irmtdbgj executable, to the effect that it cannot find the java executable.

4.3.3 Interpreted Java

The Debugger does not detect invalid JVM arguments. If any JVM arguments that are provided for debugging an application are invalid, the Debugger may either exit upon this failure or hang. Please refer to the section "SDK Tool Documentation" of your installed JDK for the complete list of valid JVM options.

General issues:

Java 2 JDK-related issues:

Debugger limitations:

Remote debugging considerations:

Local debugging considerations:

When debugging locally using idebug, if the -classpath value passed to -qjvmargs option has a space, the Debugger will not be able to launch a JVM for the application. In order to avoid this problem, add \\\" (three backslashes plus quotes) around the classpath information passed to the -qjvmargs option. For example, idebug -qjvmargs="-classpath \\\"c:\Program Files;d:\test\\\" -mx32".

4.3.4 JavaServer Pages (JSPs)

When debugging JavaServer Pages, you may step to HTML lines, however, you cannot step to or into in-line Java code. Variables declared in in-line Java code blocks may be inspected.

For example, given the following JSP fragment:

<%
java.lang.String _s1 = "<B>Hello</B>"; java.lang.String _s2 = " world!"; %>
<%= _s1 %>
<%= _s2 %>

you cannot step into the in-line java code (included in the <% %> tags) but can add the variables _s1 and/or _s2 to the program monitor list.

4.4 Limitations for all compiled languages

4.4.1 General issues

The Debugger does not allow the monitoring of an expression that uses the this pointer, such as this.x, where x is a member of a class. Use x instead.

4.4.2 AIX-specific limitations

A Halt action can be performed on the program you are debugging by opening another window on the machine on which the program you are debugging is running, finding the process ID of the program you are debugging using the ps(1) command, and then executing the kill -STOP <pid> command, where <pid> is the process id of the program you are debugging. This can interrupt long-running execution actions such as step-debug.

4.4.3 OS/390-specific issues

5.0 OBJECT LEVEL TRACE ISSUES

5.1 OLT online documentation

5.2 NL- and GUI-related limitations and considerations

>