Configuration

In order to enable console tracing, the value EnableConsoleTracing must exist under the the registry key

    HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING

and be nonzero. If this value does not exist, or is zero, console tracing is disabled. This value is read when Rtutils.dll is loaded; changes to this value after Rtutils.dll is already loaded will have no effect until the DLL is unloaded and loaded again.

In addition to the preceding "global" value, the registry may also contain values for individual clients. When a client "xyz" calls TraceRegister, tracing searches under the registry key

    HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING\XYZ

for the following values:

• EnableConsoleTracing: this is a REG_DWORD that defaults to zero; tracing to the console is enabled if this value is nonzero.
• EnableFileTracing: this is a REG_DWORD that defaults to zero; tracing to a file named XYZ.LOG is enabled if this value is nonzero.
• ConsoleTracingMask: this is a REG_DWORD that defaults to 0xFFFF0000; the bits in the high-order word correspond to components in the client. If a call to one of the extended output functions has the flag TRACE_USE_MASK set, this registry value is compared against the high-order word of the flag passed to the output function, to decide whether or not to send the output to the console.
• FileTracingMask: this is a REG_DWORD that defaults to 0xFFFF0000; it operates similarly to ConsoleTracingMask.
• MaxFileSize: this is a REG_DWORD that defaults to 0x10000; this is the maximum size a tracing file can grow to before it is renamed.
• FileDirectory: this is a REG_EXPAND_SZ that defaults to %WINDIR%\TRACING; this is the directory in which the tracing file is created.

The defaults are used only if the key is found (or can be created) but some values are absent from the key. If the registry key is not found and cannot be created, the call to TraceRegister fails.

Alternatively, a client "xyz" could call TraceRegisterEx, which takes a flag allowing the caller to specify the settings to use. Thus, a client could use tracing without creating any key in the registry. For instance,

    TraceRegisterEx("xyz", TRACE_USE_CONSOLE);

would register the client "xyz" to use the console for tracing, and the tracing API would not attempt to read the registry key for the client. Similarly,

    TraceRegisterEx("abc", TRACE_USE_FILE);

would register the client "abc" to use a file for tracing, bypassing the registry key for the client. However, for console tracing, using TraceRegisterEx still requires that the global EnableConsoleTracing value exist under

    HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\TRACING

and be nonzero.