The preferred way of configuring trace for XMS .NET applications is with an application configuration file. The Trace section of this file includes parameters that define what is to be traced, the trace file location and maximum allowed size, the number of trace files used, and the trace file format.
To turn trace on using the application configuration file, you simply place the file in the same directory as the executable file for your application.
Trace can be enabled both by component and trace type. It is also possible to turn trace on for an entire trace group. You can turn trace on for components in a hierarchy either individually or collectively. The types of trace available include:
The following example shows the trace settings defined in the Trace section of an application configuration file:
<?xml version="1.0" encoding="UTF-8"?> <configuration> <configSections> <sectionGroup name="IBM.XMS"> <section name="Trace" type="System.Configuration.SingleTagSectionHandler" /> </sectionGroup> </configSections> <IBM.XMS> <Trace traceSpecification="*=all=enabled" traceFilePath="" traceFileSize="20000000" traceFileNumber="3" traceFormat="advanced" /> </IBM.XMS> </configuration>
Table 1 describes the parameter settings in more detail.
Parameter | Description |
---|---|
traceSpecification=<ComponentName>=<type>=<state> | <ComponentName> is the name of the class that you want to trace. You can use a * wildcard character in this name. For example, *=all=enabled specifies that you want to trace all classes, and IBM.XMS.impl.*=all=enabled specifies that you require API trace only. <type> can be any
of the following trace types:
<state> can be either enabled or disabled. You can string multiple trace elements together by using a ':' (colon) delimiter. |
traceFilePath="<filename>" | If you do not specify a traceFilePath, or if the
traceFilePath is present but contains an empty string, the trace file is placed
in the current directory. To store the trace file in a named directory, specify
the directory name in the traceFilePath, for example:
traceFilePath="c:\somepath" |
traceFileSize="<size>" | The maximum allowed size of the trace file. When a file reaches this size, it is archived and renamed. The default maximum is 20 KB, which is specified as traceFileSize="20000000". |
traceFileNumber="<number>" | The number of trace files that are to be retained. The default is 4 (one active file and three archive files). The minimum number allowed is 2. |
traceFormat="<format>" | The default trace format is basic. Trace files are produced in this format if you specify traceFormat="basic", or if you do not specify a traceFormat, or if the traceFormat is present but contains an empty string. If you require trace that is compatible with trace analyzer tools, you must specify traceFormat="advanced". |
The trace settings in the application configuration file are dynamic, and are reread every time the file is saved or replaced. If errors are found in the file after it has been edited, the trace file settings revert to their default values.