IBM(R) Distributed Debugger

and

Object Level Trace

Version 8.5

RELEASE NOTES

Table of Contents

1.0 Introduction
2.0 Prerequisites
      2.1 Prerequisites for OS/390(R) users
      2.2 Prerequisites for DB2 users  
3.0 Limitations and known problems
      3.1 General distributed debugger limitations and known problems
      3.2 Debugger engine limitations and known problems for interpreted Java
      3.3 Debugger engine limitations and known problems for compiled languages
4.0 Object Level Trace
      4.1 Corrections to the OLT online documentation
      4.2 NL and GUI related limitations
      4.3 OLT user interface limitations
      4.4 Building CB ActiveX client applications for trace and debug.
5.0 Installation on Windows (R)
      5.1 Uninstalling on Windows
6.0 Installation on platforms other than Windows (R)
7.0 Browser configuration  

1.0 Introduction

The distributed debugger supports debugging on AIX(R), version 4, OS/2(R), version 4, Solaris(TM), Windows NT(R), version 4, Windows 2000, OS/390(R), version 2.4 and above, and OS/400(R), Version 4, release 2 and above.

The debugger can debug both interpreted Java and compiled languages, such as C++ or compiled Java.

The following table indicates which platforms the debugger has server/client/National Language support, and debugger invocations on:
 

idebug - Invokes the debug user interface
irmtdbgj - Invokes the interpreted Java debug engine
irmtdbgc - Invokes the compiled languages debug engine

* For OS/390 remote debugging, use the idebug command to start a debugger user interface daemon that will connect to Debug Tool or Java debug engine on the host (OS/390). Restrictions that also apply to remote debugging 390 from NT will be marked with **.

~ Group 1 Languages are Brazilian Portuguese, English, French, German, Italian, Japanese, Korean, Simplified Chinese, Spanish, and Traditional Chinese.

+ For AS/400 remote debugging, use the idebug command on workstations to start the debugger user interface and ensure that STRDBGSVR command was issued on AS/400.  

This release provides remote and distributed debugging support and tracing capabilities on Windows NT, AIX, Solaris, and HP-UX as follows:

• Windows NT Java debugging is supported on J2SDK v1.2.2
• AIX and Solaris Java debugging is supported on JDK 1.1.8
• Tracing capabilities are supported on J2DK v1.2.2 on Windows NT, AIX, and Solaris
• Debugging support on HP-UX is supported at the beta level

2.0 Prerequisites

Netscape Navigator, Version 4.5 or later is recommended for displaying debugger online help. If you reopen a help window multiple times and get a browser exception, then please ensure you are running a fairly recent version of a browser.

The interpreted debugger prerequisites are as follows:

JDK(TM) level as specified by the product with which the Distributed Debugger and Object Level Trace shipped.

For standalone debugging, the location of Java(TM) executable specified in the PATH environment variable must be from the JDK "bin" directory. If another Java executable is specified, the debugger cannot debug the application. For example,
if, on Windows NT, the PATH environment variable points to a java.exe 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.

To use the Distributed Debugger or Object Level Trace after installing V8.5 of the Distributed Debugger on top of WebSphere Enterprise Edition 3.02 on Windows NT, you must go into the IBMDebug\bin directory and rename ivbtr30i.302 to ivbtr30i.dll.

To use the Distributed Debugger or Object Level Trace on AIX, J2SDK(TM) v1.2.2 PTF8  is required.  

On OS/2, interpreted Java debugging is only supported for Java programs developed for JDK(TM) 1.1.8 or lower.

2.1 Prerequisites for OS/390 users
The following prerequisites require you to check the version of the Distributed Debugger user interface you are using on your workstation to debug your OS/390 programs. You can get the version number by issuing an "idebug" command at a command line prompt. The version number appears in the message that appears in  your Command Prompt window.

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 of the Distributed Debugger is available for download at
IBM VisualAge Developer's Domain (http://www.ibm.com/vadd)

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

09/1999 DT PTF (EQAW.SEQAMOD)
03/2000 DT PTF (Y2000.M05.D09 DT)  

