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.