Readme for the JNI Debug Utilities Technical Preview
(C) Copyright International Business Machines Corporation 2000, 2004.
All rights reserved.
U.S. Government Users Restricted Rights -- Use,
duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
See Notices and trademarks for
other related information.
This technical preview contains the following new functions:
- Attach a compiled language debugger to a running Java debug session so that native libraries can be debugged.
- Create a JVM from a native program in debug mode and automatically start a Java debug session so that Java classes can be debugged.
The following limitations apply to this technical preview:
- Java classes and native libraries should not be placed in a directory structure which contains spaces in the directory name. This applies to both user classes and libraries and the JNI utility class and libraries found in the \host directories. Please note that the default workspace location contains spaces, and thus, any Java projects created in the default location will also contain spaces.
- The Java debugger and the compiled language debugger are not integrated. When a compiled language debug engine is attached to a JVM that is being debugged by the Java debugger, two separate debug sessions will appear in the Debug view. One is the Java debugger, and the other is the compiled language debugger.
- When the compiled language debugger has suspended the JVM process so that you can debug a native library, the JVM will be unreachable by the Java debugger. Any requests by the Java debugger during this time (such as setting Java breakpoints, trying to step/run in the Java debug session, or workbench UI label requests) will fail. In some cases, the failure of these requests can cause unexpected results in the Java debug session.
- A JNI method call cannot be stepped into (either from Java to native, or native to Java). A breakpoint must be set in the method being called. Stepping over the JNI call should stop at the breakpoint set in the method.
- The "Enable JNI Debugging" action on a Java debug session only works if at least one thread in the JVM has been suspended, such as on a Java breakpoint.
- When a native program creates a JVM in debug mode and automatically starts a Java debug session, Java source location information must be picked from a list of the Java projects in the workspace.
In addition, regular Java debugging limitations and compiled language debugging limitations apply. These include, but are not limited to:
- Compiled language program input/output will not appear in the workbench Console view. On Windows, program input/output will appear in a separate DOS window. On OS/390, the program input/output will appear in the terminal window.
- The list of loaded modules (native libraries) in the Modules view may not be accurate when attaching Debug Tool to a JVM on OS/390. Some loaded modules, possibly including user libraries, may not appear in the list.
- Module names in the Modules view may be truncated when debugging on OS/390.
- Setting breakpoints in modules that have not been loaded yet on OS/390 can be difficult because the executable/object/file names must be specified exactly in the breakpoint wizard, including compiled path information. Use of the "Stop at all Function Entries" action available on the Breakpoints view context menu is recommended.
- Attaching the compiled language debugger to a JVM on Windows (such as with the "Enable JNI Debugging" action) may produce an error dialog with the text "No error message text available" or "Invalid thread ID". These errors can be ignored.
- Java debugging requires that the Java source files reside within the workbench in a Java project, even if the JVM being debugged is on a different machine. Breakpoints can be set in Java classes before debugging starts by double-clicking on the source file in the Package or Navigator view, then double-clicking beside the source line in the editor prefix area.
4.1 Workstation Installation Instructions
Note: IBM WebSphere Studio Enterprise Developer 5.1.2 must be installed before you can apply this technical preview.
- Download the JNIDebug_UpdateMangerInstall.zip file to a temporary directory on your workstation.
- Extract the contents to a temporary directory.
- If debugging programs on Windows, modify the system %PATH% variable to include WSED_INSTALL_DIR\wstools\eclipse\plugins\com.ibm.debug.pdt.win32_5.1.3.1\engine\bin, where WSED_INSTALL_DIR is the IBM WebSphere Studio Enterprise Developer 5.1.2 root installation directory.
- If debugging programs on Windows, copy the contents of \host\win32 to an easily remembered directory that does not contain spaces in the directory path name. This directory must be added to the class path and the library path of the JVM being debugged for the "Enable JNI Debugging" action to work properly.
- Start Enterprise Developer.
- Click Help > Software Updates > Update Manager.
- In the Feature Updates view, expand My Computer.
- Browse to the temporary directory where the extracted files are stored.
- Expand jnidebug, then expand JNI Debug Utilities Tech Preview.
- Select JNI Debug Utilities Tech Preview 5.1.2
- In the Preview view, click Install Now. Click Next.
- Read and accept the license agreement to continue the installation.
- Click Finish
- Click Install
- The installation process should complete within approximately 2 minutes. When prompted, restart the workbench.
- Delete the temporary directory or the unzipped fix files to conserve disk space.
4.2 OS/390 Installation Instructions
- Download the JNIDebug_UpdateMangerInstall.zip file to a temporary directory on your workstation.
- Extract the contents to a temporary directory.
- FTP the contents of \host\zOS as binary to an HFS directory the OS/390 system. This directory must be added to the class path and the library path of the JVM being debugged for the "Enable JNI Debugging" action to work properly.
- Add executable permissions to libKickerProcessAttach.so. This can be accomplished by executing the command chmod a+x libKickerProcessAttach.so in the directory where libKickerProcessAttach.so was FTP'd.
Note: Uninstall of the tech preview code is not possible, but it is
possible to disable the installed feature using the following steps:
- Start Enterprise Developer.
- Click Help > Software Updates > Update Manager.
- In the Install Configuration view, expand IBM WebSphere Studio Enterprise Developer.
- Expand file:.../wstools/eclipse.
- Select JNI Debug Utilities Tech Preview 5.1.2
- In the Preview view, click Disable Now.
- Click Finish.
- When prompted, restart the workbench.
IBM, OS/390 and WebSphere are trademarks or registered trademarks of IBM Corporation.
Java and JVM are trademarks or registered trademarks of Sun Microsystems, Inc.