2.2 Prerequisites for DB2 users
If you are using remote stored procedure debugging on DB2, you must add the dertrjrt.jar file to your system CLASSPATH.

The location is dertrjrt.jar is as follows:

AIX: /usr/lpp/idebug/lib/dertrjrt.jar
Solaris: /opt/IBMdebug/lib/dertrjrt.jar
Windows NT: \IBMDebug\lib\dertrjrt.jar

3.0 Limitations and known problems

3.1 General distributed debugger limitations and known problems

• Port 8002 is reserved for multi-user communications and is not available as an engine port or UIDaemon port. **
• Although the Distributed Debugger may be installed as part of a product install, it must be uninstalled separately.
• On AIX, if running the user interface (idebug) results in the message "killed" and the user interface does not come up (or shuts down) the likely cause is insufficient system pagefile space.
• On AIX, if the LIBPATH environment variable contains /usr/lib, please ensure that /usr/lib/threads appears before /usr/lib.
• If you attempt to debug an interpreted Java application locally and do not have the JDK installed the following error message will be issued:
  java_g program is not available (not in the users PATH)
• If you attempt to debug an interpreted Java application remotely and do not have the JDK installed the following  error message will be issued:
  Unable to find JDK install directory
• 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 XXXX" command works from the command
  line.
• If running the user interface (idebug) on Windows NT results in an "cannot create 8002 server socket" there may be an old debugger java_g process still running. Use the Windows NT Task Manager to end it.**
• If running the user interface (idebug) on AIX results in an "Cannot run SMD" error, the likely cause is that some other program is using port 8002, or there is no aixTerm (X windows) capability.
• If you attempt to load an invalid program and then dismiss the starting dialog, the engine will still attempt to load the invalid program. After the time-out, a load failed message  appears (even if you have subsequently loaded a valid program).
• Do not click in any debugger windows when the busy cursor is displayed.
• The shortcut key F10 used for the "Step Over" operation must sometimes be pressed twice to perform a single Step Over operation. To correct this problem, select the "File" menu and then close the menu by pressing ESC. The F10 key will now work correctly.
• Avoid using the online help when debugging Java AWT applications as this may cause the debugger to hang.
• Some unicode characters, such as \u03a9, will not be displayed correctly. The debugger currently cannot tell if a given character is displayable in the current user font set. **
• Do not change the File > Preferences > General settings ('Appearance','Toolbars') since that may cause erratic debugger behavior. If you do change them, and want restore the default settings, you can delete 'Workbook*.ini' and 'Panes.ini' in your 'DbgProf' profile directory. **
• The floating position of the toolbar is not working and causes the toolbar to disappear completely.
• To change the debugger defaults, load one application, change the settings, select the Debugger Defaults check box and then exit the debugger. **
• If the debugger user interface is terminated then the debugger engine ("derdfsrv" or "derdewd") may need to be manually terminated. If the "derdfsrv" or derdewd" process is running when you attempt to re-start the debugger ("idebug"), the debugger may not start.
• If you catch an exception and choose to run the exception, the debugger UI will no longer respond unless your application hits a breakpoint, runs to completion, or throws another exception. **
• If "Run To Completion" hangs on AIX in a Component Broker environment, users should terminate the client application.
• When running the debugger on a non-English version of AIX, the open dialogs for the Load Program > Compiled > Browse button and the Load Program > Interpreted > Browse > Add jar/zip button have a mixture of English and translated text in them. This is a known problem.
• Selecting a larger font by using the 'File > Increase Font' menu item may cause some text to be truncated. To correct this problem either use 'Decrease Font' to select a smaller font or restart the debugger to allow all components to adjust to the larger font.
• For Windows NT, if you receive an error message about not being able to locate CPPWMTHI.DLL, you should change the setting of the LOCPATH so that %LOCPATH% appears as the first value in the Value field. Set the LOCPATH environment variable in the "User Variables" section of the Environment page of the System Properties window. This ensures you will pick up the System LOCPATH value as well.
• If you attach to an AS/400 job without specifying the name of the program to debug and run your application to completion, you will not get notified of the application completion. At this point, you can either bring up the 'Load Program' dialog to start a new debug session, or use the HALT button to terminate the current debug session.
• When debugging an AS/400 application and using the 'Change Text File' option in the 'Source' menu, specify either a valid local file, or * to use the original AS/400 source file. If you specify an invalid source file name, the displayed view may become corrupted.
• Windows NT has a limit on the length of command lines (2100+ chars). The "idebug" command typically uses about 350 characters. You should need to ensure their CLASSPATH environment variable is less than 1750 characters in length. A CLASSPATH greater than this will result in unpredictable behaviour.
• The debugger (and many other Java products) requires TCP/IP to be functioning and that the user be able to 'ping' their own machine hostname (or, the hostname "localhost") even while disconnected from a LAN.
• If the source view scrolls after you have stopped pressing mouse button one, then click again either or below the slider to cause a single scroll once in the opposite direction.  
• If, on the Solaris operating system, when a signal occurs in a multithreaded debuggee, you examine or retry the signal, and then run it, the signal will re-occur when the thread that generated it terminates.
• When this situation occurs, the signal can not be run or discarded. Uou must terminate the debuggee.
• When debugging Java Server Pages the user may step to HTML lines, but cannot step to or into inline Java code. However, variables declared in inline 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 %>
  
  the user cannot step into the inline java code (included in the <% %> tags) but can add the variables _s1 and/or _s2 to the program monitor list.
