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.