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. |
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.
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.
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:
Util.trace(ODKConstant.TRACELEVEL0, ODKConstant.XRD_ERROR, "Invalid property value");
You can also retrieve the message string from an exception with the getMsg() method of the ODKException class, as follows:
try
{ boDef.setAttributeList(Attributes); boDef.setVerbList(Verbs); defList[i] = boDef; }
catch(BusObjInvalidAttrException e)
{ Util.trace(ODKConstant.TRACELEVEL0, ODKConstant.XRD_ERROR, e.getMsg()); }
Util.trace(ODKConstant.TRACELEVEL0, ODKConstant.XRD_WARNING, 1009);
For more information on the use of message files, see Message files.
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:
Util.trace(ODKConstant.TRACELEVEL1, ODKConstant.XRD_TRACE, "Entering method getProperties");
Util.trace(ODKConstant.TRACELEVEL1, ODKConstant.XRD_TRACE, 1009);
For more information on the use of message files, see Message files.
In this case, trace() formats the contents of the specified business object definition.
BusObjDef boDef = new BusObjDef(); // code that populates business object definition ... // write out the business object definition ODKUtility.getODKUtility().trace(ODKConstant.TRACELEVEL5, ODKConstant.XRD_TRACE, boDef);
In this case, trace() formats the list of agent properties, preceding it with a string that you can specify.
AgentProperties[] propArray; // code that populates agent-property array ... // write out the agent-property array ODKUtility.getODKUtility().trace(ODKConstant.TRACELEVEL2, ODKConstant.XRD_TRACE, propArray, "List of configuration properties:");