Sending a message to the trace file

The ODK API provides the trace() method, defined in the ODKUtility class, to log trace and error messages. The type of message that the ODA tracing mechanism sends depends on the message's trace level, as follows:

Table 57. Trace level and message type

Message trace level Description

zero (0)

The ODA tracing mechanism allows you to log error messages to the trace file.

Any level between 1 and 5

The ODA tracing mechanism allows you to log trace messages to the trace file. Trace messages are for information such as status messages, property values, and business object names.

Note:
The ODA runtime handles the ODA tracing mechanism implicitly. This mechanism does not take effect until the trace file is set in the Configure Agent dialog box of Business Object Wizard. For more information, see "Starting the ODA".

In the call to trace(), you specify the trace level as an argument. The ODK API provides the trace-level constants for this purpose. For more information on how to generate a message, see Generating a message string. For information on setting the trace level, see "Specifying the trace file and trace level".

The ODA tracing mechanism generates files in the same format as those in the Connector Development Kit and InterChange Server.

Error and informational messages

When the trace level is zero (0), an ODA can send information about its state to a log destination. Creating a record of errors and status is often called logging. The following types of information are recommended for logging:

Although an ODA can send informational or error messages, this logging process is referred to as error logging.

Important:
It is recommended that for every exception, you both throw the exception so that it displays in Business Object Wizard, and write an error message that describes the exception to the trace file. By logging all exceptions to the trace file, you can still locate them should the ODA or Business Object Designer fail.

Error logging is turned on when the trace level is zero (0). By default, logging on an ODA is turned off because the default trace level is 5. You set the trace level with the TraceLevel ODA configuration property. You can set TraceLevel to a value of 0 to indicate that a message is an error message.

To send an error message to the log, use the trace() method. Table 58 summarizes the trace information for trace() to send an error message.

Table 58. Trace information for error messages

Trace information Description ODKConstant constant
Trace level 0 TRACELEVEL0
Message type Errors XRD_FATAL, XRD_ERROR

Warnings XRD_URGENTWARNING, XRD_WARNING

Informational XRD_INFO

In addition to the information in Table 58, the trace() method also requires the content of the error message. You can obtain the message content as message text in one of the following ways:

Trace messages

Tracing is an optional troubleshooting and debugging feature that can be turned on for ODAs. When tracing is turned on, system administrators can follow generation of content as the ODA performs its tasks. Tracing allows you and other users of your ODA code to monitor the behavior of the ODA. Tracing can also track when specific ODA methods are called.

Tracing is turned on when the trace level is between 1 and 5. By default, tracing on an ODA is turned on because the default trace level is 5. You set the trace level with the TraceLevel ODA configuration property. You can set TraceLevel to a value from 1 to 5 to obtain the appropriate level of detail. Level 5 tracing logs the trace messages of all lower trace levels. You are responsible for defining what kind of information your ODA returns at each trace level. Table 15 shows the recommended content for ODA trace messages. For more information, see Setting the trace level.

To send a trace message to the trace file, use the trace() method. Table 58 summarizes the trace information for to the trace() to send a trace message.

Table 59. Trace information for trace messages

Trace information Description ODKConstant constant
Trace level 1 TRACELEVEL1

2 TRACELEVEL2

3 TRACELEVEL3

4 TRACELEVEL4

5 TRACELEVEL5
Message type Trace XRD_TRACE

In addition to the information in Table 59, the trace() method also requires the content of the trace message. You can obtain the message content in one of the following ways:

Copyright IBM Corp. 1997, 2003