Using CAP

CAP consists of the following files:

File	Description
CAP.INI	Call Attributed Profiler initialization file.
CAP.DLL	Call Attributed Profiler DLL.
CAP.LIB	Call Attributed Profiler import library.
CAPDUMP.EXE	Allows collecting or clearing of profiling data and stopping profiling at any time.
CAPSETUP.EXE	Allows attaching CAP.DLL to Win32-based applications and detaching CAP.DLL from Win32-based applications.
CAPSTATS.EXE	Allows parsing and summarizing of data in .CAP files.

Windows NT does not ship with debugging symbols in its modules because it takes many megabytes of disk space to provide them. So, you should first run the APF32CVT utility on your application, with no action specified. This will give you a list of the system DLLs that need symbols. You can get the versions of the system with symbols (.DBG files) from your Windows NT CD, under SUPPORT\DEBUG. Then you rename the current system DLL; for example, type

ren gdi32.dll gdi32.nsm

Then copy the debug DLL from the CD to GDI32.DLL. Once you have done this for all the DLLs you want to measure, you must shut down and restart Windows NT so that the DLLs with symbols are loaded.

Next, set up an initialization file called CAP.INI in one of the following locations:

The current directory
The Windows directory
The root directory of the current drive
The root directory of drive C

The CAP.INI file has sections that control the set of .EXEs and DLLs profiled. Each .EXE or .DLL listed must be placed on a separate line. The format of this file must be correct; otherwise, Windows NT might not start. The sections of CAP.INI are as follows:

Section	Description
[EXES]	A list of applications to be profiled. Each name must be on a new line. When CAP.DLL initializes, it checks the current executable name against this list and will start profiling if the name is on the list. If the name is not on the list, CAP doesn't profile that process.
[PATCH IMPORTS]	A list of .DLLs and .EXEs to be profiled for imported entries. Each name must be on a new line. Listing a .DLL or .EXE here causes the profiling of all functions called by the listed .DLLs and .EXEs.
[PATCH CALLERS]	A list of .DLLs to be profiled for exported entries. Each name must be on a new line. DLLs listed here are profiled when called by the applications listed in the [EXE] section, or by any of their DLLs.
[NAME LENGTH]	The maximum length of a symbol to be printed in the output files. This number must be in the range from 20 to 2048. For C++ programs, this value should be set to at least 128 due to the name elaboration that is performed by the linker. If a symbol is longer than this value, it is truncated. If the field is not specified or is 0, the value defaults to 40. This section is optional.
[CHRONO FUNCS]	List of .DLLs, .EXEs, and corresponding functions that start the chronological listing. For example, "test=SomeFunc" indicates that all functions called from the "SomeFunc" function of the "test" module are listed, until the call depth is less than or equal to the depth of "SomeFunc".
[EXCLUDE FUNCS]	List of .DLLs, .EXEs, and corresponding functions that will be excluded from the profiling. However, if these functions call other functions that have not been excluded, they will be still included in the profiling.
[OUTPUT FILE]	Specifies a different drive and filename for the output file. For example, use filename=c:\results\solitaire\sol.cap.
[CAP FLAGS]	The following flags can be specified as "on" or "off": profile (profiling), dumpbinary (output in binary form), capthread (start 3 threads for CapDump), loadlibrary (init symbol table on LoadLibrary), setjump (intercept setjmp and longjmp), undecoratename (undecorated names), excelaware (delimiters for Excel import), regular dump (regular data), chronocollect (chronological listing collect), chronodump (chronological listing output), and slowsymbols (exhaustive symbol lookup)

Headers for the first three sections ([EXES], [PATCH IMPORTS], and [PATCH CALLERS]) are required in the CAP.INI file, but the contents of any section may be left blank.

Next, attach CAP.DLL to the application process. Use one of the following methods to do this:

Recompile using the -Gh and -Zd options. Then link with CAP.LIB and the -debugtype:coff and -debug:mapped,partial options. Run the application. If you are using WIN32.MAK, you can automatically specify these compiler and link options by using the following command line: nmake profile=1. For more information, see Building Applications Using WIN32.MAK.
- -or-
Place CAP.DLL in your system directory (for example, C:\WINNT\SYSTEM32). Run CapSetup -A to attach CAP.DLL to all Win32-based applications (it uses the AppInit_DLLs key in the registry). Administrator privilege is required. Reboot the system. Run your application. Only those applications listed in the [EXES] section of CAP.INI are profiled. You must explicitly list the modules whose functions you want profiled in the [PATCH IMPORTS] or [PATCH CALLERS] section of CAP.INI. Run CapSetup -D to detach CAP.DLL when you have finished profiling. Reboot the system.