trace()
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 Express configuration
file, InterchangeSystem.cfg. The parameter value can be a file name or STDOUT, which writes the log to InterChange Server Express'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");
