Operations that use message files

Message files hold text for messages used in several types of operations. Table 8 lists the types of operations that use message files and the methods of the BaseDLM class that perform those operations.

Table 113. Message-generating operations

Operation Function block Method
Raising exceptions General/APIs/Maps/Exception/
Raise Map Exception
raiseException()
Logging General/Logging and Tracing/Log
Information ID
General/Logging and Tracing/Log
error ID
General/Logging and Tracing/Log
warning ID
logInfo()

logError()

logWarning()

Tracing General/Logging and Tracing/Trace/Trace on Level trace()

This section describes message-generating operations that affect map execution.

Raising exceptions

The raiseException() method has several forms. One commonly used syntax is:

raiseException(String exceptionType, 
    int messageNum, String param[,...])
 

With this syntax, you can have from one to three param String parameters. Thus, there can be up to five comma-separated parameters in a call to raiseException().

This example raises a new exception, using message number 23, and passes in two parameters to the message, the customer ID value and a string:

raiseException(AttributeException, 23,
    fromCustomer.getString("CustomerID"), 
    "greater than maximum length");
 

Figure 119 shows the text for message 23 as it appears in the message file.

Logging messages

A map can log a message whenever something occurs that might be of interest to an administrator. To log a message, a map uses the logInfo(), logWarning(), and logError() methods of the BaseDLM class. Each method is associated with a different message severity level.

Severity levels

To log a message, you must call the method associated with the message's severity level. Table 114 lists the severity levels and their associated methods.

Table 114. Message levels

Severity level Method Description
Info logInfo()
Informational only. The user does not need to take action.
Warning logWarning()
Represents information about a problem. Do not use this level for problems that the user must resolve.
Error logError()
Indicates a serious problem that the user needs to investigate.

Using a message file

Every map has at least one message file associated with it. If a map does not use custom messages, its messages come from the system map message file, CWMapMessages.txt. If a map uses customized messages, it has a map-specific message file (which is generated from the messages entered in the Messages tab of Map Designer Express). For more information, see "Message location".

When a map logs an error, the text of the error message comes from the map's message file. The following example logs an error message whose text is contained in the map's message file. The text of error message 10 appears as follows in the message file:

10 
 Credit report error for {1}, {2}. 
 

The code to log the message looks like this:

logError(10, customer.get("LName"), customer.get("FName");
 

When the logError() method executes, the text for message 10 is written to the log file, with the customer's last name and first name substituted for parameters 1 and 2. For example, the logged message for a customer named John Davidson looks like this:

Credit report error for Davidson, John.
 

Principles of good message logging

When creating messages, be sensitive to the way that administrators use the logging feature.

Assigning severity levels

It is important to be precise when assigning error levels to messages. The IBM system e-mail notification feature sends a message to a designated person, usually the administrator, when it detects the generation of an error message or fatal error message. Administrators use this IBM system e-mail notification feature, and they additionally might link it to an e-mail pager to send a page when an error occurs. By being precise when assigning error levels to messages, you can reduce the number of critical messages.

Revising messages

You can revise the text of a message at any time, such as to clarify or expand the text. However, once you assign a message number to a certain type of error, it is important that you do not reassign the number. Many administrators depend on scripts to filter log messages, and these scripts rely on the message numbers. Thus, it is important that the numbers in the message file do not change meaning. If they do, users can lose messages or receive inadvertent messages.

When to use informational messages

You can use the logInfo() method to create temporary messages for your own debugging. However, be sure to remove these debugging method calls when you are finished with development.

Resist the temptation to use the logInfo() method to document the normal operation of the collaboration. Doing so fills the administrator's log files with messages that are not of interest. Instead, use the trace() method to give the administrator detailed information for debugging.

Adding trace messages

You can add trace messages to your map so that when a map instance runs, it generates a detailed description of its actions. Trace messages are useful for your own debugging and for on-site troubleshooting by administrators.

Trace messages differ from log messages in that trace messages are suppressed by default, whereas log messages cannot be suppressed. Trace messages are generally more detailed and are meant to be viewed only under certain circumstances, such as when someone intentionally configures the map's trace level to a number higher than zero. You can send trace messages and log messages to different files.

You can add trace messages to a map to report operations that are specific to that map. These are some types of information that the map can write to the trace file:

Assigning trace levels

Each trace message must be associated with a trace level between 1 and 5. The trace level usually correlates to a level of detail: messages at level 1 typically contain less detail than messages at level 2, which contain less detail than those at level 3, and so forth. Thus, if you turn on tracing at level 1, you see messages that contain less detail than the messages at level 5. However, you can assign levels in any way that is useful to you. Here are some suggestions:

When you turn on tracing at a particular level, the messages associated with the specified level and those associated with all lower levels appear. For example, tracing at level 2 displays messages associated with both level 2 and level 1.

Tip:
Make sure to note the tracing levels with your documentation, so users know what level to use when they need to trace.

Generating a trace message

The following is an example of a message and the method call that generates the message. The message appears in the message file as follows:

20
 Begin transformation on {1} attribute: value = {2}
 

The method call obtains the value of the attribute LName, then uses the value to replace the parameter in the message. The code appears in the map as follows, and the message appears when the user sets tracing to level 3:

trace(3, 20, "LName", customer.get("LName"));
 

Setting the trace level

Figure 120 shows the General tab of the Map Properties dialog in Map Designer Express. (For information on how to display the Map Properties dialog, see "Providing map property information".) Notice that you can set the trace level for trace messages in this dialog.

Figure 120. Trace level for a map

As the map developer, you create the levels for which map-generated tracing can be requested, as described in "Assigning trace levels".

Note:
If you change the trace level for an activated map, you must stop and restart the map before the new trace level takes effect. Use the Component menu of IBM WebSphere System Manager to stop and start a map.

By setting the trace level in the Map Properties dialog of Map Designer Express, you set it for all map instances based on this map definition. You can also set the trace level for all map instances from the Map Properties window of IBM WebSphere System Manager. For more information about the Map Properties window of System Manager, see the User Guide for WebSphere Business Integration Express and Express Plus for Item Synchronization.

Copyright IBM Corp. 2003