home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / sdk / bin / capstats.txt < prev    next >
Encoding:
Text File  |  1995-07-11  |  5.7 KB  |  143 lines
  1. CapStats Usage
  2.  
  3.  
  4. What Is Capstats?
  5.  
  6.   Capstats is a utility for parsing and summarizing data in .cap files
  7.   generated by running profile code.  For more information on profiling,
  8.   see the cap.txt file or read the CAP profiling section in "Optimizing
  9.   Windows NT".
  10.  
  11.  
  12. What is this Document For?
  13.  
  14.   You can get command-line help for using capstats by typing 'capstats'
  15.   at a command prompt.  If there are options you don't understand, they
  16.   should be described in detail here.
  17.  
  18.  
  19. What Can I Do with Capstats?
  20.  
  21.   * Parse out .cap data for one or more individual threads from a .cap
  22.   file; e.g. pipe threads 1 and 37 from a list of 50 into a separate file,
  23.   or all threads except thread 2, etc.
  24.  
  25.   * Ouput summary info in .csv (comma-separated-value) format, which can be
  26.   read directly into a data processing application like Microsoft Excel.
  27.   
  28.   * List callers and callees of any function that appears in the profile
  29.   data.
  30.  
  31.   * Convert .cap files to .cab (cap binary) format, which contains (nearly)
  32.   all the data in the .cap file and can be parsed 10-100 times more quickly
  33.   by capstats.  See below for details.
  34.  
  35.  
  36. What's This .cab (cap binary) Format Business?
  37.  
  38.     CAP dumps profile information to a text file that is typically 5-20Mb.
  39.   This is very inefficient to parse(!); using capstats with the original
  40.   .cap data is not an interactive experience. This is especially annoying
  41.   when you're looking at parent-child function relationships, which
  42.   requires many runs of capstats on the same data.
  43.  
  44.     SOOoooo... You can use capstats to do a ONE-TIME conversion of your
  45.   .cap data to ".cab" format.  For example, if you have profile data in
  46.   myexe.cap, to convert to .cab format, just do 'capstats /B:myexe.cab
  47.   myexe.cap' (see command flags below).  In all subsequent capstats
  48.   operations, use myexe.cab as input to capstats, which will detect the
  49.   file type and determine whether it knows how to handle your set of
  50.   options.
  51.  
  52.  
  53. How Do I Do Everything?
  54.  
  55.   Here is a descriptive list of command line flags (these are briefly
  56.   described by capstats if you type 'capstats').  The other command line
  57.   arguments are the input file and an optional list of thread ids.  You
  58.   must specify at least one MODE and zero or more FLAGs.
  59.  
  60. Switch              Type    Argument    .cap    .cab (input format accepted)
  61. /E or /exclusive    FLAG    <none>      Yes     Yes
  62. /M or /match        FLAG    <none>      Yes     Ignored (default)
  63. /N or /profile      FLAG    <none>      Yes     No
  64. /D or /delimit      FLAG    <none>      Yes     Yes
  65. /L                  FLAG    <none>      Yes     N/A
  66. <none> (summary)    MODE    <none>      Yes     Yes
  67. /R or /raw          MODE    <none>      Yes     Yes
  68. /Q or /quick        MODE    <none>      Yes     No
  69. /P or /parent       MODE    Fxn Name    Yes     Yes
  70. /C or /child        MODE    Fxn Name    No      Yes
  71. /T or /truncate     MODE    Fxn Name    No      Yes
  72. /A or /above        MODE    Fxn Name    No      Yes
  73. /B or /bindump      both    Output File Yes     Yes
  74.  
  75. Mode/Flag Descriptions:
  76.  
  77.   (/E)xclusive: Dump all threads EXCEPT those specified.  If no threads are
  78.   specified, this flag is ignored.
  79.  
  80.   (/M)atch: Match functions by parsed function and module names instead of
  81.   the full "decorated" names.  Not necessary if using .cab input.
  82.  
  83.   (/N)Profile: If you have data from more than one test run in the same
  84.   .cap file, specify this option to use only the first batch of data.  If
  85.   you run your scenario the right way, you shouldn't ever encounter this
  86.   situation, and won't need this flag.
  87.  
  88.   (/D)elimit: Output comma separated data (.csv).
  89.  
  90.   (/L)eave: Leave function names unmangled.  Required if profilee uses
  91.   overloaded C++ functions.
  92.  
  93.   ()Summary: Summary mode; this is the default if you don't specify one of
  94.   [/Q /P /C /B].  Works with [/E /M /N /D] (all flags).
  95.  
  96.   (/R)aw: Dump (to stdout) the specified threads (see command line help)
  97.   exactly as they appear in the original .cap file, or in .csv format (/D).
  98.   Works with all flags.
  99.  
  100.   (/Q)uick: Dump the first few calls from each specified thread.  Works
  101.   with [/N /E].
  102.  
  103.   (/P)arent: Dump a list of all the callers (parent functions) of the given
  104.   function.  The data for each caller is the number of times / amounts of
  105.   time that caller spent calling the given function.  All flags ok.
  106.  
  107.   (/C)hild: Dump a list of all the callees (child functions) of the given
  108.   function.  The data for each callee is the number of times / amounts of
  109.   time the given function spent calling that callee.  All flags ok.
  110.  
  111.   (/T)runcate: Dump (raw, to stdout or .cab file) only functions appearing
  112.   under this function in the call trees.  Works with all flags and /B;
  113.   implicit /R.
  114.  
  115.   (/A)bove: Dump (raw, to stdout or .cab file) only functions appearing
  116.   above this function in the call trees.
  117.  
  118.   (/B)inDump: For selected tasks, Convert the given .cap file (see command
  119.   line help) to .cab format; output to the given output file.  FLAG if used
  120.   with /T (see above).
  121.  
  122.  
  123. How Should I Use It?
  124.  
  125.   * Run your CAP scenario and generate a .cap file:
  126.   e.g. "foo.cap".
  127.     
  128.   * Use capstats with the /B option to convert the .cap file to a .cab file:
  129.   e.g. "capstats /B:foo.cab foo.cap".
  130.     
  131.   * Make a summary of all the functions in your file and import it into a
  132.   data processing application like Microsoft Excel:
  133.   e.g. "capstats /D foo.cab > foo.csv";
  134.        "excel foo.csv".
  135.     
  136.   * When you find a function in the summary you want more detail on, use
  137.   capstats with the /P, /C or /T option and your .cab file to investigate:
  138.   e.g. "capstats /C:FFoo foo.cab" or
  139.        "capstats /T:FFoo /B:ffoo.cab foo.cab";
  140.        "capstats /R /D ffoo.cab > ffoo.csv";
  141.        "excel ffoo.csv".
  142.  
  143.