VMS Help PCA  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The Compaq Performance and Coverage Analyzer for OpenVMS (PCA)
    is a software development tool that helps you analyze the run-
    time behavior of application programs. PCA can pinpoint execution
    bottlenecks and other performance problems in user programs.
    Using this information, you can modify your programs to run
    faster. This tool also measures which parts of your program are
    or are not executed by a given set of test data so that you can
    devise tests that exercise all parts of your program.

    PCA has two operational components: the Collector and the
    Analyzer. The Collector gathers performance or coverage data
    on a running user program and writes that data to a performance
    data file. Later, the Analyzer processes the collected data to
    produce performance or coverage histograms and tables.

    The DCL command 'PCA' invokes the Analyzer. The parameter to the
    PCA command is the name of the performance data file to analyze.

    Format

      $ PCA  [file-spec]

1 - Parameters

 file-spec

    Specifies the performance data file to be analyzed. File-spec
    may be any valid OpenVMS file specification. If you omit the file
    type, .PCA is used by default. If you omit the entire file-spec
    parameter, you must use the Analyzer SET DATAFILE command to
    specify the performance data file.

2 - Qualifiers

 2.1 - /COMMAND

       /COMMAND="command [;command...]"

    Specifies a list of Analyzer commands. The Analyzer executes
    this list of commands after executing the commands in the
    initialization file (if any) and before prompting for commands
    from the terminal.

 2.2 - /INTERFACE

       /INTERFACE=[interface-type]

    Controls the display interface to be selected.

    The default qualifier value is /INTERFACE=CHARACTER_CELL.

    Qualifier Keyword  Description

    CHARACTER_CELL     Selects the character cell interface.
    DECWINDOWS         Selects the DECwindows (a.k.a Motif)
                       interface, depending on the setting of the
                       various PCA*$DEC$DISPLAY and DECW$DISPLAY
                       logicals.
    MOTIF              Selects the Motif (a.k.a DECwindows)
                       interface, depending on the setting of the
                       various PCA*$DEC$DISPLAY and DECW$DISPLAY
                       logicals.

3 - Collector

    The Collector gathers performance or coverage data from your
    program at run time and writes that data to a performance data
    file. To use the Collector, you must:

    1. Compile your sources with the "/DEBUG" qualifier;

       This puts all the necessary symbolic information PCA needs
       into the object file.

    2. The following steps specifies the PCA Collector as your
       program's "debugger":

        i Link your program with the "/DEBUG" qualifier;

       ii Define the logical name LIB$DEBUG as PCA$COLLECTOR;

    3. Run your program;

    4. Enter the "GO" command at the PCAC> prompt.

       The Collector will transfer control to your program just like
       the debugger does, and will store the data in a data file
       named your-image-name.PCA.

    The following example illustrates the DCL commands required to
    invoke the Collector on the FORTRAN program PRIMES.FOR:

  $ FORTRAN/DEBUG PRIMES.FOR
  $ LINK/DEBUG PRIMES.OBJ
  $ DEFINE LIB$DEBUG PCA$COLLECTOR
  $ RUN PRIMES.EXE

         Compaq Performance and Coverage Analyzer for OpenVMS Version V4.7-3

  PCAC>

    When you get the Collector prompt (PCAC>), you have successfully
    invoked the Collector and are ready to enter Collector commands.
    To collect PC-sampling data, it is sufficient to enter the GO
    command at this point. The Collector will create a performance
    data file with the default name "image-name.PCA", where image-
    name is the name of the executable image being run. This file
    will contain the collected data and all symbol information needed
    by the Analyzer.

  PCAC> GO
  %PCA-I-DEFDATFIL, set datafile required in this context,
                    creating '[]PRIMES.PCA'
  %PCA-I-BEGINCOL, data collection begins
  %PCA-I-DATADEFPC, defaulting to collecting PC sampling data
  %PCA-I-ENDCOL, data collection ends
  $

    For more information, enter HELP at the PCAC> prompt.

4 - Analyzer

    The Analyzer processes the data in a performance data file to
    produce histograms, tables, and other reports. The Analyzer
    enables you to interactively examine the gathered data in various
    ways until performance bottlenecks are pinpointed or code not
    covered by testing is identified.

    To invoke the Analyzer, use the PCA command at DCL level. This
    command accepts the name of a performance data file created by
    the Collector as a parameter. For example, to run the Analyzer on
    the performance data file PRIMES.PCA, use this command:

  $ PCA PRIMES

        Compaq Performance and Coverage Analyzer for OpenVMS Version V4.7-3

  PCAA>

    The PCAA> prompt indicates that The Analyzer is ready to accept
    Analyzer commands. For example, the user may just enter the
    NEXT command at this point. It will display a source plot of the
    program's routine with the most PC-sampling data points. In the
    plot, the line with the most data points will be pointed to by an
    arrow (->). In other words, the NEXT command will show where the
    program is spending most of the execution time.

  PCAA> NEXT

          Compaq Performance and Coverage Analyzer for OpenVMS          Page 1

      Program Counter Sampling Data (192 data points total) - "*"

                        Routine PRIME\PRIME

  Percent   Count    Line
  PRIME\PRIME\
    0.5%               5:       LOGICAL FUNCTION PRIME(N)
    1.6%               6:       PRIME = .TRUE.
    0.5%               7:       DO 10 I = 2, N/2
   54.7%  ******* ->   8:       IF ((N - ((N / I) * I)) .EQ. 0) THEN
                       9:           PRIME = .FALSE.
    0.0%              10:           RETURN
    0.0%              11:       ENDIF
    1.0%              12:  10   CONTINUE
    0.0%              13:       RETURN

       PCAA>

    The NEXT command can now be typed again to traverse to the point
    with the next largest number of data points, and so on. To
    end the Analyzer session, the EXIT command or Control/Z can be
    entered.

    For more information, enter HELP at the PCAA> prompt.

5 - Release Notes

    The release notes for PCA are located in SYS$HELP:PCAvvu.RELEASE_
    NOTES (ASCII text) and SYS$HELP:PCAvvu_RELEASE_NOTES.PS
    (postscript), where 'vv' represents the major version number
    and 'u' the minor version number. For example, the filename for
    the PCA V4.7 release notes is 'PCA047.RELEASE_NOTES'.