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 run-time 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:
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 start state of the ODA. The log destination is defined at ODA configuration time by the configuration property TraceFileName as the absolute path name of an external file, which must reside on the same machine as the ODA's process.
For information on the format of the trace-file name, see Specifying a 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 59. 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 60 summarizes the trace information for
trace() to send an error message.
Table 60. 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 60, 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 17 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 60 summarizes the trace information for to the
trace() to send a trace message.
Table 61. 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 61, 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:");
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 run-time 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:
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 run time 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.
An ODA can obtain its messages from one of two message files:
ODAnameAgent.txt
where ODAname is the name that uniquely identifies the ODA. For more information, see Naming the ODA. Put messages that are specific to your ODA in this message file. For example, if you create an ODA named LegacyApp, name its message file LegacyAppAgent.txt.
If you create messages that are global to all Object Discovery Agents, add those messages to the global message file.
Both these message files must be located in the following subdirectory of the product directory:
ProductDir\ODA\messages
The methods in retrieve a predefined message from a message file.
Table 62. Methods that generate a message string
The message-generation methods in Table 62 are defined in the ODKUtility class. These methods require the following information:
The message-generation methods in Table 62 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:
The message-generation methods in Table 62 also require a
message type as an argument. This argument indicates the
severity of a message. Table 63 lists the valid message types and their
associated message-type
constants.
To specify a message type to associate with a message, use one of the message-type constants in Table 63, as follows:
Message-type constants are defined in the ODKConstant class.
It is not necessary to write separate messages for each possible situation. Instead, use parameters to represent values that change at run time. 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 62, 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.
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 do 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.