Novell is now a part of Micro Focus

Debugging DirXML Drivers

Articles and Tips: article

Kevin Burnett
Senior Research Engineer
Novell AppNotes

01 Jan 2002


In the November and December 2001 issues of the AppNotes, I presented a question and answer approach to learning about DirXML drivers. This constituted an introduction to DirXML as a technology and of DirXML drivers to a lay person. To a more advanced engineer, this presented a good review of DirXML technology.

This month will continue along the same theme by tackling the subject of how to debug and test DirXML drivers.

During BrainShare 2000, Novell's Net Directory Team provided an extensive demonstration of the potential of DirXML drivers. Some of the drivers that were showcased included the JDBC driver, Windows NT driver, Lotus Notes driver, NDS-to-NDS driver, NDS-to-Active Directory driver, Microsoft Exchange driver, and Netscape driver.

Although this demonstration was all-inclusive, it did represent a possible scenario for a large company. With more and more DirXML drivers being written, the time will shortly arrive when synchronizing data from your favorite application to eDirectory will be a reality. But the big question looms: how do I set up the DirXML drivers I need initially, and even more important, how do I maintain them?

Granted, Novell provides a consulting division that is available to help you install the needed DirXML drivers for your company. But as an engineer or IS professional, having a basic understanding of DirXML driver debugging procedures can benefit your company in many ways, including saving time.

The remaining part of this article will discuss a few approaches to debugging DirXML drivers. If you have specific questions that this article does not cover, please send e-mail to me through the address listed in the front of the AppNotes.

Debugging a DirXML Driver

From my experience, the best environment for debugging a DirXML driver is a Windows NT server running eDirectory for NT. This allows you to have eDirectory, the DirXML engine, Sand the DirXML drivers all on the same platform. In addition, the graphical interface of Windows allows you to run utilities in an easier manner than using NetWare as the debugging platform. Although I favor the NT platform for debugging, I will also cover using the NetWare platform.

Use DSTRACE

Messages that are sent from the DirXML engine and DirXML drivers will show up in the DSTRACE utility if you enable the DirXML Drivers events in NT and DVRS on NetWare. By default, very little information is given--mostly just the status of events.

In order to enable more verbose output, add the DirXML-DriverTraceLevel attribute to the DirXML-DriverSet object using the "Other" tab on the ConsoleOne "Properties" dialog. The following are useful values for this attribute:

  • 1 = Informational messages about what DirXML is doing

  • 2 = Adds XML dumps that are passed to/from the driver

  • 3 = Adds XML dumps after a stylesheet is applied

  • 4 = Provides more verbose output during rule evaluation

DirXML drivers may also send messages to DSTRACE by creating and using an instance of com.novell.nds.dirxml.driver.Trace. It is recommended that drivers do not write directly to System.out or System.err (even though this will currently send the output to the DSTRACE screen) because this may not be supported in future releases.

