Library /sys$common/syshlp/PCA$HELP.HLB  —  PLOT
    Analyzer Command

    Generates performance or coverage histograms. A number of
    different kinds of data can be plotted along the horizontal axis
    and a variety of data domains can be partitioned into buckets
    along the vertical axis to form the histogram.

    Format

      PLOT  [nodespec [,nodespec...]]

1  –  Parameters

 nodespec

    Specifies a program location. Node specifications (nodespecs)
    on PLOT and TABULATE commands define how the vertical axis of a
    histogram or table is partitioned into buckets. For example, the
    node specification PROGRAM_ADDRESS BY ROUTINE selects the program
    address domain, the domain of all possible program addresses.
    From this domain, it selects the address ranges of the routines
    in the program. Each of these address ranges defines a bucket.

    See HELP Nodespecs for information about node specifications.

2  –  Description

    The PLOT command generates performance or coverage histograms.
    When you enter a PLOT command, you must specify two things: the
    kinds of data to tally, and how to partition the histogram. These
    two things define the meanings of the horizontal and vertical
    axes of the histogram. What kind of data to tally is specified
    with a data-kind qualifier (see qualifier list).

    Each histogram is partitioned into buckets representing value
    ranges. Each data point in the data file is tallied in the bucket
    whose value range includes the value of the data point.

    Every PLOT command requires one qualifier from the data kind and
    the sorting categories to generate a histogram. If you do not
    specify one qualifier from each category, a default qualifier is
    used. If your PLOT command has one or more node specifications,
    the qualifier defaults are taken from the SET PLOT defaults.
    If your PLOT command does not have a node specification, all
    qualifier and node specification defaults are taken from the
    previous PLOT or TABULATE command you entered.

    The TABULATE command displays the same information as the PLOT
    command, but in the form of tables instead of histograms.

3  –  Data-kind qualifiers

3.1    /ANC

    Has the same effect as /NONCOVERAGE, except that every acceptably
    non-covered (ANC) bucket has the ANC label placed in the
    percentage column.

3.2    /COUNTERS

    Tallies exact execution count data along the horizontal axis. To
    use this qualifier, you must have collected execution counts with
    the SET COUNTERS command.

3.3    /COVERAGE

    Tallies test coverage data along the horizontal axis. Every
    program unit that is covered (executed at least once) gets a
    full-length histogram bar. To use this qualifier, you must have
    collected test coverage or execution counts data with the SET
    COVERAGE or SET COUNTERS command.

3.4    /CPU_SAMPLING

    Tallies CPU sampling data along the horizontal axis. To use this
    qualifier, you must have collected CPU sampling data.

3.5    /FAULT_ADDRESS

    Tallies page fault data along the horizontal axis using the
    faulting address value to tally each data point. To use this
    qualifier, you must have collected page fault data.

3.6    /IO_SERVICES

    Tallies the number of I/O system service calls along the
    horizontal axis. To use this qualifier, you must have collected
    I/O services data.

3.7    /NONCOVERAGE

    Tallies test non-coverage data along the horizontal axis. Every
    program unit that is not covered (is not executed at least once)
    gets a full-length histogram bar. Program units that are covered
    do not get histogram bars. To use this qualifier, you must have
    collected coverage or execution counts data with the SET COVERAGE
    or SET COUNTERS command.

3.8    /PAGE_FAULTS

    Tallies page fault data along the horizontal axis using the
    program address value to tally each data point. To use this
    qualifier, you must have collected page fault data.

3.9    /PC_SAMPLING

    Tallies program counter sampling data along the horizontal axis.
    To use this qualifier, you must have collected program counter
    sampling data.

    Note that /PC_SAMPLING is the default data-kind qualifier.

3.10    /PHYSICAL_IO_COUNT

    Tallies the total number of physical I/O operations (reads plus
    writes) along the horizontal axis. To use this qualifier, you
    must have collected I/O services data.

3.11    /READ_COUNT

    Tallies the number of physical read operations along the
    horizontal axis. To use this qualifier, you must have collected
    I/O services data.

