Write a
trace message to the log destination.
Syntax
void trace(String traceMsg)
void trace(int traceLevel, String traceMsg)
void trace(int traceLevel, int messageNum)
void trace(int traceLevel, int messageNum, String param [,...])
void trace(int traceLevel, int messageNum, Object[] paramArray)
Parameters
- traceLevel
- The tracing level that is used to determine which trace messages are
output. The method writes the trace message when the trace level for
the collaboration object is greater than or equal to this
traceLevel value. You should define the trace
levels for this collaboration and document them so that the administrator
knows which level to use for the collaboration object.
- traceMsg
- The trace-message text that is written to the trace file.
- messageNum
- The message number of a message in the collaboration's message file,
which is indexed by message number. For information on how to set up a
message text file, refer to Creating a message file.
- param
- A value for a single message parameter. There can be up to five
message parameters, separated by commas. Each is sequentially resolved
to a parameter in the message text.
- paramArray
- An array of message-parameter values. Each is sequentially resolved
to a parameter in the message text.
Notes
The trace() method sends a trace message to the
collaboration's
log destination. By default, the log destination is the file
InterchangeSystem.log. You can change the log destination
by entering a value for the
LOG_FILE parameter in the InterChange Server configuration file,
InterchangeSystem.cfg. The parameter value can be a
file name or STDOUT, which writes the log to InterChange
Server's command window.
You can also set three other system configuration parameters related to
trace logging. All parameters are located in the configuration file,
InterchangeSystem.cfg:
- Set the maximum size of the trace file with the
MAX_TRACE_FILE_SIZE parameter. Because the default file size is
unlimited, you should always set a maximum size.
- Set from one to five archive trace files with the
NUMBER_OF_ARCHIVE_TRACES parameter. The default is five if the
parameter is not set.
- Set the
MIRROR_TRACE_TO_STDOUT parameter if you want the error messages to
display to STDOUT at the same time that they are written to the trace
file. The default value is false; messages are not simultaneously
written to STDOUT.
The trace() method has several forms:
- The first form of the method takes just a string message that appears when
tracing is set to level 1 or above.
- The second form takes a trace level and a string message that appears when
tracing is set to the specified level or a higher level.
- The third form takes a trace level and a number that represents a message
in the collaboration's message file. The entire message text
appears in the message file and is printed as it is, without parameters, when
tracing is set to the specified level or a higher level.
- The fourth form takes a trace level, a number that represents a message in
the collaboration's message file, and one or more parameters to be used in
the message. You can send up to five parameter values to be used with
the message by separating the values with commas.
- The fifth form takes a trace level, a number that represents a message in
the collaboration's message file, and an array of parameter values.
A collaboration object can be configured to generate a system-generated
trace or a collaboration-generated trace. The trace() method generates
a message that the collaboration object prints if configured to print a
collaboration-generated trace. For help in deciding when to use
tracing, refer to "Adding trace messages".
Examples
The following example uses the second form of the method to generate a
Level 2 trace message with the supplied text of the message:
trace (2, "Starting to trace at Level 2");
The following example uses the fourth form of the method to write message
201 in the collaboration's message file, if the collaboration object trace
level is 2 or higher. The message has two parameters, a name and a
year, for which this method call passes values.
trace(2, 201, "DAVID", "1961");
