CapStats Usage


What Is Capstats?

  Capstats is a utility for parsing and summarizing data in .cap files
  generated by running profile code.  For more information on profiling,
  see the cap.txt file or read the CAP profiling section in "Optimizing
  Windows NT".


What is this Document For?

  You can get command-line help for using capstats by typing 'capstats'
  at a command prompt.  If there are options you don't understand, they
  should be described in detail here.


What Can I Do with Capstats?

  * Parse out .cap data for one or more individual threads from a .cap
  file; e.g. pipe threads 1 and 37 from a list of 50 into a separate file,
  or all threads except thread 2, etc.

  * Ouput summary info in .csv (comma-separated-value) format, which can be
  read directly into a data processing application like Microsoft Excel.
  
  * List callers and callees of any function that appears in the profile
  data.

  * Convert .cap files to .cab (cap binary) format, which contains (nearly)
  all the data in the .cap file and can be parsed 10-100 times more quickly
  by capstats.  See below for details.


What's This .cab (cap binary) Format Business?

    CAP dumps profile information to a text file that is typically 5-20Mb.
  This is very inefficient to parse(!); using capstats with the original
  .cap data is not an interactive experience. This is especially annoying
  when you're looking at parent-child function relationships, which
  requires many runs of capstats on the same data.

    SOOoooo... You can use capstats to do a ONE-TIME conversion of your
  .cap data to ".cab" format.  For example, if you have profile data in
  myexe.cap, to convert to .cab format, just do 'capstats /B:myexe.cab
  myexe.cap' (see command flags below).  In all subsequent capstats
  operations, use myexe.cab as input to capstats, which will detect the
  file type and determine whether it knows how to handle your set of
  options.


How Do I Do Everything?

  Here is a descriptive list of command line flags (these are briefly
  described by capstats if you type 'capstats').  The other command line
  arguments are the input file and an optional list of thread ids.  You
  must specify at least one MODE and zero or more FLAGs.

Switch              Type    Argument    .cap    .cab (input format accepted)
/E or /exclusive    FLAG    <none>      Yes     Yes
/M or /match        FLAG    <none>      Yes     Ignored (default)
/N or /profile      FLAG    <none>      Yes     No
/D or /delimit      FLAG    <none>      Yes     Yes
/L                  FLAG    <none>      Yes     N/A
<none> (summary)    MODE    <none>      Yes     Yes
/R or /raw          MODE    <none>      Yes     Yes
/Q or /quick        MODE    <none>      Yes     No
/P or /parent       MODE    Fxn Name    Yes     Yes
/C or /child        MODE    Fxn Name    No      Yes
/T or /truncate     MODE    Fxn Name    No      Yes
/A or /above        MODE    Fxn Name    No      Yes
/B or /bindump      both    Output File Yes     Yes

Mode/Flag Descriptions:

  (/E)xclusive: Dump all threads EXCEPT those specified.  If no threads are
  specified, this flag is ignored.

  (/M)atch: Match functions by parsed function and module names instead of
  the full "decorated" names.  Not necessary if using .cab input.

  (/N)Profile: If you have data from more than one test run in the same
  .cap file, specify this option to use only the first batch of data.  If
  you run your scenario the right way, you shouldn't ever encounter this
  situation, and won't need this flag.

  (/D)elimit: Output comma separated data (.csv).

  (/L)eave: Leave function names unmangled.  Required if profilee uses
  overloaded C++ functions.

  ()Summary: Summary mode; this is the default if you don't specify one of
  [/Q /P /C /B].  Works with [/E /M /N /D] (all flags).

  (/R)aw: Dump (to stdout) the specified threads (see command line help)
  exactly as they appear in the original .cap file, or in .csv format (/D).
  Works with all flags.

  (/Q)uick: Dump the first few calls from each specified thread.  Works
  with [/N /E].

  (/P)arent: Dump a list of all the callers (parent functions) of the given
  function.  The data for each caller is the number of times / amounts of
  time that caller spent calling the given function.  All flags ok.

  (/C)hild: Dump a list of all the callees (child functions) of the given
  function.  The data for each callee is the number of times / amounts of
  time the given function spent calling that callee.  All flags ok.

  (/T)runcate: Dump (raw, to stdout or .cab file) only functions appearing
  under this function in the call trees.  Works with all flags and /B;
  implicit /R.

  (/A)bove: Dump (raw, to stdout or .cab file) only functions appearing
  above this function in the call trees.

  (/B)inDump: For selected tasks, Convert the given .cap file (see command
  line help) to .cab format; output to the given output file.  FLAG if used
  with /T (see above).


How Should I Use It?

  * Run your CAP scenario and generate a .cap file:
  e.g. "foo.cap".
	
  * Use capstats with the /B option to convert the .cap file to a .cab file:
  e.g. "capstats /B:foo.cab foo.cap".
	
  * Make a summary of all the functions in your file and import it into a
  data processing application like Microsoft Excel:
  e.g. "capstats /D foo.cab > foo.csv";
       "excel foo.csv".
	
  * When you find a function in the summary you want more detail on, use
  capstats with the /P, /C or /T option and your .cab file to investigate:
  e.g. "capstats /C:FFoo foo.cab" or
       "capstats /T:FFoo /B:ffoo.cab foo.cab";
       "capstats /R /D ffoo.cab > ffoo.csv";
       "excel ffoo.csv".