A simple rule of thumb is to do what Novell and the DirXML driver documentation (http://www.developer.novell.com ) recommends. That way your chosen route of debugging will not become obsolete.

Trace messages may also be directed to a file (in addition to DSTRACE) by setting the value of the DirXML-JavaTraceFile attribute on DirXML- DriverSet object to a valid filename. Use the "Other" tab on the ConsoleOne "Properties" dialog for the DirXML-DriverSet object.

Attach a Java Debugger

Note: This option is only supported on Win32.

There are a number of Java debuggers available and two common debugger APIs on the Java platform.

The following will introduce a few of these debuggers and how to use them:

Agent Debugger

  1. Obtain a copy of JDK 1.3.0 or greater.

  2. Make a backup copy of the DirXML jre directory that is typically located in C:\Novell\Nds\jre.

  3. Delete the DirXML jre directory.

  4. Copy the jre directory from the JDK into the DirXML jre directory.

  5. Copy the contents of the jdk lib directory (jdk/lib) into the DirXML jre/lib directory (tools.jar, etc.).

  6. Add the DirXML-JavaDebugPort attribute to the DirXML-DriverSet object (use the Other tab in the ConsoleOne Properties dialog for the DirXML-DriverSet object).

  7. Set the DirXML-JavaDebugPort value to a TCP port value not in use on your machine. Typically 8080 usually works.

  8. Restart eDirectory.

  9. Before the first driver in the driver set starts, a dialog box will pop up informing you of the debugger password. At this point you can attach a debugger to the JVM and press OK. You can also press OK without attaching a debugger.

Java Platform Debugger Architecture (JPDA)

  1. Obtain a copy of JDK 1.3.0 or greater.

  2. Copy the jdwp.dll, dt_shmem.dll, and dt_socket.dll from the bin directory in the JDK into the NDS directory.

  3. Set the appropriate debug options in the DHOST_JVM_OPTIONS environment variable (Seehttp://java.sun.com/products/jpda for details).

    For example: set DHOST_JVM_OPTIONS=Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,address=8080,suspend=n

    Note: If running as a server, you must set this in the System control panel under System variables.

  4. Restart eDirectory.

  5. Before the first driver in the driver set starts, a dialog box will pop up informing you of the debugger password. At this point you can attach a debugger to the JVM and press OK. You can also press OK without attaching a debugger.

Using the Visual Cafe Debugger (v3.0 or v4.0)

  1. Create a project to use for debugging.

  2. Set the main class to "sun.tools.agent.EmptyApp."

  3. Set the source directories and input class files directories appropriately for your environment.

  4. Attach the debugger to the DirXML JVM using Projects | Debug in Waiting VM. Use "localhost" as the host name and the password supplied by the dialog box mentioned above.

Using jdb

The jdb is an agent-type debugger. To setup a debugging session, perform the following steps:

  1. Enter the following command on the command line:

    jdb -host localhost -password <password>

  2. Set the path to your source directories using the "use" command.

  3. You can create a file named "startup.jdb" in the working directory that can contain commands that will be executed when jdb starts. This is a good place to put the "use" command.

Using the CodeWarrior 5 Debugger

  1. Add the following registry key if it doesn't already exist:

    "HKEY_LOCAL_MACHINE\SOFTWARE\Metrowerks\CodeWarrior\4.0\Java VMs"

  2. Add to that key the String value "JDWP debug ports" for JPDA debugging or "11XWP debug ports" for Agent debugging.

  3. Set the value to be the port number that DirXML was set up to use. Contrary to the documentation, apparently CodeWarrior does not seem to recognize ports greater than 9999 or more than 1 port for each value.

  4. Start CodeWarrior.

  5. Open the class or jar file that you wish to debug.

  6. Choose SunJavaPlugin.dll when asked to choose the debugger.

  7. Select Window | Process Window to open the Process window.

  8. Select the entry "JDWP debug port XXXX (inactive)" or "11XWP debug port XXXX (inactive)" (where XXXX is the port number you are using.)

  9. Press the "attach to process" button.

  10. For more information see the CodeWarrior help files.

Miscellaneous Notes About Debugger Use

  1. Usually you can attach a debugger after you have dismissed the DirXML dialog that pauses, waiting for you to attach to the JVM.

  2. If you stop the debugging session in VisualCafe or jdb, it shuts down the DirXML JVM running in the NDS process and you will have to restart NDS to get it back up again.

  3. The VisualCafe 3.0 debugger has a lot of quirks. Occasionally it has trouble attaching to the JVM.

    Sometimes it gets internal Java exceptions, after which it will display no data until you shutdown VisualCafe and restart it. Often it will stop at breakpoints that have been removed or disabled.

  4. The password is really just an obfuscated version of the port number. Since you are picking a static port number, you can reuse any of the passwords that are generated. If you see one that is easy to memorize, remember and use it instead of using a new password every time.

Environment Variables

The following environment variables are available to be use on the Win32 platform:


Variable
Explanation

DHOST_JVM_USE_VFPRINTF

If set to a value other than "0," this variable will cause the installation of a vfprintf hook function that will write to a log file named "jvm_vfprintf.log" in the temp directory. This will also enable verbose class and JNI messages.

DHOST_JVM_VERBOSE_GC

If set to a value other than "0," this variable will enable verbose garbage collector messages. This is only useful in conjunction with JVM_USE_VFPRINTF.

DHOST_JVM_INITIAL_HEAP

Sets to value, in decimal number of bytes, the initial JVM heap size.

DHOST_JVM_MAX_HEAP

Sets to value, in decimal number of bytes, the maximum JVM heap size.

DHOST_JVM_OPTIONS

Sets to arguments for the 1.2 JVM. For example:

-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,address=8080, suspend=n

Each option string is separated by whitespace. If an option string contains whitespace, it must be enclosed in double quotes.

DHOST_JVM_DESTROY

If set to a value other than "0," this variable will cause the JVM loader thread to call DestroyJavaVM() when DirXML is unloaded.

This is useful to cause the Java 2 hprof profiler to dump its data to a file. Note that the JVM is unusable after this call and cannot be reloaded. DHOST must be shutdown and restarted in order to use the JVM again (this means DirXML cannot be restarted until DHOST has been restarted).

The following variable options can be used on NetWare:


Variable
Explanation

DIRXML_JVM_INITIAL_HEAP

Sets to value, in bytes, the initial Java heap size. Works with JVM 1.1x and 1.2x.

Example: DIRXML_JVM_INITIAL_HEAP=4M

Example: DIRXML_JVM_INITIAL_HEAP=4096K

DIRXML_JVM_MAX_HEAP

Sets to value, in decimal bytes, the maximum Java heap size. Works with JVM 1.1x and 1.2x.

Example: DIRXML_JVM_MAX_HEAP=36M

Example: DIRXML_JVM_MAX_HEAP=36864K

DIRXML_JVM_VIRTUAL_HEAP

Sets to value, in decimal bytes, the virtual Java heap size. Works with JVM 1.1x and 1.2x.

Example: DIRXML_JVM_VIRTUAL_HEAP=36M

Example: DIRXML_JVM_VIRTUAL_HEAP=36864K

DIRXML_JVM_OPTIONS

Sets to arguments for the 1.2x JVM. For example:

-Xnoagent -Xdebug -Xdebugport8080 -Xmx36M

Each option string is separated by whitespace. If an option string contains whitespace, it must be enclosed in double quotes.

Note: This option only works with the 1.2x JVM.

DIRXML_JVM_C_STACK_SIZE

Sets to value, in decimal bytes, the Java C process stack size.

Example: DIRXML_JVM_C_STACK_SIZE=128K (default)

Example: DIRXML_JVM_C_STACK_SIZE=256K

Conclusion

Practice is the best way to learn how to debug and troubleshoot DirXML drivers. When debugging and troubleshooting a DirXML installation, it will take time to get familiar with all of the available tools and resources. This article is only an overview to whet your appetite. More information can be obtained from Novell's developer resources Web site: http://www.developer.novell.com.

DirXML is an evolving technology at Novell. As time progresses, new and improved tools will be introduced and techniques will be provided. Keep in contact with Novell for the latest and greatest DirXML information.

This completes the mini-series on Novell's DirXML technology, drivers, and troubleshooting. If you would like to see a particular directory concept covered in AppNotes Directory Primer, send an e-mail to gherbon@novell.com
.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates