Message file

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
Important:
Do not add your messages to the InterChange Server message file, InterchangeSystem.txt. Access only existing messages from this system message file.

This section provides the following information about a message file:

Message format

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

Note:
For additional examples of messages, see the InterChange Server message file InterchangeSystem.txt.

Name and location of a message file

A connector can obtain its messages from one of two message files:

All methods that generate messages (see Table 49) first search the connector message file for the specified message number.

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.

Note:
Connector standards suggest that trace messages are not included in a connector message file because end users do not normally view them.

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

Generating a message string

The methods in Table 49 retrieve a predefined message from a message file, format the text, and return a generated message string.

Table 49. Methods that generate a message string

Message method Description
generateMsg()
Generates a message of the specified severity from a message file. You can use the message as input to the logMsg() or traceWrite() method.
generateAndLogMsg()
Generates a message of the specified severity from a message file and sends it to the log destination
generateAndTraceMsg()
Generates a trace message from a message file and sends it to the log destination
Tip:
Before using generateMsg() for tracing, check that tracing is enabled with the isTraceEnabled() method. If tracing is not enabled, you need not generate the trace message.

In the C++ connector library, the generateMsg(), generateAndLogMsg(), and generateAndTraceMsg() methods are defined in two classes:

The message-generation methods in Table 49 require the following information:

Specifying a message number

The methods in Table 49 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 49 search the message file for the specified message number and extract the associated message text.

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
 
Note:
If the connector logs to its local log file, the connector infrastructure adds the timestamp.
WebSphere InterChange Server

If the connector logs to InterChange Server, InterChange Server adds the timestamp.

Specifying a message type

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

Table 50. Message types

Message type Severity level Description
XRD_FATAL
Fatal Error
Indicates an error that stops program execution.
XRD_ERROR
Error
Indicates a error that should be investigated.
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 50 as an argument to the message-generation method, as follows:

Message-type constants are defined in the CxMsgFormat class.

The following C++ code fragment logs an error message when it cannot connect to an application. The error message is defined in a connector message file as message 1100, Error: Failed to connect to application. The code example includes a comment explaining the message number; this makes code more readable. The example also calls freeMemory() to release memory allocated by generateMsg().

char * msg;
 ret_code = connect_to_app(userName, password);
 // Message 1100 - Failed to connect to application
 if (ret_code == -1) {
       msg = generateMsg(1100, CxMsgFormat::XRD_ERROR, NULL, 0, NULL);
       logMsg(msg);
       JToCPPVeneer::getTheHandlerStuff()->freeMemory(msg);
       return BON_FAIL; 
 }
 
Note:
For a C++ connector, after generating a message with generateMsg() and logging the message, call void freeMemory(char * mem) to release memory allocated by generateMsg().

Using parameter values

With the message-generation methods in Table 49, 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:

char val[512];
 getConfigProp("ConnectorName", val, 512);
 // Message 2887 - Initializing connector
 generateAndLogMsg(2887, CxMsgFormat::XRD_INFO, 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.

Suppose you have the following trace message in your connector message file that contains one parameter:

3033
 Opened main form for {1} object.
 

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 form as a character string. In the code fragment below, generateAndTraceMsg() is called to format a message that contains one parameter and send this trace message to the log:

char * formName[512];
 if(getFormName(theObj,formName)==0)
                return BON_FAIL;
 if(tracePtr->getTraceLevel()>= Tracing::LEVEL3) {
               // Message 3033 - Opened main form for object
              generateAndTraceMsg(3033,CxMsgFormat::XRD_TRACE,
                     Tracing::LEVEL3, 1, formName);
 }
 

This code fragment retrieves the application form name and calls Tracing::getTraceLevel() to retrieve the current tracing level as set in the repository. If the trace level is at least 3, the routine uses generateAndTraceMsg() to generate a message string and write the trace message to the log destination. The call to generateMsg() specifies that the value of argCount is 1 and val contains a character string for the form name.

For the Item object, the trace message displayed is:

[1999/05/28 12:00:00.000] [ConnectorAgent MyConnector] 
                  Trace 3033: Opened main form for Item object
 

Copyright IBM Corp. 1997, 2004