3.12    /SERVICES

    Tallies the number of system service calls along the horizontal
    axis. To use this qualifier, you must have collected system
    services data.

3.13    /UNALIGNED

    Tallies unaligned access fault data along the horizontal axis
    using the program address value to tally each data point. To use
    this qualifier, you must have collected unaligned access fault
    data.

3.14    /VCOUNTERS

    Tallies exact execution count data of vector instructions
    along the horizontal axis. To use this qualifier, you must have
    collected vector instruction counts.

3.15    /VCPU_SAMPLING

    Tallies CPU sampling data along the horizontal axis. To use this
    qualifier, you must have collected vector CPU sampling data.

3.16    /VPC_SAMPLING

    Tallies program counter sampling data along the horizontal axis.
    To use this qualifier, you must have collected vector PC sampling
    data.

3.17    /WRITE_COUNT

    Tallies the number of physical write operations along the
    horizontal axis. To use this qualifier, you must have collected
    I/O services data.

4  –  Sorting qualifiers

4.1    /ALPHABETICALLY

       /ALPHABETICALLY[=n[:m]]

    Sorts the histogram alphabetically by label names. If you specify
    histogram. If you specify =n:m, only buckets n through m (after
    sorting) are retained.

4.2    /ASCENDING

       /ASCENDING[=n[:m]]

    Sorts the histogram in ascending order by bucket data count
    (smallest count first). If you specify =n, only the first n
    buckets (after sorting) are retained in the histogram. If you
    specify =n:m, only buckets n through m (after sorting) are
    retained.

4.3    /DESCENDING

       /DESCENDING[=n[:m]]

    Sorts the histogram in descending order by bucket data count
    (largest count first). If you specify =n, only the first n
    buckets (after sorting) are retained in the histogram. If you
    specify =n:m, only buckets n through m (after sorting) are
    retained.

    Note that /DESCENDING is the default sorting qualifier.

4.4    /NOSORT

       /NOSORT[=n[:m]]

    Specifies that the histogram not be sorted. If you specify =n,
    only the first n buckets are retained in the histogram. If you
    specify =n:m, only buckets n through m are retained.

5  –  Bucket selection qualifiers

5.1    /MAXIMUM

       /MAXIMUM=n
       /NOMAXIMUM

    Determines whether to omit buckets that exceed a maximum
    percentage. The /MAXIMUM=n qualifier specifies that buckets whose
    percentage exceeds n% should be omitted from the histogram. The
    /NOMAXIMUM qualifier specifies that no maximum threshold applies.

    Note that /NOMAXIMUM, /NOMINIMUM, and /ZEROS are the default
    bucket selection qualifiers.

5.2    /MINIMUM

       /MINIMUM=n
       /NOMINIMUM

    Determines whether to omit buckets that fall below a minimum
    percentage. The /MINIMUM=n qualifier specifies that buckets whose
    percentage falls below n% should be omitted from the histogram.
    The /NOMINIMUM qualifier specifies that no minimum threshold
    applies.

    Note that /NOMAXIMUM, /NOMINIMUM, and /ZEROS are the default
    bucket selection qualifiers.

5.3    /ZEROS

       /ZEROS
       /NOZEROS

    Determines whether zero data count buckets are omitted from
    the histogram. The /NOZEROS qualifier specifies that buckets
    with zero data counts be omitted from the histogram. Thus, the
    histogram becomes smaller since buckets without data are dropped.
    The /ZEROS qualifier retains buckets with zero data counts.

    Note that /NOMAXIMUM, /NOMINIMUM, and /ZEROS are the default
    bucket selection qualifiers.

6  –  Source code display qualifiers

6.1    /SOURCE

       /SOURCE
       /NOSOURCE

    Determines whether source text is shown next to the histogram
    bars. The /SOURCE qualifier specifies to display source code
    in histograms generated with BY LINE or BY CODEPATH node
    specifications. The /NOSOURCE qualifier specifies that source
    text not be displayed.

    Note that /SOURCE is the default source code display qualifier.