• If the debugger is installed in a directory containing spaces, do not add %CLASSPATH% to the classpath if it is not yet set.

3.2 Debugger engine limitations and known problems for interpreted Java

Limitations exist in the JDK that may cause problems when debugging your interpreted Java classes. You should be aware of the following limitations and problems when debugging interpreted Java programs:

• The "JVM arguments" field in the UI lets you specify JVM arguments to use for the program you are debugging. (it is equivalent to the -jvmargs option on the command line). If you specify invalid arguments, the debugger will not be able to launch a JVM for the application. The debugger cannot detect invalid options and the debugger engine will exit upon this failure (a debug API limitation). The debugger may hangor not run if you enter an invalid JVM argument.
• Starting a Java program for the purpose of attaching to that program is done differently on the Java 2 platform than it is for JDK 1.1.X

To start a program you want to attach to with JDK 1.1.X, use the following command:

java_g -debug <classname and args>

Yo start a program you want to attach to on the Java 2 platform, use the following command:

java -Xdebug -Xbootclasspath:<JDK install directory>\lib\tools.jar;
<JDK install directory>\jre\lib\rt.jar -Djava.compiler=NONE
<classname and args>

• When invoking a Java program on the Java 2 platform to be debugged you can pass the -Denv.class.path=.... variable so that the debugger can find the .java files for the classes you are debugging. The env.class.path can be a list of JAR files or directories (or both).
• You cannot debug a program which reads from standard input - the debugger will hang. This is a JDK limitation.
• Stepping behavior may be erratic when stepping into constructors, or when stepping into or over SystemLoad library functions.
• Console input is not accepted.
• You cannot suspend or stop threads.
• You cannot modify the contents of monitored variables.
• Breakpoints set on static initializers or static blocks will be ignored. Breakpoints set on try statements will be ignored.
• The debugger will not notify the user when classes extending from java.lang.Error are thrown. The debugger will notify the user when classes extending from java.lang.Exception are thrown.
• After exiting a program block, variables that are out of scope may still be shown in the monitor. This is a JDK problem.
• Debug-agent error messages may appear intermittently while your classes are being debugged.
• If you step into a class that has not been registered with the debugger, you may receive a " No Source Available"
  error message. If this happens, issue a step return command to continue debugging. To avoid this problem, register the class with the debugger before you start debugging. Select Source> Open New Source. Enter the package name and class and click OK.
