1 SET 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] 2 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. 2 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 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 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 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. 2 COUNTERS Collector Command Establishes the collection of exact execution counts at specified program locations. Format SET COUNTERS nodespec [,nodespec...] 3 Parameters nodespec Specifies a set of program locations that gather execution counts. See HELP Nodespec for information about node specifications. 3 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. 3 Qualifiers /STACK_PCS Specifies that stack PC values are collected for counter data. Further SET COUNTERS requests will assume a default of /STACK_ PCS. /NOSTACK_PCS Specifies that no stack PC values are collected for counter data. This is the default upon entry into the collector. 3 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. 2 COVERAGE Collector Command Establishes the collection of test coverage data at specified program locations. Format SET COVERAGE [nodespec [,nodespec...]] 3 Parameters nodespec Specifies a set of program locations at which to measure test coverage. See HELP Nodespec for information about node specifications. 3 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. 3 Qualifiers /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. /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. /STACK_PCS Specifies that stack PC values are collected for coverage data. Further SET COVERAGE requests will assume a default of /STACK_ PCS. /NOSTACK_PCS Specifies that no stack PC values are collected for coverage data. This is the default upon entry into the collector. /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. 3 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. 2 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 3 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. 3 Qualifiers /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. /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. /NOSTACK_PCS Specifies that no stack PC values are collected for CPU data. 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. 2 DATAFILE PCA Command Identifies the performance data file to be used by the Collector or processed by the Analyzer. Format SET DATAFILE [file-spec] 3 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. 3 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. 3 Qualifiers /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. /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. /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. 3 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. 2 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]...] 3 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. 3 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. 3 Qualifiers /DYNAMIC /DYNAMIC /NODYNAMIC Controls whether a display automatically adjusts its window dimensions proportionally when a SET TERMINAL command is issued. /DYNAMIC is the default. /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. /POP /POP places a specified display at the top of the display pasteboard, ahead of any other displays. This is the default. /PUSH Has the same effect as /HIDE. /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. /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. 3 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. 2 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] 3 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. 3 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. 3 Qualifiers /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. /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. 3 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. 2 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...] 3 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. 3 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. 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. 2 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...] 3 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. 3 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). 3 Qualifiers /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. /NOMAIN_IMAGE Uses the first PC value when checking address filter restrictions. /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. /NOSTACK_DEPTH Does not perform stack-depth analysis. /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. /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. /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. /NOCREATOR_PC Do not use the PC value associated with the creation of the task. /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. /NOPARENT_TASK Use the current task characteristics. 3 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. 2 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 3 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. 3 Qualifiers /STACK_PCS Specifies that stack PC values are collected for I/O services data. This is the default upon entry into the Collector. /NOSTACK_PCS Specifies that no stack PC values are collected for I/O services data. /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. /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. 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. 2 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 3 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. 3 Qualifiers /LOG /LOG /NOLOG Controls whether a log message is displayed indicating that the key state has been set. The default is /LOG. /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. 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.) 2 LANGUAGE PCA Command Establishes the current language setting. The current language setting determines how symbol names are parsed. Format SET LANGUAGE language-name 3 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. 3 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. 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.) 2 LOG PCA Command Specifies that user input and PCA output be recorded in a log file. Format SET LOG [file-spec] 3 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. 3 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. 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. 2 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 3 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. 3 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. 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. 2 MODE PCA Command Establishes or cancels various mode settings that affect screen mode. Format SET MODE keyword [,keywod] 3 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. 3 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. 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. 2 NOTE Collector Command Stores an informative note about the current collection run in the PCA data file. Format SET NOTE "quoted-string" 3 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. 3 Examples PCAC> SET NOTE "G-FLAT" This command describes the current collection run and stores the quoted string in the PCA data file. 2 PAGE_FAULTS Collector Command Enables the collection of page fault data. Format SET PAGE_FAULTS 3 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. 3 Examples PCAC> SET PAGE_FAULTS This command enables the collection of page fault data. 2 PC_SAMPLING Collector Command Enables the collection of program counter sampling data. Format SET PC_SAMPLING 3 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. 3 Qualifiers /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. /STACK_PCS Specifies that stack PC values are collected for PC sampling data. This is the default upon entry into the Collector. /NOSTACK_PCS Specifies that no stack PC values are collected for PC sampling data. 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. 2 PLOT Analyzer Command Establishes default qualifiers and node specifications for the PLOT and TABULATE commands. Format SET PLOT [nodespec [,nodespec...]] 3 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. 3 Qualifiers /qualifiers The SET PLOT command accepts the same qualifiers as the PLOT and TABULATE commands. See HELP PLOT for the qualifier descriptions. 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. 3 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. 2 PROMPT PCA Command Changes the PCA prompt string from PCAC> or PCAA> to a string of your choice. Format SET PROMPT string 3 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. 3 Examples PCAC> SET PROMPT MYNAME> MYNAME> The above command will change the prompt to MYNAME>. 2 RUN_NAME Collector Command Establishes the name of the current collection run. Format SET RUN_NAME run-name 3 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. 3 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. 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. 2 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,...] 3 Parameters ALL NEXT IDENTIFIER STRING See qualifier description list. 3 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. 3 Qualifiers /ALL Makes /ALL the default SEARCH qualifier. /NEXT Makes /NEXT the default SEARCH qualifier. /IDENTIFIER Makes /IDENTIFIER the default SEARCH qualifier. /STRING Makes /STRING the default SEARCH qualifier. 3 Examples PCAC> SET SEARCH IDENTIFIER PCAC> SHOW SEARCH Default search qualifiers: /NEXT /IDENTIFIER This command sets the default SEARCH qualifier as /IDENTIFIER. 2 SERVICES Collector Command Enables the collection of system services data. Data is collected for each system service call in the program. Format SET SERVICES 3 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. 3 Qualifiers /STACK_PCS Specifies that stack PC values are collected for system services data. This is the default upon entry into the Collector. /NOSTACK_PCS Specifies that no stack PC values are collected for system services data. /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. /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. 3 Examples PCAC> SET SERVICES/NOSTACK_PCS This command specifies the collection of system services data, and disables the collection of stack PC values. 2 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...] 3 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. 3 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. 3 Qualifiers /EDIT Specifies that the indicated directory search list is to be used in locating source files for the Analyzer EDIT command. /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. 3 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. 2 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 3 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. 3 Examples PCAC> SET STACK_PCS This command enables the collection of stack PC values. 2 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 3 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. 3 Examples PCAC> SET TASKING This command causes tasking data to be collected on all tasks that are defined in the data file. 2 TERMINAL PCA Command Changes the terminal width and page size that PCA uses to format output. Format SET TERMINAL 3 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. 3 Qualifiers /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. /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. 3 Examples PCAA> SET TERMINAL/WIDTH:132 This command specifies that the terminal width is 132 columns. 2 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"...] 3 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. 3 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. 3 Qualifiers /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. 3 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. 2 UNALIGNED Collector Command Enables the collection of unaligned access fault data. Format SET UNALIGNED 3 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. 3 Qualifiers /STACK_PCS Specifies that stack PC values are collected for unaligned access fault data. This is the default upon entry into the Collector. /NOSTACK_PCS Specifies that no stack PC values are collected for unaligned access fault data. 3 Examples PCAC> SET UNALIGNED This command enables the collection of unaligned access fault data. 2 VCOUNTERS Collector Command Establishes the collection of vector processor instruction counts at specified program locations. Format SET VCOUNTERS [nodespec [,nodepsec...]] 3 Parameters nodespec Specifies a set of restricted program locations that gatehr vector processor instruction counts within the specified range. 3 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 3 Qualifiers /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. /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. 2 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 3 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. 3 Qualifiers /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. /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. /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. 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. 2 VERIFY PCA Command Causes PCA to verify command input by echoing it to the terminal. Format SET VERIFY 3 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. 3 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. 2 VPC_SAMPLING Collector Command Enables the collection of vector program counter sampling data. Format SET VPC_SAMPLING 3 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. 3 Qualifiers /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. /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. /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. 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. 2 WINDOW PCA Command Defines screen window names. Format SET WINDOW window-name AT (start-line,line-count,start-column,column-count) 3 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). 3 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. 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.