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
This section describes message-generating operations that affect map execution.
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.
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.
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.
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). 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.
When creating messages, be sensitive to the way that administrators use the logging feature.
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.
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.
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.
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:
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.
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"));
Figure 120 shows the General tab of the
Map Properties dialog in Map Designer. (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".
By setting the trace level in the Map Properties dialog of Map Designer, 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.