PCA Command
Establishes a variety of definitions, data collection options
and various mode settings. These settings are established by the
keyword specified on the command.
Format
SET keyword [parameters]
1 – Parameters
keyword
Specifies the definition, data collection option or mode setting
to establish. In the Collector, valid keywords are COUNTERS,
COVERAGE, CPU_SAMPLING, DATAFILE, DISPLAY, EVENT, IO_SERVICES,
KEY, LANGUAGE, LOG, MAX_SOURCE_FILES, MODE, NOTE, PAGE_FAULTS,
PC_SAMPLING, PROMPT, RUN_NAME, SEARCH, SERVICES, SOURCE, STACK_
PCS, TASKING, TERMINAL, UNALIGNED, VCOUNTERS, VCPU_SAMPLING,
VERIFY, VPC_SAMPING and WINDOW.
In the Analyzer, valid keywords are ANC, DATAFILE, DISPLAY,
EDITOR, FILTER, KEY, LANGUAGE, LOG,MAX_SOURCE FILES, MODE, PLOT,
PROMPT, SEARCH, SOURCE, TERMINAL, TITLE, VERIFY, and WINDOW.
parameters
Depends on the keyword specified.
2 – Description
SET is not an individual command. Each SET command has a two-
keyword name consisting of SET followed by a required keyword.
For details, see the individual SET command descriptions.
3 – ANC
Analyzer Command
Determines which coverage-set points are acceptably non-covered,
and saves that information for the next test run.
Format
SET ANC [nodespec]
3.1 – Parameters
nodespec
Specifies the address range that you want to specify as
acceptably non-covered. The nodespec must specify one or more
program address locations. If not specified, SET ANC will use the
current plot position established by a traverse command or by the
FIND command.
3.2 – Description
The SET ANC command lets you select particular coverage-set
points as acceptably non-covered, and saves that information
for the next test run.
There are two ways to specify ANC information. One is to generate
a non-coverage or ANC plot or table and then use a traverse
command (such as NEXT), or the FIND command, to pinpoint a
particular non-covered point. Line the pointer up with the
desired bucket, then issue the SET ANC command at the Analyzer
prompt. The SET ANC command saves that address as acceptably
non-covered. You can continue traversing the plot in this manner
until you have saved all the non-covered points. Note that after
you enter the first traverse command, you can enter CTRL/N to
move the pointer from one non-covered point to another, and that
the keypad COMMA key will enter the SET ANC command for you.
Another way to save ANC information is to provide a nodespec on a
SET ANC command, as in the example provided.
3.3 – Examples
PCAA> SET ANC ROUTINE R2 BY LINE, ROUTINE R4 BY LINE
This command saves all non-covered lines in routines R2 and R4
as acceptably non-covered.
4 – COUNTERS
Collector Command
Establishes the collection of exact execution counts at specified
program locations.
Format
SET COUNTERS nodespec [,nodespec...]
4.1 – Parameters
nodespec
Specifies a set of program locations that gather execution
counts.
See HELP Nodespec for information about node specifications.
4.2 – Description
The SET COUNTERS command establishes execution counters at all
program locations specified by the node specifications. After you
enter the GO command, the Collector counts the number of times
each specified program location is executed and records each
execution in the performance data file.
If you enter the SET COUNTERS command before entering a SET
DATAFILE command, the Collector establishes a default data file.
The default data file has the same file name as your program's
executable image file and a file type of PCA.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or TAB
command in the Analyzer.
4.3 – Qualifiers
4.3.1 /STACK_PCS
Specifies that stack PC values are collected for counter data.
Further SET COUNTERS requests will assume a default of /STACK_
PCS.
4.3.2 /NOSTACK_PCS
Specifies that no stack PC values are collected for counter data.
This is the default upon entry into the collector.
4.4 – Examples
PCAC> SET COUNTERS/STACK_PCS LINE PRIMES %LINE 22
This command causes PCA to count the executions of line 22
of module PRIMES when data collection starts, and enables the
collection of stack PC values. For all further SET COUNTERS
requests, a default of /STACK_PCS will be established.
PCAC> SET COUNTERS PROGRAM BY ROUTINE
This command specifies that execution counters be placed at all
routine entry points in the user program.
5 – COVERAGE
Collector Command
Establishes the collection of test coverage data at specified
program locations.
Format
SET COVERAGE [nodespec [,nodespec...]]
5.1 – Parameters
nodespec
Specifies a set of program locations at which to measure test
coverage.
See HELP Nodespec for information about node specifications.
5.2 – Description
The SET COVERAGE command establishes the collection of test
coverage data for all program locations specified by node
specifications. The Collector places a breakpoint at each
specified program location to measure test coverage. After
you enter the GO command, the Collector determines whether
each specified program location is reached during program
execution. When a test coverage breakpoint is reached during
program execution, the Collector records that program location
in the performance data file. The Collector then removes the
breakpoint so that the overhead of measuring coverage is not
incurred in subsequent executions of the same program location.
If you specify the /UNTIL:n qualifier, the Collector removes
the breakpoint after the nth execution instead of the first
execution.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or TAB
command in the Analyzer.
If you enter the SET COVERAGE command before entering a SET
DATAFILE command, the Collector establishes a default data file.
The default data file has the same file name as your program's
executable image file and a file type of PCA.
5.3 – Qualifiers
5.3.1 /PREVIOUS
Causes the Collector to use the breakpoint table left by the
previous collection run when it is appending test coverage data
to an existing performance data file. If such a breakpoint table
exists, the node specifications are ignored. Also causes the
Collector to write a table of test coverage breakpoint locations
not yet covered (or not yet covered n times if /UNTIL:n is
specified) to the data file at the end of the current collection
run.
This qualifier causes test coverage to be measured only once
(or only n times for /UNTIL:n) for an entire set of collection
runs. If a program location has been found to be covered in
one collection run, the Collector makes no attempt to measure
coverage of that location in any subsequent collection run. Use
of the /PREVIOUS qualifier makes data collection more efficient,
but you lose the ability to determine what individual collection
runs covered which program locations. If you use the /PREVIOUS
qualifier, you should use the /APPEND qualifier on the SET
DATAFILE command.
5.3.2 /UNTIL
/UNTIL:n
Causes each test coverage breakpoint to be removed the nth time
it is reached during program execution. By using the /UNTIL:n
qualifier, you can determine whether a program location is
executed at least n times. If you omit the /UNTIL:n qualifier,
each breakpoint is removed the first time it is reached.
5.3.3 /STACK_PCS
Specifies that stack PC values are collected for coverage data.
Further SET COVERAGE requests will assume a default of /STACK_
PCS.
5.3.4 /NOSTACK_PCS
Specifies that no stack PC values are collected for coverage
data. This is the default upon entry into the collector.
5.3.5 /ANC
Saves codepath information in the performance data file for every
module containing coverage-set points. This information is used
by the Analyzer MERGE/ANC command to validate the ANC information
being merged.
5.4 – Examples
PCAC> SET COVERAGE/STACK_PCS PROGRAM BY CODEPATH
This command specifies that test coverage be measured for every
codepath in the user program, and enables the collection of
stack PC values.
PCAC> SET DATAFILE/APPEND COV_TEST.PCA
PCAC> SET COVERAGE/PREVIOUS PROGRAM BY CODEPATH
The SET DATAFILE command specifies that the coverage data from
this collection run be appended to an existing performance
data file if such a file exists. The SET COVERAGE command
specifies that test coverage be measured for every codepath in
the user program. The /PREVIOUS qualifier specifies that if an
existing data file is found, then the Collector will ignore the
nodespec, and will use the breakpoint table from the previous
collection run recorded in that data file. Hence, test coverage
is measured only once for each codepath in the program over all
collection runs recorded in the performance data file.
PCAC> SET COVERAGE/UNTIL:4 MODULE NICK BY CODEPATH
This command specifies that test coverage be measured for every
codepath in module NICK. Up to four executions of each codepath
is recorded in the performance data file before the coverage
breakpoint is removed.
PCAC> SET COVERAGE PROGRAM BY ROUTINE
This command specifies that test coverage be measured for every
routine in the user program. Each routine that is called at
least once is recorded as being covered.
6 – CPU_SAMPLING
Collector Command
Enables the collection of program counter sampling data with the
sampling interval based on process CPU (or virtual) time.
Format
SET CPU_SAMPLING
6.1 – Description
The SET CPU_SAMPLING command causes PCA to collect PC values
in the same way that SET PC_SAMPLING does, with one important
exception. The CPU sampling interval is based on virtual process
or CPU time, not system time. When you issue the SET CPU_SAMPLING
command, PCA will only collect PC values whenever there has been
one or more clock ticks on the process's clock.
There are many external factors that can affect the behavior
of a program, in relation to the system (or wall) clock. For
example, page faulting and system service wait time (including
I/O wait time). These conditions make it difficult to determine
whether the program counter contains a specific location because
of the structure of the program's algorithm or because of other
operations occuring in that interval. Under these conditions,
sampling the PC values based on the process's CPU time would be
more effective and reproducible, because the effects caused by
contending processes are reduced.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or TAB
command in the Analyzer.
6.2 – Qualifiers
6.2.1 /INTERVAL
/INTERVAL:n
Specifies the sampling interval in milliseconds. The value of n
must be at least 10 milliseconds and at most 60,000 milliseconds.
Because the granularity of the system clock is 10 milliseconds,
you should use a multiple of 10. The default sampling interval is
10 milliseconds; therefore, you can use the /INTERVAL:n qualifier
only to specify a longer sampling interval.
6.2.2 /STACK_PCS
Specifies that stack PC values are collected for CPU data.
Further CPU_SAMPLING requests will assume a default of /STACK_
PCS. This is the default upon entry into the Collector.
6.2.3 /NOSTACK_PCS
Specifies that no stack PC values are collected for CPU data.
6.3 – Examples
PCAC> SET CPU_SAMPLING/INTERVAL=20/NOSTACK_PCS
This command causes the interval to be 20 milliseconds, and
disables STACK_PCS collection for this measurement. For all
further SET CPU_SAMPLING requests, a default of /NOSTACK_PCS
will be assumed.
7 – DATAFILE
PCA Command
Identifies the performance data file to be used by the Collector
or processed by the Analyzer.
Format
SET DATAFILE [file-spec]
7.1 – Parameters
file-spec
Specifies the performance data file the Collector should use
to record symbol information and performance or coverage data,
or that the Analyzer should process. File-spec can be any valid
OpenVMS file specification. If no file type is specified, the
default file type is PCA.
7.2 – Description
In the Collector, the SET DATAFILE command identifies the
performance data file the Collector should use to record symbol
information and performance or coverage data. No performance or
coverage data is actually written to the specified file until you
enter the GO command. You can thus respecify the data file with
another SET DATAFILE command if you need to correct the data file
specification.
If you want to append the data from the present collection run to
an existing performance data file, use the /APPEND qualifier. If
you want to measure the performance of a shareable image, use the
/SHAREABLE qualifier.
In the Analyzer, the SET DATAFILE command identifies a
performance data file to be processed by the Analyzer. Data from
this file is used by all subsequent PLOT, TABULATE, LIST, and
SHOW commands. You can use the SET DATAFILE command to change the
performance data file any number of times during the Analyzer
session. The Collector builds the performance data file to
contain all symbol information and all performance or coverage
data required by the Analyzer.
7.3 – Qualifiers
7.3.1 /APPEND
Appends the performance or coverage data from the current
collection run to an existing performance data file. If the file
specified by file-spec exists, the Collector opens that file
and appends the performance or coverage data from the current
collection run to it. If the file specified by file-spec does
not exist, the Collector creates a new data file by that name and
writes the performance or coverage data to that file. If you do
not specify the /APPEND qualifier, the Collector always creates
a new file. You may append data to an existing data file only by
using the same image that originally created the file.
7.3.2 /EXECUTABLE
Causes the Collector to use the default performance data file
name. The default data file name consists of the name of the user
program's executable image and the .PCA file type. You get the
default file name if you do not use the SET DATAFILE command.
However, you need the /EXECUTABLE qualifier if you want the
default file name and you also want to specify the /APPEND or
/SHAREABLE qualifier. If you specify the /EXECUTABLE qualifier,
omit the file-spec parameter.
7.3.3 /SHAREABLE
/SHAREABLE=(img-name)
Specifies that you want to measure the performance of a shareable
image and that you have created a Debug Symbol Table that fits
that shareable image. The img-name parameter specifies the
shareable image to measure.
7.4 – Examples
PCAC> SET DATAFILE [PING]TEST
This command specifies that the performance or coverage data be
written to a new file called [PING]TEST.PCA.
PCAA> SET DATAFILE [PING]TEST
This command specifies that performance or coverage data should
be taken from file [PING]TEST.PCA by subsequent PLOT, TABULATE,
and LIST commands.
PCAC> SET DATAFILE/APPEND [PING]OLDTEST
This command specifies that the performance or coverage data be
appended to the existing data file [PING]OLDTEST.PCA.
PCAC> SET DATAFILE/SHAREABLE=(MYSHR) SHRDATA
This command specifies that the performance of shareable image
MYSHR be measured. The name of the data file is SHRDATA.PCA.
8 – DISPLAY
PCA Command
Creates new screen displays to be shown on the terminal screen.
Format
SET DISPLAY display-name [AT window-spec] [display-kind] [,
display-name [AT window-spec] [display-kind]...]
8.1 – Parameters
display-name
Specifies the name of a new screen display to create. The display
name must consist of letters, digits, underscores, and dollar
signs. It cannot begin with a digit.
window-spec
Specifies the screen window at which to position the new display.
If you omit window-spec, the display is positioned at window H1
or H2 (H1 and H2 are used alternately, starting with H1).
Window-spec can be the name of a predefined window, the name of
a window you have defined with a SET WINDOW command, or a window
specification of the form:
start-line,line-count[,start-column,column-count]
Start-line is the screen line number at which you want the
top border of the display to be placed. Line-count is the
number of lines of text you want to see in the window. Start-
column and column-count specify the leftmost column and the
number of columns in the window, respectively. Start-column and
column-count default to column 1 and the current screen width,
respectively.
display-kind
Specifies the kind of display to create; OUTPUT, PLOT and SOURCE
are the valid keywords. OUTPUT indicates a regular output display
to hold the output of SHOW, LIST and SEARCH commands. PLOT
indicates a display to contain the output of PLOT and TABULATE
commands. SOURCE indicates a display to contain output from a
TYPE command. If you omit the display-kind parameter, an output
display is created.
8.2 – Description
The SET DISPLAY command creates new screen displays so that more
displays than the default PLOT, OUT, SRC and PROMPT displays
may appear on your terminal screen. By defining multiple plot
displays and selecting each one in turn as the current plot
display, you can simultaneously display several different
histograms or tables on the screen. Similarly, you can create
multiple output displays.
8.3 – Qualifiers
8.3.1 /DYNAMIC
/DYNAMIC
/NODYNAMIC
Controls whether a display automatically adjusts its window
dimensions proportionally when a SET TERMINAL command is issued.
/DYNAMIC is the default.
8.3.2 /HIDE
/HIDE conceals the display under any other displays that overlap
it. As a result, any displays that were previously hidden under
the specified display become visible.
8.3.3 /POP
/POP places a specified display at the top of the display
pasteboard, ahead of any other displays. This is the default.
8.3.4 /PUSH
Has the same effect as /HIDE.
8.3.5 /REMOVE
Creates a display that does not appear on the screen. Although
a removed display is not visible on the screen, its definition
still exists, and you can request that it be displayed by using
the DISPLAY command.
8.3.6 /SIZE
/SIZE:n
Sets the maximum size of a normal output display to be n lines.
If more than n lines are written to the display, the oldest lines
are lost as the new lines are added. If you omit this qualifier,
the maximum size is set to 50 lines.
For plot displays, n specifies the number of lines of PLOT or
TABULATE output to be buffered internally by the Analyzer at one
time. There is usually no need to change this number.
8.4 – Examples
PCAA> SET WINDOW TOP AT (1,8,45,30)
PCAA> SET DISPLAY NEWINST AT TOP PLOT
PCAA> SELECT/PLOT NEWINST
The SET WINDOW command creates a window named TOP starting
at line 1, column 45, and extending down for 8 lines and to
the right for 30 columns. The SET DISPLAY command creates an
instruction display named NEWINST to be displayed through TOP.
The SELECT/PLOT command selects NEWINST as the current PLOT
display.
PCAA> SET DISPLAY/SIZE:500 PING AT T1
PCAA> SELECT/OUTPUT PING
PCAA> LIST ALL
This SET DISPLAY command creates an output display named PING,
which is placed at window T1, the top third of the screen. PING
holds up to 500 lines of output. The SELECT command selects
PING as the current output display. The output of the LIST
command is written to PING.
PCAA> SET DISPLAY PANG AT H1 PLOT
PCAA> SELECT/PLOT/SCROLL PANG
PCAA> PLOT MODULE FOO BY LINE
PCAA> SCROLL/DOWN
The SET DISPLAY command creates a plot display to be shown
at window H1, the top half of the screen. The SELECT command
selects that display as the current plot display and as the
current scrolling display. The output of the PLOT command is
shown in the PANG display and the SCROLL command scrolls that
same display. By creating new plot displays, you can see the
output from several PLOT or TABULATE commands at the same time,
each in its own screen display.
PCAA> SET DISPLAY TINY AT (1,2)
This command creates an output display named TINY. TINY is
placed at a screen window that starts at line 1 (the top line
of the screen) and contains two lines of text.
9 – EDITOR
Analyzer Command
Determines the editor that is selected by the EDIT command. This
allows you to edit the source file displayed by the current PLOT
or TABULATE command.
Format
SET EDITOR [command-line]
9.1 – Parameters
command-line
The optional command line is only used with LSEDIT and VAXTPU,
and is passed to the respective callable editor with each
subsequent EDIT command. If you do not specify a command line, a
default of LSEDIT or TPU will be assumed. The command line should
consist of the DCL command line used to invoke the editor, except
that it should begin with LSEDIT or TPU instead of EDIT/LSEDIT or
EDIT/TPU.
9.2 – Description
The SET EDITOR command allows you to determine which editor will
be invoked, and how it will be invoked, when you issue the EDIT
command. These editors must be accessible from DCL level. If you
do not specify an editor with the SET EDITOR command, then the
EDIT command will invoke the Language Sensitive Editor.
9.3 – Qualifiers
9.3.1 /CALLABLE_EDT
/CALLABLE_EDT
/CALLABLE_LSEDIT
/CALLABLE_TPU
/CALLABLE_TECO
These qualifiers specify the callable editor that is invoked by
subsequent EDIT commands. If you do not specify a qualifier, then
the spawned command line is used to invoke the editor.
9.3.2 /START_POSITION
/START_POSITION
/NOSTART_POSITION
Specifies whether to pass the number of the source line to the
editor. /START_POSITION is appended to the command line that is
also passed to the editor with each subsequent EDIT command.
/NOSTART_POSITION is the default, unless spawned LSEDIT is
selected. In that case, /START_POSITION is the default.
9.4 – Examples
PCAA> SET EDITOR/CALLABLE_LSEDIT/START_POS "LSEDIT/READ_ONLY"
This command causes subsequent EDIT commands to invoke callable
LSEDIT with the default command line of LSEDIT/READ_ONLY. Also,
the /START_POSITION qualifier will be appended to the command
line, causing the editing session to start on the source line
that the Analyzer is currently pointing to.
10 – EVENT
Collector Command
Establishes the collection of event markers for a specified event
when specified program locations are executed.
Format
SET EVENT event-name nodespec [,nodespec...]
10.1 – Parameters
event-name
Specifies the name of an event for which event markers should
be recorded. The event name must consist of one or more letters,
digits, underscores, and dollar signs. It cannot begin with a
digit.
nodespec
Specifies a node specification. When this program location is
executed, an event marker for the event-name event is recorded in
the performance data file.
See HELP NODESPECS for more information on node specifications.
10.2 – Description
The SET EVENT command establishes the collection of event
markers for a specified event when you execute program
locations associated with that event. An event marker is a data
record written to the performance data file to mark that some
significant event has occurred during program execution. You
determine what events are significant and what names to assign to
those events.
Event markers segment the performance or coverage data so that
data can be associated with different phases or time periods
of program execution. The Analyzer uses event markers to filter
performance or coverage data so that only the data associated
with a certain event or time period is tallied in histograms and
tables. Each data point in the data file is associated with the
event name of the most recent event marker that precedes it in
the data file.
When you enter a SET EVENT command, you must specify the name
of the event you wish to define. You must also specify the node
specifications to associate with that event. The Collector places
a breakpoint on each such location and, when the breakpoint is
reached, writes an event marker for that event to the performance
data file.
If you enter the SET EVENT command before entering a SET DATAFILE
command, the Collector establishes a default data file. The
default data file has the same file name as your program's
executable image file and a file type of PCA.
You can use one event marker per program location. Multiple
program locations are allowed for each event name.
10.3 – Examples
PCAC> SET EVENT COMPUTE LINE OPENIN\%LINE 22
This command establishes the collection of an event marker for
event COMPUTE each time line 22 in routine OPENIN is executed.
11 – FILTER
Analyzer Command
Defines a new filter. Filters allow you to filter the data in
the performance data file so that only data points that satisfy
certain criteria are tallied by the PLOT and TABULATE commands.
Format
SET FILTER filter-name filter-spec [,filter-spec...]
11.1 – Parameters
filter-name
Specifies the name of the filter to define. The filter name can
be used on a later CANCEL FILTER command. The filter name can
consist of letters, digits, underscores, and dollar signs. It
cannot start with a digit. If a filter of the same name already
exists, the old filter is canceled before the new one is defined.
filter-spec
Specifies a filter restriction. Each filter restriction specifies
some criterion that a data point must satisfy. If a data point
satisfies any one restriction for a given filter, it passes the
whole filter.
The following are vector filter restrictions:
Vector Restriction Explanation
VLENGTH=number Filters the VLENGTH domain to show
only the Vector Length Register
values of a specified length.
VMASK=number Filters the VMASK domain to show the
Vector Mask Register values with the
specified number of cells enabled.
VOPCODE=vector-opcode Filters the vector instruction
opcode to include only the specified
opcodes. You must supply mnemonics
of the opcodes to be included in the
plot.
VOPERATIONS=n Restricts views based on the number
of actual operations that are
performed by vector instructions.
VREGISTER=vector-reg Filters the vector registers to show
only specific registers.
VSTRIDE=number Filters the vector stride length
values to include only the specified
values.
11.2 – Description
The SET FILTER command creates a new filter definition. When a
subsequent PLOT or TABULATE command is entered, the restrictions
specified in the filter definition are applied to all data points
in the performance data file. A data point passes a filter if it
satisfies any one filter restriction in the filter. Only those
data points that pass all defined filters are tallied in the
histogram or table.
By using multiple restrictions in a single filter, you OR the
restrictions; if a data point passes any one restriction,
it passes the filter. By using multiple filters, you AND
restrictions; a data point must pass all defined filters to be
tallied in a histogram or table.
Filter restrictions that do not apply to a given data point are
ignored. A file name restriction, for example, is ignored for
page fault data because no file name is collected for a page
fault data point.
All the qualifiers listed defined below are positional. That is,
if you place a given qualifier after "SET FILTER" but before the
first parameter, then the qualifier affects the entire command.
If you place the qualifier after a filter specification, then the
qualifier affects only that filter specification.
If you specify /MAIN_IMAGE=prog-unit, /STACK_DEPTH=n and
/CUMULATIVE=n, they are applied in the following order: /MAIN_
IMAGE, /STACK_DEPTH, then /CUMULATIVE. Therefore, if you specify
the /MAIN_IMAGE=prog-unit and /STACK_DEPTH=n qualifiers, the
Analyzer will search for the first stack PC value within the
specified program unit. However, it will not use the data
point in this address, but in the address n call frames on the
stack from the main image address, when checking address filter
restrictions. If you include /CUMULATIVE on that command, the
same action occurs, but the Analyzer also uses the PC values in
all the call frames below that (or in the first n call frames
down if /CUM=n).
11.3 – Qualifiers
11.3.1 /MAIN_IMAGE
/MAIN_IMAGE[=n:m]
/MAIN_IMAGE[=prog-unit]
Uses the first stack PC value that falls in the given address
range when checking address filter restrictions. By default, uses
the first stack PC value that falls in the main image.
11.3.2 /NOMAIN_IMAGE
Uses the first PC value when checking address filter
restrictions.
11.3.3 /STACK_DEPTH
/STACK_DEPTH=n
Uses the stack PC value that falls n call frames below the first
stack PC value when checking address filter restrictions.
11.3.4 /NOSTACK_DEPTH
Does not perform stack-depth analysis.
11.3.5 /CUMULATIVE
/CUMULATIVE[=n]
Lets a data point pass a filter restriction if any one stack
PC value for that data point passes the restriction. If n is
specified, then let the data point pass only if the PC value is
within n call frames from the start.
11.3.6 /NOCUMULATIVE
Lets a data point pass an address filter restriction only if the
first stack PC value passes the restriction.
To use the /MAIN_IMAGE, /STACK_DEPTH and /CUMULATIVE qualifiers,
you must first gather stack PC values using the Collector SET
STACK_PCS command.
11.3.7 /CREATOR_PC
Lets a data point pass a filter restriction only if it is
associated with the program address that created the task.
Overrides /MAIN_IMAGE, /STACK_DEPTH and /CUMULATIVE, and can
only be used with the program address filter specification.
11.3.8 /NOCREATOR_PC
Do not use the PC value associated with the creation of the task.
11.3.9 /PARENT_TASK
Lets a data point pass a filter restriction only if it is
associated with the parent task's characteristics. Can only be
used with the TASK and TASK_TYPE filter specifications.
11.3.10 /NOPARENT_TASK
Use the current task characteristics.
11.4 – Examples
PCAA> SET FILTER F1 RUN=1
PCAA> PLOT PROGRAM BY ROUTINE
The SET FILTER command defines a filter named F1. When the PLOT
command is executed, only data from collection run 1 is tallied
in the histogram.
PCAA> SET FILTER FUMBLE PROGRAM_ADDRESS=FRATZ
PCAA> PLOT/COUNTERS/CUMULATIVE PROGRAM BY ROUTINE
The SET FILTER command defines filter FUMBLE. To pass this
filter, the program address value of a data point must fall
in the address range of routine FRATZ. The PLOT command plots
the number of times each routine in the program calls routine
FRATZ, directly or indirectly by way of other routines.
PCAA> SET FILTER F1 RUN=3:5, RUN=8
PCAA> SET FILTER F2 TIME=COMPUTE
PCAA> SET FILTER F3 IO_SERVICE=SYS$PUT, IO_SERVICE=SYS$GET
PCAA> TABULATE/IO_SERVICES MODULE FRATZ BY LINE
The SET FILTER commands define filters F1, F2, and F3. To pass
filter F1, a data point must come from collection run 3, 4,
5, or 8. To pass filter F2, a data point must be collected
after a COMPUTE event marker and before any other event. To
pass filter F3, an I/O data point must represent a SYS$PUT
or SYS$GET system service call. To be tallied in the table
produced by the TABULATE command, an I/O data point must pass
all three filters. (Had non-I/O data been tabulated, the data
points would need to pass only filters F1 and F2 because the
IO_SERVICE restriction is not applicable to non-I/O data.)
PCAA> SET FILTER VLEN1 VLENGTH=0, VLENGTH=32, VLENGTH=64
PCAA> PLOT VLENGTH BY ELEMENT
The SET FILTER command defines a filter named VLEN1. When the
PLOT command is executed, the report view is based on the
Vector Length Register (VLR). It only shows the VLR lengths
that are of a specified value. This is useful is a certain
operation is known to work optimally when given vectors of a
given length.
PCAA> SET FILTER VLEN1 VLEN=0:7
PCAA> PLOT PROGRAM BY ROUTINE
This shows locations in the program where the use of vector
instructions is not efficient, indicating that scalar
instructions would be more appropriate.
12 – IO_SERVICES
Collector Command
Enables the collection of I/O services data. Data is collected
for each I/O system service call in the program.
Format
SET IO_SERVICES
12.1 – Description
The SET IO_SERVICES command enables the collection of I/O system
services data. After you enter the GO command with I/O data
collection enabled, the Collector intercepts every I/O system
service call during program execution. For each such call,
the Collector gathers the appropriate information from the
File Access Block (FAB), Record Access Block (RAB), or other
parameters and records it in the performance data file. The exact
information gathered depends on the I/O service, but will include
the program address of the call, the name of the service, the CPU
time stamp. It may also include the name of the file accessed,
the record size of the transfer, the physical I/O read and write
counts, and other information.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or
TABULATE command in the Analyzer.
12.2 – Qualifiers
12.2.1 /STACK_PCS
Specifies that stack PC values are collected for I/O services
data. This is the default upon entry into the Collector.
12.2.2 /NOSTACK_PCS
Specifies that no stack PC values are collected for I/O services
data.
12.2.3 /USER_ROUTINE
/USER_ROUTINE=(image-name,entry-routine,exit-routine)
/USER_ROUTINE=(image-name,entry-routine,)
/USER_ROUTINE=(image-name,,exit-routine)
Specifies that the specifed user routines shall be called at the
start and end of each system service call.
Qualifier Parameter Description
image-name The shareable image containing the
entry-routine or/and exit-routine.
entry-routine The routine to call before calling
the system service. The null string
(i.e. "") indicates no routine is to
be called.
exit-routine The routine to call after calling the
system service. The null string (i.e.
"") indicates no routine is to be
called.
The following rule applies regarding the /USER_ROUTINE qualifier:
1. Only one of the entry and exit routines may be null;
For more information on user routines in PCA, see the HELP entry
for User_Routines.
12.2.4 /NOUSER_ROUTINE
/NOUSER_ROUTINE
Specifies that no user routines shall be called at the start and
end of each system service call. This is the default upon entry
into the PCA Collector.
12.3 – Examples
PCAC> SET IO_SERVICES/STACK_PCS
This command enables the collection of I/O services data, and
specifies that stack PC values be collected.
13 – KEY
PCA Command
Changes the current key definition state. Key definition states
are used by keypad keys defined with the DEFINE/KEY command.
Format
SET KEY
13.1 – Description
When you define keypad keys using the DEFINE/KEY command, you
can assign a specific state name to each key definition. The
PCA-defined state names are DEFAULT, GOLD, BLUE, CONTRACT,
EXPAND, and MOVE. If the assigned state is not set when you
press the key, the command string to which the key is bound is
not processed. You use the SET KEY command to change the current
state so that keys for the specified state are processed.
If you do not use the SET KEY command, the current keypad state
is DEFAULT.
13.2 – Qualifiers
13.2.1 /LOG
/LOG
/NOLOG
Controls whether a log message is displayed indicating that the
key state has been set. The default is /LOG.
13.2.2 /STATE
/STATE=state-name
/NOSTATE
Specifies the keypad state to be set. The state name can be any
alphanumeric string. If you omit the /STATE qualifier or use
/NOSTATE, the current state is left unchanged. The default state
is DEFAULT.
13.3 – Examples
PCAC> SET KEY/STATE=BLUE
The SET KEY command sets the current state to BLUE. After
entering this command, when you press a keypad key with a BLUE
definition, that definition is executed even if you do not
press the PF4 key first. (The PF4 key is the PCA-defined BLUE
key.)
14 – LANGUAGE
PCA Command
Establishes the current language setting. The current language
setting determines how symbol names are parsed.
Format
SET LANGUAGE language-name
14.1 – Parameters
language-name
Specifies the name of the language to be set. The valid language
names are Ada, (Ada is a registered trademark of the U.S.
government, Ada Joint Program Office.), BASIC, BLISS, C, C_PLUS_
PLUS, COBOL, DIBOL, FORTRAN, MACRO, Pascal, PLI, RPG, SCAN, and
UNKNOWN.
14.2 – Description
The language setting determines how PCA parses symbol names in
command input. If the language is set to C/C++, PCA treats symbol
names as case-sensitive. Upper-case and lower-case letters are
then treated as different characters. If the language is set to
anything other than C/C++, symbol names are assumed to be case
insensitive, and lowercase letters are treated as if they were
uppercase letters.
When you use the SET DATAFILE command, the language setting is
determined by the language of the main routine in the program.
Normally, you need not change this setting. However, if you have
a mixed-language program which includes C/C++ modules, you may
have to change the language setting before you can reference
symbols that include lowercase letters.
14.3 – Examples
PCAC> SET LANGUAGE PASCAL
This command changes the language setting to Pascal. Symbol
names are then parsed by Pascal rules. (Pascal is case
insensitive.)
15 – LOG
PCA Command
Specifies that user input and PCA output be recorded in a log
file.
Format
SET LOG [file-spec]
15.1 – Parameters
file-spec
Specifies the log file to create. All subsequent PCA input and
output is recorded in this file until logging is disabled. File-
spec is any valid OpenVMS file specification. The default file
type is LOG. An omitted file-spec defaults to PCAC.LOG when you
are in the Collector, or PCAA.LOG when you are in the Analyzer.
15.2 – Description
The SET LOG command records all PCA input and output in the
specified log file. Input is recorded as entered. Output is
recorded with a leading exclamation point (!). Since the
exclamation point is the PCA comment character, you can rerun the
logged PCA session by using the log file as a command procedure.
15.3 – Examples
PCAC> SET LOG [PING]PONG
This command establishes the file [PING]PONG.LOG as the
Collector log file. All subsequent commands and their output
are recorded in this file.
16 – MAX_SOURCE_FILES
PCA Command
Specifies the maximum number of source files that PCA can keep
open at any one time.
Format
SET MAX_SOURCE_FILES n
16.1 – Parameters
n
Specifies the maximum number of source files that PCA can keep
open at any one time. The value of n cannot exceed 20. The
default value is 10.
16.2 – Description
The SET MAX_SOURCE_FILES command specifies the number of source
files that PCA can have open at one time. Opening a source file
requires the use of an I/O channel, which is a limited system
resource. Using the SET MAX_SOURCE_FILES command, you can specify
how many I/O channels PCA can use to read source files. If PCA
reaches this limit, it must close one source file before it can
open and read another one. In such cases, source display still
works, but at some performance cost.
By default, PCA keeps up to ten source files open at any one
time. Normally there is no need to change this value.
16.3 – Examples
PCAA> SET MAX_SOURCE_FILES 20
This command sets the number of source files PCA can keep open
at one time to 20.
17 – MODE
PCA Command
Establishes or cancels various mode settings that affect screen
mode.
Format
SET MODE keyword [,keywod]
17.1 – Parameters
keyword
Specifies the mode settings to be enabled or disabled. Following
are the valid keyword parameters:
Keyword Description
KEYPAD Enables the use of the numeric keypad for
command entry. When PCA is in keypad mode,
you can associate keys on the numeric keypad
with PCA command definitions. Keypad mode is
enabled by default.
NOKEYPAD Disables the use of the numeric keypad for
command entry. You must disable keypad mode
when the program you are measuring requires
the numeric keypad on your terminal to be in
numeric mode.
LOG_SCREEN Causes screen images to be logged in the
log file each time the terminal screen is
updated. Screen logging occurs only if output
logging in general is enabled with the SET LOG
command.
NOLOG_SCREEN Disables the logging of screen images. NOLOG_
SCREEN is the default mode.
MOVIE Causes the terminal screen to be updated each
time a command line is read, even if the line
comes from a command file. In movie mode, you
can "play" a command file on the screen.
NOMOVIE Causes the terminal screen to be updated only
after each line of terminal input. NOMOVIE is
the default mode.
SCREEN Enables screen mode so that you see PCA output
in the form of screen displays viewed through
windows on the terminal screen. Screen mode
should be used only on VT100 or VT200 class
terminals.
NOSCREEN Disables screen mode. PCA output is then
displayed line by line. NOSCREEN is the
default mode.
SCROLL Causes the screen to be updated for every line
of output in screen mode. Thus, the output
scrolls through the output window. SCROLL is
the default mode.
NOSCROLL Causes the screen to be updated only after a
full command has completed. As a result, you
may see only the last part of the command's
output in its screen window.
17.2 – Description
The SET MODE command sets or cancels screen mode and various
submodes within screen mode. Keypad mode is enabled by default.
You must disable keypad mode only if your program requires the
use of the numeric keypad for its own purposes.
17.3 – Examples
PCAA> SET MODE SCREEN
This command enables screen mode.
PCAA> SET MODE NOSCREEN
This command disables screen mode.
PCAA> SET MODE SCREEN, LOG_SCREEN
This command enables both screen mode and the logging of screen
images in the log file. Screen images are logged only if output
logging in general is enabled with the SET LOG command.
18 – NOTE
Collector Command
Stores an informative note about the current collection run in
the PCA data file.
Format
SET NOTE "quoted-string"
18.1 – Description
The SET NOTE command allows you to describe the current
collection run in a quoted string following standard PCA rules
for quoted strings. This description is stored in the PCA
data file. You can retrieve the note by entering the SHOW RUN_
DESCRIPTION command in the PCA Analyzer or the SHOW NOTE command
in the PCA Collector.
18.2 – Examples
PCAC> SET NOTE "G-FLAT"
This command describes the current collection run and stores
the quoted string in the PCA data file.
19 – PAGE_FAULTS
Collector Command
Enables the collection of page fault data.
Format
SET PAGE_FAULTS
19.1 – Description
The SET PAGE_FAULTS command enables the collection of page
fault data. After you enter the GO command with page fault data
collection enabled, the Collector records in the performance data
file every page fault that occurs during program execution. The
Collector records the program counter value, the faulting virtual
address, and a CPU time stamp for each page fault. You cannot
collect stack PC values with page fault data.
19.2 – Examples
PCAC> SET PAGE_FAULTS
This command enables the collection of page fault data.
20 – PC_SAMPLING
Collector Command
Enables the collection of program counter sampling data.
Format
SET PC_SAMPLING
20.1 – Description
The SET PC_SAMPLING command enables the collection of program
counter sampling data. After you enter the GO command with
program counter sampling enabled, the Collector samples the
program counter (PC) every 10 milliseconds and records each
observed program counter value in the performance data file. You
can change the sampling interval with the /INTERVAL:n qualifier.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or
TABULATE command in the Analyzer.
20.2 – Qualifiers
20.2.1 /INTERVAL
/INTERVAL:n
Specifies the sampling interval in milliseconds. The value of n
must be at least 10 milliseconds and at most 60,000 milliseconds.
Because the granularity of the system clock is 10 milliseconds,
you should use a multiple of 10. The default sampling interval is
10 milliseconds; therefore, you can use the /INTERVAL:n qualifier
only to specify a slower sampling rate.
20.2.2 /STACK_PCS
Specifies that stack PC values are collected for PC sampling
data. This is the default upon entry into the Collector.
20.2.3 /NOSTACK_PCS
Specifies that no stack PC values are collected for PC sampling
data.
20.3 – Examples
PCAC> SET PC_SAMPLING/STACK_PCS
This command enables the collection of program counter sampling
data, and specifies that stack PC values are collected for this
measurement.
21 – PLOT
Analyzer Command
Establishes default qualifiers and node specifications for the
PLOT and TABULATE commands.
Format
SET PLOT [nodespec [,nodespec...]]
21.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.
21.2 – Qualifiers
21.2.1 /qualifiers
The SET PLOT command accepts the same qualifiers as the PLOT and
TABULATE commands. See HELP PLOT for the qualifier descriptions.
21.3 – Description
The SET PLOT command sets the default qualifiers and node
specifications used by the PLOT and TABULATE commands. Qualifiers
explicitly specified on the PLOT or TABULATE command override the
current defaults.
21.4 – Examples
PCAA> SET PLOT/SOURCE/DESCENDING/NOZEROS
After this SET PLOT command is entered, all subsequent PLOT and
TABULATE commands use the /SOURCE, /DESCENDING, and /NOZEROS
qualifiers unless these qualifiers are explicitly overridden.
22 – PROMPT
PCA Command
Changes the PCA prompt string from PCAC> or PCAA> to a string of
your choice.
Format
SET PROMPT string
22.1 – Parameters
string
Specifies the string which is to become the new prompt. If the
string contains blanks, semicolons, or lowercase characters, then
it must be enclosed in quotation marks.
22.2 – Examples
PCAC> SET PROMPT MYNAME>
MYNAME>
The above command will change the prompt to MYNAME>.
23 – RUN_NAME
Collector Command
Establishes the name of the current collection run.
Format
SET RUN_NAME run-name
23.1 – Parameters
run-name
Specifies the name of the current collection run. If the run-name
parameter begins with a digit or contains any characters other
than letters, digits, underscores, or dollar signs, enclose it in
quotation marks.
23.2 – Description
The SET RUN_NAME command establishes a name for the current
collection run. When you enter the GO command, this name is
recorded in the performance data file. If you do not enter a
SET RUN_NAME command, the null run-name (the name with zero
characters) is recorded. You can use the collection run name
to filter performance or coverage data in the Analyzer.
23.3 – Examples
PCAC> SET RUN_NAME PC_SAMPLE_RUN
This command specifies that the collection run name is PC_
SAMPLE_RUN. This run name is recorded in the performance data
file when you enter the GO command.
24 – SEARCH
PCA Command
Sets/resets the SEARCH command's default qualifiers. Establishes
current qualifiers and/or parameters to be used by PCA in the
absence of SEARCH command qualifiers.
Format
SET SEARCH [parameter,...]
24.1 – Parameters
ALL NEXT IDENTIFIER STRING
See qualifier description list.
24.2 – Description
The SET SEARCH command allows you to set the SEARCH command's
default qualifiers. If you provide two parameters or qualifiers
that have contradictory actions (such as ALL and NEXT), then the
latter parameter or qualifier in the sequence is accepted. If
you provide a qualifier and a parameter that have contradictory
meanings (such as /ALL and NEXT), then the parameter takes
precedence. Each of the qualifiers may be expressed as a
parameter.
24.3 – Qualifiers
24.3.1 /ALL
Makes /ALL the default SEARCH qualifier.
24.3.2 /NEXT
Makes /NEXT the default SEARCH qualifier.
24.3.3 /IDENTIFIER
Makes /IDENTIFIER the default SEARCH qualifier.
24.3.4 /STRING
Makes /STRING the default SEARCH qualifier.
24.4 – Examples
PCAC> SET SEARCH IDENTIFIER
PCAC> SHOW SEARCH
Default search qualifiers: /NEXT /IDENTIFIER
This command sets the default SEARCH qualifier as /IDENTIFIER.
25 – SERVICES
Collector Command
Enables the collection of system services data. Data is collected
for each system service call in the program.
Format
SET SERVICES
25.1 – Description
The SET SERVICES command enables the collection of system
services data. After you enter the GO command with system
services data collection enabled, the Collector intercepts every
system service call in the user program and records it in the
performance data file. For each call, the Collector records the
name of the system service, the program location where it was
called, and a CPU time stamp.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or
TABULATE command in the Analyzer.
25.2 – Qualifiers
25.2.1 /STACK_PCS
Specifies that stack PC values are collected for system services
data. This is the default upon entry into the Collector.
25.2.2 /NOSTACK_PCS
Specifies that no stack PC values are collected for system
services data.
25.2.3 /USER_ROUTINE
/USER_ROUTINE=(image-name,entry-routine,exit-routine)
/USER_ROUTINE=(image-name,entry-routine,)
/USER_ROUTINE=(image-name,,exit-routine)
Specifies that the specifed user routines shall be called at the
start and end of each system service call.
Qualifier Parameter Description
image-name The shareable image containing the
entry-routine or/and exit-routine.
entry-routine The routine to call before calling
the system service. The null string
(i.e. "") indicates no routine is to
be called.
exit-routine The routine to call after calling the
system service. The null string (i.e.
"") indicates no routine is to be
called.
The following rule applies regarding the /USER_ROUTINE qualifier:
1. Only one of the entry and exit routines may be null;
For more information on user routines in PCA, see the HELP entry
for User_Routines.
25.2.4 /NOUSER_ROUTINE
/NOUSER_ROUTINE
Specifies that no user routines shall be called at the start and
end of each system service call. This is the default upon entry
into the PCA Collector.
25.3 – Examples
PCAC> SET SERVICES/NOSTACK_PCS
This command specifies the collection of system services data,
and disables the collection of stack PC values.
26 – SOURCE
PCA Command
Directs PCA to a specified list of directories for source files
when source text must be displayed.
Format
SET SOURCE dirname [,dirname...]
26.1 – Parameters
dirname
Specifies a directory to search. If multiple dirname parameters
are specified, the specified directories are searched for source
files in that order. You may specify a OpenVMS logical name for a
dirname.
Note that dirname may consist of one, several, or all the fields
in a full file specification, though it typically consists only
of a directory name. A full file specification has the following
format:
node::device:[directory]file-name.file-type;version-number
When specifying any of these fields, you must include the
punctuation for that field as shown in this format.
26.2 – Description
The SET SOURCE command directs PCA to a specified list of
directories for source files when source text must be displayed.
By default, PCA expects a source file to be in the same location
it was in when it was compiled; that is, in the same directory
and in the same exact file. If that file has been moved to
another location, you must use the SET SOURCE command to specify
that location. Note that you must also establish a directory
search list with the SET SOURCE command if you wish to view
source files in a source window when in screen mode.
26.3 – Qualifiers
26.3.1 /EDIT
Specifies that the indicated directory search list is to be used
in locating source files for the Analyzer EDIT command.
26.3.2 /MODULE
/MODULE=modname
Specifies that the indicated directory search list is to be used
in locating source files for the specified module. Other modules
do not use this search list.
26.4 – Examples
PCAC> SET SOURCE [PROJA], [PROJB], DISK:[PETER.PAN]
This command tells the Collector to locate all source files by
searching directories [PROJA], [PROJB], and DISK:[PETER.PAN],
in that order.
PCAC> SET SOURCE/MODULE=NICK [TSAKERES]
This command tells the Collector to search directory [TSAKERES]
when accessing source files for module NICK.
27 – STACK_PCS
Collector Command
Enables the collection of stack PC values (return addresses from
the call stack) when data is gathered.
Format
SET STACK_PCS
27.1 – Description
The SET STACK_PCS command enables the collection stack PC values
for program counter sampling data, CPU sampling data, system
services data, I/O services data, exact execution count data,
and test coverage data. The stack PC values for a data point
consist of the program counter value and all call stack return
addresses for that data point. In addition, you can collect or
not collect stack PC values for these data kinds by using the
/STACK_PCS or /NOSTACK_PCS qualifiers. See the Command Dictionary
description for each of the previously mentioned data kinds for
more information.
If you collect stack PC values in the Collector, the Analyzer is
able to charge back the resources consumed in shareable images
(such as the Run-Time Library) to the code in your program that
calls the shareable images. To use the stack PC information, use
the /MAIN_IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the
PLOT or TABULATE command in the Analyzer.
27.2 – Examples
PCAC> SET STACK_PCS
This command enables the collection of stack PC values.
28 – TASKING
Collector Command
Instructs the Collector to gather tasking information. The
Analyzer can then associate the gathered data with the task that
caused that data to be gathered.
Format
SET TASKING
28.1 – Description
The SET TASKING command instructs the Collector to gather tasking
information. The Analyzer can then associate the gathered data
with the task that caused that data to be gathered. Any data kind
may be plotted against the TASK domain. This allows you to plot
the amount of time or other resource used in various tasks.
To get the Analyzer to report on data by task, specify the SET
TASKING command in the Collector, then specify the appropriate
domain in the Analyzer by providing that domain's node
specification on a PLOT or TABULATE command.
28.2 – Examples
PCAC> SET TASKING
This command causes tasking data to be collected on all tasks
that are defined in the data file.
29 – TERMINAL
PCA Command
Changes the terminal width and page size that PCA uses to format
output.
Format
SET TERMINAL
29.1 – Description
The SET TERMINAL command sets the terminal width or page size
that PCA uses to format output. It does not reset the terminal
itself, however; you must do that manually. If you are in screen
mode, the screen is refreshed.
The default terminal width and page size are determined by your
device type or by the last SET TERMINAL command you entered at
DCL level.
29.2 – Qualifiers
29.2.1 /PAGE
/PAGE:n
Specifies that the terminal page size (the number of lines per
page) should be set to n lines. Normally n is 24, but you may use
any value from 11 to 100.
29.2.2 /WIDTH
/WIDTH:n
Specifies that the terminal width should be set to n columns or
spaces. Typically n is 80 or 132, but you may use any value from
40 to 255.
29.3 – Examples
PCAA> SET TERMINAL/WIDTH:132
This command specifies that the terminal width is 132 columns.
30 – TITLE
Analyzer Command
Specifies the text of the title lines on each page of PLOT and
TABULATE output.
Format
SET TITLE "title-text" [,"title-text"...]
30.1 – Parameters
title-text
Specifies the text of one title line. The text must be enclosed
in quotation marks, and cannot be longer than the current
terminal width. In a list of title-text parameters, the first
title-text parameter specifies the text for the first title line,
the second parameter specifies the text for the second title
line, and so on. If you use the /LINE=n qualifier, the first
title-text parameter specifies the text for line n, the second
parameter specifies the text for line n+1, and so forth. You can
specify up to six lines of title text.
30.2 – Description
The SET TITLE command establishes up to six lines of title text
to be displayed on each page of output from PLOT, TABULATE and
related commands. The new title does not take effect until you
enter another PLOT or TABULATE command (it does not affect the
current plot or table). Each title line is centered within the
current terminal width. After centering, the rightmost 10 columns
of the first title line are overlaid with the page number. To
prevent truncation, the first title line should thus be limited
to the current terminal width minus 20 characters of text.
If you have established a multiline title, you can change
individual lines within that title by using the /LINE=n
qualifier. If /LINE=n is not used, the new title completely
replaces all of the previous title lines.
If you do not issue a SET TITLE command, "Performance and
Coverage Analyzer for OpenVMS" is shown on the first title line.
30.3 – Qualifiers
30.3.1 /LINE
/LINE=n
Specifies that the first title-text parameter should go in line
n of the title, that the second title-text parameter should go
in line n+1 of the title, and so on. This qualifier is used
to selectively replace certain lines of an already established
title.
30.4 – Examples
PCAA> SET TITLE "Welcome to Wonderland", "Enjoy your visit"
This command establishes the specified two-line title for the
output of subsequent PLOT and TABULATE commands.
PCAA> SET TITLE/LINE=2 'Come Again, Good Day', 'Area "END"'
This command replaces line 2 of the title established in
Example 1 and adds a third line. The resulting three-line title
is displayed on the output of subsequent PLOT and TABULATE
commands.
31 – UNALIGNED
Collector Command
Enables the collection of unaligned access fault data.
Format
SET UNALIGNED
31.1 – Description
The SET UNALIGNED command enables the collection of unaligned
access fault data. After you enter the GO command with unaligned
access fault data collection enabled, the Collector records in
the performance data file every unaligned access fault that
occurs during program execution. The Collector records the
faulting virtual address and program location where it occured.
You must collect stack PC information if you want to use a /MAIN_
IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or
TABULATE command in the Analyzer.
31.2 – Qualifiers
31.2.1 /STACK_PCS
Specifies that stack PC values are collected for unaligned access
fault data. This is the default upon entry into the Collector.
31.2.2 /NOSTACK_PCS
Specifies that no stack PC values are collected for unaligned
access fault data.
31.3 – Examples
PCAC> SET UNALIGNED
This command enables the collection of unaligned access fault
data.
32 – VCOUNTERS
Collector Command
Establishes the collection of vector processor instruction counts
at specified program locations.
Format
SET VCOUNTERS [nodespec [,nodepsec...]]
32.1 – Parameters
nodespec
Specifies a set of restricted program locations that gatehr
vector processor instruction counts within the specified range.
32.2 – Description
The SET VCOUNTERS Collector command enables the counting of
vector processor instructions. The collected data can help you
determine to what extent the vector processor is being used. You
must specify at least one node specification on the command line
to indicate the domain of the data to be collected.
The following node specifications are used when collecting vector
instruction counts:
o PROGRAM ADDRESS by VINSTRUCTION
o MODULE module-name by VINSTRUCTION
o ROUTINE routine-name by VINSTRUCTION
32.3 – Qualifiers
32.3.1 /STACK_PCS
Specifies that stack PC values for counter data are to be
collected. If you use /STACK_PCS, further SET VCOUNTERS requests
assume a default of /STACK_PCS.
32.3.2 /NOSTACK_PCS
Specifies that no stack PC values for counter data are to be
collected. This is the default setting upon entry into the
Collector.
33 – VCPU_SAMPLING
Collector Command
Enables the collection of vector program counter sampling data
that occurs during virtual process or CPU time.
Format
SET VCPU_SAMPLING
33.1 – Description
The SET VCPU_SAMPLING Collector command enables the collection
of PC values for random vector instructions. The collected data
lets you determine the scalar/vector parallelism throughout your
entire program.
When you collect vector CPU samples, the sampling interval timer
includes only the time that the program is actually running
the processor. This form of sampling allows you to focus on the
particular areas of the program's algorithm where time is being
spent, and not on the areas where outside influences consume
time.
33.2 – Qualifiers
33.2.1 /INTERVAL
Specifies the sampling interval in milliseconds. The value of n
must be at least 10 milliseconds and at most 60,000 milliseconds.
Because the granularity of the system clock is 10 milliseconds,
use a multiple of 10. The default sampling interval is 10
milliseconds; therefore, you can use the /INTERVAL:n qualifier
only to specify a longer sampling interval.
33.2.2 /STACK_PCS
Specifies that stack PC values for vector CPU data are to be
collected. The /STACK_PCS qualifier is the default upon entry
into the Collector.
33.2.3 /NOSTACK_PCS
Specifies that not stack PC values for vector CPU data are to be
collected. If used, /NOSTACK_PCS causes further SET VCPU_SAMPLING
requests to assume a default of /NOSTACK_PCS.
33.3 – Examples
PCAC> SET VCPU_SAMPLING/INTERVAL:20/NOSTACK_PCS
This command causes the interval to be 20 milliseconds, and
disables STACK_PCS collection for this measurement. For all
further SET VCPU_SAMPLING requests, a default of /NOSTACK_PCS
will be assumed.
34 – VERIFY
PCA Command
Causes PCA to verify command input by echoing it to the terminal.
Format
SET VERIFY
34.1 – Description
The SET VERIFY command causes PCA to echo subsequent command
input to the terminal. Input verification is useful when you
want to see the commands from command procedures as they are
executed. You can disable input verification with the CANCEL
VERIFY command.
34.2 – Examples
PCAC> SET VERIFY
PCAC> @X.COM
@X.COM
SET DATAFILE [SAGER.TST]PCAPRIME
SET LANGUAGE C
PCAC>
The SET VERIFY command enables input verification. The next
command entered (@X.COM) is therefore echoed to the terminal.
Then a SET DATAFILE and a SET LANGUAGE command are read from
the command procedure X.COM. Both commands are echoed to the
terminal.
35 – VPC_SAMPLING
Collector Command
Enables the collection of vector program counter sampling data.
Format
SET VPC_SAMPLING
35.1 – Description
The SET VPC_SAMPLING Collector command enables the collection of
PC values for random vector instructions and causes the sampling
rate to be applied to the wall clock. The collected data lets you
determine the scalar/vector parallelism throughout your entire
program.
When you collect vector PC samples, the sampling interval timer
includes all idle time associated with the current run of the
program. This form of sampling shows you where the time is being
spent in the program with little cost to the time of actually
running the program. time. You can set the time interval by using
the /INTERVAL qualifier.
35.2 – Qualifiers
35.2.1 /INTERVAL
/INTERVAL:n
Specifies the sampling interval in milliseconds. The value of
n must be at the least 10 milliseconds and at the most 60,000
milliseconds. Because the granularity of the system clock is 10
milliseconds, use a multiple of 10. The default sampling interval
is 10 milliseconds; therefore, you can use the /INTERVAL:n
qualifier only to specify a longer sampling interval.
35.2.2 /STACK_PCS
Specifies that stack PC values for vector PC data are to be
collected. The /STACK_PCS qualifier is the default upon entry
into the Collector.
35.2.3 /NOSTACK_PCS
Specifies that stack PC values for vector PC data are not to be
collected. If you specify /NOSTACK_PCS, further SET VPC_SAMPLING
requests assume a default of /NOSTACK_PCS.
35.3 – Examples
PCAC> SET VPC_SAMPLING/INTERVAL:20/NOSTACK_PCS
This command causes the interval to be 20 milliseconds, and
disables STACK_PCS collection for this measurement. For all
further SET VPC_SAMPLING requests, a default of /NOSTACK_PCS
will be assumed.
36 – WINDOW
PCA Command
Defines screen window names.
Format
SET WINDOW window-name AT
(start-line,line-count,start-column,column-count)
36.1 – Parameters
window-name
Specifies the name of the window to define. The window name must
consist of letters, digits, underscores, and dollar signs. It
cannot begin with a digit.
start-line
Specifies the starting line number of the window. This line
displays the top header line for the screen display using the
window. The top line of the screen is line number 1.
line-count
Specifies the number of text lines in the window.
start-column
Specifies the starting (leftmost) column number of the window
(the default is column 1).
column-count
Specifies the number of columns in the window (the default is the
current screen width).
36.2 – Description
The SET WINDOW command allows you to assign a name to a screen
window. A screen window is a region on the terminal screen
through which you can view a display. You must specify the
window in terms of a starting line number on the screen and a
line count. Once defined, a window name can be used in subsequent
DISPLAY and SET DISPLAY commands.
PCA provides a substantial number of predefined window names. You
can list all defined window names using the SHOW WINDOW command.
36.3 – Examples
PCAA> SET WINDOW TINY AT (1,2)
PCAA> DISPLAY OUT AT TINY
The first command defines a window named TINY. The top border
line for the window is at line 1 of the terminal screen. The
window can display two additional lines of text. The second
command displays the OUT screen display through window TINY.