• When debugging remotely, communication between the debugger and the program being debugged may be terminated prematurely by the JVM.
• When stepping over a statement which causes an exception to be thrown, the debugger will not always correctly step into the catch block for the exception.
• Applets contained within a JAR file cannot be debugged. For example, although breakpoints can be set, they will not be hit when the applet is executed. In order to debug the applet, the class files must be extracted from the JAR.
• Some non-English characters will not display correctly in the debugger console window ("System.out").
• When debugging interpreted Java, the debugger provides 2 different ways of stepping into a method:

1. Step Into - This will step into the specified method regardless of what package the method is in.
2. Step Debug - This will only step into methods which are not in the following packages:
   - java.*
   - javax.*
   - sun.*
   - com.sun.*
   - com.ibm.*
   - org.omg.*
   - org.xml.*
   - org.w3c.*

• When running your debugger remotely and the source files reside on the machine where you are running the debugger user interface, set DER_DBG_PATH environment variable to include your source files.
• When debugging remotely using irmtdbgj in Windows NT, if the -classpath value passed to -jvmargs option has a space, the debugger will not be able to launch a JVM for the application. In order to avoid this problem you can do one of the following:
  • add the classpath information to the CLASSPATH environment variable instead of -jvmargs option.
  • add \\\" (three backslashes plus quotes) around the classpath information passed to -jvmargs option. For example:

  irmtdbgj -jvmargs="-classpath \\\"c:\Program Files;d:\test\\\" -mx32"

• On the Java 2 platform, you can Step Debug into a constructor only if you have set a breakpoint in the constructor prior to issuing a Step Debug command.
• Monitoring a variable on its declaration line in order to monitor it will fail. You must click on the variable within its scoping block. A variable's scoping block begins after it has been declared and used.  

3.3 Debugger Engine limitations and known problems for compiled languages

Be aware of the following limitations and problems when debugging with the compiled language debugger.  

The following statements apply to debugging High Performance Java programs:

• Compiled Java programs provide static typing information to the debugger. This limits an object's representation in the debugger to its initial declared type. For example an object of type Fred will always be displayed as a Fred in the debugger, even if this object becomes another type during program execution.
• The dot operator is used as a member selector only. That is, the debugger supports expressions of the type <instance var>.<member> but does not support expressions such as <static_class_name>.<static_member>
  or <package_qualifier>.<member>.
• You may encounter difficulties using step debug and step return when the debugger enters HPJ.DLL. HPJ.DLL is invoked on some method calls and constructors but does not contain debug information. This may result
  in an unexpected current execution point.
• The debugger does not allow you to inspect the derived type of a variable. For example:
  B b;            // where B is a base class
  D d = new D(); // where D is derived from class B
  b = d;        // assignment
  Monitoring b will only show the members of class B, and not of class D. Monitoring d will show the members of class D.
• Some classes may not show inherited data members when being monitored by the debugger.
• Monitored variables of type 'char' do not default to the character representation.
• Monitored variables of type 'boolean' are displayed as 1 and 0 instead of true and false.
• Monitoring an expression that will change under a series of 'step over' actions may cause the debugger to abend.
• If stepping into a class for which the source is not available, do not attempt to click on the stack frame to view the source. This will cause the debugger to crash.
• When doing 'step over' actions in a catch block within a finally block,  the debugger will crash.
• Monitoring a variable on its declaration line in order to monitor it will fail. You must click on the variable within its scoping block. A variable's scoping block begins after it has been declared and used.   

Other issues to be aware of:

• Three pieces of information are displayed in any monitors' view of a string:
  1. value - the string buffer
  2. length - the length of your string
  3. offset - the offset into the string buffer where the string begins

• If the thread on which you are monitoring a variable ends, the Storage Monitor will stop updating until a new thread (with the same number) is created.
• Explicit throws are not seen by the debugger if the catch block is in the same method.
• When a Step Over command is executed while the current execution line is in a for loop, the debugger may stop on the wrong line.
• Due to some Java line number problems, the debugger may exhibit some incorrect stepping behavior.
• Due to some Java line number problems, the debugger may indicate 'not allocated' for some variables.

The following statements apply to all compiled languages (C, C++, HPJ):

