Debugging the extension

This section gives information about debugging the extension.

What is in the IBM Director log directory?

Under the directory where IBM Director is installed, there is a subdirectory named "log". This directory contains debug information in log files. There are several different types of logs

TWGServer.err

This file is created if the IBM Director server fails with a Java exception. Click herefor a sample view.

The RAS log

TWGRas.log is the log file for RAS logging. This file is useful because it wraps and will not fill up the disk.

There are three types of RAS log messages:

Error
These messages are always written to the TWGRas.log file.
In your extension, you can write a RAS error message with the following code:
TWGRas.error(TWGRas.EX0,"This is my error message");
or
TWGRas.error(TWGRas.EX0,"This is my error message - I caught an exception", myException);
Debug
These messages are only written when TWGRas messages are enabled. Click here for directions to enable TWGRas.
In your extension, you can write a RAS error message with the following code:
TWGRas.debug(TWGRas.EX0,"This is my error message");
High
These messages are only written when TWGRas is enabled and the high flag is used. These messages are used to time critical sections of code. Click here for directions to enable TWGRas.
In your extension, you can write a RAS error message with the following code:
TWGRas.debugH(TWGRas.EX0,"This is my error message");

TWGRas messages might be displayed in two ways:

  1. Real time - use the raswatch command to display the messages as they are written to the TWGRas.log file. One important note: on Windows, raswatch will actually turn logging on, but on Linux, you must turn the logging on in the twgras.properties file.
  2. Dump - at any time, you can dump the entire contents of the TWGRas.log file with the rasdump command. Be sure that you are in the log directory when you run rasdump.


Improving performance when logging Is enabled

Using RAS creates more processing overhead, consequently performance might be affected. To minimize the overhead of your debug logging, wrap each call to TWGRas.debug inside of a twg for the boolean for that trace flag. It will look something like this:

if (TWGRas.isTraceEX0)
   TWGRas.debug(TWGRas.EX0,"This code only runs when tracing is ON");

The above code will avoid the overhead of the logging method call and message string construction.

Note:  A check for this condition should be wrapped around each log method, so that you enable and disable RAS dynamically during the execution of your extension. You should not check if debug is enabled only once during the lifetime of your extension because this will prevent you from dynamically activating and deactivating RAS output with RasWatch.

Turning on TWGRas logging

To turn on RAs logging, go to the data directory and edit the twgras.properties file. Modify the file as shown in the following diagram:

Additionally, on Windows platforms, the raswatch program will dynamically turn on RAS flags. For help with raswatch, use the command:

raswatch -?


Output logs

The STDOUT and STDERR output for an extension is captured by the IBM Director Server. Normally, this output is discarded. When debugging, you can cause IBM Director to write the output messages to files in the log directory.

Turning on output logging

The output logging must be turned on to see the data in the output logs. The procedure for turning on the output logging is different on Windows platforms and on Linux.

Turning on output logging for Windows

Use the Windows registry editor. Find the key:
HKEY_LOCALE_MACHINE\SOFTWARE\Tivoli\Director\CurrentVersion
Set the value of LogDir to 1.
It will look like this:

Turning on output logging for Linux

Go to the IBM Director data directory. Edit the file TWGRas.properties. Uncomment the line for twg.sysout=1.
The file will look like this:

Where to find the output logs

The output logs are written into the IBM Director log directory. The file names are determined as follows:

The file extension
The file name
The file name is the classname used for the JVM. Usually, you will be using one of these files:

Using a debugger

Use the following steps to attach a debugger to the IBM Director Server to debug your code:

  1. Set a property to turn on the debug socket in the IBM Director Server. Go to the IBM Director log directory and create a fiel names twgsrv.properties. Add the following line to the file:

    jdpw=true

    save the file.
  2. Restart the IBM Director Server
  3. Use Eclipse or another Java debugger to attach to the IBM Director Server. Use port number 8000.


Using the Ras log with the IBM Director Console

The previous sections have described how to debug code that resides on the IBM Director Server; however, you might need to debug the user interface portion of your new task. Most of the facilities you have for debugging your extension server can be used to debug your extension code on a machine that has the IBM Director Console installed.

Like the IBM Director Server, the IBM Director Console does have the facility to capture STDOUT and STDERR and pipe it to a file. This is accomplished on Windows using the registry.

Now, using regedit.exe, modify the following server registry entry:

HKEY_LOCAL_MACHINE\SOFTWARE\Tivoli\Director\User\[computer]\[userid]\MainGUIConsole.ConsolePrefs

[computer] is the computer or domain name entered before the slash and the user ID on the IBM Director Console when logging onto the IBM Director Server.
[userid] is the user ID entered after the slash on the IBM Director Console when logging onto the IBM Director Server. The second byte of this binary data controls the IBM Director Console's use of native RAS support. The following values are used:

00
The IBM Director Console does not support RAS.
01
The IBM Director Console supports RAS using TWGRas.log as the log file.
02
The IBM Director Console supports RAS using TWGConRas.log as the log file.

Changing the value from 00 to 01 allows you to use the RasWatch or RasDump without having to specify a different log file for your console code. You then start the console as you normally would from the program menu. You should now be able to view RAS messages you have logged from your extension's console code.


Common problems with extensions

Problem Possible causes
The extension is not in the product information. The extension file does not end in ".TWGExt:.
The extension file is not located in the classes\extensions directory.
The extension is in the product information panel but has the wrong NLS string.
The IBM Director Server fails to start. The IBM Director Server cannot find the extension class.
- The classpath.append.x line does not point to the correct classname
- The twg.extension.classname does not match the extension class name
. The extension failed to initialize
- One of the extension methods threw an exception
The extension is in the product information but the string is wrong. Problem with NLs bundle lookup
- The bundle classname was not found.
- the value of twg.extension.name does not make the key in the NLS Resource Bundle.

Common problems with tasks

Problem Possible Causes
Task is not displayed on the Director Console There was an exception during the pocessing of new TWGDefaultTask(); Make sure that you catch and log the information in the TWGTaskCreationException.