7  –  Program address selection qualifiers

7.1    /CUMULATIVE

       /CUMULATIVE[=n]
       /NOCUMULATIVE

    Tallies all stack PC values for each data point in the histogram.
    Thus, each bucket shows how much time or other resource is
    spent in the corresponding program unit and all program units
    it calls. The /CUMULATIVE qualifier has no effect if you are
    not plotting against the program address domain. To use the
    /CUMULATIVE qualifier, you must have collected stack PC values in
    the Collector. You may specify an integer to cuase only the first
    "n" routines down the stack to be used. If used with /STACK_
    DEPTH=m, the Analyzer will charge the data point to all calls (or
    "n" calls for /CUMULATIVE=n) below the specified depth.

    The /NOCUMULATIVE qualifier tallies only the original program
    counter value for each data point.

    Note that /NOCUMULATIVE, /NOMAIN_IMAGE and /NOSTACK_DEPTH are the
    default program address selection qualifiers.

7.2    /MAIN_IMAGE

       /MAIN_IMAGE[=n[:m]]
       /MAIN_IMAGE[=prog-unit]

    Specifies to use the first call stack PC value that falls in your
    program's main image, when tallying program addresses. You may
    specify the PC value to be n or the range n:m. If you specify a
    program unit or address range, it will select the first PC value
    in that address. The /NOMAIN_IMAGE qualifier specifies to use the
    original program counter value for each data point, to tally the
    data point.

    Note that /NOCUMULATIVE, /NOMAIN_IMAGE and /NOSTACK_DEPTH are the
    default program address selection qualifiers.

7.3    /STACK_DEPTH

       /STACK_DEPTH=n
       /NOSTACK_DEPTH

    Determines whether the Analyzer will climb the call stack to
    determine the PC values.

    Note that /NOCUMULATIVE, /NOMAIN_IMAGE and /NOSTACK_DEPTH are the
    default program address selection qualifiers.

8  –  Design qualifiers

8.1    /FILL

       /FILL=("*","O","x","@",":","#","/","+")

    Specifies the fill to be used for the first, second, etc., data
    kind in a plot. A maximum of eight character strings can be
    defined, and each must be delimited by double or single quotation
    marks.

    Note that /FILL=("*","O","x","@",":","#","/","+"), /NOSCALE and
    /NOWRAP are the default design qualifiers.

8.2    /SCALE

       /SCALE=n
       /NOSCALE

    Determines whether fixed or adjusted histogram scale is used.
    The /SCALE=n qualifier allows you to select a fixed scale for the
    plot. The /NOSCALE default qualifier selects adjusted scaling,
    which causes the longest bar on the histogram to occupy the full
    width of the plot.

    Note that /FILL=("*","O","x","@",":","#","/","+"), /NOSCALE and
    /NOWRAP are the default design qualifiers.

8.3    /WRAP

       /WRAP
       /NOWRAP

    Specifies to wrap PLOT output that is too long. /NOWRAP specifies
    to truncate PLOT output that is too long.

    Note that /FILL=("*","O","x","@",":","#","/","+"), /NOSCALE and
    /NOWRAP are the default design qualifiers.

9  –  Tasking qualifiers

9.1    /CREATOR_PC

       /CREATOR_PC
       /NOCREATOR_PC

    Charges a data point to the location in the program that created
    the task, rather than to the PC value of the measurement. This
    qualifier can only be used when the PROGRAM_ADDRESS domain is in
    effect, and when TASKING data has been collected. It overrides
    /MAIN_IMAGE, STACK_DEPTH and /CUMULATIVE.

9.2    /PARENT_TASK

       /PARENT_TASK
       /NOPARENT_TASK

    Charges a data point to the parent of the current task, rather
    than to the current task. It can only be used when the TASK or
    the TASK_TYPE domain is in effect, and when TASKING data has been
    collected.

9.3    /TASK_SWITCH

    Represents the number of times there was a task context switch.
    It may be applied to the following domains: TIME BY n MSECs,
    TASK, TASK_PRIORITY, and TASK_TYPE. This qualifier will only
    work with the TIME, TASK, TASK_PRIORITY, and TASK_TYPE filter
    specifications.

