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 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:

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 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.

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 running
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 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.

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 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.

Copyright IBM Corp. 1997, 2003