DSTrace is an eDirectory trace facility that displays messages from internal eDirectory activities. These messages can be displayed on the DSTrace screen, logged to a file, or both. The messages can be filtered by category. For DirXML driver development, you will want to activate the DirXML Drivers messages.
To enable the DirXML Drivers messages, select the platform and follow the steps.
From the eDirectory console, select NDS Trace Facility and press the Start button.
The NDS Trace Facility screen appears.
From the Edit option on the NDS Trace Facility menu bar, select Options.
Press the Clear All button.
Check the DirXML Drivers box.
If you want DirXML Drivers messages enabled each time you run DSTrace, press the Save Default button.
To activate the settings and return to the trace screen, press the OK button.
From the server console, enter
dstrace
To start the trace facility, enter
dstrace on
To enable DirXML driver messages, enter
dstrace +dvrs
To view the output, toggle to the DSTrace window.
Enter following command in the shell: ndstrace.
2 Shut off all debug flags to avoid unnessesary messages. At the ndstrace screen, enter set ndstrace = nodebug.
3 To enable DirXML driver messages, enter dstrace +dvrs.
4 To enable DirXML events, enter dstrace +dxml.
5 To enable the log file option, enter dstrace file on.
On Unix systems, the events are written to the /var/nds/NDSTRACE.LOG file.
Verbose DirXML Driver messages can be used to determine what is happening in the DirXML engine and what your driver is processing. To enable verbose messages, complete the following steps.
From ConsoleOne, right click on DirXML-Driver Set object and select the Properties option.
Select the Other tab.
Press the Add button.
Select DirXML-DriverTraceLevel and press the OK button.
Enter one of the following values:
Press the OK button.
DSTrace messages are useful, but they eventually scroll out of the DSTrace buffer. To preserve the DirXML messages, you can set up a log file into which the DirXML Driver messages will be written (even when DSTrace is not running). To enable the trace log, complete the following steps:
From ConsoleOne, right click on DirXML-Driver Set object and select the Properties option.
Select the Other tab.
Press the Add button.
Select DirXML-JavaTraceFile and press the OK button.
Enter the name of a file into which the DirXML Driver messages are to be written.
The location for the log file depends on the platform:
Press the OK button on the Properties dialog.
Drivers should send messages to DSTrace by creating and using one or more DirXML trace objects. Using these objects, your driver can write messages and XML documents to the DSTrace screen and the DirXML Trace Log.
Each trace object has an identifying string associated with it, and this string appears in the trace message. A driver typically creates three trace objects:
For example, if the subscriber object creates a trace object with the identifying string "NdsToNds Subscriber" then all trace messages output using that object will look similar to the following.
TRACE: NdsToNds Subscriber: <message>
In Java the trace objects are simply instances of the com.novell.nds.dirxml.driver.Trace class. For example:
//In the class definition
Trace tracer;
//In the constructor
tracer = new Trace("My Subscriber");
In C++ a factory method from InterfaceFactory.h, Trace_new(), is called.
//in the class definition:
Trace * tracer;
//in the constructor:
Trace * tracer = Trace_new("My Subscriber");
//in the destructor:
Trace_destroy(tracer);
Writing a message is as simple as calling the trace method with a literal string argument. Additionally, XML documents can be written to the trace screen and log, using an overload of the trace method. There are also trace method overloads that let you specify at what level the associated message appears. For example, if you want to specify an excruciating level of detail for debugging, you could specify that such messages only appeared at DirXML-DriverTraceLevel values of 4 or higher. See the Javadocs and Trace Interface in XML Interfaces for C++ for detailed descriptions of the trace overloads.
//output a message to the trace facility
tracer.trace("init");
//output a document to the trace facility
tracer.trace(initDocument);
//output a message to the trace facility
tracer->trace("init");
//output a document to the trace facility
tracer->trace(initDocument);