Node specifications (nodespecs) specify code locations, and
are passed as parameters to Collector and Analyzer commands.
Nodespecs allow you to specify individual locations (e.g., a
line, or codepath), or a class of locations (e.g., all routines
in the program).
1 – Collector Nodespecs
In the Collector, the SET COUNTERS and SET COVERAGE commands
require one or more nodespecs to specify the program locations at
which to collect execution counts or coverage data. The following
example specifies an execution counter on every routine in the
entire program. Notice that it has two clauses. The first clause
(PROGRAM_ADDRESS) specifies the range, and the second clause (BY
ROUTINE) specifies the unit.
PCAC> SET COUNTERS PROGRAM_ADDRESS BY ROUTINE
In the Collector, only nodespecs in the program address domain,
specifying routines, codepaths, or lines, can be used. See
Program_Address_Domain in this HELP entry for valid forms of
the nodespecs.
2 – Analyzer Nodespecs
In the Analyzer, nodespecs are required on PLOT and TABULATE
commands to define how to partition the histogram or table
into buckets. Depending on the partitioning you specify, the
Analyzer selects a data domain and partitions it into value
ranges (buckets).
The buckets are then displayed along the vertical axis of the
histogram. The Analyzer accepts a wider range of nodespecs than
the Collector does because Analyzer nodespecs can cover domains
other than the program address domain.
The following nodespec specifies a set of buckets. It consists
of an address range specification, followed by a BY clause. The
result is a plot which shows one histogram bar for each routine
in module M1.
PCAC> PLOT MODULE M1 BY ROUTINE
See Program_Address_Domain and Non-Program_Address_Domains in
this HELP entry for nodespecs that are valid in the Analyzer.
3 – Program Address Domain
LINE [pathname\] %LINE n
LINE [pathname\] %LINE n BY [n] BYTES
LINE [pathname\] %LINE n BY CODEPATH
MODULE pathname MODULE pathname BY ROUTINE
MODULE pathname BY [n] LINES MODULE pathname BY CODEPATH
MODULE pathname BY [n] BYTES MODULE pathname BY VINSTRUCTION
PROGRAM_ADDRESS BY MODULE PROGRAM_ADDRESS BY ROUTINE
PROGRAM_ADDRESS BY [n] LINES PROGRAM_ADDRESS BY CODEPATH
PROGRAM_ADDRESS BY [n] BYTES PROGRAM ADDRESS BY VINSTRUCTION
ROUTINE pathname ROUTINE pathname BY ROUTINE
ROUTINE pathname BY [n] LINES ROUTINE pathname BY CODEPATH
ROUTINE pathname BY [n] BYTES ROUTINE pathname BY VINSTRUCTION
3.1 – Pathname
This is the BNF description of the PCA pathname syntax.
a-char ::==
'a' |
'A'
alpha-char ::==
'a' .. 'z' |
'A'..'Z'
b-char ::==
'b' |
'B'
digit-char ::==
'0' .. '9'
dot-char ::==
'.'
double-colon-char ::==
':'
double-quote-char ::==
'"'
e-char ::==
'e' |
'E'
i-char ::==
'i' |
'I'
l-char ::==
'l' |
'L'
m-char ::==
'm' |
'M'
n-char ::==
'n' |
'N'
percent-char ::==
'%'
single-quote-char ::==
'''
space-char ::==
space |
horizontal-tab
special-char ::==
'^' |
'~' |
'|' |
'#' |
'$' |
'-' |
'=' |
'&' |
'+' |
'<' |
'>' |
'*' |
'_'
zero-char ::==
'0'
operator-char ::==
space-char |
'[' |
']' |
',' |
'(' |
')' |
'/' |
'!' |
'\'
quote-char ::=
single-quote-char |
double-quote-char
separator-char ::==
'\' |
dot-char (Ada only)
terminator-char ::==
space-char |
carriage-return |
'[' |
']' |
',' |
'(' |
')' |
'/' |
'!'
double-quoted-char ::==
alpha-char |
digit-char |
dot-char |
double-colon-char |
operator-char |
percent-char |
single-quote-char |
special-char
single-quoted-char ::==
alpha-char |
digit-char |
double-colon-char |
double-quote-char |
dot-char |
operator-char |
percent-char |
special-char
unquoted-char ::==
alpha-char |
digit-char |
dot-char (not Ada) |
double-quote-char |
percent-char |
single-quote-char |
special-char
double-quote-quote ::==
double-quote-char double-quote-char
double-quote-sequence ::==
double-quoted-char |
double-quote-quote
double-quoted-identifier ::==
double-quote-char double-quote-sequence [{double-quoted-sequence}]
double-quote-char
single-quote-quote ::==
single-quote-char single-quote-char
single-quote-sequence ::==
single-quoted-char |
single-quote-quote
single-quoted-identifier ::==
single-quote-char single-quote-sequence [{single-quoted-sequence}]
single-quote-char
double-colon-colon ::==
double-colon-char double-colon-char
unquoted-identifier ::==
{[ [{unquoted-char}] double-colon-colon]}
unquoted-char [{unquoted-char}]
quoted-identifier ::==
double-quoted-indentifier |
single-quoted-identifer
token-identifier ::==
quoted-identifier | unquoted-identifier
label-identifier ::==
percent l-char a-char [b-char e-char l-char]
space-char [{space-char}]
token-identifer
line-identifier ::==
percent l-char i-char [n-char e-char]
space-char [{space-char}]
[{'0'}] digit-char {digit-char}
[dot [{'0'}] digit-char {digit-char}]
name-identifier ::==
percent n-char a-char [m-char e-char]
space-char [{space-char}]
token-identifer
identifier ::==
line-identifier |
label-identifier |
name-identifier |
token-identifier
path-name :==
[{identifier separator-char}] identifier terminator-char
The following BNF operator definitions are used:
::== assignment operator.
| exclusive OR operator.
[] optional operator.
.. range operator.
{} repeat operator.
4 – Non-Program Address Domains
CALL_TREE BY CHAIN_MODULE CALL_TREE BY CHAIN_ROUTINE
CALL_TREE BY CHAIN_LINE CHAIN_MODULE chain-name
CHAIN_ROUTINE chain-name CHAIN_LINE chain-name
TIME BY EVENT TIME BY [n] MSECS
EVENT event-name EVENT event-name BY [n] MSECS
IO_SYSTEM_SERVICE BY IO_SERVICE IO_SERVICE io-service-name
FILE_NAME BY FILE
FILE_KEY BY [n] KEY FILE_VBN BY [n] BLOCKS
PHYSICAL_IO_COUNT BY [n] COUNTS RECORD_SIZE BY [n] BYTES
READ_COUNT BY [n] COUNTS WRITE_COUNT BY [n] COUNTS
SYSTEM_SERVICE BY SERVICE SERVICE service-name
TASK BY TASK_IDENTIFIER TASK_IDENTIFIER task-id
TASK_TYPE BY TASK_TYPE_NAME TASK_TYPE_NAME task-type
TASK_PRIORITY BY [n] PRIORITY_UNITS
VLENGTH BY [n] ELEMENTS VMASK BY [n] CELLS
VOPERATIONS BY [n] OPERATIONS VSTRIDES BY [n] BYTES
INSTRUCTION BY VOPCODES VOPCODE vector-opcode
VREGISTER BY VREGISTER REGISTER vector-reg