• The debugger will sometimes not accept changes to the values of variables, expressions, or storage. This is due to a focusing problem and can be resolved by setting active a non-debugger window or other running application, and then refocusing the debugger. The problem appears on AIX while debugging compiled languages.
• Editing Storage Monitors will cause your monitor to switch to the current stopping thread, which may or may not be the thread you created the monitor on. This also occurs when you are using the "goto address" on the storage monitor pane. This problem does not occur with single-threaded applications.
• Editing text values in the various panes requires the user to press Enter when done. Clicking elsewhere in the pane without first pressing Enter will cancel the editing.
• The debugger does not allow the monitoring of an expression such as "this.x", where x is a member of a class. Use "x" instead.
• On AIX, a "HALT" action can be performed on the program you are debugging by opening another window on the program you are debugging's machine, finding the process ID of the program you are debugging using the ps(1)
  command, and then executing the command "kill -STOP <pid>", where <pid> is the process id of the program you are debugging. This can interrupt long-running execution actions such as step-debug.
• AIX m-n pthread support. When debugging an application that makes use of m-n pthreads, force the kernel to allocate 1 kernel thread for each pthread. The debugger will then display all of the applications threads. Set the following environment variable to cause the number kernel threads to match the number of pthreads: AIXTHREAD_SCOPE=S
• The operation of step-debug has been changed to allow the user to bias the step-debug behaviour either toward performance or function. The default is tailored toward better stepping performance. It steps over calls made to
  shared libraries that do not have any debug information. This improves performance by ignoring libraries that are unlikely to lead to debuggable code. If the environment variable DER_DBG_DEEP_STEP_DEBUG is set to 1,step-debug will follow such calls. This allows step-debug to reach callbacks from libraries that have no debug information, at the cost of somewhat degraded stepping performance.
  For example:

Module A and C contain debug information, B does not. 

line module A     line module B     line module C
==== ========     ==== ========     ==== ========
100  call B()    
                                5    call C()
                                                                     500 do some stuff
                                                                     510 return
                                 6    do stuff
                                 20   return
101 do stuff

A default step debug executed at line 100 in module A will cause the debugger to stop next at line 101 in module A. If the DER_DBG_DEEP_STEP_DEBUG environment variable is set then the debugger will stop at line 500 in module C.

4.0 Object Level Trace

Troubleshooting information for Object Level Trace is found in the OLT reference section of the online documentation. You can access this information from the help menu in any debugger or OLT window, or you can open \help\en_us\index.htm
in your IBMDebug install directory.

For Internet Explorer users: If you get a "file not found" error when launching online help from an OLT user interface, you may have outdated versions of two Internet Explorer DLLs on your system (URL.DLL and SHLWAPI.DLL). This causes the
"file://" string to be dropped from the URL. Installing Internet Explorer 4.01 or later corrects the problem.  

4.1 Corrections to the OLT online documentation
For all the WebSphere 3.5 documentation:

• Replace all references to IBMDebug\lib\dertrjrt.jar with %SOMCBASE%\lib\dertrjrt.jar
• Replace all references to IBMDebug\lib\derdbpw.jar with %SOMCBASE%\lib\derdbpw.jar.
• The following information should have been included in the section "Enabling OLT for Component Broker":
  For Component Broker, AIX or Solaris servers only:
  In the System Manager, change the Health monitor polling interval value to 0 on the host image that corresponds to the name of your server. You must start the System Manager user interface with the -repair  option, then select Host Images->yourhostname and right click on it. Select "Properties" from the pop-up menu. Under the Main tab, change the Health monitor polling interval to 0. If you see a big blue square replacing the arrow tip of the scroll arrow or
  the slide bar, change the look and feel from Metal to Windows or Motif.
• Java runs out of memory while running OLT
• The following error is a JDK limitation (JDC defect 4074669). There is nothing to do to fix it in this JDK level. It will not stop OLT, but it will slow down OLT and your system. Here is the error:

