Handling trace and error messages

A message is a string of information that the ODA can send to an external ODA log, where it can be reviewed by the system administrator or the developer to provide information about the runtime state of the ODA. There are two different categories of messages that an ODA can send to the ODA log:

Messages can be generated within the ODA code or obtained from a message file. The ODK API provides the trace() method, defined in the ODKUtility class, to log trace and error messages. This section provides the following information:

Indicating a log destination

An ODA sends its messages into its log destination. The log is an external destination that is available for viewing by those needing to review the execution state of the ODA. The log destination is defined at ODA configuration time by the configuration property TraceFileName as the absolute pathname of an external file, which must reside on the same machine as the ODA's process.

Note:
Because the ODK API provides a single method to log both trace and error messages, an ODA has only a single file to hold both these kinds of messages. Therefore, although this file is called a trace file, it also contains any error messages that the ODA generates.

For information on the format of the trace-file name, see Specifying a trace file.

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 of Business Object Wizard. For more information, see "Beginning execution of 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:

Message files

In both an error or trace, message, you can provide the message content as a hardcoded string or as a string retrieved from a message file. A message file is a text file that contains message numbers and associated message text. The message text can contain positional parameters for passing runtime data out of your ODA. You can provide a message file by creating a file and defining the messages you need.

This section provides the following information about message files:

Message format

Within a message file, messages have the following format:

MessageNum
Message
[EXPL]
Explanation

The MessageNum is an integer that uniquely identifies the message. This message number must appear on one line. The Message text can span multiple lines, which a carriage return terminating each line. The Explanation text is a more detailed explanation of the condition that causes the message to occur. Do not insert a blank line after the last line of the explanation text. The number of the next message should appear on the line immediately after the explanation. Edit the message file with any text editor, such as Notepad.

For example, message number 1005 might look like the following:

1005
ODA content generation is complete.
[EXPL]
This is a log message that indicates successful completion of the ODA.

Messages can contain parameters whose values are replaced at runtime by values from the program. These parameters are positional and are indicated in the message by a number in braces. For example the following message has three parameters to specify agent-property names:

1003
The agent configuration properties are {1}, {2}, {3}.
[EXPL]
This is a trace message that provides startup properties.

For more information on how to provide message parameters, see Using parameter values.

Name and location of a message file

An ODA can obtain its messages from one of two message files:

Both these message files must be located in the following subdirectory of the product directory:

ProductDir\ODA\messages

Generating a message string

The methods in retrieve a predefined message from a message file.

Table 60. Methods that generate a message string

Message method Description
getMsg()
Generates a message of the specified severity from a message file.
trace()
Generates a message of the specified severity from a message file and sends it to the trace file.

The message-generation methods in Table 60 are defined in the ODKUtility class. These methods require the following information:

Specifying a message number

The message-generation methods in Table 60 require a message number as an argument. This argument specifies the number of the message to obtain from the message file. As described in Message format, each message in a message file must have a unique integer message number associated with it. These message-generation methods search the message file for the specified message number and extract the associated message text.

These methods search the ODA message files for the message number in the following order:

  1. The ODA-specific message file, whose default name is ODAnameAgent.txt
  2. The global ODK message file, useragentmessages.txt

Specifying a message type

The message-generation methods in Table 60 also require a message type as an argument. This argument indicates the severity of a message. Table 61 lists the valid message types and their associated message-type constants.

Table 61. Message types

Message-type constant Severity level Description
XRD_FATAL Fatal error Indicates an error that stops program execution
XRD_ERROR Error Indicates an error that should be investigated
XRD_URGENTWARNING Urgent warning Indicates a condition that probably represents a problem and should probably not be ignored
XRD_WARNING Warning Indicates a condition that might represent a problem but that can be ignored
XRD_INFO Informational Information message only; no action required
XRD_TRACE ---- Use for trace messages

To specify a message type to associate with a message, use one of the message-type constants in Table 61, as follows:

Message-type constants are defined in the ODKConstant class.

Using parameter values

It is not necessary to write separate messages for each possible situation. Instead, use parameters to represent values that change at runtime. The use of parameters allows each message to serve multiple situations and helps to keep the message file small.

A parameter always appears as a number surrounded by curly braces: {number}. For each parameter you want to add to the message, insert the number within curly braces into the text of the message, as follows:

message text {number} more message text.

With the message-generation methods in Table 60, you can specify an optional number of values for message parameters. The number of parameter values in the method call must match the number of parameters defined in the message text. The message-generation method must supply a value for each parameter. For example, consider message 1003 again:

1003
The agent configuration properties are {1}, {2}, {3}.
[EXPL]
This is a trace message that provides startup properties.

In the code that sends this message, the following lines might appear:

Vector params = new Vector(3);
for(int i=0; i<3; i++)
   params.add(agtProperties[i].propName);
Util.trace(ODKConstant.TRACELEVEL2, 1003, ODKConstant.XRD_TRACE,
   params);

The trace() method combines these parameter values with the message text in the message file and forms the message. Before writing the message to the trace file, trace() replaces the message parameters with the values of the params variable.

Message 1003 might appear in the trace file as follows:

The agent configuration properties are Username, Password, Url.

Because the message text uses parameters to specify the specific property types, rather than including them as hard-coded strings, you can use the same message for any set of missing properties.

Maintaining the message file

At a user site, an administrator might set up a procedure for filtering ODA messages and using e-mail or e-mail pager to notify someone who can resolve problems. Because of this, it is important that the error numbers and the meanings associated with the numbers remain the same after the first release of an Object Discovery Agent. You can change the text associated with an error number, but you should not change the meaning of the text or reassign error numbers.

However, if you must change the meanings associated with error numbers, make sure you document the change and notify users of the Object Discovery Agent.

You can change an Object Discovery Agent's message file while the Object Discovery Agent is running. However, the changes do not take effect until the next time the Object Discovery Agent's is started and the message file is read into memory. If InterChange Server fails while an Object Discovery Agent is running, the server automatically reads into memory the message files for all Object Discovery Agents that were previously running.

Copyright IBM Corp. 1997, 2003