You can provide message input to the connector error logging or tracing method be as text strings or as references to a message file. A message file is a text file containing message numbers and message text. The message text can contain positional parameters for passing runtime data out of your connector. You can provide a message file by creating a file and defining the messages that you need.
WebSphere InterChange Server |
---|
This section provides the following information about a message file:
Within a message file, messages have the following format:
message number message text[EXPL]explanation text
The message number is an integer that uniquely identifies the message. This message number must appear on one line. The message text can span multiple lines, with a carriage return terminating each line. The explanation text is a more detailed explanation of the condition that causes the message to occur.
As an example of message text, a connector can call the following message when it determines that its version differs from the version of the connector infrastructure.
20017 Connector Infrastructure version does not match.
Messages can contain parameters whose values are replaced at runtime by values from the program. The parameters are positional and are indicated in the message file by a number in braces. For example, the following message has two parameters to record an unsubscribed event.
20026 Warning: Unsubscribed event: Object Name:{1}, Verb: {2}.
For information on how to provide values to message parameters, see "Using parameter values".
A connector can obtain its messages from one of two message files:
connectors\messages
For example, the connector message file for the IBM WebSphere Business Integration Adapter for Clarify is named ClarifyConnector.txt.
When you generate a message, you can specify which of these two message files to extract a message from with a message-file constant. All methods that generate messages (see Table 56) provide a parameter to specify which message file to use. For more information, see "Specifying a message number"."Specifying a message number" on page 142
WebSphere InterChange Server |
---|
If a connector message file does not exist, the InterChange Server message file InterchangeSystem.txt (located in the product directory) is used as the message file. |
The connector message file should contain all text strings that the application-specific component uses. These strings include those for logging as well as hardcoded strings.
For an internationalized connector, it is important that text strings are isolated into the connector message file. This message file can be translated and the messages can then be easily available in different languages. The name of the translated connector message file should include the name of the associated locale, as follows:
AppnameConnector_ll_TT.txt
In the preceding line, ll is the two-letter abbreviation for the locale (by convention in lowercase letters) and TT is the two-letter abbreviation for the territory (by convention in uppercase letters). For example, the version of the connector message file for the WBI Adapter for Clarify that contains U.S. English messages would have the following name:
ClarifyConnector_en_US.txt
At runtime, the connector framework locates the appropriate message file for the connector framework locale from the connectors\messages subdirectory. For example, if the connector framework's locale is U.S. English (en_US), the connector framework retrieves messages from the AppnameConnector_en_US.txt file.
For more information on how to internationalize the text strings of a connector, see An internationalized connector.
The methods in Table 56 retrieve a predefined message from a message file, format
the text, and return a generated message string.
Table 56. Methods that generate a message string
In the Java connector library, the generateMsg(), generateAndLogMsg(), and generateAndTraceMsg() methods are defined in the CWConnectorUtil class
The message-generation methods in Table 56 require the following information:
The methods in Table 56 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 (identifier) associated with it. The methods in Table 56 search the message file for the specified message number and extract the associated message text.
To indicate which message file these methods search in, you specify an
integer
message-file constant as an argument, as Table 57 shows.
Table 57. Message-file constants
In the Java connector library, the message-file constants are defined in the CWConnectorLogAndTrace class.
The IBM WebSphere business integration system generates the date and time and displays the following message:
[1999/05/28 11:54:15.990] [ConnectorAgent ConnectorName] Error 1100: Failed to connect to application
WebSphere InterChange Server |
---|
If the connector logs to InterChange Server, InterChange Server adds the timestamp. |
The methods in Table 56 also require a message type as an argument. This
argument indicates the severity of the message. Table 58 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 58 as an argument to the message-generation method, as follows:
In the Java connector library, the generateAndTraceMsg() method does not require a message type for trace messages. Although the Java connector library supports a deprecated version of generateAndTraceMsg() that requires the message type, the nondeprecated version of this method automatically specifies the XRD_TRACE message type; therefore, you do not need to provide it as an argument.
Message-type constants are defined in the CWConnectorLogAndTrace class.
With the message-generation methods in Table 56, you can specify an optional number of values for message-text parameters. The number of parameter values must match the number of parameters defined in the message text. For information on how to define parameters in a message, see "Message format".
To specify parameter values, you must include the following arguments:
Suppose you have the following informational message in your connector message file that contains one parameter:
2887 Initializing connector {1}
Because this message contains a single parameter, a call to one of the message-generation methods must specify an argument count of 1 and then provide the name of the connector as a character string. In the code fragment below, generateAndLogMsg() is called to format a message that contains one parameter and send this message to the log:
String val = CWConnectorUtil.getConfigProp("ConnectorName"); CWConnectorUtil.generateAndLogMsg(2887, CWConnectorLogAndTrace.XRD_INFO, CWConnectorUtil.CONNECTOR_MESSAGE_FILE, 1, val);
The parameter value of val is combined with the message in the message file. If val is set to MyConnector, the resulting message is:
[1999/05/28 11:54:15.990] [ConnectorAgent MyConnector] Info 2887: Initializing connector MyConnector
You can also locate trace messages in the connector message file.