1 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...]]
2 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.
2 Data-kind_qualifiers
/ANC
Has the same effect as /NONCOVERAGE, except that every acceptably
non-covered (ANC) bucket has the ANC label placed in the
percentage column.
/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.
/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.
/CPU_SAMPLING
Tallies CPU sampling data along the horizontal axis. To use this
qualifier, you must have collected CPU sampling data.
/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.
/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.
/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.
/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.
/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.
/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.
/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.
/SERVICES
Tallies the number of system service calls along the horizontal
axis. To use this qualifier, you must have collected system
services data.
/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.
/VCOUNTERS
Tallies exact execution count data of vector instructions
along the horizontal axis. To use this qualifier, you must have
collected vector instruction counts.
/VCPU_SAMPLING
Tallies CPU sampling data along the horizontal axis. To use this
qualifier, you must have collected vector CPU sampling data.
/VPC_SAMPLING
Tallies program counter sampling data along the horizontal axis.
To use this qualifier, you must have collected vector PC sampling
data.
/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.
2 Sorting_qualifiers
/ALPHABETICALLY
/ALPHABETICALLY[=n[:m]]
Sorts the histogram alphabetically by label names. 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.
/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.
/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.
/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.
2 Bucket_selection_qualifiers
/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.
/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.
/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.
2 Source_code_display_qualifiers
/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.
2 Program_address_selection_qualifiers
/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.
/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.
/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.
2 Design_qualifiers
/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.
/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.
/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.
2 Tasking_qualifiers
/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.
/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.
/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.
2 CALL_TREE_domain_qualifiers
/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.
/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.
2 Default_qualifiers
/DEFAULT
Specifies that all default qualifiers and node specifications be
taken from the SET PLOT defaults instead of from the currently
active plot.
2 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.