java.lang.OutOfMemoryError
    at sun.awt.image.ImageRepresentation.setPixels(Compiled Code)
    at java.awt.image.RGBImageFilter.setPixels(Compiled Code)
    at sun.awt.image.PixelStore8.replayLines(PixelStore8.java:53)
    at sun.awt.image.PixelStore.replay(Compiled Code)
    at sun.awt.image.PixelStore.replay(PixelStore.java:161)
    at sun.awt.image.InputStreamImageSource.updateFromStore (InputStreamImageSource.java :301)
    at sun.awt.image.InputStreamImageSource.doFetch (InputStreamImageSource.java:255)
    at sun.awt.image.ImageFetcher.fetchloop(Compiled Code)
    at sun.awt.image.ImageFetcher.run(Compiled Code)
java.lang.OutOfMemoryError
    at sun.awt.image.ImageRepresentation.setPixels(Compiled Code)
    at java.awt.image.RGBImageFilter.setPixels(Compiled Code)
    at sun.awt.image.PixelStore8.replayLines(PixelStore8.java:53)
    at sun.awt.image.PixelStore.replay(Compiled Code)
    at sun.awt.image.PixelStore.replay(PixelStore.java:161)
    at sun.awt.image.InputStreamImageSource.updateFromStore (InputStreamImageSource.java :301)
    at sun.awt.image.InputStreamImageSource.doFetch (InputStreamImageSource.java:255)
    at sun.awt.image.ImageFetcher.fetchloop (Compiled Code)
    at sun.awt.image.ImageFetcher.run(Compiled Code)

• Some trace lines have Server as the Object name. This problem seems to occur when the application is debug enabled and is run before launching OLT. What happens is that the objects are already initialized, and so when OLT is launched and these objects are called, they do not call their respective initializers and therefore OLT can not determine what the objects are. You should always start OLT before running a debuggable application if you want to use OLT.
• If you are using any Websphere 3.5 Applications with a different codepage than the OLT Tool workstation, you must set the following environment variable on the Websphere 3.5 Applications workstations:

OLT_TRC_SRV_CODEPAGE=codepage of the OLT Tool host

4.2 NL and GUI related limitations

• Do not set the TCP/IP debugger port value to 8002 in the Client Controller. Doing so causes the tool to hang for DBCS locales. The port 8002 cannot be used in this case since it is reserved for the debugger use.
• The "Show logo at startup" checkbox in the Preferences > General pane is not used.
• The floating position of the toolbar is not working and causes the toolbar to disappear completely.
• While choosing the toolbar appearance as "Text" or "Pictures and text" in  Preferences > General > Toolbars, if there are enough tool buttons, the toolbar is truncated and there is no scrollbar or other means to enable making all the buttons visible. For some languages the text for the buttons is so long that the problem may occur with only a few buttons being present in the toolbar.
• In some cases, the OLT tool may display error messages which for non-English versions may still have the last part of the text in English. This text is a system error and cannot be generated in languages other than English. 
• The vertical display mode has been disabled for this release.
• While tracing in the real-time mode users OLT tool may hang. The workaround for this problem is to trace first the execution of the application in the normal mode and then switch to real-time mode for consecutive runs in the same OLT session.
• For Windows(R), the help settings in Preferences > General > Help dialog may not seem to be working, as the help system always selects the default browser, regardless of which browser you specify in this dialog.

4.3 OLT user interface limitations
When OLT is in step-by-step debug mode, the OLT Viewer displays a dialog box at each debuggable method prompting you to step into the next debuggable method. You may not see this dialog box if the Distributed Debugger user interface is covering the OLT Viewer. If you are waiting to be prompted to step into the next debuggable method by the OLT Viewer, bring the OLT Viewer in focus so that you will see the dialog box.

4.4 Building CB ActiveX client applications for trace and debug
Follow the instructions in Chapter 8 of the Component Broker Programming Guide to
build the ActiveX(R) client DLLs. 

Visual Basic(R) or other OLE Automation client applications using the ActiveX interface 
may be traced but not debugged (i.e. you cannot step back from a server business 
object method into the client method).

Microsoft Visual C++(R) clients may be traced and debugged provided they are compiled 
and linked to be compatible with the Distributed Debugger format.