10  –  CALL TREE domain qualifiers

10.1    /CHAIN_NAME

       /CHAIN_NAME
       /NOCHAIN_NAME

    Specifies to use the comma list form of presentation on the plot
    for call trees. /NOCHAIN_NAME specifies to use the indentation
    form. If you specify /NOCHAIN_NAME, then the PLOT command's
    maximum and mininum sorting qualifiers are not in effect. If
    you specify /CHAIN_NAME, then /NOZEROS is in effect.

    Note that /NOCHAIN_NAME and /NOPATHNAME are the default CALL_TREE
    domain qualifiers.

10.2    /PATHNAME

       /PATHNAME
       /NOPATHNAME

    Specifies to use full pathnames for each routine name in the
    plot. /NOPATHNAME specifies to use unqualified routine names.

    Note that /NOCHAIN_NAME and /NOPATHNAME are the default CALL_TREE
    domain qualifiers.
    Note that if you do not specify one qualifier from each category,
    a default qualifier is used. If your PLOT command has one or
    more node specifications, the qualifier defaults are taken from
    the SET PLOT defaults. If your PLOT command does not have a node
    specification, all qualifier and node specification defaults are
    taken from the last PLOT or TABULATE command you entered.

11  –  Default qualifiers

11.1    /DEFAULT

    Specifies that all default qualifiers and node specifications be
    taken from the SET PLOT defaults instead of from the currently
    active plot.

12  –  Examples

  PCAA> PLOT PROGRAM BY MODULE

      Program counter sampling data is plotted by default. The
      vertical axis has one histogram bar for each module in
      the program. It also has one bar for each shareable image
      used. Each bar indicates how much time is consumed in the
      corresponding program unit.

  PCAA> PLOT/PAGE_FAULTS/SOURCE MODULE FOO BY LINE

      The histogram has one bar for each line in module FOO of the
      user program. The length of each histogram bar is proportional
      to the number of page faults that occurred at the corresponding
      line. Because the /SOURCE qualifier is present, the text of
      each source line is shown next to the histogram bar for that
      line.

  PCAA> PLOT/NONCOVERAGE/SOURCE MODULE FOO BY CODEPATH

      The histogram has one bucket for each codepath in module FOO.
      Any codepath that is not covered has a full-length histogram
      bar. Thus, the histogram highlights code that is not tested.
      The text of each source line is shown next to the corresponding
      codepaths.

  PCAA> PLOT/IO_SERVICES/MAIN_IMAGE PROGRAM BY ROUTINE

      The number of I/O system service calls is plotted along the
      horizontal axis. The routines of the program are plotted along
      the vertical axis. I/O data originating in shareable images
      (such as the Run-Time Library) are charged back to the routines
      in the main image (the user program) that called the shareable
      images to cause I/O.

  PCAA> PLOT/SERVICES/DESCENDING/NOZEROS SYSTEM_SERVICES BY SERVICE

      The names of the OpenVMS system services are plotted along the
      vertical axis. The number of calls on each system service is
      plotted along the horizontal axis. The histogram is sorted so
      that the most frequently used services are listed first. All
      system services that were never called are omitted from the
      histogram.

  PCAA> PLOT/PHYSICAL_IO_COUNTS FILE_NAME BY FILE

      The names of the RMS files opened or created by the program are
      plotted along the vertical axis of the histogram. The number
      of physical I/O operations for each file is plotted along the
      horizontal axis.

  PCAA> PLOT/VCOUNTERS INSTRUCTION BY VOPCODE

      This command causes the report view to be based on the
      disassembled opcode for each vector instruction in the
      entire application that is sampled. The number of times a
      vector instruction is used lets you see if your application
      is spending a lot of time performing certain operations.
      For example, if you see that the SYNC vector instruction
      is executed more than any other vector instruction, you can
      infer that the scalar processor is spending too much idle time
      waiting for the vector processor to finish an operation.
Close Help