Trace record-enabling mechanism

Only trace records that are enabled are reported. Disabled traces are discarded (except for cases where the enabling mechanism is bypassed). You can configure the trace system to enable traces at the following two levels of scope:

Global
The global-level settings affect all components. These settings correspond to the "traceTypes" and "traceLevels" elements of the "traces" keyed collection as found in the dse.ini file.
Component
The component-level scope corresponds to the elements of the keyed collection with the "requestersComponents" ID, which itself is an element of the "traces" keyed collection. At the component level of scope, an element can exist for each toolkit component, and a default element can be included for use with those components not directly associated with any other element.

In order to be included as part of the Trace Facility report, a trace record must be enabled on at least one of these levels.

In total, there are six trace configuration values that are considered in determining if a trace record will be reported when a trace call is made. These values are shown in the following table:

Table 1. Trace record configuration
Trace-enabling specification Permissible values
Global-level traceType Any concatenated combination of 'P', 'I', 'W', 'E', 'S', and 'D', which have the following meanings:
  • P = Display
  • I = Information
  • W = Warning
  • E = Error
  • S = Severe error
  • D = Debug
Global-level traceLevel Any concatenated combination of 'H', 'M', and 'L', which have the following meanings:
  • H = High
  • M = Medium
  • L = Low
Component-level component identifier code A text string that is either an internal toolkit component identifier code or a user-assigned identifier code for a user component. (Codes beginning with '#' are reserved for internal component codes. The default component element must be given the "unAssigned" value as its ID code.)
Component-level trace (enable) setting The following are the possible values:
  • yes
  • no
Component-level traceType Any concatenated combination of 'P', 'I', 'W', 'E', 'S', and 'D', which have the following meanings:
  • P = Display
  • I = Information
  • W = Warning
  • E = Error
  • S = Severe error
  • D = Debug
Component-level traceLevel Any concatenated combination of 'H', 'M', and 'L', which have the following meanings:
  • H = High
  • M = Medium
  • L = Low

For more information on these settings and their permissible values, refer to Configuring the Trace Facility.

When a trace call is made from a component, the trace is associated with the calling component, and the trace call is assigned a trace type and a trace level. (You may specify the trace type and trace level using static variables that are defined in the Trace class for this purpose.) These three trace call characteristics are compared against the trace enablement values to determine if the trace call should result in a trace report. The following conditions must be met in order for a trace call to result in a trace report:

Note that at the component level, the default component values are used if the calling component's values are not directly specified. (That is, there is no element in the "requestersComponents" collection that has the calling component's identifier.) The default component (component id = "unAssigned") element must have been defined for this substitution to occur; otherwise, the component's "trace" value is effectively considered to be "no" and therefore the trace call will not result in a reported trace.

Note that the enabling mechanism described above can be bypassed at any time with the appropriate trace method; this will force the trace to be reported.

Related tasks
Configuring the Trace Facility