You must specify the /Z7 compiler option to produce Microsoft C 7.0 debug information
and the /DEBUG and /PDB:NONE linker options to generate the necessary debug information and embed it in the executable (rather than generating a program database file).

If you are using a Microsoft Visual Studio(R) project the options are accessible from the
Project Settings dialog as follows:
- the /Z7 option: from the C/C++ tab select Category: General and select Debug info: 
C7 Compatible
- the /PDB:NONE option: from the Link tab uncheck the Use program database check box. 

5.0 Installation on Windows

Installing the Distributed Debugger on Windows is automatic and does not require you to manually issue any commands or move any file (beyond selecting to install it in the installation setup screen).

If you have previously installed a beta version of the IBM Distributed Debugger you must first uninstall the beta version of the debugger before installing this product.

The debugger will not function if installed in a directory whose name contains DBCS characters.  

5.1 Uninstalling on Windows
On Windows, the debugger should not be uninstalled using the Add/Remove Programs icon in the Control Panel. The debugger should only be uninstalled via the product that installed it. Refer to the uninstallation instructions for the product.

If you previously installed a beta version of the IBM Distributed Debugger and you did not uninstall the beta version of the debugger before installing the product, either follow the process below to remove the debugger from your system and reinstall it.

IMPORTANT: The following process requires manual deletions to your registry information. If you accidentally delete any other registry key/entry than those identified below, your system may become unstable or unusable. Do NOT use this process if you are not experienced at manual registry editing.

To remove the IBM Distributed Debugger, perform the following steps:

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\CurentVersion\Install
4. If the Refcount value is greater than 1, then decrement the "RefCount" value data by 1.
5. Click on the Uninstaller icon of the newer (non-beta) version of the Debugger.
6. 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)
7. If the "RefCount" value data is equal to one, remove the following registry key, if it exists:
   HKEY_LOCAL_MACHINE\SOFTWARE\IBM\IBM Distributed Debugger

If your RefCount entry is not equal to one, you are finished this process.

To reinstall the IBM Distributed Debugger, use the product CD.

You must uninstall the Distributed Debugger before you uninstall VisualAge for Java. Refer to the "Known problems and limitations with Uninstallation" section (for either Entry Enterprise or Entry Professional edition) in the Installation and Migration guide for more information. 

6.0 Installation on platforms other than Windows

Search for the install image of the distributed debugger. Copy the install file(s) to the machine on which debugger is to be installed.

To install on AIX (R): Use installp or 'smitty install_latest'.

To install on Solaris: Issue "pkgadd -d [name of the install image]"

To install on OS/2:

1. Choose a drive on which to install the Debugger Engine.
2. Create a directory called "\IBMDebug".
3. cd 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 cause these changes to permanent, modify the environment variable settings in the CONFIG.SYS file. 

7.0 Browser configuration

7.1 Internet Explorer for Windows

• You  must have Microsoft (R) Internet Explorer, Version 4.0 or later
• Ensure you have a JDK installed on your system before performing these steps. In order to debug applets inside Internet Explorer, you must install the Java(TM) Plug-in 1.1.1 or greater, available from http://www.javasoft.com and configure your HTML pages to use the modified applet tag format.
  1. Close your browsers.
  2. Start the Java Plug-in Properties panel.
  3. Click the Advanced tab.
  4. Select 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 your 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 and
      Windows (R):

irmtdbgj -qport=<port> -host=<hostname> -password=<agent password>

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

7.2 Netscape for Windows

You must have Netscape Navigator, Version 4.0 or greater.

Follow the instructions for Microsoft Internet Explorer with the following
modifications:

If you wish to debug more than one applet on the same system or if port 2502 is being used by another application, you may use the  following port/password pairs:

Port in Plug-In Panel     Agent Password for jdebug
-------------------------  ------------------------------
2502                             52fd4n
2503                             527dkr
2504                             4k6h32
2505                             44edjc
2506                             5ifdjf
----                                 ------
8003                             3kyt2g
8004                             44rtii
8005                             54rtik
8006                             4kyxkx