Using a DEBUG Version of MAPI

By default, the RETAIL version of MAPI is installed on your development computer. You can replace the standard DLLs with the DEBUG version of the MAPI DLLs, which are located on the distribution medium. Installing the DEBUG MAPI DLLs changes the behavior of your MAPI-compliant application so that it displays asserts for many different conditions, and provides other valuable testing information.

The volume of output produced by the DEBUG version of MAPI can be alarming, especially if you apply it to a function that already runs smoothly. The MAPI DEBUG version will point out obscure problems that may not have previously appeared, such as memory leaks. It points out MAPI objects that have not been freed, and memory that was allocated but not released. This internal method is more specific than most outside memory checkers.

Please note that the steps for installing DEBUG MAPI DLLs on Windows NT Server differ from those used for Windows 95.

    To install debug MAPI DLLs for Windows NT Server
  1. Change to the debug MAPI DLL directory on the distribution medium drive:

    CD MSTOOLS\MAPI\WINNTRT\CHECKED

  2. Copy the files into the SYSTEM32 directory:

    COPY *.* C:\WINNT\SYSTEM32

    To install debug MAPI DLLs for Windows 95
  1. Change to the following directory on the development computer:

    CD C:\MSTOOLS\BIN

  2. Run the N2D (normal-to-debug) batch file with no switches set:

    Type N2D

When you no longer need to test your application by running it with MAPI debug DLLs, you can reinstall the nondebug version.

You can reinstall standard MAPI DLLs from the \\MSTOOLS\MAPI\WINNTRT directory. These files have the same names as their debug counterparts in the MSTOOLS\MAPI\WINNTRT\CHECKED directory.

To simplify this task, you can write a batch file to copy the files.

    To reinstall nondebug MAPI DLLs for Windows NT Server
  1. To use a batch file, enter the following lines into a text file, designating the distribution medium in the first line:

    CD MSTOOLS\MAPI\WINNTRT\CHECKED

    FOR %%F IN (*.*) DO:

    COPY ..\%%F C:\WINNT\SYSTEM32

  2. Run this file by typing its name at the command line.
  3. Save this file and use it if you need to reinstall the nondebug MAPI DLLs.

It is not necessary to use a batch file. You can enter these commands at a command prompt instead. Type the following :

FOR %F IN (*.*) DO COPY ..\%F C:\WINNT\SYSTEM32

Reinstalling MAPI DLLs for Windows 95 can also be done from a batch file or from the command line.

    To reinstall nondebug MAPI DLLs for Windows 95
  1. Change to the following directory on the development computer:

    CD C:\MSTOOLS\BIN

    This assumes that the MSTOOLS directory has been installed on the C drive.

  2. Run the D2N (debug-to-normal) batch file with no switches set:

    Type D2N

Setting Values in MAPIDBG.INI

The MAPI DEBUG DLLs and their behavior are controlled by the MAPIDBG.INI file. For Windows NT Server, this file is located in the %SYSTEMROOT% directory. For Windows 95, it is located in the %WINDR% directory.

Changing DEBUG MAPI DLL Behavior

You can change the behavior of the DEBUG DLLs. For example, you can modify the VirtualMemory DLL tag, the AssertLeaks or DumpLeaks DLL settings, and the FillMemory and FillByte DLL settings.

If set to 1, the VirtualMemory tag allocates memory and alerts you to memory overruns. If you do overrun memory, it will usually cause a general protection fault rather than allow random overrunning. The VirtualMemory tag clearly shows overrunning because memory is allocated in distinct blocks away from other allocations, and adjoining pages will also be protected. Do not use this setting in a nondebug environment. It is useful only for testing and debugging.

The AssertLeaks or DumpLeaks settings display message boxes that describe memory leaks, as well as MAPI objects that have not been freed. They also describe MAPI memory that is allocated but not freed when your application closes.

When you allocate or free memory, you can turn on memory fills using the FillMemory and FillByte settings. This allows you to clearly see what memory is freed or initialized.

You can set the following values in the MAPIDBG.INI file:

[General]
DebugTrace=<0/1>
AssertLeaks=<0/1>
AssertBadBlocks=<0/1>           ;Default is on.
VirtualMemory=<0/1/4>
MemoryFillRandom=<0/1>
CheckHeapOften=<0/1>
EventLog=<0/1>
VerboseSpooling=<0/1>
LowPrioritySpooling=<0/1>       ;Default is on.
[Memory Management]
VirtualMemory=<0/1/4>
AssertLeaks=<0/1>
DumpLeaks=<0/1>
FillMemory=<0/1>
FillByte=<0xNN>                 ;Where NN is some hex number.
SharedMemMaxSize=<# of bytes>   ;0 is default. Grow as big as necessary.
[MAPIX]
FlushRegistry=<0/1>             ;0 is default 
[Remoting]
TraceCalls=<0/1>