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 60. Methods that generate a message string
The message-generation methods in Table 60 are defined in the ODKUtility class. These methods require the following information:
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:
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.
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.
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 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.
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.