Microsoft Foundation Classes                             Microsoft Corporation
Technical Notes             

#7 : Windows debugging trace options

To help debug windows programs, the TRACE() mechanism is used.
Textual debugging output will go to the debug console (debug terminal
or CVW window).  Debugging and trace options are enabled when
you compile your program with the _DEBUG symbol defined.

The options described in this note can be set using a debugger,
in the initialization code of your application, or by using the
AFX.INI file.  A sample AFX.INI file is provided in the \C700\MFC\SRC
subdirectory.  This .INI file turns on diagnostic messages and uses the
standard options.  The file must be placed in your Windows directory.


Global switch:
==============

By default TRACE output is ignored.  If you set the global integer
'afxTraceEnabled' to TRUE (1), then TRACE output (and default afxDump output)
is routed to the debugger.  

In CodeView, the following command can be used to set this value using the
Command Window:

    MEI _afxTraceEnabled 1

This is the "memory enter integer" command.  Note the use of the leading
underscore.  This is required when using the MEI command on externally
visible C symbols.  If you are using an MFC library variant with 
CodeView information (the CL /Zi option combined with the LINK /CODEVIEW
option), which is the default for the _DEBUG libary and program variants, 
then the following will also work:
    
    ? afxTraceEnabled = 1


The flags:
==========

The global integer 'afxTraceFlags' is used to turn on the built-in reporting
features of the MFC library.

The flags are all stored in the global integer 'afxTraceFlags'.  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.

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

This functionality only exists in the debugging version of the library.
Using the "memory enter integer" command of CodeView, you can set
the value of this global variable, for example:

    MEI _afxTraceFlags 0x004

Again, note the use of the leading underscore for the MEI command. Also,
when CodeView information is available the following command works:
    
    ? afxTraceFlags = 0x004

-----------------------------------------------------------------------------
The options:
------------

    0x01 : Multi-app debugging.
            This will prefix each 'TRACE' output with the name of the
            application.  This will affect not only the explicit
            TRACE output of your program, but also the additional
            report options described below:

    0x02  : Windows Message report - in message pump
            Report each message received in the main CWinApp message pump.
            List the window handle, the message name or number,
            and the 'wParam' and 'lParam'.
            The report is made after the GetMessage, but before any
            translate or dispatch.

            DDE messages will display additional data which is good for
            some debugging scenarios in OLE).

            This will display messages that are posted - not those that
            are sent.

    0x04  : Windows Message report - in WndProc
            Like option '2' but applies to messages dispatched in the
            CWnd::WindowProc (i.e. handles both posted and sent messages).
            that are about to be dispatched).
    
    0x08  : Command handling report
            A special case for WM_COMMAND/OnCommand handling.  Will
            report the progress of the command routing mechanism.
            Reports which class receives the command (i.e. there is
            a matching message map entry).  Also reports when classes
            don't receive a command (i.e. there is no matching message
            map entry).
            This is useful for MDI apps to see the flow of command
            messages (i.e. child gets first crack, then frame).

    0x10 : Verbose OLE reporting.
            This will report significant OLE notifications or requests.
            Turn this on for an OLE client or server to get an indication
            of the communication between the OLE DLLs and your OLE app.
    
-----------------------------------------------------------------------------
Ease of Reading:
----------------

For ease of reading, certain frequent messages are not reported.
These include:
        mouse move messages (non-client and client)
        WM_NCHITTEST
        WM_SETCURSOR
        WM_ENTERIDLE
        WM_CTLCOLOR

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

-----------------------------------------------------------------------------
