TN007: Debugging Trace Options

To help debug windows programs, MFC provides a TRACE output mechanism. This will display, to a debugging output window or console, messages about the internal operation of the MFC library as well as warnings and errors if something goes wrong in your application.

Turning on TRACE output is strongly recommended, since it will sometimes give you advanced warning of problems that are about to occur or give more verbose reasons why problems do occur.

How to Turn on TRACE Output

By default TRACE message output is disabled. In order for trace output to be seen, you must perform the following steps:

  1. Compile your program with the _DEBUG symbol defined and link with a debug version of the MFC library. Debugging and trace options are only available in the _DEBUG version of the library.

  2. Enable the afxTraceEnabled flag. There are several ways to do this, but using the TRACER.EXE utility is highly recommended.

  3. Customize the afxTraceFlags to the level of detail you would like to see in trace messages. Use of the TRACER.EXE utility is highly recommended.

Where the Output Goes

When afxTraceEnabled is TRUE, then TRACE output (and default afxDump output) will go to the output window if present. When afxTraceEnable is FALSE, TRACE output and afxDump output will not be displayed.

If a debugger is present, then TRACE output will go to the debugger's output window. If no debugger is present, then TRACE output will not be seen.

Using TRACER.EXE

TRACER.EXE is a small MFC Programming Utilities sample program that allows you to set the options in AFX.INI. TRACER is installed in your BIN directory by the Visual C++ setup. The source code for TRACER is provided as well, so you can rebuild it and customize it as you wish.

A sample AFX.INI file is provided in the MFC\SRC subdirectory. This .INI file turns on diagnostic messages and uses the standard options. You should place this AFX.INI file in your Windows directory or run the TRACER.EXE program to create a new AFX.INI file and set options in it using a dialog box.

Any changes to AFX.INI will take effect in any debug MFC application launched after the changes are saved.

The global integer afxTraceFlags is used to turn on the built-in reporting features of the MFC and to store all flags. It can be set under program control or with the debugger. The global integer afxTraceFlags uses each bit to select a trace reporting option.

You can turn any bit on or off as desired. Try playing with them to get a flavor of the report information they generate. See the AFXWIN.H header for the numeric values of the different options.

// example under program control
afxTraceFlags = 4 + 8;        // windows message dumping

Ease of Reading

For ease of reading, certain frequent messages are not reported. These include:

Mouse move messages (non-client and client):

These messages are sent every time the mouse moves or during idle processing or other common dialog processing.

Technical Notes by Number |  Technical Notes by Category