% Librarian I01-42ޤ f fHI EEE5 ` @file-spec Acceptable_Noncoverage0Analyzer_Command_Summary"APPENDPATTACHBACKCall_Stack_Analysis$CANCEL@Collector_Command_SummaryComparing_DataZCoverage_AnalysisvCURRENT Data_FileDEFINE>DELETE6DemoDISPLAY$DTM,EDIT Event_MarkersEXCLUDELFiltersFinding_Hot_SpotsFrequently_Asked_QuestionsA Getting_StartedD IntroductionFH IO_AnalysisfHKeypadLISTQ Logical_NamesMERGE"MOVEX Multi-Tasking'&NEXTZ Nodespecs(PAGElPage_Fault_AnalysisnParallel_Processing,PLOTNPRINTp& Release_NotesRSAVEpScreen_FeaturesU(SCROLLZSEARCHbtSELECTmSETrShareable_ImagesSHOW5SPAWNv$SPMvVSummaryySystem_Service_Analysis:TABULATEzR Time_Analysis|Traverse_Commands~n User_RoutinesVectors> Event_Markers IO_AnalysisSPMVectorsEXCLUDE@EXITEXPANDXEXTRACTFILELFiltersFINDFinding_Hot_SpotsFIRSTFrequently_Asked_QuestionsA Getting_Started$GOHELP,INCLUDED IntroductionFH IO_AnalysisvVSummaryySystem_Service_Analysis:TABULATEzR Time_Analysis|Traverse_Commands?TYPEBUNDEFINE~n User_RoutinesVectors  f1 Acceptable_NoncoverageD Noncoverage plots are typically used to see what portions of yourB program are not covered by your test system. Often, portions ofD your program cannot or should not be tested, or are too difficultD to test. PCA provides ways to preserve the decisions and analysisD from run to run of the same image, and from version to version of a program.B The SET ANC command is used to specify which lines or codepathsD in your program are a cceptably not covered. It can be used with aB program address domain nodespec or in conjunction with traverseD commands. See SET ANC and Traverse_Commands for more information.= The PLOT/ANC command will highlight those portions of your> program that are not covered and have not been specified asB acceptably not covered. That is, those portions of your program% for which you want to write tests.< The MERGE/ANC command is used to bring forward acceptableC noncoverage point s from one version of an image to another. NoteB that when you have modified your program, you cannot append newC coverage data to the old data file. While some of the acceptably? noncovered points specified in the old file may not be validA because you have changed the program, chances are that most ofB the points are still valid and you would like to preserve them.; The MERGE/ANC command does just that. It preserves thoseA acceptably noncovered points which are still vali d for the newB image. It validates the points on a routine-by-routine basis by? looking at the codepath information from both images. If all> the codepaths are at the same offsets from the beginning of@ the routine, then the routine is considered unchanged and anyB acceptably noncovered points within that routine are moved from7 the old version of the data file to the new version.D The SET COVERAGE/ANC command instructs the Collector to store the: codepath information required by the MERGE/ANC command. ww f1 Analyzer_Command_Summary% @file-spec APPEND# ATTACH BACK. CANCEL ANC CANCEL DATAFILE, CANCEL DISPLAY CANCEL FILTER* CANCEL LOG CANCEL PLOT+ CANCEL SOURCE CANCEL TITLE, CANCEL VERIFY CANCEL WINDOW- CURRENT DEFINE/COMMAND- DEFINE/KEY DELETE/COMMAND& DELETE/KEY DISPLAY& EDIT EXCLUDE% EXIT EXPAND# EXTRACT FILE$ FIND FIRST& HELP INCLUDE$ LIST MERGE# MOVE NEXT# PAGE PLOT# PRINT SAVE% SCROLL SEARCH& SELECT SET ANC* SET DATAFILE SET DISPLAY)  SET EDITOR SET FILTER+ SET KEY SET LANGUAGE3 SET LOG SET MAX_SOURCE_FILES' SET MODE SET PLOT) SET PROMPT SET SEARCH+ SET SOURCE SET TERMINAL) SET TITLE SET VERIFY' SET WINDOW SHOW ALL, SHOW ANC SHOW DATAFILE* SHOW DISPLAY SHOW EDITOR' SHOW FILTER SHOW KEY' SHOW LANGUAGE SHOW LOG( SHOW MAX_SOURCE_FILES SHOW MODE3 SHOW PLOT SHOW RUN_DESCRIPTION* SHOW SEARCH SHOW SELECT* SHOW SOURCE SHOW SYMBOL) SHOW TERMINAL SHOW TITLE* SHOW VERIFY SHOW WINDOW' SPAWN TABULATE/ TYPE UNDEFINE/COMMAND UNDEFINE/KEY ww f1 Call_Stack_AnalysisD Call stack analysis is useful, for exam ple, when data is gathered@ in an RTL. This allows the Analyzer to "charge back" the data= to the lines within the program that caused the data to be= gathered. It can also be helpful when you need to know the: dynamic relationships between portions of your program.D Call stack analysis requires that call stack data be gathered. ToB gather call stack data, use the Collector SET STACK_PCS command? or use the /STACK_PCS qualifier with the SET command used to gather data. B The PLOT, TABULATE, INCLUDE, and SET FILTER commands accept the following qualifiers:D /MAIN_IMAGE[=prog-unit] Start at the top of the stack and useD the first PC within the main image or5 prog-unit if provided.> /STACK_DEPTH=n After doing /MAIN_IMAGE, go "n"A frames down the stack and use that* PC instead.@ /CUMULATIVE[=n] Charge the rest or "n" PCs to the3 appropriate buckets.A The PLOT and TABULATE commands can also produce a dynamic call= tree. This will show all the call chains in the data beingC plotted and their frequency. The following nodespec will produce4 a dynamic call tree of the specified granularity. CALL_TREE BY CHAIN_MODULE CALL_TREE BY CHAIN_ROUTINE CALL_TREE BY CHAIN_LINE6 The SET FILTER command accepts the following filter specification: CHAIN_NAME=chain-name ww f1 Collector_Command_Summary% @file-spec ATTACH. CANCEL ALL CANCEL COUNTERS2 CANCEL COVERAGE CANCEL CPU_SAMPLING- CANCEL DATAFILE CANCEL DISPLAY1 CANCEL EVENT CANCEL IO_SERVICES1 CANCEL LOG CANCEL PAGE_FAULTS. CANCEL PC_SAMPLING CANCEL SERVICES/ CANCEL SOURCE CANCEL STACK_PCS/ CAN CEL TASKING CANCEL UNALIGNED3 CANCEL VCOUNTERS CANCEL VCPU_SAMPLING2 CANCEL VERIFY CANCEL VPC_SAMPLING- CANCEL WINDOW DEFINE/COMMAND- DEFINE/KEY DELETE/COMMAND& DELETE/KEY DISPLAY% EXIT EXPAND! EXTRACT GO# HELP MOVE% SAVE SCROLL% SEARCH SELECT+ SET COUNTERS  SET COVERAGE+ SET CPU_SAMPLING SET DATAFILE( SET DISPLAY SET EVENT& SET IO_SERVICES SET KEY& SET LANGUAGE SET LOG' SET MAX_SOURCE_FILES SET MODE. SET NOTE SET PAGE_FAULTS) SET PC_SAMPLING SET PROMPT) SET RUN_NAME SET SEARCH) SET SERVICES SET SOURCE* STACK_PCS SET TASKING, SET TERMINAL SET UNALIGNED0 SET  VCOUNTERS SET VCPU_SAMPLING/ SET VERIFY SET VPC_SAMPLING' SET WINDOW SHOW ALL, SHOW COUNTERS SHOW COVERAGE, SHOW CPU_SAMPLING SHOW DATAFILE) SHOW DISPLAY SHOW EVENT' SHOW IO_SERVICES SHOW KEY' SHOW LANGUAGE SHOW LOG( SHOW MAX_SOURCE_FILES SHOW MODE/ SHOW NOTE SHOW PAGE_FAULTS, SHOW PC_SAMPLING SHOW RUN_NAME* SHOW SEARCH SHOW SELECT* SHOW SERVICES SHOW SOURCE* SHOW STACK_PCS SHOW SYMBOL, SHOW TASKING SHOW TERMINAL- SHOW VCOUNTERS SHOW UNALIGNED* SHOW VCPU_SAMPLING SHOW VERIFY* SHOW VPC_SAMPLING SHOW WINDOW# SPAWN TYPE+ UNDEFINE/COMMAND UNDEFINE/KEY ww f1 Comparing_DataC You can compare more than one kind of data in the same plot. ForC example, you can plot PC sampling data, page fault data, and I/OD service calls in the same histogram. This way, you can easily seeD if the PC sampling spikes are caused by page faults or I/O system service calls.B See INCLUDE and EXCLUDE for more information about how to build multiple data kind plots. ww f1 Coverage_Analysis? PCA's coverage analysis consists of two parts: gathering and? analyzing the data. To gather the data, use the SET COV ERAGED command. A typical command might be SET COVERAGE PROGRAM BY LINE.B This would set a coverage point on every executable line in the2 program. For more information see SET COVERAGE.> To analyze coverage information, you must use the /COVERAGE= qualifier with the PLOT or TABULATE command. To view those8 portions of the program that are not covered, use theD /NONCOVERAGE qualifier. For more information about histograms andD tables see PLOT or TABULATE. Please also refer to the Acceptable_A Noncoverage HELP entry, describing how acceptable non-coverage2 (ANC) information is specified and used in PCA. ww, f 1 Data_FileB PCA data files, also called performance data files, are createdA by the PCA Collector to store the collected data. The data canB then be read and analyzed by the Analyzer. For more informationB on how performance data files are used in PCA, see HELP entriesB for the SET DATAFILE, SHOW DATAFILE, CANCEL DATAFILE, LIST, and MERGE commands. ww, f1 DemoD During the installation of DIGITAL PCA, a PCA demo package can beB optionally placed in the PCA$EXAMPLES directory. To run the PCA demos, type at DCL: $ @PCA$EXAMPLES:PCA_DEMO.COM ww, f1 DTM= PCA can be used with DIGITAL Test Manager (DTM) to provide= information on how well the tests managed by DTM cover theC software being tested, as well as information on the performa nce( of that software under verious tests.B For more information on DTM, refer to the Guide to DIGITAL Test> Manager. For information on using PCA and DTM together, see Chapter 10 in Using VAXset. ww, f1 Event_Markers4 See the HELP entries SET EVENT and Time_Analysis. ww, f 1 Filters See SET FILTER. ww, f1 Finding_Hot_Spots See Traverse_Commands. ww, f1 Frequently_Aske !d_QuestionsC Included below are some frequently asked questions about PCA and their answers. 2 80%_of_Time_Spent_in_P1_SpaceC Why is 80% of my program in P1 space? How do I get the wait time" reflected in code I can change?A When your program is waiting for a system service to complete,A the program counter points to a location in the system serviceC vector in P1 space. Since the most common form of system serviceA wait is waiting for an I/O operation to compl "ete, your program< thus appears to be spending most of its time in P1 space.D If your program does a lot of terminal I/O, you should expect the? program to be I/O-bound and to appear to spend a lot of time> in P1 space; the terminal is a slow device. If your program@ primarily does disk or tape I/O and appears to spend a lot ofC time in P1 space, you should investigate why the program is I/O-? bound. By reprogramming your program's I/O to reduce the I/OD wait-time, you ma #y be able to speed up your program considerably.D To get the system service wait time reflected in the code of yourB own program, you should gather stack PC values using the STACK_C PCS command in the Collector, then use the /MAIN_IMAGE qualifierB on a PLOT or TABULATE command in the Analyzer. This will chargeA the time outside your image (including that spent in P1 space)@ to the actual location within your image that caused it to be spent. ,2 Charging_Back_Shareable $_Image_Data_PointsC How do I get the time spent in shareable images to be charged to( the parts of my program that used it?= Gather STACK_PCs in the Collector, and use the /MAIN_IMAGED qualifier on your PLOT or TABULATE commands in the Analyzer. ThisA will charge the time spent outside your image to the PC within( the image that caused it to be spent. 2 Charging_Back_RTL_Data_PointsA How do I get the time spent in a specific RTL to be charged to( the parts of my p%rogram that used it?9 Gather STACK_PCs in the Collector, then use the /MAIN_? IMAGE=SHARE$mumbleRTL and /STACK=n qualifiers on the PLOT or% TABULATE commands in the Analyzer. $2 Analyzing_Individual_InstructionsB How can I find the specific instructions within a line that are taking the most time?? Use PLOT LINE module_name\%LINE nnn BY BYTE. Then, look at aB machine listing to correlate byte offsets from the beginning of) the line to the specific instructions.& 2 Getting_Rid_of_Terminal_I/O: How do I get rid of all the time spent in terminal I/O?? Place an event marker before each terminal I/O statement and= a different event marker after the terminal I/O statement.A Then use SET FILTER foo TIME <> the_first_event_marker_name inA the Analyzer. This will discard all the time spent waiting for terminal I/O. !2 ACCVIO_in_Program_Run_with_PCA3 Why does my program ACCVIO when linked with PCA?@ If the PCAC> prompt' never appears, the Collector has probablyA not been installed as a privileged image. Possibly, the system= manager forgot to edit the system start-up file to includeB @SYS$MANAGER:PCA$STARTUP. If the PCAC> prompt does appear, then see question 7. 2 PCA_Changes_Program_Behavior< Why does my program behave differently when ran with PCA?3 One of the following conditions probably exists:# - Uninitialized stack variables# - Dependence on memory above SP) ( - Assumptions about memory allocationA Cases 1 and 2 occur because PCA comes in as a handler and uses> the stack above the user program's stack. Consequently, the@ stack is manipulated in ways that are different than when runB without PCA. Although this is unlikely to happen, compiler code5 generation bugs have caused this sort of behavior.B Case 3 above occurs because PCA now lives in the process memoryC space and requests memory by means of SYS$EXPREG. PCA requests aD ) large amount of memory at initialization to minimize the altering3 of memory allocation, but this still may happen.B PCA may have a bug where it is smashing the stack or the random@ user memory. HP appreciates your input because these bugs areC hard to track down, and because they have been known to come and= go based on the order of modules in a linker options file., HP recommends that you try the following:C - Try GO/NOCOLLECT. If the program malfunctions, it's your * LINK with PCA.@ - Try a run with simple PC sampling only. PC sampling is the? least likely mode for bugs. If your program malfunctions,B the problem probably lies with your program. If your program> doesn't malfunction, the problem probably lies with PCA.B If you are still convinced that PCA is changing the behavior of your program:: If you have a support contract, contact your HP supportD representative. Otherwise, contact your HP account representa+tive or your authorized reseller.9 When reporting a problem, please include the following information:C o The versions of PCA and of the OpenVMS operating system being used.B o As complete a description of the problem as possible, trying" not to overlook any details.9 o The problem reduced to as small a size as possible.+ o If the problem is with the collector:+ - Does the program run GO/NOCOLLECT?8 - Does the program run with, the OpenVMS debugger?@ - If Counters, Coverage, or Events are involved, does the@ program behave properly when breakpoints are put in the2 same locations with the OpenVMS debugger?; - Please supply the version of the compiler(s) used.; - Files needed to build the program, including build procedures.* o If the problem is with the Analyzer: - The .PCA file involved0 - The sources referenced by the .PCA file< - A- PCA initialization file to reproduce the problem.< o All file should be submitted on machine-readable media< (magnetic tape `*preferred`*, floppy diskette, or tape cassette).2 o Any stack dumps the occurred, if applicable. %2 Creating_Data_File_Takes_Very_Long> Why does it take so long to create a performance data file?? The Collector copies the portions of the DST it needs to the; performance data file. This can take some time for large> programs. The. DST is placed in the performance data file toA avoid confusion over which image contains the DST for the dataC gathered. Also, PCA does not need all the information in the DST@ and condenses it. This avoids the overhead of reading useless+ information every time the file is used. 2 Using_PCA_in_a_Batch_Process Will PCA run in batch?4 Yes. However, you should avoid using screen mode. 2 Avoiding_Recompilation@ My application takes 10 days to compile. Is the /re a way I can4 avoid compiling my whole application with /DEBUG?B Yes. PCA will provide all functionality except annotated sourceA listings and codepath analysis, as long as the objects containA traceback information because most of the DST information thatC PCA needs is there. Once you find which modules are of interest,A you can compile those with /DEBUG, then relink the application and gather the data again. 2 CPU_Time_Stamp_Explained$ What exactly is a CPU 0 time stamp?? The time stamp found in the PCA performance data file always? expresses the CPU time from the start of the current programC execution. In the data file, it is represented as 10-millisecondB increments (number of CPU ticks), but to the user, it is always@ presented as milliseconds. This CPU time represents the totalB amount of CPU time consumed by the program and by the Collector/ from the time the program started executing. 2 CALL_Instruction_Gets_a_Spi 1ke? PCA tells me that a large amount of time is being spent at aD CALL instruction. Why? The CALL instruction should only consume a6 small part of the time spent executing the routine.A First, check page faulting. Sometimes the faulting behavior of@ a program causes a moderately called routine to get paged outB just before it is called. If that isn't the case, check for JSB linkages to an RTL routine.D For performance reasons, some RTL routines use JSB linkages. ThisB 2 can cause confusion for the user when the /MAIN_IMAGE qualifierB is used. This is especially true with PC sampling data, but can@ occur with any kind of data for which you can gather stack PC data.B Because a JSB linkage does not place a call frame on the stack,= the return address to the site of the call is lost to PCA.A Consequently, the first return address found by /MAIN_IMAGE isC the site of the call to the routine that called the RTL by means? of a JSB linkage. As 3an example, suppose routine MAIN called> routine FOO which in turn called the RTL via a JSB linkage.A Then, suppose that a PC sampling hit occurred in the RTL. ThisA will cause the PC of the call to FOO and the PC of the call to@ MAIN to be recorded. Thus, in the presence of the /MAIN_IMAGED qualifier, the first PC within the image is the PC of the call toD FOO. Consequently, FOO's call site will be inflated by the number@ of data points in the RTL that are in routines which ha 4ve JSB linkages.C Note that the above can yield useful information. If you compareB the time with /MAIN to the time without /MAIN, you can tell howD much time was spent in JSB linkage routines. You cannot, however,B separate the various JSB linkage routines. Note further that ifC the JSB routine is called from the main program, the data points? will be lost because there is no caller of the main program. 2 0.0%_With_********_in_PlotsA Why does the Analyzer report 50.0% for a line and then output a< full line of stars, indicating that the line was covered?A Probably the total number of data points is over 2000, and the> percentage is less than 0.05%. Therefore, rounding makes it 0.0%. '2 Optimizing_Calls_To_Utility_RoutinesD I have a utility routine which I have optimized as much as I can.B I need to know who is calling it and how often, so I can reduce< the number of calls to it. How do I get this information?B Use /MAIN_I6MAGE=utility-routine on the plot command. This gives you the following options:C - PLOT CALL_TREE BY CHAIN_ROUTINE will list all the call chains@ which pass through utility-routine with the number of data! points for each call chain.B - PLOT/STACK=1 PROGRAM BY ROUTINE will list all the callers of utility-routine.A - If one particular caller of utility-routine is of interest, try the following:@ PCAA> SET FILTER filter-name CHAIN=(*,caller,utility-7routine,*)? This will assure that the data being viewed is only of those7 whose chains have a subchain caller,utility-routine.A - Many other combinations of /CUMULATIVE, /MAIN_IMAGE, /STACK7 with various filters and nodespecs may be useful. 2 FAULT_ADDRESS_Data_Kind> What information does the /FAULT_ADDRESS data kind provide?@ When a page fault occurs, two virtual addresses are gathered:A the PC of the instruction and the virtual address which caused? the 8 fault. The CPU time is also gathered. In general, the PCB which caused the fault, i.e., the /PAGEFAULT data kind, is mostD significant because PCA can plot this against the PROGRAM_ADDRESS? domain and show where the page faulting is occurring in your program.? The /FAULT_ADDRESS data kind can also be plotted against the< PROGRAM_ADDRESS domain to find where the page faulting is? occurring. This can be useful in laying out CLUSTERs for theA link. (Note that these same p9age faults should also show up at= the branch or call instructions when plotting /PAGEFAULT.) $2 Stack_PC_Data_and_Page_Fault_Data9 Why can't I do stack PC analysis with page fault data?@ While the Collector is gathering page fault data, walking theA stack might cause additional page faults. This problem has not5 been addressed for the current release of OpenVMS. 2 Routines_and_Coverage_DataC Why am I getting several coverage data points associated with my6 : routine declaration when I do COVERAGE BY CODEPATH?A Several languages generate prologue code at each routine entry? to initialize the language specific semantics. As far as PCA> is concerned, code is code and deserves code path analysis.A This environment is usually set up by a CALLS or JSB to an RTLA routine. PCA considers CALLS, CALLG and JSB to be transfers ofD control, because control does not in principle have to come back,1 and places a BPT in the instruction followi;ng. 2 HEX_Numbers_in_CALLTREE_Plots8 Why are HEX numbers showing up in the CALL_TREE plot?? The Analyzer was not able to symbolize the return address itD found in the call stack. If IO_SERVICES or SERVICES data is beingC gathered, these may be addresses in the relocated system service vector. 2 Getting_Right_To_Hot_SpotsB How can I avoid all the source header information and get right to the most interesting line?A Use the traverse commands, NEXT, FIRS<T, PREVIOUS, and CURRENT. $2 Comparing_Different_Kinds_of_Data4 How can I easily compare different kinds of data? Use the INCLUDE command. !2 Virtual_Memory_in_the_Analyzer? The Analyzer is running out of virtual memory. What do I do?B Raise the appropriate quotas, limit the number of displays, and3 limit the memory used by displays (use /SIZE=n).; Limit the size of your plots with the following methods:@ - Use limiting nodespecs. For example, if PROG=RAM_ADDRESS BYB LINE doesn't work, try MODULE foo BY LINE, or ROUTINE fee BY LINE.B - Use the traverse commands after issuing PLOT/your_qualifiers PROGRAM_ADDRESS BY MODULE6 - Use the /NOZEROS, /MINIMUM, /MAXIMUM qualifiers.B - Use filters with CALL_TREE nodespecs to reduce the number of call chains. "2 Virtual_Memory_in_the_Collector@ The Collector is running out of virtual memory. What do I do?B If you are doing coverage or counter analys >is, limit the number> of breakpoint settings by using either MODULE BY LINE or BYC CODEPATH node specifications instead of using PROGRAM_ADDRESS BYB LINE or BY CODEPATH. Then, do several collection runs to gather the data. 2 Some_Plots_Appear_So_Quickly6 Why do some plots execute more quickly than others?B Some PLOT commands execute more quickly than others because PCAC uses all available information from the previous plot to produce? the requested one. For exampl?e, if you enter PLOT PROGRAM BY? LINE, and then enter PLOT/DESCENDING, PCA will only sort the@ previous plot. However, if you use a different nodespec, suchA as PLOT ROUTINE foo$bar BY CODEPATH, then PCA must rebuild itsB internal tables and read the data again, which takes more time.D In addition, the number of filters and/or buckets you use affectsD the time it takes to build a plot. This is because filters affectD the amount of data the Analyzer looks at, and because all buc@kets( must be searched for each data point. 2 Missing_Subroutine_CallsB Why don't I see all of my subroutine calls in a CALL_TREE plot?A It may be that your routine has a JSB linkage. See question 7. 2 Bad_Offsets_In_MACRO_Modules@ Why do I get bad offsets when plotting MACRO modules by byte?C When plotting MACRO modules by byte, the offset is actually fromB the beginning of the module, including the data psects. You get? bad offsets because the linker move As the psects around basedA on the psect attributes. Thus, the offsets you get may have noA relationship to any listing you have. However, if you use PLOTC ROUTINE foo BY BYTE, then the offsets will be from the beginningA of the routine. (This will only work if you have an .ENTRY foo" ... directive in your program.) 2 LIB$FIND_IMAGE_SYMBOL? Can PCA measure shareable images activated "on the fly" with LIB$FIND_IMAGE_SYMBOL?A Yes, if you relink against the image Byou want to activate. PCA@ uses a structure built by the image activator to find all the@ shareable image information it needs. By relinking the image,D the image activator will know about the image and LIB$FIND_IMAGE_ SYMBOL will work. ww{ f1 Getting_StartedC You only have to know two PCA commands to do simple PC sampling.> PC sampling is typically the first kind of data you want to? gather. It provides a good overview of where your program is6 sCpending the most time. To do PC sampling you must:7 1. Compile your sources with the "/DEBUG" qualifier;@ This puts all the necessary symbolic information PCA needs into the object file.= 2. The following steps specifies the PCA Collector as your program's "debugger":7 i Link your program with the "/DEBUG" qualifier;< ii Define the logical name LIB$DEBUG as PCA$COLLECTOR; 3. Run your program;1 4. Enter the "GO" command at the PCAC> promDpt.C The Collector will transfer control to your program just like? the debugger does, and will store the data in a data file named your-image-name.PCA.A 5. Enter "PCA your-image-name" at DCL level after your program has finished. This invokes the Analyzer.2 6. Enter the "NEXT" command at the PCAA> promptA This will give you an annotated source listing and point to? the line where your program spent the most time. ContinueA issu Eing NEXT commmands and "walk" from the most significantA line ("hot spot") to the next one, and so on. See Traverse_? Commands for more information on moving from "hot-spot to hot-spot". ww{ f1 IntroductionD The DIGITAL Performance and Coverage Analyzer (PCA) is a software= development tool that helps you analyze the performance ofB applications programs. It can measure, among others, where yourC program spends its time, where it page faulFts, where it performs? I/O. It can also measure test coverage so you can tell whichC codepaths in your program are or are not executed by a given set of tests." PCA consists of two components: o The Collector; o The Analyzer;= The Collector gathers performance and coverage data from aC running program and writes that data to a performance data file.? The Analyzer processes and displays that data in the form of histograms and tables.C Type New_FeGatures for a description of what's new with PCA V5.1. ww{ f1 IO_AnalysisC I/O analysis requires that I/O data be gathered. Use the SET IO_8 SERVICES command in the Collector to gather I/O data.9 The PLOT and TABULATE commands accept several datakind qualifiers:@ /IO_SERVICES Tallies I/O system service call counts6 /READ_COUNT Tallies physical read counts7 /WRITE_COUNT Tallies physical write counts; /PHYSICAL_IO_HCOUNT Tallies total physical I/O counts; The PLOT and TABULATE commands accept several nodespecs: FILE_KEY BY [n] KEY FILE_NAME BY FILE FILE_VBN BY [n] BLOCKS" IO_SYSTEM_SERVICE BY IO_SERVICE IO_SERVICE io-service-name" PHYSICAL_IO_COUNT BY [n] COUNTS READ_COUNT BY [n] COUNTS RECORD_SIZE BY [n] BYTES WRITE_COUNT BY [n] COUNTS8 The SET FILTER command accepts several filter specs.: FILE_KEY=n:[m] FILE_NAME=file-specification FILIE_VBN=n:[m] IO_SERVICE=io-service-name PHYSICAL_IO_COUNT=n:[m] READ_COUNT=n:[m] RECORD_SIZE=n:[m] WRITE_COUNT=n:[m] ww{ f 1 Keypad? You can use the numeric keypad on your terminal to enter PCAA commands. When you press a defined keypad key, PCA accepts theC associated "equivalence string" as command input. PCA predefinesC a number of keypad keys; pressing such a key enters the command.C Some keys have GOLD definitions, and some h Jave BLUE definitions.A To access a GOLD definition, press the GOLD (PF1) key and thenA the defined keypad key. To access a BLUE definition, press theA BLUE (PF4) key before pressing the defined keypad key. You canB define your own keypad definitions with the DEFINE/KEY command. 2 NOCOLOR; +-------------+-------------+-------------+-------------+ Default keypadJ | GOLD | Help Keypad | Set Mode | BLUE | definitions.< | | Nocolor | K Screen | |; +-------------+-------------+-------------+-------------+ For more keypadN | Display | Scroll/Up | Display | Display | help, enter HELPL | Src, Out | | %Nextdisp | %Nextdisp | KEYPAD GOLD or; +-------------+-------------+-------------+-------------+ HELP KEYPAD BLUE.< | Scroll/Left | First | Scroll/Right| Set ANC |F | | | | | Control-W does a; +------ L-------+-------------+-------------+-------------+ Display/RefreshO | Page | Scroll/Down |Select/Scroll| E | to refresh screenM | Previous | | %Nextscroll | N | in screen mode.< +-------------+-------------+-------------+ T |< | Page Next | Reset | E |< | | | R |< +---------------------------+-------------+-------------+ 2 GOLD; +----M---------+-------------+-------------+-------------+ Keypad defs. inM | GOLD | Help Keypad | Set Mode | BLUE | effect when youO | | Gold | Noscreen | | press GOLD first.< +-------------+-------------+-------------+-------------+O | | Scroll/Top | Set Key/ | | Reset cancels theG | | |State=Default| | GOLD key.< +-------------+-------------+-------------+------ N-------+F | Scroll/ | First | Scroll/ | | Control-W does aM | Left:255 | Subtree | Right:255 | | Display/Refresh; +-------------+-------------+-------------+-------------+ to refresh screenM | Page 1 | Scroll/ |Select/Output| E | in screen mode.< | | Bottom | %Nextoutput | N |< +-------------+-------------+-------------+ T |< | Page Summary | Reset | O E |< | | | R |< +---------------------------+-------------+-------------+ 2 BLUE; +-------------+-------------+-------------+-------------+ Keypad defs. inM | GOLD | Help Keypad | | BLUE | effect when youO | | Blue | | | press BLUE first.< +-------------+-------------+-------------+-------------+N | | Scroll/ | Set Key/ P |Display Plot,| "..." means thatL | | Up... | State=Move | Src, Out | you must enter; +-------------+-------------+-------------+-------------+ more input afterO | Scroll/ | | Scroll/ | | pressing the key.< | Left... | | Right... | |; +-------------+-------------+-------------+-------------+ Reset cancels theG | | Scroll/ | Select/Plot | E | BLUE key.< | Q | Down... | %Nextplot | N |< +-------------+-------------+-------------+ T |< | | Reset | E |< | | | R |< +---------------------------+-------------+-------------+ 2 CommandsD The following commands are used to control PCA's keypad features: DEFINE/KEY DELETE/KEY SET KEY SHOW KEY UNDEFINE/KEYD You can get furthRer information on each of these commands throughD HELP. Use DEFINE KEY, DELETE KEY, SET KEY, SHOW KEY, and UNDEFINE. KEY, respectively, as the HELP topic names. ww{ f1 Logical_Names> The Collector accepts the following logical names which, if= defined, passes some item of information to the Collector.@ PCAC$DECW$DISPLAY If PCAC$DECW$DISPLAY is defined as a valid@ logical name (but not set as " ") then the> DECwin Sdows Motif interface will be used.A Otherwise the character cell interface will be used.> PCA$DECW$DISPLAY If PCAC$DECW$DISPLAY is not defined as a? valid logical name (or set as as " ") andD PCA$DECW$DISPLAY is defined as a valid logicalC name (but not set as " ") then the DECwindowsA Motif interface will be used. Otherwise the< character Tcell interface will be used.D DECW$DECW$DISPLAY If both PCAC$DECW$DISPLAY and PCA$DECW$DISPLAYD are not defined as valid logical names (or setA as as " ") and DECW$DISPLAY is defined as aB valid logical name (but not set as " ") thenB the DECwindows Motif interface will be used.D Otherwise the character cell interface will be used.B PCA$DATAFILE Defines th Ue performance data file to be used? by the Collector; equivalent to using SET% DATAFILE/APPEND@ PCA$RUN_NAME Defines the name of the current collection; run; equivalent to using SET RUN_NAME> PCA$INHIBIT_MSG Specifies that informational messages be suppressed? PCAC$INIT Defines the Collector initialization file8 PCA$INPUT Defines the Collector input stream9 PCA$OUTPUT V Defines the Collector output stream= The Analyzer accepts the following logical names which, ifA defined, determine the Analyzer initialization file, the inputD and output streams, and the number of lines per page of PRINT and FILE output:@ PCAA$DECW$DISPLAY If /INTERFACE was not specified on the PCAC command and PCAA$DECW$DISPLAY is defined as aB valid logical name (but not set as " ") thenB the DECwin Wdows Motif interface will be used.D Otherwise the character cell interface will be used.@ PCA$DECW$DISPLAY If /INTERFACE was not specified on the PCAB command and PCAA$DECW$DISPLAY is not definedD as a valid logical name (or set as as " ") andD PCA$DECW$DISPLAY is defined as a valid logicalC name (but not set as " ") then the DECwindowsA Moti Xf interface will be used. Otherwise the< character cell interface will be used.< DECW$DECW$DISPLAY If /INTERFACE was not specified on the< PCA command and both PCAA$DECW$DISPLAY= and PCA$DECW$DISPLAY are not defined as@ valid logical names (or set as as " ") and@ DECW$DISPLAY is defined as a valid logicalC name (but not set as " ") then the DECwindowsA Y Motif interface will be used. Otherwise the< character cell interface will be used.> PCAA$INIT Defines the Analyzer initialization file7 PCAA$INPUT Defines the Analyzer input stream8 PCAA$OUTPUT Defines the Analyzer output streamB SYS$LP_LINES Specifies the number of lines per page to beC assumed when formatting histograms and tables7 using the PRINT and FILE commands ww Z f1 Multi-TaskingC PCA provides support for analyzing the performance of Ada multi-D tasking applications. The Collector SET TASKING command instructs= the Collector to gather tasking information. PCA uses thisB information to associate other kinds of data with the task thatA caused that data to be gathered. The following nodespecs allow9 you to group the data by task, task type and priority: TASK BY TASK_IDENTIFIER! TASK_TYPE BY TASK_TYPE_NAME([ TASK_PRIORITY BY nn PRIORITY_UNITS@ See PLOT for more information about plotting various kinds of data.B Data may also be filtered based on tasking information (see the SET FILTER entry in HELP). ww f 1 Nodespecs> 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., aB line, or codepath), or a class of locatio \ns (e.g., all routines in the program). 2 Collector_Nodespecs? In the Collector, the SET COUNTERS and SET COVERAGE commandsD require one or more nodespecs to specify the program locations atD which to collect execution counts or coverage data. The followingA example specifies an execution counter on every routine in theC entire program. Notice that it has two clauses. The first clauseC (PROGRAM_ADDRESS) specifies the range, and the second clause (BY ROUTINE) spec ]ifies the unit.-PCAC> SET COUNTERS PROGRAM_ADDRESS BY ROUTINEB 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 theB histogram. The Analyzer accepts a wider range of nodespecs thanB the Collector does because Analyzer nodespecs can cover domains) other than the program address domain.A The following nodespec specifies a set of buckets. It consistsB of an address range specification, followed by a BY clause. TheB result is a plot which sh_ows 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. 2 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 CODEPATHB ` 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 CODEPATHB PROGRAM_ADDRESS BY [n] BYTES PROGRAM ADDRESS BY VINSTRUCTION> ROUTINE pathname ROUTINE pathname BY ROUTINE? ROUTINE pathname BY [n] LINES ROUTINE pathname BY CODEPATHC ROUTINE pathname BY [n] BYTES ROUTINE pathname BY VINSTRUCTION 3 Pathname: This is the BNFa 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 b::== '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 | horizonctal-tab special-char ::== '^' | '~' | '|' | '#' | '$' | '-' | '=' | '&' | '+' | '<' | '>' | '*' | '_' zero-char ::== '0' operator-char ::== space-char | '[' | ']' | ',' |d '(' | ')' | '/' | '!' | '\' quote-char ::=" single-quote-char | double-quote-char separator-char ::== '\' |" dot-char (Ada only) terminator-char ::== space-char | carriage-return | '[' | ']' | ',' | '(' | ')'e | '/' | '!'" 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 |f 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 ::==2 double-quote-char double-quote-char% double-quote-gsequence ::==# double-quoted-char |! double-quote-quote( double-quoted-identifier ::==Q double-quote-char double-quote-sequence [{double-quoted-sequence}] double-quote-char" single-quote-quote ::==2 single-quote-char single-quote-char% single-quote-sequence ::==# single-quoted-char |! single-quote-quote( single-quoted-identifier ::==Q h single-quote-char single-quote-sequence [{single-quoted-sequence}] single-quote-char" double-colon-colon ::==2 double-colon-char double-colon-char# unquoted-identifier ::==8 {[ [{unquoted-char}] double-colon-colon]}. unquoted-char [{unquoted-char}]! quoted-identifier ::==* double-quoted-indentifier |& single-quoted-identifer token-identifier ::==i6 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 ::==5 percent l-char i-char [n-char e-char]) space-char [{space-char}]/ [{'0'}] digit-char {digit-char}5 [dot [{'0'}] digit-char {digit-char}] name-identifier :j:==5 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 :==H [{identifier separator-char}] identifier terminator-char3 The following BNF operator definitions are used:7 ::== k assignment operator.9 | exclusive OR operator.5 [] optional operator.2 .. range operator.3 {} repeat operator. 2 Non-Program_Address_DomainsA 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-name8 TIME BY EVENT l TIME BY [n] MSECSD EVENT event-name EVENT event-name BY [n] MSECSA 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_IDENmTIFIER task-id? TASK_TYPE BY TASK_TYPE_NAME TASK_TYPE_NAME task-type& TASK_PRIORITY BY [n] PRIORITY_UNITS9 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 ww&ɥ f1 Page_Fault_AnalysisD The PLOT and TABULATE commands (see the PLOT and TABULATE entriesC in PCA HELPn) accept the following datakind qualifiers to analyze) your program's page-faulting behavior:@ /PAGE_FAULT Tallies the PC where the pagefault occured: /FAULT_ADDRESS Tallies the virtual address accessed; The PLOT and TABULATE commands accept nodespecs (see the= Nodespecs entry in PCA HELP) from the following domains to0 analyze your program's pagefaulting behavior: PROGRAM_ADDRESS TIME TASK TASK_PRIORITY TASK_TYPE6 The S oET FILTER command accepts the following filterB specifications to analyze your program's pagefaulting behavior:A FAULT_ADDRESS = n[:m] The faulting address is within3 the range n to mA FAULT_ADDRESS = prog-unit The faulting address is within, prog-unitD PROGRAM_ADDRESS = n[:m] The PC is within the range n to m= PROGRAM_ADDRESS = prog-unit The PC is within prog-unit ww p&ɥ f1 Parallel_Processing= For those applications that have the same image running inB parallel, each process can gather data with PCA and write it toD its own data file. Note that you can use the SET PROMPT Collector@ command to easier distinguish among all the simultaneous data collection runs.D When the application is finished, PCA's MERGE command can be usedC in the Analyzer to view all the data as a whole. For information9 on the MERGE command, see the MERGEq entry in PCA HELP. ww&ɥ f1 Release_NotesD The release notes for PCA are located in SYS$HELP:PCAvvu.RELEASE_: NOTES (ASCII text) and SYS$HELP:PCAvvu_RELEASE_NOTES.PS? (postscript), where 'vv' represents the major version numberB and 'u' the minor version number. For example, the filename for8 the PCA V4.7 release notes is 'PCA047.RELEASE_NOTES'. ww&ɥ f1 Screen_Features? PCA provides a set of screen features designed to be used on r> VT100 or VT200 class terminals. The command SET MODE SCREENA activates screen mode and SET MODE NOSCREEN deactivates it. In? screen mode, output is stored in "screen displays" which are3 viewed through scrollable windows on the screen.8 The following commands control PCA's screen features:3 SET MODE SCREEN MOVE SET WINDOW4 SET MODE NOSCREEN SCROLL SHOW WINDOW6 SET DISPLAY SELECT CANCEL WINDOW5 SHOW DISPLAY SHOWs SELECT SET TERMINAL/ CANCEL DISPLAY SAVE EXPAND DISPLAYD You can get further information on each of these commands through HELP. ww&ɥ f1 Shareable_ImagesA There are two classes of shareable images; those that are user@ written, and those that are provided. The Analyzer can report6 symbolically only on user written shareable images.@ Before you can collect data, you must build a shareable imageC on which to collectt that data. Next, you must link an executable@ image that uses that shareable image. The following steps are necessary:7 1. Compile your sources with the "/DEBUG" qualifier;@ This puts all the necessary symbolic information PCA needs into the object file.C 2. Link your shareable image program with the "/SHAREABLE/DEBUG" qualifiers;A This creates a version of the shareable image that contains) the DST information that PCA needs.= 3. The ufollowing steps specifies the PCA Collector as your program's "debugger":7 i Link your program with the "/DEBUG" qualifier;< ii Define the logical name LIB$DEBUG as PCA$COLLECTOR; 4. Run your program;@ 5. Enter the "SET DATAFILE/SHAREABLE=img-name" command at the PCAC> prompt.@ This command specifies the shareable image to be measured.6 Specify your remaining data collection commands.1 Enter the "GO" command at the PCAC> prompt. vC The Collector will transfer control to your program just like? the debugger does, and will store the data in a data file named your-image-name.PCA.A The /APPEND qualifier may be used to collect data from several@ program executions into one data file, even if the executionsB are of different programs. However, you must always measure theA same shareable image. Thus, you may measure the performance ofA one shareable image averaged over many executions of differwent programs. ww&ɥ f1 SPM= PC sampling data collected by the VAX Software PerformanceC Monitor (SPM) can be merged into PCA performance data files with@ the Analyzer MERGE/SPM_PROCESS_ID command, to be subsequentlyA analyzed by the Analyzer. See HELP MERGE for more information. ww&ɥ f 1 SummaryJ @file-spec APPEND ATTACH BACK CANCEL CURRENT DEFINEK DELETE DISPLAY EDIT EXCLUDE EXIT EX xPAND EXTRACTH FILE FIND FIRST GO HELP INCLUDE LISTH MERGE MOVE NEXT PAGE PLOT PRINT SAVEL SCROLL SEARCH SELECT SET SHOW SPAWN TABULATE TYPE UNDEFINE? Acceptable_Noncoverage Analyzer_Command_Summary@ Call_Stack_Analysis Collector_Command_Summary8 Comparing_Data Coverage_Analysis+ Data_File Demo y4 DTM Event_Markers8 Filters Finding_Hot_Spots6 Frequently_Asked_Questions Getting_Started2 Introduction IO_Analysis4 Keypad Logical_Names3 Multi-Tasking New_Features: Nodespecs Page_Fault_Analysis3 Parallel_Processing Restrictions7 Screen_Features Shareable_Images. SzPM Summary4 System_Service_Analysis Time_Analysis4 Traverse_Commands User_Routines Vectors ww&ɥ f1 System_Service_Analysis? System service analysis requires that system service data beD gathered. Use the SET SERVICES command in the Collector to gather system service data.< The PLOT and TABLUATE commands in the Analyzer accept one6 datakind qualifier to analyze system service usage:<{ /SERVICES Tallies system service call counts; The PLOT and TABULATE commands accept several nodespecs: SYSTEM_SERVICE BY SERVICE SERVICE service-nameC The SET FILTER Analyzer command accepts one filter specification# to analyze system service usage: SERVICE=service-name ww&ɥ f1 Time_Analysis= PCA can analyze your program's resource consumption in the> time domain. That is, PCA can tell you when your program isC perfo |rming the most I/O, issues system service calls, and so on.C PCA provides two ways to view time. The first is by millisecond;A the second is in relationship to the execution of your program@ and involves the use of event markers. See SET EVENT for more. information on gathering event marker data.C The PLOT and TABULATE commands accept the following nodespecs to+ analyze your program's behavior in time: TIME BY [nn] MSEC TIME BY EVENTA The PLOT and TABULA}TE commands accepts all datakind qualifiersA with TIME BY EVENT nodespecs, and the following qualifiers for TIME BY [nn] MSEC: /PAGE_FAULTS /FAULT_ADDRESS /SERVICES /IO_SERVICE /READ_COUNT /WRITE_COUNT /PHYSICAL_IO_COUNT /TASK_SWITCH6 The SET FILTER command accepts the following filter= specifications to analyze your program's behavior in time: TIME = n[:m] TIME = event-name ww6 f ~1 Traverse_Commands@ The Analyzer provides four related commands which make moving= from one hot spot to another easy. These commands take the< current plot and use it to produce annotated source plots6 positioned at the most interesting lines. They are:- NEXT Go to the next interesting line1 BACK Go to the previous interesting line. FIRST Go to the first interesting line( CURRENT Redisplay the current lineA Note that if there is no current plot (as when you first enter> the Analyzer), then a default plot is be supplied, with the' PROGRAM_ADDRESS BY ROUTINE nodespec.= Also note that the command parameter SUBTREE may be useful@ when the current plot is a BY ROUTINE or BY MODULE plot. ThisB parameter allows you to move between the routines or modules of these plots. ww6 f1 User_Routines> User routines are called by the PCA collector during systemA service interception. They provide the user with the following capabilities:C o Independent recording (including system service information);9 o Control of the recording by PCA of system services; 2 API? The PCA Collector supports the following application program interface to user routines. pca-control-flag = entry-routine( ap-pointer, sequence-number, CPU-time,% system-service-name-pointer,# system-service-name-index,% user-routine-buffer-pointer) pca-control-flag = exit-routine( ap-pointer, sequence-number, CPU-time,% system-service-name-pointer, system-service-index,% user-routine-buffer-pointer)* Routine Parameter DescriptionA pca-control-flag Flag to indicate whether PCA is toB attempt to write the system service= record. The write will only be? attempted if the low bit is set.C ap-pointer The contents of the argument pointerC at the system service call by value.D sequence-number The PCA sequence number corresponding@ to the performance data record by% value.5 CPU-time The CPU time by value.C system-service-name- The name of the system service beingA point er called by the address of a counted, ASCII string.D system-service-index The index of the system service being/ called by value.B user-routine-buffer- User specified buffer by reference. pointer@ The following rule applies regarding the construction of user routines images:A 1. The user must write a shareable image, making the entry and# exit routine names UNIVERSAL;  2 Example= The DEMO_USER_ROUTINE example is intended to introduce the3 concept of User Routines. The example files are:% PCA$EXAMPLES:*DEMO_USER_ROUTINE*.* 3 Construction@ The example user routine image can be constructed by running:& $ @PCA$EXAMPLES:DEMO_USER_ROUTINE.COMD If you are using the VAX C rather than DEC C compiler replace the line:& SYS$LIBRARY:DECCRTL.OLB/LIBRARY ^^^' from VAX_DEMO_USER_ROUTINE.OPT with:&  SYS$LIBRARY:VAXCRTL.OLB/LIBRARY ^^^ 3 Usage8 Run an example program to check user routine support:= $ DEFINE DEMO_USER_ROUTINE DISKN:[USER]DEMO_USER_ROUTINE.EXED You must define the logical name to access the user routine image# if it is not found in SYS$SHARE.! $ DEFINE LIB$DEBUG PCA$COLLECTOR# $ RUN PCA$EXAMPLES:PCA$8QUEENS.EXE6 PCAC> SET SERVICES/USER_ROUTINE=(DEMO_USER_ROUTINE,-)! _PCAC> DEMO_ENTRY$USER_ROUTINE,- _PCAC> DEMO_EXIT$USER_ROUTINE PCAC> GO< Using LIB$DEBUG is the preferred method for using the PCA collector. 2 UsageD For information on specifying collection with user routines enter the following commands: $ PCA( PCAA> HELP SET SERVICES /NOUSER_ROUTINE& PCAA> HELP SET SERVICES /USER_ROUTINE+ PCAA> HELP SET IO_SERVICES /NOUSER_ROUTINE) PCAA> HELP SET IO_SERVICES /USER_ROUTINE 3 RestrictionsD - PCA will not call, or invoke, your user routine image if it is% linked wit h warnings or errors.? - You must define a logical name to access the user routine, image if it is not found in SYS$SHARE.< - A system service routine which is invoked from a user-> supplied routine should be written in the C language (as? referenced by the /USER_ROUTINE qualifier in the glossaryB of the DIGITAL Performance and Coverage Analyzer for OpenVMSC Reference Manual). If written in some other languages, it mayA have the effect of locking up PCA. Examples are provided in PCA$EXAMPLES. 3 Side_EffectsC Lost Data Indications will occur in the PCA Analyzer if the userB supplied routines instructs PCA not to write some data records; ww6 f 1 Vectors; With DIGITAL PCA, you can examine how you have split the: processing of the application between scalar and vector? processors. You can also analyze how well your application's@ algorithms use the vector processor. Certain programs can runA significantly faster on computers containing scalar and vector? processors than on those containing scalar processors alone.? Programs that use repetitive array and matrix operations can= run faster on a vector processor because they are the most? constrained by scalar performance bottlenecks. Programs that= spend most of their time performing I/O operations, systemA services, or using data types not supported by vector hardwareB (for example, BYTE and LOGICAL) do not benefit as much by beingA executed on a computer with both scalar and vector processors. !2 Finding_Vector_Processor_Usage= The Collector provides two data kinds for sampling vector-< processing information: vector PC sampling and vector CPU? sampling. You use the SET command, as shown in the following= example, to enable sampling of PC values for random vector instructions: PCAC> SET VPC_SAMPLINGB The preceeding command enables the sampling of vector PC va lues@ and shows you where the wall-clock time is being spent in the@ application performing vector instructions. The sampling rate> defaults to an interval of 10 milliseconds and includes allB the idle process time associated with running the program. CallC stack information is collected by default. The following commandD enables the sampling of vector PC values and lets you examine theC particular areas of your application where process time is spent" performing vector instructions. PCAC> SET VCPU_SAMPLING? The sampling rate defaults to an interval of 10 milliseconds@ and includes only the time that the application is running on@ the processor (process clock time). Call stack information is collected by default.> When you sample the vector PC values, you can determine the@ scalar/vector parallelism throughout your entire program. TheA collection of vector PC or CPU sampling data provides you with the following information:3 o The program counter of the vector instruction$ o The program relative timestamp# o The vector instruction opcode o The vector stride5 o The vector control word (instruction dependent) o The vector length register o The vector mask register) o Call stack information (optionally) 32 Collecting_Concurrent_Scalar_and_Vector_Sampling= You can collect both scalar and vector PC samples during a@ collection run. The timer intervals must be the s ame for both< types of PC sampling. If you have set different intervals> for each, the Collector uses the timer interval of the last@ sampling command entered. The following example shows settingB the timer interval to 20 milliseconds for CPU sampling, and 100( milliseconds for vector CPU sampling.# PCAC> SET CPU_SAMPLING/INTERVAL:20% PCAC> SET VCPU_SAMPLING/INTERVAL:100B In the example above, the interval for both CPU sampling and PC' sampling is set to 100 milliseconds.  )2 Counting_Vector_Processor_Instructions? You can instruct the Collector to count all vector processor@ instructions in all or in part of an application with the SETA VCOUNTERS command. From this information, you can determine to@ what extent the vector processor is used. You must specify atC least one nodespec to indicate the domain of the data collected.4 PCAC> SET VCOUNTERS PROGRAM_ADDRESS BY VINSTRUCTIONC The following example shows collecting vector instruction countsA for an entire program using the nodespec of PROGRAM ADDRESS BY VINSTRUCTION.0 PCAC> SET VCOUNTERS ROUTINE XYZ BY VINSTRUCTIOND The following example example shows collecting vector instruction: counts for routine XYZ using the nodespec of ROUTINE BY VINSTRUCTION.? See the Command Dictionary in the Guide to DIGITAL PCA for a> complete list of available nodespecs with the SET VCOUNTERS command. "2 Analyzing_Vector_Processor_Data< The Analyzer plots and displays the results of the vectorA instructions data gathered in the Collector. You can use three> views to aid in the analysis of the scalar/vector processor7 parallelism: Table, Histogram, and Annotated Source.C You can set the data kind to the any of the following, depending. on what was gathered by the collection run:! o Vector instructions counted o Vector PC sampling o Vector CPU sampling= The following additional domains are available with vector instruction analysis:? o INSTRUCTIONS-Sets the domain to be the vector instruction) found at the sampled or counted PC.D o VLENGTH-Sets the domain to be the Vector Length Register (VLR) values@ o VMASK-Sets the domain to be the Vector Mask Register (VMR) values@ o VOPCODE-Sets the domain to be specific vector instructionsD o VOPERATIONS-Sets the domain to be the number of operations per Vector instruction@ o VREGISTERS-Sets the domain to be the Vector Register usage< o VSTRIDE-Sets the domain to be the Vector Stride values (2 Finding_Most_Used_Vector_InstructionsD In the INSTRUCTION domain, to determine which vector instructionsC are used most by your program, enter the following command line:, PCAC> PLOT/VCOUNTERS INSTRUCTION BY VOPCODE9 This command causes the report view to be based on the@ disassembled opcode for each vector instruction in the entire< application that is sampled. The number of times a vectorC instruction is used lets you see if your application is spendingC a lot of time performing certain operations. For example, if youA see that the SYNC vector instruction is executed more than anyD other vector instruction, you can infer that the scalar processorB is spending too much idle time waiting for the vector processor to finish an operation. -2 Finding_Where_Vector_Instructions_are_UsedC To find where in your program you are using vector instructions, use the following command:5 PCAA> PLOT/VCOUNTERS PROGRAM_ADDRESS BY VINSTRUCTION? This command displays the address of each vector instructionD that is used in your program and shows what percentage of program/ execution time is spent on each instruction. 2 System_ConfigurationsC The following illustrates the possible system configurations and their effect on performance:' o CPU1 and CPU2 with VVIEF support:C Efficent for program d evelopment, but can be 3-5 times slower> than the scalar performance. Cost-effective for parallel5 applications that do not use vector processing.( o CPU1 - CPU2 with Vector processor:D Efficent vector performance: As soon as a processor issues itsA first vector instruction, VMS schedules it only for vector-@ present(VP) CPU2. If the process is executing on CPU1, VMS> swaps out and gives it to CPU2. If CPU2 is not free, theA process waits for it to become free: VMS does not use VVIEF on this system. o CPU1 and CPU2:D Fatal to vector programs. They will fail when the first vector? instruction issues and neither VVIEF nor any other vector processors are present.+ o CPU1 and CPU2 with Vector processors:C Most efficent parallel-vector performance and cost-effective.; o CPU1 and CPU2 - CPU3 and CPU4 with Vector processors:+ Efficent parallel-vector performance. 3 VVIEF_on_ VAX_MultiprocessorsA If no vector-present CPU is available, OpenVMS executes vectorB instructions using the VAX Vector Instruction Emulator Facility7 (VVIEF), which is much slower than scalar execution.& NOTEA VVIEF must be enabled on the OpenVMS system; it is disabledB by default. To enable VVIEF, the system manager must execute< the command file SYS$UPDATE:VVIEF$INSTAL.COM. For more; information, refer to your OpenVMS documentation set. wwF f 1 @file-spec PCA Command; Executes PCA commands contained in the specified command? procedure or requests that PCA read subsequent command input% from the specified file or device. Format @ file-spec 2 Parameters file-spec@ Specifies the command procedure to execute or the device from? which to read input. File-spec can be any valid OpenVMS fileC specification. If no file type is specified, th e default is PCAC8 when in the Collector, and PCAA when in the Analyzer. 2 Description< The @file-spec command causes PCA to read and execute theB commands contained in the specified command procedure as if the? commands were entered at the terminal. The command procedureA may contain any valid PCA commands, including other @file-spec commands.@ When PCA executes an EXIT command in the command procedure orA reaches the end of the file, it returns control to the commandA stream that invoked the command procedure. That command stream? can be the terminal or a previous command procedure. Command- procedure nesting is limited to 16 levels.B If you enter the SET VERIFY command, all commands read from the* command procedure echo on the terminal. 2 Examples PCAC> @CMD_FILE.PCAC= This command reads Collector commands from the file CMD_? FILE.PCAC until an EXIT command is encountered in the file' or the end of the file is reached. wwF f 1 APPEND Analyzer CommandA Appends the output from the most recent PLOT, TABULATE or LIST$ command to an existing text file. Format APPEND [file-spec] 2 Parameters file-spec= Specifies the file to which the output from the last PLOT,> TABULATE or LIST command will be appended. The default file= specification is taken from the most recent FILE or APPEND command. 2 Description= The APPEND Analyzer command allows you to concatenate manyB separate histograms, tables or listings into a single file. YouB can specify a file, or accept the most recently created file as- the default; however, the file must exist. 2 Examples& PCAA> TABULATE/SOURCE PROGRAM BY LINE$ PCAA> APPEND [MYDIR]FOOLINES.PCALIS> %PCA-I-APPFILE, appending to file DEV$:[MYDIR]FOOLINES.PCALIS? A table is generated with the TABULATE command. That tableB is then appended to the existing text file FOOLINES.PCALIS in directory [MYDIR]. wwF f 1 ATTACH PCA Command? Passes control of your terminal from your current process to another process. Format ATTACH process-name 2 Parameters process-name@ Specifies an existing process to which you want to attach theB terminal. If the process name includes spaces, enclose the name in quotation marks. 2 DescriptionD The ATTACH command allows you to connect your terminal to anotherA process. Using the ATTACH command, you can switch control backB and forth between several different active processes. To createD additional processes, use the SPAWN command from within PCA or at DCL level. 2 Examples1 PCAC> SPAWN ! Spawn subprocess NICK_1: $ TYPE FOO.DAT ! Enter DCL commands in subprocess text line in foo.dat4 $ ATTACH NICK ! Attach to original process2 %PCA-I-RETURNED, control re turned to process NICK2 PCAC> SHOW LANGUAGE ! Enter Collector commands Language: PASCAL3 PCAC> ATTACH NICK_1 ! Attach back to subprocess9 %PCA-I-ATTACHED, terminal now attached to process NICK_1 $@ In this example, a subprocess is created with the Collector@ SPAWN command. DCL commands are executed in the subprocess.> An ATTACH command at DCL level reattaches the terminal to@ the Collector session. The Collector session continues withC additional Collector commands until a Collector ATTACH commandA is entered. This ATTACH command connects the terminal to the? subprocess again so that more DCL commands can be entered. wwF f1 BACK Analyzer Command; Traverses the current plot to display the previous leaf. Format BACK [parameter] 2 Parameters SUBTREE= Applies BACK to subtrees instead of to the list within theD subtree. The BACK SUBTREE command places the pointer at t he first$ leaf within the previous subtree. 2 Description> The BACK Analyzer command is one of a series of directionalB commands that allows you to traverse a program's structure. TheD BACK command displays the current plot, and positions an arrow toB point to the bucket with the next highest number of data points? (the previous leaf). The corresponding source lines for thatA portion of the program are displayed alongside the plot. Other1 traverse commands are FIRST, NEXT and CURRENT. wwV> f 1 CANCEL PCA Command@ Cancels a variety of data collection options, definitions and@ mode settings. The data collection option, definition or modeD setting canceled depends on the keyword specified on the command. Format! CANCEL keyword [parameters] 2 Parameters keywordD Specifies the data collection option, definition, or mode setting@ to cancel. Valid keywords in the Collector are ALL, COUNTERS,A COVERAGE, CPU_SAMPLING, DATAFILE, DISPLAY, EVENT, IO_SERVICES,> LOG, PAGE_FAULTS, PC_SAMPLING, SERVICES, SOURCE, STACK_PCS,= TASKING, UNALIGNED, VCOUNTERS, VCPU_SAMPLING, VERIFY, VPC_ SAMPLING and WINDOW.= Valid keywords in the Analyzer are ANC, DATAFILE, DISPLAY,7 FILTER, LOG, PLOT, SOURCE, TITLE, VERIFY and WINDOW. parameters$ Depends on the keyword specified. 2 DescriptionD CANCEL is not an individual command. Each CANCEL command consists= of the word CANCEL followed by a required keyword. See the> descriptions of the individual CANCEL commands for details. 2 ALL Collector Command' Cancels all data collection options. Format CANCEL ALL 3 Description? The CANCEL ALL Collector command cancels all data collection> options established with the SET commands listed below. PC_A SAMPLING with the sampling interval of 10 milliseconds becomes the new collection default.+ SET COUNTERS  SET COVERAGE$ SET CPU_SAMPLING EVENT- SET IO_SERVICES SET PAG_FAULTS+ SET PC_SAMPLING SET SERVICES, SET TASKING SET UNALIGNED0 SET VCOUNTERS SET VCPU_SAMPLING SET SET VPC_SAMPLING 2 ANC Analyzer CommandD Removes the ANC attribute from the specified coverage-set points. Format CANCEL ANC [nodespec] 3 Parameters nodespecA Provides the address location or locations for which to remove@ the ANC attribute from the coverage-set points in the currentC data file. For additional information on nodespecs, refer to the Nodespecs entry in PCA HELP. 3 Qualifiers /ALLD Removes the ANC attribute from all the coverage-set points in theA current data file. You cannot specify a nodespec with the /ALL qualifier. 2 COUNTERS Collector Command@ Cancels the collection of exact execution counts at specified program locations. Format/ CANCEL COUNTERS [nodespec, [nodespec...]] 3 Parameters nodespec; Specifies a node specification to be canceled. This node? specification must have been established with a previous SET COUNTERS command.? See HELP Nodespec for information about node specifications. 3 DescriptionC The CANCEL COUNTERS Collector command cancels execution counters? at the program locations specified by the node specification? or by the /ALL qualifier. Any node specifications you cancel@ must have been established by previous SET COUNTERS commands.> If you first set an execution counter at a program location@ with SET COUNTERS and then cancel it with CANCEL COUNTERS, noC execution count is measured at that location when the GO command is entered. 3 Qualifiers /ALLA Specifies that all execution counters established with earlier= SET COUNTERS commands be canceled. If you specify the /ALL+ qualifier, omit the node specifications. 3 Examples PCAC> CANCEL COUNTERS/ALL> This command cancels all previously established execution counters.) PCAC> CANCEL COUNTERS PROGRAM BY ROUTINE@ This command cancels the execution counters placed on every! routine in the user program. 2 COVERAGE Collector CommandD Cancels the collection of test coverage data at specified program locations. Format/ CANCEL COVERAGE [nodespec [,nodespec...]] 3 Parameters nodespec; Specifies a node specification to be canceled. This node? specification must have been established with a previous SET COVERAGE command.? See HELP Nodespec for information about node specifications. 3 DescriptionB The CANCEL COVERAGE Collector command cancels the collection ofD test coverage data at the program locations specified by the nodeB specification or by the /ALL qualifier. Any node specificationsA you cancel must have been established by previous SET COVERAGE@ commands. If you first establish test coverage measurement at? a program location with SET COVERAGE and then cancel it withD CANCEL COVERAGE, no data is gathered at that location when the GO command is entered. 3 Qualifiers /ALL@ Specifies that all test coverage breakpoints established with@ earlier SET COVERAGE commands be canceled. If you specify the0 /ALL qualifier, omit the node specifications. 3 Examples PCAC> CANCEL COVERAGE/ALLB This command cancels all previously established test coverage breakpoints.* PCAC> CANCEL COVERAGE PROGRAM BY CODEPATH> This command cancels the test coverage breakpoints on all# codepaths in the user program. 2 CPU_SAMPLING Collector Command0 Disables the collection of CPU sampling data. Format CANCEL CPU_SAMPLING 3 DescriptionD The CANCEL CPU_SAMPLING Collector command disables the collectionA of CPU sampling data. It thus cancels the effect of an earlier SET CPU_SAMPLING command. 2 DATAFILE PCA CommandB Cancels the performance data file established with the last SET DATAFILE command. Format CANCEL DATAFILE 3 DescriptionB The CANCEL DATAFILE command closes the current performance dataB file. The Collector does not record data in that file when dataC collection starts. Instead, it uses the default data file or theB data file you establish with a subsequent SET DATAFILE command.? The Analyzer does not read or process data until another SET DATAFILE command is entered. 2 DISPLAY PCA Command) Deletes the specified screen displays. Format6 CANCEL DISPLAY [display-name [,display-name...]] 3 Parameters display-name> Specifies a screen display to be canceled. If you specify a/ display-name, do not use the /ALL qualifier. 3  DescriptionD The CANCEL DISPLAY command cancels the specified screen displays.C When a screen display is canceled, it disappears from the screen8 and its contents and definition are permanently lost. 3 Qualifiers /ALLA Cancels all screen displays (except PROMPT) including the PCA-= defined PLOT, SOURCE and OUT displays. After canceling all? displays, you must use the SET DISPLAY command to create newD screen displays if you want to select them for use in screen mode@ (see SELECT command). If you use the /ALL qualifier, omit the display-name list. 3 Examples PCAA> CANCEL DISPLAY FOO7 This command removes the screen display named FOO. 2 EVENT Collector CommandD Cancels the collection of event markers established with previous SET EVENT commands. Format9 CANCEL EVENT [event-name [nodespec [,nodespec...]]] 3 Parameters event-name> Specifies the name of an event for which event markers willA be canceled. This event name must have been established with a previous SET EVENT command. nodespecD Specifies a node specification already associated with the event-D name event through a previous SET EVENT command. The CANCEL EVENTA command breaks the association between this node specification and the event-name event.B See HELP NODESPECS for more information on node specifications. 3 Description? The CANCEL EVENT Collector command cancels the collection ofA event markers for a specified event when the specified programC locations associated with that event are executed. Event markersD for the event-name event are thus not recorded in the performance> data file when these program locations are executed. If you= specify an event-name without a program location, then allA program locations associated with the event-name are canceled. 3 Qualifiers /ALLA Specifies that the collection of all event markers establishedB with earlier SET EVENT commands be canceled. If you specify the? /ALL qualifier, omit the event-name and prog-loc parameters. 3 Examples) PCAC> CANCEL EVENT COMPUTE LINE %LINE 22@ This command cancels the event marker established for event' COMPUTE at line 22 of the program. PCAC> CANCEL EVENT TERM_IO? This command cancels all the event markers established for event TERM_IO. 2 FILTER Analyzer CommandC  Deletes filters established with the SET FILTER command. FiltersD specify which data points from the performance data file to tally in histograms and tables. Format3 CANCEL FILTER [filter-name [,filter-name...]] 3 Parameters filter-nameD Specifies an existing filter to cancel. The filter must have been. created with an earlier SET FILTER command. 3 DescriptionC The CANCEL FILTER Analyzer command deletes the specified filtersD so they no longer filter the performance or coverage data used byD the PLOT and TABULATE commands. Filters are established using the SET FILTER command. 3 Qualifiers /ALLB Specifies that all currently defined filters be deleted. If you; use the /ALL qualifier, omit the filter-name parameters. 3 Examples PCAC> CANCEL FILTER FOO, BARA This command cancels the previously set filters FOO and BAR. 2 IO_SERVICES Collector Command0 Disables the collection of I/O services data. Format CANCEL IO_SERVICES 3 DescriptionC The CANCEL IO_SERVICES Collector command disables the collectionA of I/O services data. It thus cancels the effect of an earlier SET IO_SERVICES command. 2 LOG PCA Command@ Disables the recording of PCA input and output in a log file. Format CANCEL LOG 3 DescriptionD The CANCEL LOG command disables the recording of input and outputC in a log file. Input and output logging is established using the SET LOG command. 2 PAGE_FAULTS Collector Command. Disables the collection of page fault data. Format CANCEL PAGE_FAULTS 3 DescriptionC The CANCEL PAGE_FAULTS Collector command disables the collectionC of page fault data. It thus cancels the effect of an earlier SET PAGE_FAULTS command. 2 PC_SAMPLING Collector Command< Disables the collection of program counter sampling data.  Format CANCEL PC_SAMPLING 3 DescriptionC The CANCEL PC_SAMPLING Collector command disables the collectionB of program counter sampling data. It thus cancels the effect of& an earlier SET PC_SAMPLING command. 2 PLOT Analyzer Command8 Resets the SET PLOT defaults to their initial values. Format CANCEL PLOT 3 Description? The CANCEL PLOT Analyzer command resets the SET PLOT defaultC qualifiers to their initial values. It also cancels the SET PLOTA node specifications, if defined. The SET PLOT defaults are set? with the SET PLOT command and specify qualifier defaults forC PLOT and TABULATE commands which have node specifications. (PLOT? and TABULATE commands without node specifications take theirB defaults from the currently active plot.) The SET PLOT defaults@ also specify all qualifier and nodespec defaults for PLOT and6 TABULATE commands that have the /DEFAULT qualifier.8 The CANCEL PLOT command resets the default qualifiers5 to the following values: /PC_SAMPLING, /NOMINIMUM,6 /NOMAXIMUM, /NOCUMULATIVE, /NOMAIN_IMAGE, /NOSCALE,? /DESCENDING, /SOURCE, /NOSTACK_DEPTH, /ZEROS, /NOCHAIN_NAME,< /NOPATH_NAME, /NOWRAP, /NOPARENT_TASK, /NOCREATOR_PC, and+ /FILL=("*","O","x","@",":","#","/","+").= This command also resets the default node specification to PROGRAM_ADDRESS BY ROUTINE. 2 SERVICES Collector Command3 Disables the collection of system services data. Format CANCEL SERVICES 3 DescriptionC The CANCEL SERVICES Collector command disables the collection ofA system services data. It thus cancels the effect of an earlier SET SERVICES command. 2 SOURCE PCA CommandD Cancels the current source file directory search list established& with a previous SET SOURCE command. Format CANCEL SOURCE 3 Description> The CANCEL SOURCE command cancels the source file directoryD search list established with a previous SET SOURCE command. AfterC the directory search list is canceled, PCA is unable to find anyC source file which has been moved or copied since being compiled.A If you have established a directory search list for a specificB module with the SET SOURCE/MODULE=modname command, you must useD the same /MODULE qualifier on the CANCEL SOURCE command to cancel that search list.? If you have established a directory search list for the EDIT> command using the SET SOURCE/EDIT command, you must use theC same /EDIT qualifier on the CANCEL SOURCE command to cancel that search list. 3 Qualifiers /EDITD Specifies that the EDIT command directory search list establishedD with a previous SET SOURCE/EDIT command be canceled. This command? should only be used if the EDIT command has its own specific directory search list. /MODULE /MODULE=module-nameA Specifies that the directory search list for a specific module; established with a previous SET SOURCE/MODULE command beB canceled. This qualifier should be used only if the module-name5 module has its own specific directory search list. 3 Examples PCAA> CANCEL SOURCE PCAA> SHOW SOURCE No source directory search listA The above CANCEL SOURCE command cancels any directory searchB list previously established for all modules with a SET SOURCE command. 2 STACK_PCS Collector CommandD Disables the collection of stack PC values (return addresses from9 the call stack) when other kinds of data are gathered. Format CANCEL STACK_PCS 3 DescriptionA The CANCEL STACK_PCS Collector command disables the collectionD of call stack PC values. It thus cancels the effect of an earlier SET STACK_PCS command. 2 TASKING Collector Command+ Disables the collection of tasking data. Format CANCEL TASKING 3 Description@ The CANCEL TASKING command disables the collection of taskingC data established with any previously issued SET TASKING command. 2 TITLE Analyzer CommandD Cancels the title text for histograms and tables established with a previous SET TITLE command. Format CANCEL TITLE 3 Description; The CANCEL TITLE Analyzer command deletes the title textB established with the last SET TITLE command. That title text noD longer appears on each page of PLOT and TABULATE output. Instead,- the default title text appears as follows:? Performance and Coverage Analyzer for OpenVMS 2 UNALIGNED Collector Command: Disables the collection of unaligned access fault data. Format CANCEL UNALIGNED 3 DescriptionA The CANCEL UNALIGNED Collector command disables the collectionC of unaligned access fault data. It thus cancels the effect of an! earlier SET UNALIGNED command. 2 VCOUNTERS Collector CommandC Cancels the collection of vector instruction counts at specified program locations. Format1 CANCEL VCOUNTERS [nodespec [, nodespec...]] 3 Parameters nodespec; Specifies a node specification to be canceled. This nodeB specification must have been established with the SET VCOUNTERS command. 3 DescriptionC The CANCEL VCOUNTERS command cancels vector instruction counters? at the program locations specified by the node specificationB or by the /ALL qualifier. If you first set a vector instructionC counter at a program location with SET VCOUNTERS and then cancelC it with CANCEL VCOUNTERS, no execution count is measured at that+ location when the GO command is entered. 3 Qualifiers /ALLB Specifies that all vector instruction counters established withA earlier SET VCOUNTERS commands be canceled. If you specify the0 /ALL qualifier, omit the node specifications. 3 Examples PCAC> CANCEL VCOUNTERS/ALL; This command cancels all previously established vector instruction counters.3 PCAC> CANCEL VCOUNTERS ROUTINE FOO BY VINSTRUCTIONB This command cancels the vector instruction counters place in% routine FOO in the user program. 2 VCPU_SAMPLING Collector Command7 Disables the collection of vector CPU sampling data. Format CANCEL VCPU_SAMPLING 3 Description: The CANCEL VCPU_SAMPLING Collector command disables the= collection of vector CPU sampling data established with an% earlier SET VCPU_SAMPLING command. 2 VERIFY PCA Command9 Disables the echoing of command input to the terminal. Format CANCEL VERIFY 3 DescriptionB The CANCEL VERIFY command disables the echoing of command inputB to the terminal. It cancels the effect of an earlier SET VERIFY command. 2 VPC_SAMPLING Collector Command6 Disables the collection of vector PC sampling data. Format CANCEL VPC_SAMPLING 3 DescriptionD The CANCEL VPC_SAMPLING Collector command disables the collectionB of vector PC sampling data established with an earlier SET VPC_ SAMPLING command. 2 WINDOW PCA Command& Deletes a screen window definition. Format3 CANCEL WINDOW [window-name [,window-name...]] 3 Parameters window-nameC Specifies the name of a screen window def inition to be canceled. 3 Description@ The CANCEL WINDOW command cancels the specified screen windowA definitions. After a window definition has been canceled, that> window name can no longer be used on DISPLAY or SET DISPLAY? commands. Only the definition of the window name is deleted;? the actual screen region specified by the window name is not? affected. Screen displays that were declared with the windowC name are not affected except that the SHOW DISPLAY command showsB numeric window coordinates instead of the canceled window name. 3 Qualifiers /ALL< Specifies that all screen window definitions be canceled,? including all window definitions predefined by the Analyzer.B If you use the /ALL qualifier, omit the window-name parameters. 3 Examples PCAC> SHOW WINDOW SMALL window SMALL at (1,2,1,80) PCAC> CANCEL WINDOW SMALL PCAC> SHOW WINDOW SMALL window(s) not defined> Above, the CANCEL WINDOW command is used to cancel window< SMALL, which was previously defined with the SET WINDOW command. wwv f 1 CURRENT Analyzer CommandA Displays the current traverse subtree. Used within a series of8 traverse commands, essentially to refresh the screen. Format CURRENT [parameter] 2 Parameters SUBTREE2 Displays the current subtree at its first leaf. 2 DescriptionA The CURRENT Analyzer command is one of a series of directional> commands that allows you to traverse a program's structure.@ Depending on the command (FIRST, BACK, or NEXT), a pointer isA placed at plot locations of interest to you. The corresponding= source lines for that portion of the program are displayedC alongside the plot. However, the CURRENT command does not changeA the position of the pointer. Rather, it redisplays the currentC plot with the pointer and corresponding source lines in the same position.B The CURRENT SUBTREE command displays the current subtree at its0 first leaf (equivalent to the FIRST command). wwv f 1 DEFINE PCA CommandB Command keyword for the commands DEFINE/COMMAND and DEFINE/KEY.C DEFINE/COMMAND establishes command abbreviations, and DEFINE/KEY" establishes keypad definitions. Format DEFINE/COMMAND parameters DEFINE/KEY parameters 2 Parameters parameter& Depends on the qualifier specified. 2 /COMMAND PCA Command@ Defines a command synonym by associating a symbol name with a$ list of one or more PCA commands. Format3 DEFINE/COMMAND symbol-name = "command-string" 3 Parameters symbol-nameA Specifies the symbol name that you want associated with a listD of PCA commands. The symbol name can be up to 255 characters longB and may include letters, digits, underscores, and dollar signs.C It cannot start with a digit. If symbol-name is already defined,2 the new definition replaces the old definition. command-stringD Specifies the string of PCA commands to associate with the symbolC name. The command string must be enclosed in quotation marks andD consist of the first part of a PCA command, a whole command, or a+ list of commands separated by semicolons 3 DescriptionA The DEFINE/COMMAND command associates a symbol name with a PCAA command string. The command string consists of one or more PCAC commands separated by semicolons, and must end with a partial orC full PCA command. When the symbol name appears at the start of aD subsequent PCA command, it is replaced by the command string. TheA resulting string is parsed and executed by PCA. DEFINE/COMMANDA thus gives you the same command abbreviation capability as theA symbol assignment statement (symbol-name := command-string) inC DCL. The command string may contain previously defined commands,@ when those symbols translate directly into PCA commands. (PCA- supports one level of symbol translation.)7 To display the current symbol definitions created by7 DEFINE/COMMAND, use the SHOW SYMBOL/DEFINED command. 3 Examples% PCAC> DEFINE/COMMAND SA = "SHOW ALL" PCAC> SA? This command associates the symbol SA with the PCA commandA SHOW ALL. When the SA command is used, SA is expanded to the8 equivalent command string, which PCA then executes. 2 /KEY PCA CommandA Associates a PCA command string and a set of attributes with a key on the terminal keyboard. Format* DEFINE/KEY key-name "command-string" 3 Parameters key-name( Specifies the key you want to define. command-stringB Specifies the command string to be processed when you press theC defined key. Enclose the command string in quotation marks if it contains a space. 3 Description? The DEFINE/KEY command assigns PCA command strings to keypadB keys. When you press the appropriate keypad key, PCA enters the4 associated command string into your command line.> The key definition remains in effect until you redefine the@ key (by issuing another DEFINE/KEY command for the same KEY),> issue the DELETE/KEY command for that key, or exit. You can? include key definitions in a command procedure, such as your PCA initialization file. 3 Qualifiers /ECHO /ECHO /NOECHOA Determines whether the equivalence string is displayed on yourB terminal after you press the defined key. The default is /ECHO.= You cannot use the /NOECHO qualifier with the /NOTERMINATE qualifier. /IF_STATE" /IF_STATE=(state-name[,...]) /NOIF_STATEC Specifies one or more states, one of which must be in effect for@ the key definition to be processed. If you omit the /IF_STATEB qualifier or if you use /NOIF_STATE, the current state is used.C The state-name is an alphanumeric string. States are established8 with the /SET_STATE qualifier or the SET KEY command. /LOCK_STATE /LOCK_STATE /NOLOCK_STATEC Specifies that the state set by the /SET_STATE qualifier remainsC in effect until explicitly changed. If you use the /NOLOCK_STATEC qualifier, the state set by /SET_STATE is in effect only for the@ next definable key you press or for the next read-terminating character you type.A The default is /NOLOCK_STATE unless you specify the /TERMINATE qualifier. /LOG /LOG /NOLOG@ Controls whether the system displays a log message indicatingC that a key definition has been successfully created. The default is /LOG. /SET_STATE /SET_STATE=state-name /NOSET_STATE< Causes the specified state-name to be set when the key is: pressed. The state-name can be any alphanumeric string.C If you omit the /SET_STATE qualifier or if you use /NOSET_STATE,@ the current state that was locked remains in effect after youA press the defined key. If you have not included this qualifierC with a key definition, you can use the SET KEY command to change the current state. /TERMINATE /TERMINATE /NOTERMINATE= Determines whether the current equivalence string is to beB terminated (that is, processed as command input) when you press= the defined key. The default is /NOTERMINATE, which allowsA you to enter additional input before the equivalence string isD processed. Pressing the RETURN key after pressing the defined keyA has the same effect as using /TERMINATE in the key definition. 3 Examples/ PCAC> DEFINE/KEY/TERMINATE KP7 "SHOW ALL/FULL"A This command associates the keypad key KP7 (the 7 key on the@ numeric keypad) with the SHOW ALL/FULL command. Because the? /TERMINATE qualifier is used, you do not need to press theB RETURN key after pressing the KP7 key to execute the command. ww f 1 DELETE PCA CommandB Command keyword for the commands DELETE/COMMAND and DELETE/KEY.? These commands delete command abbreviations established withD DEFINE/COMMAND or keypad definitions established with DEFINE/KEY. Format DELETE/COMMAND parameters DELETE/KEY parameters 2 Parameters parameters% Depend on the qualifier specified. 2 /COMMAND PCA CommandB Deletes command definitions established with the DEFINE/COMMAND command. Format1 DELETE/COMMAND symbol-name[,symbol-name...] 3 Parameters symbol-nameC Specifies the name of a command symbol whose definition is to beC deleted. This symbol name must have been defined with a previous DEFINE/COMMAND command. 3 Description@ The DELETE/COMMAND command is used to delete command synonyms/ established with the DEFINE/COMMAND command. 3 Examples PCAC> DELETE/COMMAND FOO, FEEA This example shows how to delete the command definitions for symbols FOO and FEE. 2 /KEY PCA CommandC Deletes key definitions established with the DEFINE/KEY command. Format DELETE/KEY [key-name] 3 Parameters key-name= Specifies the name of the key whose definition you want to delete. 3 Description= The DELETE/KEY command deletes key definitions established>  with the DEFINE/KEY command. The DELETE/KEY command and the2 UNDEFINE/KEY command perform the same function. 3 Qualifiers /ALL? Specifies that all key definitions in the specified state be? deleted. If you use the /ALL qualifier, do not specify a keyB name. If you do not specify a state, all key definitions in theA current state are deleted. Use the /STATE qualifier to specify one or more states. /LOG /LOG /NOLOGB Controls whether a log message is displayed indicating that theB specified key definition has been deleted. The default is /LOG. /STATE /STATE=(state-name [,...]) /NOSTATEB Specifies the names of the states under which the specified key? definitions are to be deleted. If you specify only one state> name, you can omit the parentheses. A state name can be any# appropriate alphanumeric string.> If you omit the /STATE qualifier of if you use the /NOSTATE? qualifier, key definitions in the current state are deleted. 3 Examples PCAC> DELETE/KEY KP7A This command shows how to delete the key definitions for the6 keypad key KP7 (the 7 key on the numeric keypad). ww f 1 DISPLAY PCA CommandC Outputs the specified displays on the terminal screen or changesD the attributes of those screen displays. Also used to refresh the terminal screen. Format> DISPLAY [display-name [AT window-spec] [display-kind] [,> display-name [AT window-spec)] [display-kind]]]) DISPLAY/REFRESH 2 Parameters display-nameB Specifies the name of a screen display that you want to view or@ whose characteristics you want to modify. This screen displayB must be predefined (PLOT, SRC, OUT or PROMPT) or defined with a previous SET DISPLAY command. window-spec@ Specifies a new screen window for the display. If you specify@ window-spec, the display is shown in that window. If you omit: window-spec, the display remains in its current window.B Window-spec can be the name of a predefined window, the name ofC a window you have defined with a SET WINDOW command, or a window specification of the form: 1start-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 theB number of columns in the window, respectively. Start-column andA column-count default to column 1 and the current screen width, respectively. display-kind@ Specifies a new display kind; OUTPUT, SOURCE and PLOT are theD valid keywords. OUTPUT indicates a regular output display for theB SHOW and LIST commands. PLOT indicates a display that holds theC output of the PLOT or TABULATE command. The SOURCE display holdsA the output from the TYPE command. If you omit the display-kind5 parameter, the kind of the display is not changed. 2 DescriptionA The DISPLAY command performs a variety of functions. Its major; function is to show the contents of the specified screenA displays. Each specified display is placed on top of any otherC displays that occupy overlapping windows on the terminal screen.D The specified displays then become fully visible and any displays they overlap are hidden.@ You can also use the DISPLAY command to change the attributesA of the specified screen displays. You can create displays thatC do not appear on the screen, you can change their sizes, you canB clear their contents, and you can change their window locations and display kinds. 2 Qualifiers /CLEAR= Erases the entire textual contents of the specified screen displays. /DYNAMIC /DYNAMIC /NODYNAMIC> Controls whether a display automatically adjusts its windowC dimensions proportionally when a SET TERMINAL command is issued. /DYNAMIC is the default. /HIDEA Conceals the display under any other displays that overlap it.B As a result, any displays that were previously hidden under the$ specified display become visible. /POP /POP /NOPOP< /POP places a specified display at the top of the display@ pasteboard, ahead of any other displays. This is the default.@ /NOPOP preserves the order of all displays on the pasteboard. /PUSH /PUSH /NOPUSHB /PUSH has the same effect as /HIDE. /NOPUSH preserves the order= of all displays on the pasteboard (same effect as /NOPOP). /REFRESH@ Refreshes the terminal screen. Do not use parameters or other+ qualifiers on a DISPLAY/REFRESH command. /REMOVE< Creates a display that does not appear on the screen. Its@ definition and textual contents are saved, and can be brought% back with another DISPLAY command. /SIZE /SIZE:nB Changes the maximum size of a normal output display to n lines.D If more than n lines are written to the display, the oldest linesC are lost as the new lines are added. If you omit this qualifier,# the maximum size is not changed. 2 Examples PCAA> DISPLAY PLOTA This command displays the screen display named PLOT. PLOT is= placed over any other displays with overlapping windows. PCAA> DISPLAY/SIZE:200 OUTA This command changes the size of the OUT display so that OUT= holds the 200 most recent lines of output instead of the> default 100 lines. It also places OUT on top of any other' displays with overlapping windows. wwڦ f1 EDIT Analyzer Command> Allows you to use an editor (such as the Language Sensitive@ Editor) to edit the source file displayed by the current PLOT or TABULATE command.  Format' EDIT [[module-name\] line-number] 2 Parameters module-nameC Positions the editor in the specified module. When you specify a/ module, you must also specify a line number. line-numberD Positions the editor at the specified line number. If you specifyC a line-number without a module-name, the module is assumed to beB the module at which you are currently positioned in the PLOT orB TABULATE source display. If you do not specify line-n umber, the@ editor is positioned at the line at the center of the current# page of PLOT or TABULATE output. 2 Description= The EDIT command invokes an editor to edit the source fileA displayed by the current PLOT or TABULATE command. To edit theD default module, use a traverse command (see the Traverse_CommandsB topic in HELP) or the /SOURCE qualifier on the PLOT or TABULATE? command and use a BY LINE or BY CODEPATH node specification.> If you specify no parameter on the EDIT command, the editorA is positioned at the central line of the PLOT or TABULATE pageD currently shown on your terminal. The module-name and line-numberD parameters allow you to position the editor at a different source file or line.> When you exit from the editor, you are then returned to theC Analyzer session. However, if you use the /EXIT qualifier on theB EDIT command, the Analyzer session is terminated and the editor" is invoked in the same process.D The editor you call must be accessible from DCL level, and may be# set with the SET EDITOR command. 2 Qualifiers /EXIT /EXIT /NOEXIT= The /EXIT qualifier terminates the Analyzer session beforeB invoking the editor. The editor is then run in the same process= and you are returned to DCL level when exiting the editor.A The /NOEXIT qualifier returns you to the Analyzer session when/ you exit the editor. /NOEXIT is the default. wwڦ f 1 EXCLUDE Analyzer CommandB Excludes one data kind from a multiple data-kind plot or table.? Multiple data-kind plots are created by the INCLUDE command. Format EXCLUDE n 2 Parameters n> The parameter n is an integer representing the data kind to? remove from the plot. This integer must be greater than one,B because the data kind placed in the plot by the initial PLOT orB TABULATE command is the first data kind and cannot be excluded.A The data kind on the following line is considered to be number> two, and so on. The default is the last data kind included. 2 DescriptionB The EXCLUDE command removes one data kind from a multiple data-B kind plot. EXCLUDE provides an incremental approach to buildingA a plot or table. After you execute this command, a new plot or" table is created and displayed. 2 Examples PCAA> EXCLUDE 6B This command creates, then displays, a new plot or table that" excludes the sixth data kind. wwڦ f1 EXIT PCA CommandB Ends the current session or ends the execution of commands in a command procedure. Format EXIT 2 DescriptionD When you enter the EXIT command at the terminal, the session endsD and you return to DCL level. You can also enter CTRL/Z to end the session.D When PCA executes an EXIT command in a command procedure, controlD returns to the command stream that invoked the command procedure.@ This command stream may be the terminal or a previous command procedure. wwڦ f 1 EXPAND PCA CommandD Expands or contracts the window associated with a screen display. Format EXPAND [disp-name[,...]] 2 Parameters disp-nameD Specifies a display to be expanded or contracted. You may specify any of the following:2 o A predefined display: SRC, OUT, PROMPT, PLOT? o A display previously created with the SET DISPLAY command= o A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP,6 %NEXTOUTPUT, %NEXTPLOT, %NEXTSCROLL, %NEXTSOURCEB If you do not specify a display, the current scrolling display,: as established by the SELECT/SCROLL command, is chosen. 2 Description> The EXPAND command moves one or more display-window borders= according to the qualifiers specified (/UP[:n], /DOWN[:n], RIGHT[:n], /LEFT[:n]).? The EXPAND command does not affect the order of a display on= the display pasteboard. Depending on the relative order ofB displays, the EXPAND command may cause the specified display toC hide or uncover another display or be hidden by another display, partially or totally.B Except for the PROMPT display, any display can be contracted to@ the point where it disappears (at which point it is marked asC "removed"). It can then be expanded from that point. Contracting> a display to the point wh ere it disappears will cause it to< lose any attributes that were selected for it. The PROMPT@ display cannot be contracted or expanded horizontally but can5 be contracted vertically to a height of two lines.= A window border can be expanded only up to the edge of theD screen. The left and top window borders cannot be expanded beyondA the left and top edges of the display, respectively. The rightA border can be expanded up to 255 columns from the left displayD edge. The bottom border of a display can be expanded down only toD the bottom edge of the plot's summary page display (to the end of the source module).+ You must specify at least one qualifier. 2 Qualifiers /DOWN /DOWN[:n]B Moves the bottom border of the display down by n lines (if n isB positive) or up by n lines (if n is negative). If n is omitted,( the border is moved down by one line. /LEFT /LEFT[:n]D Moves the left border of the display to the left by n lines (if nC is positive) or to the right by n lines (if n is negative). If n; is omitted, the border is moved to the left by one line. /RIGHT /RIGHT[:n]D Moves the right border of the display to the right by n lines (ifD n is positive) or to the left by n lines (if n is negative). If n< is omitted, the border is moved to the right by one line. /UP /UP[:n]= Moves the top border of the display up by n lines (if n isD positive) or down by n lines (if n is negative). If n is omitted,& the border is moved up by one line. 2 Examples PCAA> EXPAND/RIGHT:6= The EXPAND command moves the right border of the current1 scrolling display to the right by 6 columns. PCAA> EXPAND/UP/RIGHT:-12 OUT2D The EXPAND command moves the top border of display OUT2 up by 1: line, and the right border to the left by 12 columns. PCAA> EXPAND/DOWN:99 SRCC The EXPAND command moves the bottom border of display SRC down& to the bottom edge of the screen. ww f 1 EXTRACT PCA Command@ Saves the contents of a screen display in a file or creates aC file with all of the commands necessary to re-create the current screen state at a later time. Format+ EXTRACT [disp-name[,...]] [file-spec] 2 Parameters disp-name@ Specifies a display to be extracted. You can use the wildcardC character (*) in a display name. When using /ALL, do not specify a display name. file-specC Specifies the file to which the information will be written. You can specify a logical name.A If you specify /SCREEN_LAYOUT to save the configuration of theB screen, then the default specification for the file is PCA.PCAC= in the Collector, PCA.PCAA in the Analyzer. Otherwise, the) default file specification is PCA.TXT. 2 Description= When you use the EXTRACT command to save the contents of aB display into a file, only those lines that are currently stored= in the display's memory buffer (as determined by the /SIZE? qualifier on the DISPLAY or SET DISPLAY command) are written to the file.? You cannot extract the contents of the PROMPT display into a file. 2 Qualifiers /ALLC Extracts all displays. If /ALL is used, do not specify a display1 name. Do not specify /SCREEN_LAYOUT with /ALL. /APPEND> Appends the information at th e end of the file, rather thanA creating a new file. By default, a new file is created. Do not' specify /SCREEN_LAYOUT with /APPEND. /SCREEN_LAYOUTB Writes a file that contains the commands describing the currentC state of the screen. This information includes the screen heightD and width, and the position, display kind, and display attributesA of every existing display. This file can then be executed withD the @file-spec command to reconstruct the screen at a later time. 2 Examples PCAA> EXTRACT SRC? This command writes all the lines in display SRC into file PCA.TXT., PCAA> EXTRACT/APPEND OUT [STEVE.WORK]MYFILED This command appends all the lines in display OUT to the end of! file [STEVE.WORK]MYFILE.TXT. PCAA> EXTRACT/SCREEN_LAYOUTC This command writes the PCA commands needed to reconstruct the screen into file PCA.PCAA. ww f1 FILE Analyzer CommandB Writes the output from the most recent PLOT, TABULATE, INCLUDE,5 EXCLUDE, LIST, or traverse command to a text file. Format FILE file-spec 2 Parameters file-spec= Specifies the file to which the output from the last PLOT,? TABULATE, INCLUDE, EXCLUDE, LIST or traverse command will beA written. The file-spec parameter can be any valid OpenVMS file> specification. If no file type is specified, it defaults to PCALIS. 2 DescriptionC The FILE Analyzer c ommand writes the output from the most recent@ PLOT, TABULATE, INCLUDE, EXCLUDE, LIST or traverse command to? a file. Thus, to write a histogram, table, or listing of rawD performance data to a file, first enter a command to generate theA report on the terminal, and then enter a FILE command to writeA that report to a file. The text file can be printed or used as input to other programs.A When writing histograms and tables to a file, the FILE commandB assumes that there are 66 lines per page and formats the output> accordingly. You can change the number of lines per page by7 defining the logical name SYS$LP_LINES at DCL level.D You can concatenate many separate histograms, tables, or listings2 into a single file by using the APPEND command. 2 Examples) PCAA> PLOT/IO_SERVICE MODULE FOO BY LINE PCAA> FILE FOOLINES: %PCA-I-CREFILE, creating file DEV$:[MYDIR]FOOLINES.PCALISC A histogram is generated with the PLOT command. That histogram6 is then written to the text file FOOLINES.PCALIS. PCAA> LIST ALL PCAA> FILE PING.DAT3 %PCA-I-CREFILE, creating file DEV$:[MYDIR]PING.DAT> A listing of all raw data in the performance data file is@ generated with the LIST command. (If the output is long, it@ can be stopped with CTRL/C.) That listing is written to theC file PING.DAT. This file can later be printed or used as input- to a data reduction program of your own. ww f1 FIND Analyzer Command> Finds and displays the page of PLOT or TABULATE output thatB contains the histogram bar or table entry for a specified label or line number. Format FIND [label-name] 2 Parameters label-nameA Specifies a label, or bucket name, associated with a histogramD bar or table entry. The FIND command displays the first histogramA or table page that contains this label. If the label is a line? number, it must be specifie d as %LINE n, where n is the line> number. Asterisks in the label-name are treated as wildcardA characters. An asterisk (*) matches zero or more characters inB a bucket name. If the label-name parameter is omitted, the next< occurrence of the last label-name specified is displayed. 2 DescriptionA The FIND Analyzer command finds the first page of histogram orA table output that contains a specified label and displays that? page on the terminal. Thus, it is useful for quickly finding6 specific bucket names in long histograms or tables. 2 Examples PCAA> PLOT PROGRAM BY ROUTINE PCAA> FIND OUTPUT_TO_DATAFILEA A histogram is generated by the PLOT command. Each bucket inA the histogram corresponds to one routine in the program. The? FIND command displays the histogram page that contains the2 histogram bar for routine OUTPUT_TO_DATAFILE. PCAA> PLOT PROGRAM BY ROUTINE PCAA> FIND PRIM* PCAA> FINDC A histogram is generated by the PLOT command. The FIND commandC displays the first histogram page that contains a routine nameB that begins with PRIM. The second FIND command finds the next' occurrence of such a routine name., PCAA> TABULATE ROUTINE PRIM_NUM_GEN BY LINE PCAA> FIND %LINE 1024@ A table is generated by the TABULATE command. The page thatD contains the table entry for line 1024 is displayed by the FIND command. ww f1 FIRST Analyzer CommandD Positions the current traverse subtree to display its first leaf. Format FIRST [parameter] 2 Parameters SUBTREE> Applies FIRST to subtrees instead of to the list within the? subtree. The FIRST SUBTREE command places the pointer at the' first leaf within the first subtree. 2 Description? The FIRST command is one of a series of directional commands? that allows you to traverse a program's structure. The FIRST> command displays the current traverse subtree and positionsA an arrow to point to the bucket with the most data points. TheA corresponding source lines for that portion of the program areB displayed alongside the plot. Other traverse commands are NEXT, BACK, and CURRENT. ww f1 GO Collector Command1 Executes a program and starts data collection. Format GO 2 Description= The GO command executes a program and collects performance? o r coverage data while the program runs to completion. After; entering the GO command, you cannot enter more Collector commands.? If you do not establish a performance data file with the SETA DATAFILE command before entering the GO command, the CollectorD uses a default data file. The default data file has the same fileB name as your program's executable image file and a file type ofC .PCA. If you do not establish any data collection options beforeA entering the GO command, the Collector gathers program counter+ sampling data and stack data by default. 2 Qualifiers /NOCOLLECT> Executes the user program without collecting performance or coverage data. ww f1 HELP PCA Command= Displays information about PCA commands and features. ThisB information describes each command, its format, its qualifiers, and its parameters. Format HELP [topic [subtopic...]] 2 Parameters topicA Specifies the name of the command or topic with which you need help. subtopicB Specifies a particular qualifier or parameter on which you want? further information, or a keyword that gives you information- about a range of qualifiers or parameters. 2 Description: If you want information about a particular qualifier or? parameter, specify it as a subtopic. If you want informationC about all command qualifiers, specify "Qualifier" as a subtopic.D If you want information about all parameters, specify "Parameter"? as a subtopic. If you want all available information about aA command, specify an asterisk (*) as a subtopic. If you want toB redisplay the last help entry you viewed, enter a question mark (?). ww( f 1 INCLUDE Analyzer CommandA Adds a new data kind into the plot. This command allows you to: compare more than one data kind in the same collection. Format INCLUDE  2 DescriptionB The INCLUDE command adds a new data kind into the current plot.A It is used with the EXCLUDE command to incrementally build oneC plot that contains a maximum of eight data kinds per bucket. TheA data kinds must be compatible with the node specifications forC the current plot. If you want a new set or order of the buckets,A then you must issue a new PLOT or TABULATE command. The use of@ INCLUDE command qualifiers does not affect the old qualifiers? i n the PLOT/TAB default entry of the current active plot. If= no active plot is available an error message is displayed.? A different filter can be applied to the data kind for everyD INCLUDE command. The first page of the newly created plot appears after you issue the command. 2 Qualifiers /ANC. Adds this data kind to the current buckets. /COUNTERS. Adds this data kind to the current buckets. /COVERAGE. Adds this data kind to the current % buckets. /CPU_SAMPLING. Adds this data kind to the current buckets. /CREATOR_PCA Charges the data point to the program address that created the task. /NOCREATOR_PC< Charges the data point to the address of the data record. /FAULT_ADDRESS. Adds this data kind to the current buckets. /IO_SERVICES. Adds this data kind to the current buckets. /NONCOVERAGE. Adds this data kind to the current buckets. /PAGE_FAULTS. A$ dds this data kind to the current buckets. /PARENT_TASK< Charges the data point to the task that created the task. /NOPARENT_TASK& Charges the data point to the task. /PC_SAMPLING. Adds this data kind to the current buckets. /PHYSICAL_IO_COUNT. Adds this data kind to the current buckets. /READ_COUNT. Adds this data kind to the current buckets. /SERVICES. Adds this data kind to the current buckets. /TASK_SWITCH2 Adds " this Ada data kind to the current buckets. /UNALIGNED. Adds this data kind to the current buckets. /VCOUNTERS. Adds this data kind to the current buckets. /VCPU_SAMPLING. Adds this data kind to the current buckets. /VPC_SAMPLING. Adds this data kind to the current buckets. /WRITE_COUNT. Adds this data kind to the current buckets. /FILL /FILL=? Defines the fill to be used within a PLOT command. A maximum> of eight ch aracter strings can be defined, and each must beB delimited by double or single quotation marks. The default fill< characters are: (/FILL=\"*","^","@",">","o","#","$","x"). /DEFAULTC Applies the default characteristics from the SET PLOT command toC the specified data kind. Only the applicable qualifiers that are( following in the list may be applied. /CUMULATIVE /CUMULATIVE[=n]> Performs the cumulative tabulation for this data kind only. /MAIN_IM AGE /MAIN_IMAGE[=prog-unit]> Performs the main image tabulation for this data kind only. /NOCUMULATIVEA Does not perform the cumulative tabulation for this data kind. /NOMAIN_IMAGEA Does not perform the main image tabulation for this data kind. /NOSTACK_DEPTH2 Does not apply a stack depth to this data kind. /STACK_DEPTH /STACK_DEPTH=n< The stack is measured to a depth of n for this data kind. 2 Examples: PCAA> PLOT/MAIN/IO_SERVICES/FILL=("io","pc") PROG BY ROUT PCAA> INCLUDE/PC_SAMPLING) PCAA> INCLUDE/PHYSICAL_IO/FILL="phys_io"@ This series of commands plots I/O services, PC sampling and4 physical I/O data points in the same histogram. ww( f1 LIST Analyzer CommandA Displays raw performance or coverage data. Also displays other3 information stored in the performance data file. Format$ LIST data-kind [,data-kind...] 2 Parameters data-kindC Specifies a kind of performance or coverage data. All records inD the performance data file that contain the specified kind of data5 are listed. The valid data-kind parameters follow:! Keyword Description, ALL Lists all data records@ BEGIN_END Lists collection run begin and end records5 COUNTERS Lists execution counter records1 COVERAGE Lists test coverage records0 CPU_SAMPLING Lists CP U sampling records/ EVENTS List event marker records; IO_SERVICES Lists I/O system service call records. PAGE_FAULTS Lists page fault records< PC_SAMPLING Lists program counter sampling records> RUN_DESCRIPTION Lists collection run description records7 SERVICES Lists system service call records@ SHAREABLE_IMAGES Lists all shareable image name and address# range records+ TASKING Lists tasking re cords/ TASK_SWITCH Lists task switch records- UNALIGNED Lists unaligned records> VCOUNTERS Lists vector instruction counter recordsD VCPU_SAMPLING Lists CPU sampling records for code containing) vector instructions@ VPC_SAMPLING Lists program counter sampling records for9 code containing vector instructions 2 DescriptionB The LIST command displays information stored in the performanceB dat a file. If you specify data-kind parameters, it displays all> corresponding performance or coverage data records from the> file. Thus, you can inspect the raw performance or coverageA data gathered by the Collector. If you specify the appropriateD qualifiers, the LIST command displays other information stored inB the performance data file (see qualifier list). You must alwaysB request at least one kind of information from the LIST command.B The output of the LIST command is often extensive. You can stop& the LIST output by entering CTRL/C.D The LIST output can be sent to the printer with the PRINT command? or written to a file with the FILE command. If you write theB LIST output to a file, you can use it as input to your own data reduction programs. 2 Qualifiers /CODEPATHS= Lists the names of all modules for which codepath data was gathered. /COVERAGE_SET0 Lists the contents of the coverage-set table. /CPT,% Lists the contents of the codepath table. /DMT! Lists the contents of the DMT. /DST! Lists the contents of the DST. /EVENT_NAMES: Lists all event marker names recorded in the data file. /FILE_NAMES= Lists the names of all files opened or created by the user program. /GST! Lists the contents of the GST. /HEADER* Lists the performance data file header. /HEXADECIMAL< Lists all performance data records in hexadecimal form in$ addition to the normal text form. /IMAGED Lists information about the user program's executable image file. /LOST_DATA /LOST_DATA=[keyword]B Controls the output of lost data indications and the displaying of lost data records.+ The default qualifier is /LOST_DATA=ALL. Qualifier Keyword DescriptionE ALL Outputs any lost data indications and displays any lost data records.B NONE Does not output any lost data indications or display$ any lost data records.B PCA Outputs lost data indications and displays lost data/ records which were caused by PCA.B USER Outputs lost data indications and displays lost data4 records which were caused by the user. /NOLOST_DATA /NOLOST_DATA@ Does not output any lost data indications or display any lost data records.& This is the default LIST qualifier. /MODULE_NAMES@ Lists the names of all the modules in the image for which the data was collected. /SEQUENCE_NUMBERS /SEQUENCE_NUMBERSB Outputs sequence numbers when listing performance data records. /NOSEQUENCE_NUMBERS /NOSEQUENCE_NUMBERSA Does not output sequence numbers when listing performance data records.& This is the default LIST qualifier. /SHAREABLE_IMAGEC Lists the names of all shareable images used by the user program # or by the Collector. /START_TIME /START_TIME> Outputs CPU start and end times when listing system service records. /NOSTART_TIME /NOSTART_TIMED Output only the CPU end time when listing system service records.& This is the default LIST qualifier. /TASK_NAME Lists the task name section. /TASK_TYPE Lists the task type section. 2 Examples PCAA> LIST ALLC This command lists all performance or coverage data records in the data file.# PCAA> LIST IO_SERVICE, PAGE_FAULTS= This command lists only I/O services and page fault data records from the data file. PCAA> LIST/HEADER@ This command lists the header of the performance data file. PCAA> LIST VCOUNTERS@ This command lists the execution counter records for vector# instructions in the data file. wwO f1 MERGE Analyzer CommandD Combines several PCA performance data files into one file, and/orC combines data extracted from several SPM data files into one PCA data file. Format0 MERGE input-file-spec[,input-file-spec...] 2 Parameters input-file-specA Any valid OpenVMS file specification that identifies the filesC you want to merge or to take ANC information from. Wildcards mayC be used in the file name and/or in the extension. If you specify> the /SPM_PROCESS_ID qualifier, then the local node, currentB  default device and current default directory are assumed as theA default for each of the input file-specs provided, and defaultB file name extensions are not applied. If you do not specify theA /SPM_PROCESS_ID qualifier, then the same defaults are assumed,/ but the file name extensions default to PCA. 2 DescriptionC The MERGE command makes it possible for you to process data fromB several files by combining information from several performanceA data files into one PCA performance data file. You can use theD MERGE command to combine several PCA performance data files or toB combine data extracted from several SPM data files into one PCAD data file. This allows you to process and display the PC samplingC data collected by SPM (Software Performance Measurement). MergedC data is always appended to the currently opened performance data file. 2 Qualifiers /SPM_PROCESS_ID( /SPM_PROCESS_ID=(process-id[,...])A Merges the specified SPM data files. Each process-id parameterC must be a valid OpenVMS process identification number, specified@ as a hexadecimal number. You may omit the leading zeros. Each= collection of PC data is assigned a RUN_NAME identifier of@ the form SPM_n, where n is the OpenVMS process identificationC number that you specify in the process-id list. The data must beB collected for the image of the currently open data file. A listB of more than one number must be enclosed in parentheses. If youB omit this qualifier, the Analyzer assumes that all of the files are PCA performance files. /ANCD For PCA data files with identical image names, image identifiers,B link times and link identifiers; PCA writes all ANC (acceptableD non-coverage) information to the coverage-set table in the output file.D For PCA data files with identical image names and different imageC identifiers, link times or link identifiers; PCA writes only ANC@ (acceptab le non-coverage) information from the input PCA dataA file to the coverage-set table in the output file which can beB validated by the codepath data in both the input and output PCA data files.? /ANC and /SPM_PROCESS_ID cannot be used together in the same@ command. The /ANC qualifier can only be used when merging PCA performance data files. /SINCE /SINCE="time-spec" /BEFORE="time-spec"A Sets the lower and/or higher limits on the collection times of!C the SPM data being merged. These optional qualifiers can only beC specified together with the /SPM_PROCESS_ID qualifier. The time-D spec parameters must be enclosed within double quotation marks ("B ") and must be valid OpenVMS absolute date/time specifications,+ as described in the DCL Concepts manual. 2 Examples PCAA> SHOW DATAFILE0 Performance Data File: USRD$:[USER]PRIMES.PCA;1 PCAA> MERGE PRIMES.OLD;*' Merging file USRD$:[USER]PRIMES.OLD;2' Merging file U "SRD$:[USER]PRIMES.OLD;1 PCAA>= The MERGE command is used above to merge the contents of= all the versions of the performance data file PRIMES.OLDB found in the current default directory into the currently set) performance data file, PRIMES.PCA;1.= PCAA> MERGE/SPM=2A80B7/BEFORE="4-JUL-1987" SPM1.DAT,SPM2.DAT9 This MERGE command will merge into the currently set@ performance data file any PC sampling data found in the SPM> data files SPM1.DAT and SPM2.DA#T that have been collected< before July 4, 1987 for the process whose id number was 002A80B7 (hexadecimal). wwO f1 MOVE PCA CommandC Moves a screen display vertically and/or horizontally across the screen. Format MOVE [disp-name[,...]] 2 Parameters disp-name> Specifies a display to be moved. You may specify any of the following:2 o A predefined display: SRC, OUT, PROMPT, PLOT? o A display previo $usly created with the SET DISPLAY command= o A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP,6 %NEXTOUTPUT, %NEXTPLOT, %NEXTSCROLL, %NEXTSOURCEB If you do not specify a display, the current scrolling display,: as established by the SELECT/SCROLL command, is chosen. 2 Description@ For each display specified, the MOVE command simply creates aA window of the same dimensions elsewhere on the screen and mapsD the display to it, while maintaining the relative p%osition of the text within the window.A The MOVE command does not change the order of a display on theC display pasteboard. Depending on the relative order of displays,D the MOVE command may cause the display to hide or uncover anotherA display or be hidden by another display, partially or totally.< A display can be moved only up to the edge of the screen.+ You must specify at least one qualifier. 2 Qualifiers /DOWN /DOWN[:n]B Moves the d&isplay down by n lines (if n is positive) or up by nB lines (if n is negative). If n is omitted, the display is moved down by one line. /LEFT /LEFT[:n]A Moves the display to the left by n lines (if n is positive) orD right by n lines (if n is negative). If n is omitted, the display$ is moved to the left by one line. /RIGHT /RIGHT[:n]B Moves the display to the right by n lines (if n is positive) orC left by n lines (if n is negative). If n is' omitted, the display% is moved to the right by one line. /UP /UP[:n]B Moves the display up by n lines (if n is positive) or down by nB lines (if n is negative). If n is omitted, the display is moved up by one line. 2 Examples PCAA> MOVE/LEFT@ The MOVE command moves the current scrolling display to the left by one column. PCAA> MOVE/UP:3/RIGHT:5 NEW_OUTD The MOVE command moves display NEW_OUT up by three lines and to the rig(ht by five columns. wwv f1 NEXT Analyzer CommandB Traverses the current plot to display the next most significant leaf. Format NEXT [parameter] 2 Parameters SUBTREE= Applies NEXT to subtrees instead of to the list within theD subtree. The NEXT SUBTREE command places the pointer at the first leaf within the next subtree. 2 DescriptionC The NEXT command is one of a series of directional commands thatA ) allows you to traverse a program's structure. The initial NEXT@ command displays the first traverse subtree, and positions an> arrow to point to the bucket with the most data points. TheA corresponding source lines for that portion of the program areB displayed alongside the plot. Subsequent NEXT commands move the? arrow to the bucket with the next most data points (the nextA leaf), and so on. Other traverse commands are FIRST, BACK, and CURRENT. wwv f*1 PAGE Analyzer CommandC Displays a specified page of a PLOT, TABULATE, INCLUDE, EXCLUDE,A or traverse command's output on the terminal. The PAGE commandC displays the next page, the current page, the previous page, the= first summary page, or a page with a specific page number. Format PAGE parameter 2 Parameters n@ Specifies the page number of the page you want displayed. TheC first page is page 1. If n is larger than the number of+ the last$ page, the last page is displayed. keywordD Displays the first summary page or a page relative to the current7 page. The following keyword parameters are accepted:) CURRENT Redisplays the current page6 NEXT Displays the page after the current page7 PREVIOUS Displays the page before the current pageB SUMMARY Displays the first summary page of the plot or table 2 Description? The PAGE command gives you random access to the pages of ,theD histogram or table generated by the last PLOT, TABULATE, INCLUDE,C EXCLUDE or traverse command you entered. You cannot use the PAGE< command unless there is a currently active plot or table. 2 Examples" PCAA> PLOT/SOURCE PROGRAM BY LINE PCAA> PAGE 16B The PLOT command generates a histogram and displays page 1 ofB that histogram. The PAGE command then displays page 16 of the same histogram. PCAA> PAGE PREVIOUSD This command displays the previou-s page of the currently active@ plot. If the current page is page 16, this command displays page 15. PCAA> PAGE SUMMARYB This command displays the first summary page of the currently active plot. wwv f1 PLOT Analyzer Command< Generates performance or coverage histograms. A number ofC different kinds of data can be plotted along the horizontal axis@ and a variety of data domains can be partitioned into buckets1 along the ver.tical axis to form the histogram. Format$ PLOT [nodespec [,nodespec...]] 2 Parameters nodespec@ Specifies a program location. Node specifications (nodespecs)B on PLOT and TABULATE commands define how the vertical axis of aC histogram or table is partitioned into buckets. For example, theD node specification PROGRAM_ADDRESS BY ROUTINE selects the program@ address domain, the domain of all possible program addresses.B From this domain, it selects the /address ranges of the routinesA in the program. Each of these address ranges defines a bucket.@ See HELP Nodespecs for information about node specifications. 2 DescriptionA The PLOT command generates performance or coverage histograms.B When you enter a PLOT command, you must specify two things: theD kinds of data to tally, and how to partition the histogram. These@ two things define the meanings of the horizontal and verticalA axes of the histogram. What kind of data 0to tally is specified3 with a data-kind qualifier (see qualifier list).@ Each histogram is partitioned into buckets representing valueD ranges. Each data point in the data file is tallied in the bucket: whose value range includes the value of the data point.C Every PLOT command requires one qualifier from the data kind and@ the sorting categories to generate a histogram. If you do notC specify one qualifier from each category, a default qualifier isB used. If your PLOT 1command has one or more node specifications,? the qualifier defaults are taken from the SET PLOT defaults.? If your PLOT command does not have a node specification, all? qualifier and node specification defaults are taken from the1 previous PLOT or TABULATE command you entered.A The TABULATE command displays the same information as the PLOT< command, but in the form of tables instead of histograms. 2 Data-kind_qualifiers /ANCD Has the same effect as /NONCO2VERAGE, except that every acceptably; non-covered (ANC) bucket has the ANC label placed in the percentage column. /COUNTERSC Tallies exact execution count data along the horizontal axis. ToD use this qualifier, you must have collected execution counts with the SET COUNTERS command. /COVERAGE> Tallies test coverage data along the horizontal axis. Every? program unit that is covered (executed at least once) gets aB full-length histogram bar. To use this 3qualifier, you must have@ collected test coverage or execution counts data with the SET$ COVERAGE or SET COUNTERS command. /CPU_SAMPLINGC Tallies CPU sampling data along the horizontal axis. To use this8 qualifier, you must have collected CPU sampling data. /FAULT_ADDRESS> Tallies page fault data along the horizontal axis using the? faulting address value to tally each data point. To use this6 qualifier, you must have collected page fault data. /IO_SERV4ICES; Tallies the number of I/O system service calls along theB horizontal axis. To use this qualifier, you must have collected I/O services data. /NONCOVERAGEB Tallies test non-coverage data along the horizontal axis. EveryC program unit that is not covered (is not executed at least once)C gets a full-length histogram bar. Program units that are coveredB do not get histogram bars. To use this qualifier, you must haveD collected coverage or execution counts data5 with the SET COVERAGE or SET COUNTERS command. /PAGE_FAULTS> Tallies page fault data along the horizontal axis using the> program address value to tally each data point. To use this6 qualifier, you must have collected page fault data. /PC_SAMPLINGC Tallies program counter sampling data along the horizontal axis.A To use this qualifier, you must have collected program counter sampling data.= Note that /PC_SAMPLING is the default data-kind qualifier.6 /PHYSICAL_IO_COUNTB Tallies the total number of physical I/O operations (reads plus@ writes) along the horizontal axis. To use this qualifier, you) must have collected I/O services data. /READ_COUNT; Tallies the number of physical read operations along theB horizontal axis. To use this qualifier, you must have collected I/O services data. /SERVICESB Tallies the number of system service calls along the horizontal> axis. To use this qualifier, you 7must have collected system services data. /UNALIGNED@ Tallies unaligned access fault data along the horizontal axisC using the program address value to tally each data point. To useA this qualifier, you must have collected unaligned access fault data. /VCOUNTERS< Tallies exact execution count data of vector instructionsB along the horizontal axis. To use this qualifier, you must have' collected vector instruction counts. /VCPU_SAMPLINGC Talli8es CPU sampling data along the horizontal axis. To use this? qualifier, you must have collected vector CPU sampling data. /VPC_SAMPLINGC Tallies program counter sampling data along the horizontal axis.D To use this qualifier, you must have collected vector PC sampling data. /WRITE_COUNT< Tallies the number of physical write operations along theB horizontal axis. To use this qualifier, you must have collected I/O services data. 2 Sorting_qualifiers9 /ALPHABETICALLY /ALPHABETICALLY[=n[:m]]D Sorts the histogram alphabetically by label names. If you specifyC =n, only the first n buckets (after sorting) are retained in theB histogram. If you specify =n:m, only buckets n through m (after sorting) are retained. /ASCENDING /ASCENDING[=n[:m]]> Sorts the histogram in ascending order by bucket data count> (smallest count first). If you specify =n, only the first n@ buckets (after sorting) are r:etained in the histogram. If you= specify =n:m, only buckets n through m (after sorting) are retained. /DESCENDING /DESCENDING[=n[:m]]? Sorts the histogram in descending order by bucket data count= (largest count first). If you specify =n, only the first n@ buckets (after sorting) are retained in the histogram. If you= specify =n:m, only buckets n through m (after sorting) are retained.: Note that /DESCENDING is the default sorting qualifier. ;/NOSORT /NOSORT[=n[:m]]A Specifies that the histogram not be sorted. If you specify =n,A only the first n buckets are retained in the histogram. If you7 specify =n:m, only buckets n through m are retained. 2 Bucket_selection_qualifiers /MAXIMUM /MAXIMUM=n /NOMAXIMUM; Determines whether to omit buckets that exceed a maximumD percentage. The /MAXIMUM=n qualifier specifies that buckets whoseB percentage exceeds n% should be omitted from <the histogram. TheD /NOMAXIMUM qualifier specifies that no maximum threshold applies.? Note that /NOMAXIMUM, /NOMINIMUM, and /ZEROS are the default bucket selection qualifiers. /MINIMUM /MINIMUM=n /NOMINIMUM? Determines whether to omit buckets that fall below a minimumD percentage. The /MINIMUM=n qualifier specifies that buckets whoseB percentage falls below n% should be omitted from the histogram.? The /NOMINIMUM qualifier specifies that no minimum =threshold applies.? Note that /NOMAXIMUM, /NOMINIMUM, and /ZEROS are the default bucket selection qualifiers. /ZEROS /ZEROS /NOZEROS> Determines whether zero data count buckets are omitted from? the histogram. The /NOZEROS qualifier specifies that bucketsA with zero data counts be omitted from the histogram. Thus, theD histogram becomes smaller since buckets without data are dropped.> The /ZEROS qualifier retains buckets with zero data counts.>? Note that /NOMAXIMUM, /NOMINIMUM, and /ZEROS are the default bucket selection qualifiers. !2 Source_code_display_qualifiers /SOURCE /SOURCE /NOSOURCE@ Determines whether source text is shown next to the histogram? bars. The /SOURCE qualifier specifies to display source code; in histograms generated with BY LINE or BY CODEPATH node@ specifications. The /NOSOURCE qualifier specifies that source text not be displayed.B Note that /SO?URCE is the default source code display qualifier. '2 Program_address_selection_qualifiers /CUMULATIVE /CUMULATIVE[=n] /NOCUMULATIVED Tallies all stack PC values for each data point in the histogram.= Thus, each bucket shows how much time or other resource is@ spent in the corresponding program unit and all program units? it calls. The /CUMULATIVE qualifier has no effect if you are> not plotting against the program address domain. To use theD /CU @MULATIVE qualifier, you must have collected stack PC values inD the Collector. You may specify an integer to cuase only the first? "n" routines down the stack to be used. If used with /STACK_D DEPTH=m, the Analyzer will charge the data point to all calls (or: "n" calls for /CUMULATIVE=n) below the specified depth.@ The /NOCUMULATIVE qualifier tallies only the original program% counter value for each data point.D Note that /NOCUMULATIVE, /NOMAIN_IMAGE and /NOSTACK_DEPTH are tAhe0 default program address selection qualifiers. /MAIN_IMAGE /MAIN_IMAGE[=n[:m]] /MAIN_IMAGE[=prog-unit]D Specifies to use the first call stack PC value that falls in yourA program's main image, when tallying program addresses. You mayB specify the PC value to be n or the range n:m. If you specify aC program unit or address range, it will select the first PC valueD in that address. The /NOMAIN_IMAGE qualifier specifies to use theC original program coBunter value for each data point, to tally the data point.D Note that /NOCUMULATIVE, /NOMAIN_IMAGE and /NOSTACK_DEPTH are the0 default program address selection qualifiers. /STACK_DEPTH /STACK_DEPTH=n /NOSTACK_DEPTH? Determines whether the Analyzer will climb the call stack to determine the PC values.D Note that /NOCUMULATIVE, /NOMAIN_IMAGE and /NOSTACK_DEPTH are the0 default program address selection qualifiers. 2 Design_qualifiers C/FILL- /FILL=("*","O","x","@",":","#","/","+")B Specifies the fill to be used for the first, second, etc., data> kind in a plot. A maximum of eight character strings can beD defined, and each must be delimited by double or single quotation marks.B Note that /FILL=("*","O","x","@",":","#","/","+"), /NOSCALE and- /NOWRAP are the default design qualifiers. /SCALE /SCALE=n /NOSCALE@ Determines whether fixed or adjusted histogram scale is used.DD The /SCALE=n qualifier allows you to select a fixed scale for theA plot. The /NOSCALE default qualifier selects adjusted scaling,C which causes the longest bar on the histogram to occupy the full width of the plot.B Note that /FILL=("*","O","x","@",":","#","/","+"), /NOSCALE and- /NOWRAP are the default design qualifiers. /WRAP /WRAP /NOWRAPD Specifies to wrap PLOT output that is too long. /NOWRAP specifies, to truncate PLOT output that is tEoo long.B Note that /FILL=("*","O","x","@",":","#","/","+"), /NOSCALE and- /NOWRAP are the default design qualifiers. 2 Tasking_qualifiers /CREATOR_PC /CREATOR_PC /NOCREATOR_PCC Charges a data point to the location in the program that createdA the task, rather than to the PC value of the measurement. ThisC qualifier can only be used when the PROGRAM_ADDRESS domain is inA effect, and when TASKING data has been collected. It overrides, /MAFIN_IMAGE, STACK_DEPTH and /CUMULATIVE. /PARENT_TASK /PARENT_TASK /NOPARENT_TASKA Charges a data point to the parent of the current task, ratherA than to the current task. It can only be used when the TASK orD the TASK_TYPE domain is in effect, and when TASKING data has been collected. /TASK_SWITCHB Represents the number of times there was a task context switch.? It may be applied to the following domains: TIME BY n MSECs,? TASK, TASK_PRIORITYG, and TASK_TYPE. This qualifier will only@ work with the TIME, TASK, TASK_PRIORITY, and TASK_TYPE filter specifications. 2 CALL_TREE_domain_qualifiers /CHAIN_NAME /CHAIN_NAME /NOCHAIN_NAMEC Specifies to use the comma list form of presentation on the plotA for call trees. /NOCHAIN_NAME specifies to use the indentation> form. If you specify /NOCHAIN_NAME, then the PLOT command's? maximum and mininum sorting qualifiers are not in effect. If7 yHou specify /CHAIN_NAME, then /NOZEROS is in effect.D Note that /NOCHAIN_NAME and /NOPATHNAME are the default CALL_TREE domain qualifiers. /PATHNAME /PATHNAME /NOPATHNAME? Specifies to use full pathnames for each routine name in the@ plot. /NOPATHNAME specifies to use unqualified routine names.D Note that /NOCHAIN_NAME and /NOPATHNAME are the default CALL_TREE domain qualifiers.D Note that if you do not specify one qualifier from each category,I? a default qualifier is used. If your PLOT command has one orB more node specifications, the qualifier defaults are taken fromC the SET PLOT defaults. If your PLOT command does not have a nodeC specification, all qualifier and node specification defaults are< taken from the last PLOT or TABULATE command you entered. 2 Default_qualifiers /DEFAULTC Specifies that all default qualifiers and node specifications beA taken from the SET PLOT defaults instead of froJm the currently active plot. 2 Examples PCAA> PLOT PROGRAM BY MODULE= Program counter sampling data is plotted by default. The; vertical axis has one histogram bar for each module in> the program. It also has one bar for each shareable image> used. Each bar indicates how much time is consumed in the corresponding program unit.1 PCAA> PLOT/PAGE_FAULTS/SOURCE MODULE FOO BY LINEA The histogram has one bar for each line in module FOO of theC K user program. The length of each histogram bar is proportionalD to the number of page faults that occurred at the corresponding@ line. Because the /SOURCE qualifier is present, the text ofA each source line is shown next to the histogram bar for that line.5 PCAA> PLOT/NONCOVERAGE/SOURCE MODULE FOO BY CODEPATHB The histogram has one bucket for each codepath in module FOO.A Any codepath that is not covered has a full-length histogramA bar. Thus, the histog Lram highlights code that is not tested.D The text of each source line is shown next to the corresponding codepaths.5 PCAA> PLOT/IO_SERVICES/MAIN_IMAGE PROGRAM BY ROUTINE@ The number of I/O system service calls is plotted along theC horizontal axis. The routines of the program are plotted along@ the vertical axis. I/O data originating in shareable imagesD (such as the Run-Time Library) are charged back to the routinesC in the main image (the user program) th Mat called the shareable images to cause I/O.B PCAA> PLOT/SERVICES/DESCENDING/NOZEROS SYSTEM_SERVICES BY SERVICEC The names of the OpenVMS system services are plotted along theA vertical axis. The number of calls on each system service isB plotted along the horizontal axis. The histogram is sorted soA that the most frequently used services are listed first. All@ system services that were never called are omitted from the histogram.0 PCAA> PLOT/PHYSICAL N_IO_COUNTS FILE_NAME BY FILED The names of the RMS files opened or created by the program areA plotted along the vertical axis of the histogram. The numberB of physical I/O operations for each file is plotted along the horizontal axis., PCAA> PLOT/VCOUNTERS INSTRUCTION BY VOPCODE; This command causes the report view to be based on the; disassembled opcode for each vector instruction in the> entire application that is sampled. The number of times a@ vOector instruction is used lets you see if your application= is spending a lot of time performing certain operations.= For example, if you see that the SYNC vector instruction@ is executed more than any other vector instruction, you canC infer that the scalar processor is spending too much idle time= waiting for the vector processor to finish an operation. wwħ f1 PRINT Analyzer CommandA Sends the output from the most recent PLOT, TABULATPE, INCLUDE,4 EXCLUDE, LIST or traverse command to the printer. Format PRINT 2 DescriptionA The PRINT command sends the output of the last PLOT, TABULATE,< INCLUDE, EXCLUDE, LIST, or traverse command to the system: printer. To print a histogram, table, or listing of rawB performance data, enter the command to generate a report on the? terminal, and then enter a PRINT command to send that reportB to the printer. The print file produced by the PRINT command Qis0 named PCAPLOT.TMP and is queued to SYS$PRINT.A When printing histograms and tables, the PRINT command assumes: that there are 66 lines per page and formats the output> accordingly. You can change the number of lines per page by7 defining the logical name SYS$LP_LINES at DCL level.@ To be notified at your terminal when your output has finished' printing, use the /NOTIFY qualifier. 2 Qualifiers /NOTIFYA Sends a message to your terminal when the printRer has finished your print job. 2 Examples* PCAA> PLOT/IO_SERVICES PROGRAM BY ROUTINE PCAA> PRINT. %PCA-I-FILQUE, print file queued to SYS$PRINTD The PLOT command generates a histogram. The PRINT command sends# that histogram to the printer.) PCAA> TABULATE/SOURCE MODULE FOO BY LINE PCAA> PRINT/NOTIFY. %PCA-I-FILQUE, print file queued to SYS$PRINT PCAA>3 Job PCAPLOT (queue SYS_LPA0, entry 1354) completed PCAA>C The TABULATE command generates a tablSe. The PRINT command thenB sends that table to the printer. When the TABULATE output has? finished printing, a message is displayed on the terminal. wwħ f1 SAVE PCA Command@ Preserves the contents of an existing screen display in a new screen display. FormatB SAVE old-displayname AS new-displayname [,old-displayname AS new-displayname...] 2 Parameters old-displaynameD Specifies the name of a screen Tdisplay whose contents you want to save. new-displayname> Specifies the name of the new screen display to be created.@ This new display receives the contents of the old-displaynameA display. The new display name must consist of letters, digits,? underscores, and dollar signs. It cannot start with a digit. 2 DescriptionD The SAVE command saves a "snapshot" of an existing screen display@ in a new display for later reference. The new display has the@ same textUual contents as the existing display. It has all theC attributes and characteristics of the old display except that itD does not appear on the screen. Using the DISPLAY command, you can9 later recall the saved display to the terminal screen. 2 Examples PCAA> SAVE PLOT AS SAVED_PLOT@ This command moves the contents of the screen display namedA PLOT into the newly created screen display named SAVED_PLOT.> You can get further information on each of these commanVds through HELP. wwħ f 1 SCROLL PCA CommandB Scrolls a display's screen window in a specified direction over> the text of the display, making additional display contents visible. Format SCROLL [display-name] 2 Parameters display-nameA Specifies the screen display to scroll. This display must be aA predefined display (PLOT, SRC or OUT) or a display established@ with the SET DISPLAY command. If you omit this Wparameter, the? current scrolling display, as specified by the SELECT/SCROLL command, is scrolled. 2 DescriptionC The SCROLL command is used to view display contents that are notC currently visible in a display's screen window. Using the SCROLLC command, you can move the screen window up or down over the textD of the display. You can also move it left or right. By scrolling,? you can see all parts of a large display, even though only a> small part may fit in the dXisplay's window at any one time.: The easiest way to use the SCROLL command is to use theB predefined scrolling keys (see the Keypad entry in PCA HELP for PCA key definitions). 2 Qualifiers /BOTTOM? Scrolls the window down to the bottom of the display's text. /DOWN /DOWN[:n]= Scrolls the window down through the display to reveal textB farther down in the display. If the optional :n is omitted, the@ window scrolls approximately 3/4 of theY window height. If theB optional :n is specified, the window scrolls down the specified number of lines. /LEFT /LEFT[:n]A Scrolls the window left over the display to reveal text beyondC the left margin. If :n is not specified, the window scrolls left@ by eight columns. If the optional :n is specified, the windowB scrolls left the specified number of columns. You cannot scroll past the first column. /RIGHT /RIGHT[:n]B Scrolls the windoZw right over the display to reveal text beyond? the right margin. If :n is not specified, the window scrolls? right by eight columns. If the optional :n is specified, the8 window scrolls right the specified number of columns. /TOP: Scrolls the window up to the top of the display's text. /UP /UP[:n]C Scrolls the window up through the display to reveal text farther? up in the display. If the optional :n is omitted, the windowB scrolls approximately 3[/4 of the window height. If the optionalA :n is specified, the window scrolls up the specified number of lines. 2 Examples PCAA> SCROLL/RIGHTB This command scrolls the window to the right by eight columnsD over the current scrolling display so that you can see the rest of long source lines. PCAA> SCROLL/UP:4 OUTB This command scrolls the window up through the OUT display by four lines. wwħ f 1 SEARCH PCA Command\A Searches the source code for a specified string, then displaysC the source line or lines containing an occurrence of that string in the output window. Format SEARCH [range] [string] 2 Parameters range> Defines the boundaries of the search. If you do not specify@ a range, the SEARCH command searches the module most recentlyD referenced with a SEARCH or TYPE command, from the line followingC the last line displayed to the end of the module. P ]CA can searchB only one module at a time. These boundaries may be defined with any of the following formats:D modname Searches the entire specified. module.D [modname\]line-number Searches the specified module> from the specified line? number to the end of the. module.= [modname\]line-nu ^mber:line-number Searches the inclusive? interval between the twoD line numbers of the specified. module. stringD Specifies the sequence of characters to search for in the source.C If you do not specify a string, then the most recently specified> search string is used. If the string contains spaces, tabs,= commas or parentheses, then it must be delimited by eit _her? double or single quotation marks. If the string delimited by? quotation marks has a quotation mark within it, the enclosed@ quotation mark must be expressed as two consecutive quotation@ marks (i.e. If the string delimited by single quotation marksB has a single quote within it, the enclosed single quote must beD expressed as two consecutive single quotes (e.g. '')). The searchD is case sensitive depending on the currently set language. If theA string is not delimited, `then the default range parameter mustA not be used and the string may not contain any blanks, tabs or semicolons. 2 Description? The SEARCH command allows you to search your source code for= a specified string. The source line or lines containing an@ occurrence of that string are then displayed. You can use theA SEARCH and TYPE commands to display specific lines, or a rangeC of lines. However, if you have moved your source files, then youD must establish a sourcea directory search list with the SET SOURCE* command in order to use these commands. 2 Qualifiers /ALLA Searches the specified range for all occurrences of the string0 and display every line containing the string. /NEXT? Searches the specified range for the first occurrence of the5 string and display that line. This is the default. /IDENTIFIER< Names the string as an identifier. The specified range is? searched for the first occurrence of thbis identifier. If theB string (identifier) is bound on either side by a character thatD can be part of an identifier defined by the SET LANGUAGE command,C then it is not displayed. The search continues until it finds anA occurrence of the string that is not bound by such characters. /STRING? Searches the specified range for an occurrence of the stringC without interpreting the context surrounding the string. This is the default. 2 Examples, PCAC> SEARCcH/STRING/ALL COBOLTEST "D" 40:50, 40: 02 D2N COMP-2 VALUE -234560000000) 41: 02 D COMP-2 VALUE 222222.33# 47: 02 DRO COMP-2 VALUE 0.1( 50: 02 DR5 COMP-2 VALUE 0.000001A This command searches for all occurrences of the letter D inB lines 40 through 50 of the module COBOLTEST, and displays the result. ww f 1 SELECT PCA Command@ Selects a screen display as the current output, plot, source,& scrolling, error, or dinput display. Format SELECT [display-name] 2 Parameters disp-name@ Specifies the display to be selected. You may specify any oneA of the following, with the restrictions noted in the qualifier descriptions:8 o A predefined display (SRC, OUT, PLOT, and PROMPT).? o A display previously created with the SET DISPLAY command= o A pseudo-display name: %CURDISP, %CURSCROLL, %NEXTDISP,6 %NEXTOUTPUT, %NEXTPLOT, %NEXTSCROLL, %NEXTSOURCE eA If you omit this parameter and do not specify a qualifier, youB deselect the current scrolling display (no display then has theA scrolling attribute). If you omit this parameter but specify aC qualifier (/INPUT, /SOURCE, and so on), you deselect the current@ display with that attribute (see the qualifier descriptions). 2 DescriptionB Attributes are used to select the current scrolling display and@ to direct various types of PCA output to particular displays.C This fgives you the option of mixing or isolating different typesB of information, such as PCA input, output, diagnostic messages,$ and so on in scrollable displays.= You can use the SELECT command with one or more qualifiersC (/ERROR, /SOURCE, and so on) to assign one or more correspondingB attributes to a display. If you do not specify a qualifier, the+ /SCROLL qualifier is assumed by default.= If you use the SELECT command without specifying a display= name, in general thge attribute assignment indicated by the: command qualifier is canceled (deselected). To reassignB display attributes you must use another SELECT command. See the1 individual qualifier descriptions for details. 2 Qualifiers /ERROR< If you specify a display, selects it as the current errorA display. This causes all PCA diagnostic messages to go to thatB display. The display specified must be either an output display or the PROMPT display.B If you do not shpecify a display, the PROMPT display is selectedC as the current error display. By default, the PROMPT display has the error attribute. /INPUT< If you specify a display, selects it as the current inputD display. This causes that display to echo PCA input (which alwaysC appears in the PROMPT display). The display specified must be an output display.@ If you do not specify a display, the current input display isC deselected and PCA input is not echoed to any displiay (PCA inputB appears only in the PROMPT display). By default, no display has the input attribute. /OUTPUT= If you specify a display, selects it as the current output? display. This causes PCA output that is not already directedB to another display to go to that display. The display specified: must be either an output display or the PROMPT display.B If you do not specify a display, the PROMPT display is selectedA as the current output display. By default, the jOUT display has the output attribute. /PLOTA Directs all output from PLOT, TABULATE and related commands to? the specified display. This display becomes the current plot@ display. By default, the PLOT display has the plot attribute. /PROMPT? Selects the specified display as the current prompt display.; This is where PCA prompts for input. Currently, only theA PROMPT display may be specified. Note that you cannot deselect? the PROMPT display (the PROMPkT display always has the prompt attribute). /SCROLL@ If you specify a display, selects it as the current scrolling= display. This is the default display for the SCROLL, MOVE,@ and EXPAND commands. Although any display may have the scroll< attribute, note that you can use only the MOVE and EXPAND= commands (not the SCROLL command) with the PROMPT display.D If you do not specify a display, the current scrolling display is6 deselected and no display has the scroll lattribute. /SOURCE= If you specify a display, selects it as the current source@ display. This causes the output of all TYPE commands to go to@ that display. The display specified must be a source display.A If you do not specify a display, the current source display is6 deselected and no display has the source attribute. 2 Examples PCAC> SELECT/SOURCE/SCROLL SRC2A The SELECT/SOURCE/SCROLL command selects display SRC2 as the* current source and scromlling display. PCAC> SELECT/INPUT/ERROR OUT> The SELECT/INPUT/ERROR command selects display OUT as the< current input and error display. This causes PCA input,A output (assuming OUT is the current output display), and PCA? diagnostic messages to be logged in the OUT display in the correct sequence. PCAA> SELECT/SCROLL OUT PCAA> SCROLL/UP= The first command selects the OUT display as the current> scrolling display. The SCROLL command has no display-nname6 parameter, and therefore scrolls the OUT display. PCAA> SELECT/PLOTC This command cancels the plot display. All PLOT command output' is directed to the output display. ww f1 SET PCA Command@ Establishes a variety of definitions, data collection optionsC and various mode settings. These settings are established by the$ keyword specified on the command. Format SET keyword [parameters] 2 Parameters ke oywordC Specifies the definition, data collection option or mode setting? to establish. In the Collector, valid keywords are COUNTERS,A COVERAGE, CPU_SAMPLING, DATAFILE, DISPLAY, EVENT, IO_SERVICES,A KEY, LANGUAGE, LOG, MAX_SOURCE_FILES, MODE, NOTE, PAGE_FAULTS,B 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, DATAFILEp, DISPLAY,C 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-A keyword name consisting of SET followed by a required keyword.< For details, see the individual SET command descriptions. 2 ANC Analyzer CommandC Determines which coverage-set points are qacceptably non-covered,4 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 moreD program address locations. If not specified, SET ANC will use theD current plot position established by a traverse command or by the FIND command. 3 Description> The SET ANC command lets you select r particular coverage-set? points as acceptably non-covered, and saves that information for the next test run.D 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 theA desired bucket, then issue the SET ANC command at the Analyzer? prompt. The SET ANC command saves that address as ascceptablyC non-covered. You can continue traversing the plot in this mannerC until you have saved all the non-covered points. Note that after@ you enter the first traverse command, you can enter CTRL/N toC move the pointer from one non-covered point to another, and that? the keypad COMMA key will enter the SET ANC command for you.D Another way to save ANC information is to provide a nodespec on a/ SET ANC command, as in the example provided. 3 Examples5 PCAA> StET ANC ROUTINE R2 BY LINE, ROUTINE R4 BY LINEC This command saves all non-covered lines in routines R2 and R4 as acceptably non-covered. 2 COUNTERS Collector CommandD 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 u about node specifications. 3 DescriptionA The SET COUNTERS command establishes execution counters at allD program locations specified by the node specifications. After youA 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 SETC DATAFILE command, the Collector establishes a default data file.A v The default data file has the same file name as your program's0 executable image file and a file type of PCA.D You must collect stack PC information if you want to use a /MAIN_D IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or TAB command in the Analyzer. 3 Qualifiers /STACK_PCSA Specifies that stack PC values are collected for counter data.A Further SET COUNTERS requests will assume a default of /STACK_ PCS. /NOSTACK_PCSD Speciwfies that no stack PC values are collected for counter data.5 This is the default upon entry into the collector. 3 Examples2 PCAC> SET COUNTERS/STACK_PCS LINE PRIMES %LINE 22? This command causes PCA to count the executions of line 22B 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 ROUTINED Txhis 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 D yescription> 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 duringA program execution, the Collector records that p zrogram location? in the performance data file. The Collector then removes the? breakpoint so that the overhead of measuring coverage is notB 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.D You must collect stack PC information if you want to use a /MAIN_D 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 SETC DATAFILE command, the Collector establishes a default data file.A The default data file has the same file name as your program's0 executable image file and a file type of PCA. 3 Qualifiers /PREVIOUS? Causes the Collector to use the breakpoint table left by theB previous collection run when it is appending test coverage dataC to an existing performance data file. If su |ch a breakpoint table? exists, the node specifications are ignored. Also causes theC Collector to write a table of test coverage breakpoint locations= not yet covered (or not yet covered n times if /UNTIL:n isC specified) to the data file at the end of the current collection run.? This qualifier causes test coverage to be measured only onceA (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 measureB coverage of that location in any subsequent collection run. UseC of the /PREVIOUS qualifier makes data collection more efficient,C but you lose the ability to determine what individual collectionA runs covered which program locations. If you use the /PREVIOUS= qualifier, you should use the /APPEND qualifier on the SET DATAFILE command. /UNTIL /UNTIL:nB 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 isA executed at least n times. If you omit the /UNTIL:n qualifier,; each breakpoint is removed the first time it is reached. /STACK_PCSB Specifies that stack PC values are collected for coverage data.A 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. /ANCD Saves codepath information in the performance data file for everyB module containing coverage-set points. This information is usedD by the Analyzer MERGE/ANC command to validate the ANC information being merged. 3 Examples1 PCAC> SET COVERAGE/STACK_PCS PROGRAM BY CODEPATHD This command specifies that test coverage be measured for every@ codepath in the user pr ogram, and enables the collection of stack PC values.' PCAC> SET DATAFILE/APPEND COV_TEST.PCA0 PCAC> SET COVERAGE/PREVIOUS PROGRAM BY CODEPATHC 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 commandC specifies that test coverage be measured for every codepath inC the user program. The /PREVIOUS qualifier specifies that if anD exi sting data file is found, then the Collector will ignore theB nodespec, and will use the breakpoint table from the previousD collection run recorded in that data file. Hence, test coverageD is measured only once for each codepath in the program over all; collection runs recorded in the performance data file.3 PCAC> SET COVERAGE/UNTIL:4 MODULE NICK BY CODEPATHD This command specifies that test coverage be measured for everyD codepath in module NICK. Up to four executions of each codepathA is recorded in the performance data file before the coverage breakpoint is removed.& PCAC> SET COVERAGE PROGRAM BY ROUTINED 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 CommandC 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 importantC exception. The CPU sampling interval is based on virtual processD or CPU time, not system time. When you issue the SET CPU_SAMPLINGC command, PCA will only collect PC values whenever there has been2 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. ForA example, page faulting and system service wait time (includingB I/O wait time). These conditions make it difficult to determineC whether the program counter contains a specific location becauseB of the structure of the program's algorithm or because of other@ operations occuring in that interval. Under these conditions,B sampling the PC values based on the process's CPU time would beA more effective and reproducible, because the effects caused by$ contending processes are reduced.D You must collect stack PC information if you want to use a /MAIN_D IMAGE, /CUMULATIVE or /STACK_DEPTH qualifier with the PLOT or TAB command in the Analyzer. 3 Qualifiers /INTERVAL /INTERVAL:nB Specifies the sampling interval in milliseconds. The value of nD must be at least 10 milliseconds and at most 60,000 milliseconds.B Because the granularity of the system clock is 10 milliseconds,D you should use a multiple of 10. The default sampling interval isD 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.A 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 allA further SET CPU_SAMPLING requests, a default of /NOSTACK_PCS will be assumed. 2 DATAFILE PCA CommandC 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 useA to record symbol information and performance or coverage data,B 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 theB performance data file the Collector should use to record symbol B information and performance or coverage data. No performance orD coverage data is actually written to the specified file until youB enter the GO command. You can thus respecify the data file withD another SET DATAFILE command if you need to correct the data file specification.D If you want to append the data from the present collection run toC an existing performance data file, use the /APPEND qualifier. IfD you want to measure the performance of a shareable image, use t he /SHAREABLE qualifier.9 In the Analyzer, the SET DATAFILE command identifies aC performance data file to be processed by the Analyzer. Data from@ this file is used by all subsequent PLOT, TABULATE, LIST, andD 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 toA 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 currentC 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 doesD not exist, the Collector creates a new data file by that name andB writes the performance or coverage da ta to that file. If you doB not specify the /APPEND qualifier, the Collector always createsC a new file. You may append data to an existing data file only by9 using the same image that originally created the file. /EXECUTABLE@ Causes the Collector to use the default performance data fileD name. The default data file name consists of the name of the userA 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 orB /SHAREABLE qualifier. If you specify the /EXECUTABLE qualifier, omit the file-spec parameter. /SHAREABLE /SHAREABLE=(img-name)D Specifies that you want to measure the performance of a shareableA 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]TESTD This command specifies that the performance or coverage data be1 written to a new file called [PING]TEST.PCA. PCAA> SET DATAFILE [PING]TESTD This command specifies that performance or coverage data shouldD be taken from file [PING]TEST.PCA by subsequent PLOT, TABULATE, and LIST commands.( PCAC> SET DATAFILE/APPEND [PING]OLDTESTD This command specifies that the performance or coverage data be: appended to the existing data file [PING]OLDTEST.PCA.- PCAC> SET DATAFILE/SHAREABLE=(MYSHR) SHRDATAC This command specifies that the performance of shareable imageA MYSHR be measured. The name of the data file is SHRDATA.PCA. 2 DISPLAY PCA CommandB Creates new screen displays to be shown on the terminal screen. FormatA SET DISPLAY display-name [AT window-spec] [display-kind] [,B display-name [AT window-spec] [display-kind]...] 3 Parameters display-nameD 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-specD Specifies the screen window at which to position the new display.B If you omit window-spec, the display is positioned at window H1< or H2 (H1 and H2 are used alternately, starting with H1).B Window-spec can be the name of a predefin ed window, the name ofC a window you have defined with a SET WINDOW command, or a window specification of the form: 1start-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 theB number of columns in the window, respectively. Start-column a ndA column-count default to column 1 and the current screen width, respectively. display-kindC Specifies the kind of display to create; OUTPUT, PLOT and SOURCED are the valid keywords. OUTPUT indicates a regular output display= to hold the output of SHOW, LIST and SEARCH commands. PLOTA indicates a display to contain the output of PLOT and TABULATE@ commands. SOURCE indicates a display to contain output from aB TYPE command. If you omit the display-kind parameter, an output display is created. 3 DescriptionC 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 windowC dimensions proportionally when a SET TERMINAL command is issued. /DYNAMIC is the default. /HIDEC /HIDE conceals the display under any other displays that overlapB 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. /REMOVEA Creates a display that does not appear on the screen. AlthoughA a removed display is not visible on the screen, its definitionB still exists, and you can request that it be displayed by using the DISPLAY command. /SIZE /SIZE:nB Sets the maximum size of a normal output display to be n lines.D If more than n lines are written to the display, the oldest linesC 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 orC TABULATE output to be buffered internally by the Analyzer at one8 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 s tarting@ at line 1, column 45, and extending down for 8 lines and toA the right for 30 columns. The SET DISPLAY command creates anC 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 ALLC This SET DISPLAY command creates an output display named PING,D which is placed at window T1, the top third o f 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 shownA at window H1, the top half of the screen. The SELECT command@ selects that display as the current plot display and as t heA current scrolling display. The output of the PLOT command isB shown in the PANG display and the SCROLL command scrolls thatA same display. By creating new plot displays, you can see theD 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 isB placed at a screen window that starts at line 1 (the top line3 of the screen) and contains two lines of text. 2 EDITOR Analyzer CommandC Determines the editor that is selected by the EDIT command. ThisC allows you to edit the source file displayed by the current PLOT or TABULATE command. Format SET EDITOR [command-line] 3 Parameters command-lineA The optional command line is only used with LSEDIT and VAXTPU,< and is passed to the respective callable editor with eachC subsequent EDIT command. If you do not specify a command line, aD default of LSEDIT or TPU will be assumed. The command line shouldD consist of the DCL command line used to invoke the editor, exceptD that it should begin with LSEDIT or TPU instead of EDIT/LSEDIT or EDIT/TPU. 3 DescriptionC The SET EDITOR command allows you to determine which editor willB be invoked, and how it will be invoked, when you issue the EDITC command. These editors must be accessible from DCL level. If youA 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_TECOB These qualifiers specify the callable editor that is invoked byD subsequent EDIT commands. If you do not specify a qualifier, then9 the spawned command line is used to invoke the editor. /START_POSITION /START_POSITION /NOSTART_POSITIONA Specifies whether to pass the number of the source line to theB 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"D This command causes subsequent EDIT commands to invoke callableD LSEDIT with the default command line of LSEDIT/READ_ONLY. Also,B the /START_POSITION qualifier will be appended to the commandB line, causing the editing session to start on the source line0 that the Analyzer is currently pointing to. 2 EVENT Collector CommandD Establishes the collection of event markers for a specified event1 when specified program locations are executed. Format2 SET EVENT event-name nodespec [,nodespec...] 3 Parameters  event-name@ Specifies the name of an event for which event markers shouldC 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 isD executed, an event marker for the event-name event is recorded in the performance data file.B See HELP NODESPECS for more information on node specifications. 3 Description < The SET EVENT command establishes the collection of event9 markers for a specified event when you execute programB 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. YouD determine what events are significant and what names to assign to those events.A Event markers segment the performance or coverage data so that? data can be associate d with different phases or time periodsB of program execution. The Analyzer uses event markers to filter@ performance or coverage data so that only the data associatedC with a certain event or time period is tallied in histograms andB tables. Each data point in the data file is associated with theA 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 nameB of the event you wish to define. You must also specify the nodeD specifications to associate with that event. The Collector placesA a breakpoint on each such location and, when the breakpoint isD reached, writes an event marker for that event to the performance data file.D 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's0 executable image file and a file type of PCA.> You can use one event marker per program location. Multiple5 program locations are allowed for each event name. 3 Examples- PCAC> SET EVENT COMPUTE LINE OPENIN\%LINE 22C This command establishes the collection of an event marker forC 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 inB the performance data file so that only data points that satisfyB certain criteria are tallied by the PLOT and TABULATE commands. Format: SET FILTER filter-name filter-spec [,filter-spec...] 3 Parameters filter-nameB 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. ItB cannot start with a digit. If a filter of the same name alreadyD exists, the old filter is canceled before the new one is defined. filter-specD Specifies a filter restriction. Each filter restriction specifiesA some criterion that a data point must satisfy. If a data pointB satisfies any one restriction for a given filter, it passes the whole filter.0 The following are vector filter restrictions:* Vector Restriction ExplanationA VLENGTH=number Filters the VLENGTH domain to show> only the Vector Length Register<  values of a specified length.C VMASK=number Filters the VMASK domain to show theC Vector Mask Register values with theA specified number of cells enabled.= VOPCODE=vector-opcode Filters the vector instructionC opcode to include only the specifiedA opcodes. You must supply mnemonicsC of the opcodes to be included in the$ plot.B VOPERATIONS=n Restricts views based on the number< of actual operations that are@ performed by vector instructions.C VREGISTER=vector-reg Filters the vector registers to show7 only specific registers.? VSTRIDE=number Filters the vector stride lengthC values to inclu de only the specified& values. 3 DescriptionA The SET FILTER command creates a new filter definition. When aC subsequent PLOT or TABULATE command is entered, the restrictionsD specified in the filter definition are applied to all data pointsC in the performance data file. A data point passes a filter if itA satisfies any one filter restriction in the filter. Only those? data points that pass all defined filters are tallied in the histo gram 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 ANDA restrictions; a data point must pass all defined filters to be# tallied in a histogram or table.B 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.C All the qualifiers listed defined below are positional. That is,C if you place a given qualifier after "SET FILTER" but before theB first parameter, then the qualifier affects the entire command.D If you place the qualifier after a filter specification, then the4 qualifier affects only that filter specification.; If you specify /MAIN_IMAGE=prog-unit, /STACK_DEPTH=n andA /CUMULATIVE=n, they are applied in the following order: /MAIN_C 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 dataA point in this address, but in the address n call frames on theB stack from the main image address, when checking address filter@ restrictions. If you include /CUMULATIVE on that command, theB 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 addressD range when checking address filter restrictions. By default, uses9 the first stack PC value that falls in the main image. /NOMAIN_IMAGE7 Uses the first PC value when checking address filter restrictions. /STACK_DEPTH /STACK_DEPTH=nC 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 isB specified, then let the data point pass only if the PC value is' within n call frames from the start. /NOCUMULATIVEC Lets a data point pass an address filter restriction only if the/ first stack PC value passes the restriction.C 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_PCD 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 isA 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 P CAA> SET FILTER F1 RUN=1 PCAA> PLOT PROGRAM BY ROUTINED The SET FILTER command defines a filter named F1. When the PLOTD command is executed, only data from collection run 1 is tallied in the histogram.. PCAA> SET FILTER FUMBLE PROGRAM_ADDRESS=FRATZ2 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 fallB in the address range of routine FRATZ. Th e PLOT command plotsB 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$GET0 PCAA> TABULATE/IO_SERVICES MODULE FRATZ BY LINEC 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 tableB produced by the TABULATE command, an I/O data point must passB all three filters. (Had non-I/O data been tabulated, the dataA points would need to pass only filters F1 and F2 because the? IO_SERVICE restriction is not applicable to non-I/O data.) 9 PCAA> SET FILTER VLEN1 VLENGTH=0, VLENGTH=32, VLENGTH=64 PCAA> PLOT VLENGTH BY ELEMENTB 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 certainA 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 CommandA Enables the collection of I/O services data. Data is collected3 for each I/O system service call in the program. Format SET IO_SERVICES 3 DescriptionC 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 otherD parameters and records it in the performance data file. The exactD information gathered depends on the I/O service, but will includeD the program address of the call, the name of the service, the CPUA time stamp. It may also include the name of the file accessed,C the record size of the transfer, the physical I/O read and write! counts, and other information.D 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_PCSC 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)C Specifies that the specifed user routines shall be called at the- start and end of each system service call.* Qualifier Parameter DescriptionA image-name The  shareable image containing theA entry-routine or/and exit-routine.A entry-routine The routine to call before callingB the system service. The null stringC (i.e. "") indicates no routine is to) be called.D exit-routine The routine to call after calling theD system service. The null string (i.e.@  "") indicates no routine is to be& called.D The following rule applies regarding the /USER_ROUTINE qualifier:: 1. Only one of the entry and exit routines may be null;C For more information on user routines in PCA, see the HELP entry for User_Routines. /NOUSER_ROUTINE /NOUSER_ROUTINEC Specifies that no user routines shall be called at the start andB end of each system service call. This is the default upon entry into the PCA Collector. 3 Examples PCAC> SET IO_SERVICES/STACK_PCSB This command enables the collection of I/O services data, and1 specifies that stack PC values be collected. 2 KEY PCA CommandB 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 youA press the key, the command string to which the key is bound isC not processed. You use the SET KEY command to change the current< state so that keys for the specified state are processed.B If you do not use the SET KEY command, the current keypad state is DEFAULT. 3 Qualifiers /LOG  /LOG /NOLOGB Controls whether a log message is displayed indicating that the/ key state has been set. The default is /LOG. /STATE /STATE=state-name /NOSTATEB Specifies the keypad state to be set. The state name can be any? alphanumeric string. If you omit the /STATE qualifier or useC /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. AfterC entering this command, when you press a keypad key with a BLUE? definition, that definition is executed even if you do notB press the PF4 key first. (The PF4 key is the PCA-defined BLUE key.) 2 LANGUAGE PCA CommandA Establishes the current language setting. The current language2 setting determines how symbol names are parsed. Format SET LANGUAGE language-name 3 Parameters language-nameC  Specifies the name of the language to be set. The valid language< names are Ada, (Ada is a registered trademark of the U.S.C government, Ada Joint Program Office.), BASIC, BLISS, C, C_PLUS_B PLUS, COBOL, DIBOL, FORTRAN, MACRO, Pascal, PLI, RPG, SCAN, and UNKNOWN. 3 DescriptionA The language setting determines how PCA parses symbol names inD command input. If the language is set to C/C++, PCA treats symbolA names as case-sensitive. Upper-case and lower-case letters areB then treated as different characters. If the language is set toA anything other than C/C++, symbol names are assumed to be caseA insensitive, and lowercase letters are treated as if they were uppercase letters.A When you use the SET DATAFILE command, the language setting isA determined by the language of the main routine in the program.C Normally, you need not change this setting. However, if you haveA 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 A Specifies the log file to create. All subsequent PCA input andC output is recorded in this file until logging is disabled. File-A spec is any valid OpenVMS file specification. The default fileB type is LOG. An omitted file-spec defaults to PCAC.LOG when youB 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 theD exclamation point is the PCA comment character, you can rerun theC 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 theA Collector log file. All subsequent commands and their output are recorded in this file. 2 MAX_SOURCE_FILES PCA CommandA Specifies the maximum number of source files that PCA can keep open at any one time. Format SET MAX_SOURCE_FILES n 3 Parameters nA 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 DescriptionB The SET MAX_SOURCE_FILES command specifies the number of sourceB 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 systemD resource. Using the SET MAX_SOURCE_FILES command, you can specifyA how many I/O channels PCA can use to read source files. If PCAB reaches this limit, it must close one source file before it canA 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 one8 time. Normally there is no need to change this value. 3 Examples PCAA> SET MAX_SOURCE_FILES 20C This command sets the number of source files PCA can keep open at one time to 20. 2 MODE PCA CommandB Establishes or cancels various mode settings that affect screen mode. Format SET MODE keyword [,keywod] 3 Parameters keywordC 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,B you can associate keys on the numeric keypadB with PCA command definitions. Keypad mode is) enabled by default.@ NOKEYPAD Disables the use of the numeric keypad forA command entry. You must disable keypad modeA when the program you are measuring requiresB 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 isC updated. Screen logging occurs only if outputD logging in general is enabled with the SET LOG command.C NOLOG_SCREEN Disables the logging of screen images. NOLOG_1 SCREEN is the default mode.C MOVIE Causes the termina l screen to be updated eachC time a command line is read, even if the lineC comes from a command file. In movie mode, you> can "play" a command file on the screen.C NOMOVIE Causes the terminal screen to be updated onlyC after each line of terminal input. NOMOVIE is' the default mode.D SCREEN Enables screen mode so that you see PCA outputC  in the form of screen displays viewed throughA windows on the terminal screen. Screen modeA 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.D SCROLL Causes the screen to be updated for every line@ of output in screen mode. Th us, the outputB scrolls through the output window. SCROLL is' the default mode.B NOSCROLL Causes the screen to be updated only after aB full command has completed. As a result, youA may see only the last part of the command's2 output in its screen window. 3 Description? The SET MODE command sets or cancels screen mode and variousB submodes within screen mode. Keypad mode is enabled by default.A You must disable keypad mode only if your program requires the2 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_SCREEND This command enables both screen mode and the logging of screenD 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 CommandA 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 currentA collection run in a quoted string following standard PCA rules< for quoted strings. This description is stored in the PCAA data file. You can retrieve the note by entering the SHOW RUN_C DESCRIPTION command in the PCA Analyzer or the SHOW NOTE command in the PCA Collector. 3 Examples PCAC> SET NOTE "G-FLAT"A 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 pageB fault data. After you enter the GO command with page fault dataD collection enabled, the Collector records in the performance dataB file every page fault that occurs during program execution. TheD Collector records the program counter value, the faulting virtual@ address, and a CPU time stamp for each page fault. You cannot0 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 eachC observed program counter value in the performance data file. YouC can change the sampling interval with the /INTERVAL:n qualifier.D 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:nB Specifies the sampling interval in milliseconds. The value of nD must be at least 10 milliseconds and at most 60,000 milliseconds.B Because the granularity of the system clock is 10 milliseconds,D you should use a multiple of 10. The default sampling interval isD 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_PCSB Specifies that no stack PC values are collected for PC sampling data. 3 Examples PCAC> SET PC_SAMPLING/STACK_PCSD This command enables the collection of program counter samplingD data, and specifies that stack PC values are collected for this measurement. 2 PLOT Analyzer CommandA 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)B on PLOT and TABULATE commands define how the vertical axis of aC histogram or table is partitioned into buckets. For example, theD node specification PROGRAM_ADDRESS BY ROUTINE selects the program@ address domain, the domain of all possible program addresses.B From this domain, it selects the address ranges of the routinesA in the program. Each of these address ranges defines a bucket.@ See HELP Nodespecs for information about node specifications. 3 Qualifiers /qualifiersC The SET PLOT command accepts the same qualifiers as the PLOT andC  TABULATE commands. See HELP PLOT for the qualifier descriptions. 3 Description< The SET PLOT command sets the default qualifiers and nodeD specifications used by the PLOT and TABULATE commands. QualifiersD explicitly specified on the PLOT or TABULATE command override the current defaults. 3 Examples) PCAA> SET PLOT/SOURCE/DESCENDING/NOZEROSD After this SET PLOT command is entered, all subsequent PLOT andA TABULATE commands use the /SOURCE, /DESCENDING, and /NOZEROSB qualifiers unless these qualifiers are explicitly overridden. 2 PROMPT PCA CommandC Changes the PCA prompt string from PCAC> or PCAA> to a string of your choice. Format SET PROMPT string 3 Parameters stringA Specifies the string which is to become the new prompt. If theD string contains blanks, semicolons, or lowercase characters, then* it must be enclosed in quotation marks. 3 Examples PCAC> SET PROMPT MYNAME> MYNAME>9 The above command will change the prompt to MYNAME>. 2 RUN_NAME Collector Command6 Establishes the name of the current collection run. Format SET RUN_NAME run-name 3 Parameters run-nameD Specifies the name of the current collection run. If the run-nameA parameter begins with a digit or contains any characters otherD 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_B SAMPLE_RUN. This run name is recorded in the performance data( file when you enter the GO command. 2 SEARCH PCA CommandC 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 Descripti on@ The SET SEARCH command allows you to set the SEARCH command'sB default qualifiers. If you provide two parameters or qualifiersC that have contradictory actions (such as ALL and NEXT), then the@ latter parameter or qualifier in the sequence is accepted. IfB 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. /IDENTIFIER2 Makes /IDENTIFIER the default SEARCH qualifier. /STRING. Makes /STRING the default SEARCH qualifier. 3 Examples PCAC> SET SEARCH IDENTIFIER PCAC> SHOW SEARCH0 Default search qualifiers: /NEXT /IDENTIFIERC This command sets the default SEARCH qualifier as /IDENTIFIER. 2 SERVICES Collector CommandD 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 systemC services data collection enabled, the Collector intercepts every@ system service call in the user program and records it in theB 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.D 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_PCSC 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)C Specifies that the specifed user routines shall be called at the- start and end of each system service call.* Qualifier Parameter DescriptionA image-name The shareable image containing theA entry-routi ne or/and exit-routine.A entry-routine The routine to call before callingB the system service. The null stringC (i.e. "") indicates no routine is to) be called.D exit-routine The routine to call after calling theD system service. The null string (i.e.@ "") indicates no routine is to be&  called.AThe following rule applies regarding the /USER_ROUTINE qualifier:: 1. Only one of the entry and exit routines may be null;C For more information on user routines in PCA, see the HELP entry for User_Routines. /NOUSER_ROUTINE /NOUSER_ROUTINEC Specifies that no user routines shall be called at the start andB end of each system service call. This is the default upon entry into the PCA Collector. 3 Examples PCAC> SET SERVICES/NOSTACK_PCSC This command specifies the collection of system services data,4 and disables the collection of stack PC values. 2 SOURCE PCA CommandB Directs PCA to a specified list of directories for source files& when source text must be displayed. Format& SET SOURCE dirname [,dirname...] 3 Parameters dirnameB Specifies a directory to search. If multiple dirname parametersC are specified, the specified directories are searched for sourceD files in that order. You may specify a OpenVMS logical name for a dirname.C Note that dirname may consist of one, several, or all the fieldsB in a full file specification, though it typically consists onlyC 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 the6 punctuation for that field as shown in this format. 3 Description< The SET SOURCE command directs PCA to a specified list ofC directories for source files when source text must be displayed.C By default, PCA expects a source file to be in the same locationA 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 toC 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 view7 source files in a source window when in screen mode. 3 Qualifiers /EDITC Specifies that the indicated directory search list is to be used: in locating source files for the Analyzer EDIT command. /MODULE /MODULE=modnameC Specifies that the indicated directory search list is to be usedC in locating source files for the specified module. Other modules do not use this search list. 3 Examples4 PCAC> SET SOURCE [PROJA], [PROJB], DISK:[PETER.PAN]C This command tells the Collector to locate all source files byB searching directories [PROJA], [PROJB], and DISK:[PETER.PAN], in that order.( PCAC> SET SOURCE/MODULE=NICK [TSAKERES]D This command tells the Collector to search directory [TSAKERES]1 when accessing source files for module NICK. 2 STACK_PCS Collector CommandC Enables the collection of stack PC values (return addresses from)  the call stack) when data is gathered. Format SET STACK_PCS 3 DescriptionC 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 pointA consist of the program counter value and all call stack returnA addresses for that data point. In addition, you can collect or@  not collect stack PC values for these data kinds by using theD /STACK_PCS or /NOSTACK_PCS qualifiers. See the Command DictionaryB description for each of the previously mentioned data kinds for more information.C If you collect stack PC values in the Collector, the Analyzer isA able to charge back the resources consumed in shareable imagesB (such as the Run-Time Library) to the code in your program thatC calls the shareable images. To use the stack PC information, useB 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. TheC Analyzer can then associate the gathered data with the task that# caused that data to be gathered. Format SET TASKING 3 DescriptionD The SET TASKING  command instructs the Collector to gather taskingA information. The Analyzer can then associate the gathered dataD with the task that caused that data to be gathered. Any data kindB may be plotted against the TASK domain. This allows you to plot> the amount of time or other resource used in various tasks.A To get the Analyzer to report on data by task, specify the SETA TASKING command in the Collector, then specify the appropriate9 domain in the Analyzer by providing that domain's node/ specification on a PLOT or TABULATE command. 3 Examples PCAC> SET TASKINGB This command causes tasking data to be collected on all tasks' that are defined in the data file. 2 TERMINAL PCA CommandC 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 sizeA that PCA uses to format output. It does not reset the terminalC itself, however; you must do that manually. If you are in screen! mode, the screen is refreshed.B The default terminal width and page size are determined by yourA device type or by the last SET TERMINAL command you entered at DCL level. 3 Qualifiers /PAGE /PAGE:nA Specifies that the terminal page size (the number of lines perD page) should be set to n lines. Normally n is 24, but you may use any value from 11 to 100. /WIDTH /WIDTH:nB Specifies that the terminal width should be set to n columns orC spaces. Typically n is 80 or 132, but you may use any value from 40 to 255. 3 Examples PCAA> SET TERMINAL/WIDTH:132C This command specifies that the terminal width is 132 columns. 2 TITLE Analyzer CommandA 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-textB 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 firstD 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 firstA title-text parameter specifies the text for line n, the s econdC parameter specifies the text for line n+1, and so forth. You can) specify up to six lines of title text. 3 DescriptionB The SET TITLE command establishes up to six lines of title textA to be displayed on each page of output from PLOT, TABULATE andA related commands. The new title does not take effect until youA enter another PLOT or TABULATE command (it does not affect theA current plot or table). Each title line is centered within theD current terminal wi dth. After centering, the rightmost 10 columns@ of the first title line are overlaid with the page number. ToB 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 andC Coverage Analyzer for OpenVMS" is shown on the first title line. 3 Qualifiers /LINE /LINE=nB Specifies that the first title-text parameter should go in lineA 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 usedA to selectively replace certain lines of an already established title. 3 Examples< PCAA> SET TITLE "Welcome to Wonderland", "Enjoy your visit"B This command establishes the specified two-line title for the5 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 inD 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 Command9 Enables the collection of unaligned access fault data. Format SET UNALIGNED 3 Description@ The SET UNALIGNED command enables the collection of unalignedC access fault data. After you enter the GO command with unalignedA 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 theB faulting virtual address and program location where it occured.D 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_PCSD Specifies that stack PC values are collected for unaligned accessA 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 UNALIGNEDB This command enables the collection of unaligned access fault data. 2 VCOUNTERS Collector CommandD 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 gatehrB vector processor instruction counts within the specified range. 3 Description> The SET VCOUNTERS Collector command enables the counting ofA vector processor instructions. The collected data can help youC determine to what extent the vector processor is being used. YouC must specify at least one node specification on the command line6 to indicate the domain of the data to be collected.D 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 beC 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 CommandA Enables the collection of vector program counter sampling data2 that occurs during virtual process or CPU time. Format SET VCPU_SAMPLING 3 DescriptionA The SET VCPU_SAMPLING Collector command enables the collectionB of PC values for random vector instructions. The collected dataC lets you determine the scalar/vector parallelism throughout your entire program.C When you collect vector CPU samples, the sampling interval timer> includes only the time that the program is actually runningB the processor. This form of sampling allows you to focus on theB particular areas of the program's algorithm where time is being? spent, and not on the areas where outside influences consume time. 3 Qualifiers /INTERVALB Specifies the sampling interval in milliseconds. The value of nD must be at least 10 milliseconds and at most 60,000 milliseconds.B Because the granularity of the system clock is 10 milliseconds,< use a multiple of 10. The default sampling interval is 10A 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_PCSC Specifies that not stack PC values for vector CPU data are to beD collected. If used, /NOSTACK_PCS causes further SET VCPU_SAMPLING0 requests to assume a default of /NOSTACK_PCS. 3  Examples0 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 allB further SET VCPU_SAMPLING requests, a default of /NOSTACK_PCS will be assumed. 2 VERIFY PCA CommandD 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 nextB command entered (@X.COM) is therefore echoed to the terminal.A Then a SET DATAFILE and a SET LANGUAGE command are read fromA the command procedure X.COM. Both commands are echoed to the terminal. 2 VPC_SAMPLING Collector CommandB Enables the collection of vector program counter sampling data. Format SET VPC_SAMPLING 3 DescriptionC The SET VPC_SAMPLING Collector command enables the collection ofC PC values for random vector instructions and causes the samplingD rate to be applied to the wall clock. The collected data lets youA determine the scalar/vector parallelism throughout your entire program.B When you collect vector PC samples, the sampling interval timer@ includes all idle time associated with the current run of theC program. This form of sampling shows you where the time is being@ spent in the program with little cost to the time of actuallyD 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,000B milliseconds. Because the granularity of the system clock is 10D milliseconds, use a multiple of 10. The default sampling interval= is 10 milliseconds; therefore, you can use the /INTERVAL:n8 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_PCSB Specifies that stack PC values for vector PC data are not to beC 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 allA 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 ATB (start-line,line-count,start-column,column-count) 3 Parameters window-nameC 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 the7 window. The top line of the screen is line number 1. line-count4 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-countD Specifies the number of columns in the window (the default is the current screen wi dth). 3 DescriptionA 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 aD line count. Once defined, a window name can be used in subsequent$ DISPLAY and SET DISPLAY commands.D PCA provides a substantial number of predefined window names. YouC can list all defined window names using the SHOW WINDOW command. 3 Examples PCAA> SET WINDOW TINY AT (1,2) PCAA> DISPLAY OUT AT TINYB The first command defines a window named TINY. The top borderA line for the window is at line 1 of the terminal screen. The@ window can display two additional lines of text. The secondA command displays the OUT screen display through window TINY. ww$ f1 SHOW PCA CommandA Displays various definitions, data collection options and mode? settings, depending on the keyword specified on the command. Format SHOW keyword [parameters] 2 Parameters keywordA Specifies the data collection option or the kind of definitionC or mode setting to display. Valid keywords in the Collector are:C ALL, COUNTERS, COVERAGE, CPU_SAMPLING, DATAFILE, DISPLAY, EVENT,B IO_SERVICES, LANGUAGE, LOG, MAX_SOURCE_FILES, MODE, NOTE, PAGE_C FAULTS, PC_SAMPLING, RUN_NAME, SEARCH, SELECT, SERVICES, SOURCE,D STACK_PCS, SYMBOL, TASKING, TERMINAL, UNALIGNED, VCOUNTERS, VCPU_- SAMPLING, VERIFY, VPC_SAMPLING and WINDOW.D In the Analyzer, valid keywords are: ALL, ANC, DATAFILE, DISPLAY,D EDITOR, FILTER, KEY, LANGUAGE, LOG, MAX_SOURCE_FILES, MODE, PLOT,D RUN_DESCRIPTION, SEARCH, SELECT, SOURCE, SYMBOL, TERMINAL, TITLE, VERIFY, and WINDOW. parameters$ Depends on the keyword specified. 2 DescriptionB SHOW is not an individual command. Each SHOW command has a two-B keyword name consisting of SHOW followed by a required keyword.= For details, see the individual SHOW command descriptions. 2 ALL PCA CommandB Displays a summary of all data collection options and all major( Collector and Analyzer mode settings. Format SHOW ALL 3 Description= The SHOW ALL command displays all data collection options,> definitions and mode settings you have established. It alsoA displays the name of the log file, the name of the performanceB data file, and information on all major mode settings. EnteringB SHOW ALL is the same as entering a number of more detailed SHOW commands. 3 Qualifiers /FULL> Gives more complete status information than the unqualified< SHOW ALL command. If you specify the /FULL qualifier, you@ see the status of all data collection options, even those notB established, and all mode settings. You also see full data fileA information. If you omit the /FULL qualifier, you see only theD data collection options that are established and only a subset of$ the remaining status information. 3 Examples PCAC> SHOW ALL. Output logging on file: DEV$:[STAR]SHOW.LOG;1 Language: BLISS0 Performance Data File: DBGD$:[STAR]PRIMES.PCA;1 Counters* Set Counters PROGRAM_ADDRESS BY ROUTINE+ Set Counters LINE PRIMES\OPENIN\%LINE 22 Gathering I/O service data Gathering system service data+ Default SEARCH qualifiers: /NEXT /STRING@ This command displays the name of the log file, the currentA language setting, the name of the performance data file, and" all data collections options. 2 ANC Analyzer Command= Displays all the coverage-set points currently set as ANC. Format SHOW ANC 2 COUNTERS Collector Command= Displays the node specifications for which exact execution; counters have been established with earlier SET COUNTERS commands. Format  SHOW COUNTERS 3 Examples PCAC> SHOW COUNTERS Counters* Set Counters PROGRAM_ADDRESS BY ROUTINE+ Set Counters LINE PRIMES\OPENIN\%LINE 22D The SHOW COUNTERS command shows that exact execution counts areD collected for every routine in the user program and for line 22( of routine OPENIN in module PRIMES. 2 COVERAGE Collector Command> Displays the current settings for the SET COVERAGE command. Format SHOW COVERAGE 3 Exa mples PCAC> SHOW COVERAGE CoveragesA Set Coverage /Until=1 /Previous PROGRAM_ADDRESS BY CODEPATH; This SHOW COVERAGE command shows that test coverage isC measured for every codepath in the user program. Each coverage9 breakpoint is removed the first time it is executed. 2 CPU_SAMPLING Collector CommandC Displays whether the collection of program counter sampling data6 that occurs during a process's CPU time is enabled. Format SHOW  CPU_SAMPLING 3 Examples PCAC> SHOW CPU_SAMPLING( Gathering CPU sampling data with STACK_!PCS, AST Timer Interval is 10 ms.? The SHOW CPU_SAMPLING command shows that CPU sampling data< is collected with stack PCs, that the sampling interval> is 10 milliseconds, and that the AST Timer Interval is 10 milliseconds. 2 DATAFILE PCA Command: Displays the name of the current performance data file.< Optionally, other information about the data file i s also displayed. Format SHOW DATAFILE 3 Qualifiers /FULLA Gives more detailed information from the performance data file header. 3 Examples PCAC> SHOW DATAFILE8 Performance Data File: DEV$:[PCA.TST]CUMU_MAIN_IO.PCA;1? The SHOW DATAFILE command displays the name of the current performance data file. PCAC> SHOW DATAFILE/FULL8 Performance Data File: DEV$:[PCA.TST]CUMU_MAIN_IO.PCA;1A Created by: PCA V1.0 Last updated by: PCA V1.0O Created on:25-MAR-1985 15:51:19.07 Last updated on:25-MAR-1985 15:51:30.62- Image file: DEV$:[SAGER.TST]PCAPRIME.EXE;19= Image name: PCAPRIME Image ID: 01@ Image linked on: 8-MAR-1985 13:57:53.14 by Linker: 04-00 There is 1 collection run The DST is 481 bytes long Known shareable images:> FORRTL LIBRTL PCA$COLLECTOR DBGSSISHR+ PCA$PRVSHR LBRSHR SMGSHRB The /FULL qualifier gives more complete information about the data file. 2 DISPLAY PCA CommandA Lists all screen display definitions. The name, screen window,D maximum size, and kind of each defined display are listed. Screen6 displays are created using the SET DISPLAY command. Format SHOW DISPLAY 3 Examples PCAA> SHOW DISPLAY@ display SRC at Q123, size = 64, removed, dynamic, kind = SOURCE6 display PLOT at Q123, size = 64, dynamic, kind = PLOT6 display OUT at E7, size = 100, dynamic, kind = OUTPUT9 display PROMPT at E8, size = 64, dynamic, kind = PROGRAM@ This command displays the definitions of the default screen( displays SRC, PLOT, OUT and PROMPT. 2 EDITOR Analyzer Command@ Displays the current setting of the editor. Also displays the current command line. Format SHOW EDITOR 3 Examples PCAA> SHOW EDITOR4 The editor is CALLABLE_TPU having the command line: "TPU"D This command displays the setting of the editor and its command line. 2 EVENT Collector Command@ Displays the event names and the associated program locations0 established with previous SET EVENT commands. Format SHOW EVENT 3 Examples PCAC> SHOW EVENT Events+ Set Event COMPUTE PRIMES\OPENIN\%LINE 22A This command shows that an event marker for event COMPUTE is? recorded in the performance data file each time line 22 in routine OPENIN is executed. 2 FILTER Analyzer Command+ Displays all current filter definitions. Format SHOW FILTER 3 DescriptionA The SHOW FILTER command lists the name and filter restrictionsD for each defined filter. Filters determine which data points fromA the performance data file are tallied by the PLOT and TABULATEC commands. You can create filters with the SET FILTER command and. delete them with the CANCEL FILTER command. 3 Examples PCAA> SHOW FILTER Filter definitions: Filter F1: RUN_NAME = 1:3 RUN_NAME = 8 Filter F2:! TIME = OUTPUT (event marker)@ The SHOW FILTER command shows that two filters are defined.A Filter F1 has two run-name restrictions and filter F2 has an event marker restriction. 2 IO_SERVICES Collector CommandC Displays whether the collection of I/O services data is enabled. Format SHOW IO_SERVICES 3 Examples PCAC> SHOW IO_SERVICES* Gathering I/O service data with STACK_PCSA The SHOW IO_SERVICES command shows that I/O services data is collected. 2 KEY PCA CommandA Displays predefined key definitions or key definitions created with the DEFINE/KEY command. Format SHOW KEY [key-name] 3 Parameters key-name: Specifies the name of the key whose definition you want@ displayed. See the DEFINE/KEY command for a list of the valid  key names. 3 DescriptionD The SHOW KEY command displays your current key definitions. AfterA you have defined keypad keys using the DEFINE/KEY command, youA can use the SHOW KEY command to list your key definitions. YouC can use the /DIRECTORY qualifier to list the names of all statesB (DEFAULT, GOLD, BLUE, EXPAND, MOVE and CONTRACT) in which there are key definitions. 3 Qualifiers /ALL= Specifies that all key definitions in the current state be= displayed. You can use the /STATE qualifier to request keyA definitions in other states. If you use the /ALL qualifier, do not specify a key name. /BRIEF /BRIEF /NOBRIEF= The /BRIEF qualifier requests that only the key definition@ and state be displayed. /NOBRIEF requests that all qualifiers< associated with a key definition be displayed. The /BRIEFA qualifier performs the same function as the /NOFULL qualifier. /BRIEF is the default. /DIRECTORYB Specifies that the names of all states for which keys have been? defined be displayed. The predefined key states are DEFAULT,) GOLD, BLUE, EXPAND, MOVE and CONTRACT. /FULL /FULL /NOFULLC The /FULL qualifier requests that all qualifiers associated with@ a key definition be displayed. The /NOFULL qualifier requestsA that only the key definition and state be displayed. The /FULLB qualifier performs the same function as the /NOBRIEF qualifier. /NOFULL is the default. /STATE /STATE=(state-name[,...]) /NOSTATE< Specifies the name of a state for which the specified keyA definitions are to be displayed. If you specify only one stateA name, you can omit the parentheses. The predefined state namesA are DEFAULT, GOLD, BLUE, EXPAND, MOVE and CONTRACT. Additional7 state names are created with the DEFINE/KEY command.D If you omit the /STATE qualifier or use /NOSTATE, key definitions& in the current state are displayed. 3 Examples PCAC> SHOW KEY KP2 DEFAULT keypad definitions: KP2 = "SHOW ALL/FULL"> This command displays the DEFAULT definition for key KP2. 2 LANGUAGE PCA Command> Displays the current language setting. The language setting? determines how symbol names are parsed. The language settingC is initially determined from the language of the main routine inA the user program. You change it with the SET LANGUAGE command.  Format SHOW LANGUAGE 3 Examples PCAC> SHOW LANGUAGE Language: FORTRANC This command shows that FORTRAN is the currently set language. 2 LOG PCA Command< Shows whether PCA input and output is being recorded in a? log file. If logging is enabled, the name of the log file is: displayed. Logging is enabled with the SET LOG command. Format SHOW LOG 3 Examples PCAC> SHOW LOG2 Output logging on file: USRD$:[CARRELL]PCAC.LOG;1D This command shows that output logging is enabled and gives the name of the log file. 2 MAX_SOURCE_FILES PCA Command@ Displays the maximum number of source files that PCA can keepD open at any one time. This value can be changed with the SET MAX_ SOURCE_FILES command. Format SHOW MAX_SOURCE_FILES 3 Examples PCAA> SHOW MAX_SOURCE_FILES Max_source_files: 10@ This command shows that PCA can keep up to ten I/O channels'  open for source files at one time. 2 MODE PCA CommandB Displays whether keypad mode is enabled. Keypad mode is enabled) or disabled with the SET MODE command. Format SHOW MODE 3 Examples PCAC> SHOW MODE6 Mode: noscreen, keypad, scroll, nomovie, nolog_screen4 This command shows that keypad mode is enabled. 2 NOTE Collector Command< Displays the note defined for the current collection run. Format SHOW NOTE 3 DescriptionD The SHOW NOTE command allows you to retrieve the note defined for5 the current collection run from the PCA data file. 3 Examples PCAC> SET NOTE "G_FLAT" PCAC> SHOW NOTE Run note: "G-FLAT"@ Thess command set and then display the note for the current collection run. 2 PAGE_FAULTS Collector CommandA Displays whether the collection of page fault data is enabled. Format SHOW PAGE_FAULTS 3 Examples PCAC> SHOW PAGE_FAULTS Gathering page fault data? The SHOW PAGE_FAULTS command shows that page fault data is collected. 2 PC_SAMPLING Collector CommandC Displays whether the collection of program counter sampling data is enabled. Format SHOW PC_SAMPLING 3 Examples PCAC> SHOW PC_SAMPLING' Gathering PC sampling data with STACK_!PCS, AST Timer Interval is 10 ms.< The SHOW PC_SAMPLING command shows that program counter> sampling data is collected with stack PC values, that theA sampling interval is 10 milliseconds, and that the AST Timer! Interval is 10 milliseconds. 2 PLOT Analyzer CommandC Displays the current SET PLOT and active plot default qualifiers and node specifications. Format SHOW PLOT 3 Description@ The SHOW PLOT command shows both the SET PLOT and the current active plot defaults. 3 Examples PCAA> SHOW PLOT Plot and tabulate defaults: Qualifiers:3 /PC_SAMPLING /DESCENDING /NOMINIMUM /NOMAXIMUM8 /NOCUMULATIVE /SOURCE /ZEROS /NOSCALE /NOCREATOR_PC3 /NOPATHNAME /NOCHAIN_NAME /WRAP /NOPARENT_TASK, /FILL=("*","O","x","@",":","#","/","+")! /NOSTACK_DEPTH /NOMAIN_IMAGE Node specifications: PROGRAM_ADDRESS BY ROUTINE Setting for current plot: Qualifiers:3 /PC_SAMPLING /DESCENDING /NOMINIMUM /NOMAXIMUM8 /NOCUMULATIVE /SOURCE /ZEROS /NOSCALE /NOCREATOR_PC3 /NOPATHNAME /NO CHAIN_NAME /WRAP /NOPARENT_TASK, /FILL=("*","O","x","@",":","#","/","+")! /NOSTACK_DEPTH /NOMAIN_IMAGE Node specifications: TIME BY EVENTD The SHOW PLOT command displays the SET PLOT defaults first. TheD qualifiers and node specifications of the currently active plot are shown next. 2 RUN_DESCRIPTION Analyzer Command: Displays the kinds of data that were collected for each@ collection run in the performance data file. This information? c!onstitutes a condensed version of what the SHOW ALL command; would have shown you in the original Collector sessions. Format$ SHOW RUN_DESCRIPTION parameter 3 Parameters run-name? Specifies a collection run name. The run description for anyB run whose run name matches the run-name parameter is displayed.B If run-name includes asterisks (*), each asterisk is treated asA a wildcard character that matches any zero or more characters.B If run-name is "not an alphanumeric name, or if it begins with a1 digit, it must be enclosed in quotation marks. run-numberA Specifies a collection run number. The run description for any6 collection run in the specified range is displayed. 3 Examples PCAA> SHOW RUN_DESCRIPTION 2:3$ Collection number 2. Named - "FOO" Events& Set Event MARK_ROUTINE PRIMEPRIME: Gathered PC sampling data, AST Timer Interval is 10 ms.) Collection number 3. Named - "COVERAGE" Coverag#es5 Set Coverage /Until=1 PROGRAM_ADDRESS BY ROUTINE@ This command describes what data was gathered in collectionC runs 2 through 3. Run 2 gathered program counter sampling dataA and used an event marker. Run 3 gathered test coverage data. PCAA> SHOW RUN_DESCRIPTION *! Collection number 1. Named - "" Counters, Set Counters PROGRAM_ADDRESS BY ROUTINE Gathered I/O service data Gathering stack PC data- Collection number 2. Named - "event_marker": G$athered PC sampling data, AST Timer Interval is 10 ms.) Collection number 3. Named - "COVERAGE" Coverages5 Set Coverage /Until=1 PROGRAM_ADDRESS BY ROUTINEB This command describes all collection runs. The asterisk is a2 wildcard character and matches all run names. 2 RUN_NAME Collector Command< Displays the current collection run name. The run name is- established with the SET RUN_NAME command. Format SHOW RUN_NAME 3 Examples P%CAC> SHOW RUN_NAME Current run name = "STEVE"C This command shows that the name of the current collection run is STEVE. 2 SEARCH PCA Command2 Displays the current default SEARCH qualifiers. Format SHOW SEARCH 3 Examples PCAC> SET SEARCH ALL, STRING PCAC> SHOW SEARCH* Default search qualifiers: /ALL /STRING: This command shows the current default SEARCH command qualifiers. 2 SELECT PCA CommandB Displays &the names of the current output, plot, source, and theB current scrolling display. These settings are established using the SELECT command. Format SHOW SELECT 3 Examples PCAA> SHOW SELECT screen mode not set display selections: scroll = PLOT input = none output = OUT error = PROMPT source = SRC program = PROMPT prompt = PROMPT plot = PLOTA The SHOW SELECT command shows that screen display OUT is theB ' current output display, display PLOT is the current scrolling display, and so on. 2 SERVICES Collector Command= Displays whether the collection of system services data is enabled. Format SHOW SERVICES 3 Examples PCAC> SHOW SERVICES- Gathering system service data with STACK_PCSA The SHOW SERVICES command shows that system services data is collected. 2 SOURCE Collector CommandA Displays the current source dir(ectory search lists established with the SET SOURCE command. Format SHOW SOURCE 3 Description@ The SHOW SOURCE command displays the current source directory> search lists. The source directory search list currently inC effect determines what directories are searched for source filesB when source text must be displayed. The source directory search4 list is established using the SET SOURCE command. 3 Qualifiers /EDIT> Shows the directory) search list established by the last SET@ SOURCE/EDIT command. If specified, this directory search list9 is used in locating source files for the EDIT command. 3 Examples PCAC> SHOW SOURCE+ source directory search list for PCAPRIME: [BEANDER]- source directory list for all other modules: [] SRC$B This command shows that two source directory search lists areD defined: one for module PCAPRIME and one for all other modules. 2 STA*CK_PCS Collector Command= Displays whether the collection of stack PC values (return- addresses from the call stack) is enabled. Format SHOW STACK_PCS 3 Examples PCAC> SHOW STACK_PCS Not gathering stack PC data? This command shows that stack PC values are not collected. 2 SYMBOL PCA Command< Displays information about symbols in the program addressD domain, or symbol definitions established with the DEFINE/COMMAND command.+ FormatB SHOW SYMBOL namespec[, namespec ...] [IN scope[, scope ...]] 3 Parameters namespecA Specifies the name of the symbol to show. If namespec includesB asterisks (*), each asterisk is treated as a wildcard characterD that matches any zero or more characters. All symbols whose names match namespec are shown. scopeA Specifies the name of a module, routine, or lexical block, and& may include pathname qualification. 3 Description,> The SHOW SYMBOL command lets you see symbols in the program7 address domain, or symbols you have defined with the DEFINE/COMMAND command.C You can use the /ADDRESS and /DIRECT qualifiers or the IN clause> only if /DEFINED is not specified. If you do not specify anA IN clause, then the whole program will be the scope for symbol selection.A The /DEFINED qualifier can not be used in combination with any/ other qualifiers to the SHOW SYMBOL command. 3 Quali-fiers /ADDRESSD Displays the address specification for each selected symbol, when applicable. /DEFINEDB Displays symbol definitions established with the DEFINE/COMMAND command. /DIRECT; Displays symbols that are defined directly in the symbol> selection scope. Symbols defined in lexical entities nestedD within the scope specified by the scope parameters are not shown. 3 Examples PCAA> SHOW SYMBOL/DEFINED * Defined commands: P = ".PLOT/NOZERO/DESCENDING"7 BSGB = "SET FILTER FUM PROGRAM_ADDRESS=MUMBLE_FRATZ"= This SHOW SYMBOL command displays the definitions of allB symbols defined using DEFINE/COMMAND. Only two symbols, P andB BSGB, are defined. Their names and definitions are displayed. PCAA> SHOW SYMBOL/ADDRESS SCALE Module SCALE, language PASCAL& Address range: 00000200 to 00000297 Routine SCALE\SCALE& Address range: 00000200 to 0000020BB This SHOW SYMBOL command is used to dis/play address ranges of" any program unit named SCALE. 2 TASKING Collector CommandB Displays the status of the tasking measurement set with the SET TASKING command. Format SHOW TASKING 2 TERMINAL PCA Command= Displays the terminal width and page size used by PCA whenA formatting output. These settings can be changed using the SET TERMINAL command. Format SHOW TERMINAL 3 Examples PCAA> SHOW TERMINAL+ Termi0nal page size: 24, Terminal width: 80= This command shows that the Analyzer currently assumes a> terminal page size of 24 lines and a terminal width of 80$ columns when formatting output. 2 TITLE Analyzer Command@ Displays the current title text established with the last SETC TITLE command. This title text is output on top of every page of PLOT and TABULATE output. Format SHOW TITLE 3 Examples PCAA> SHOW TITLE Current title t1ext: "Welcome to Wonderland" "Enjoy your visit"B This command displays the text of the current two-line title. 2 UNALIGNED Collector CommandD Displays whether the collection of unaligned access fault data is enabled. Format SHOW UNALIGNED 3 Examples PCAC> SHOW UNALIGNED/ Gathering unaligned access data with STACK_PCSA The SHOW UNALIGNED command shows that unaligned access fault data is collected. 2 VCOUNTERS2 Collector Command@ Displays the node specifications for which vector instruction< counters have been established with earlier SET VCOUNTERS commands. Format SHOW VCOUNTERS 3 Examples PCAC> SHOW VCOUNTERS4 Set Vector Counters MODULE PRIMES BY VINSTRUCTIOND The SHOW VCOUNTERS command shows what vector instruction counts9 are collected for MODULE in the user program PRIMES. 2 VCPU_SAMPLING Collector Command@ Displays whether a 3collection of vector program sampling data6 that occurs during a process's CPU time is enabled. Format SHOW VCPU_SAMPLING 3 Examples PCAC> SHOW VCPU_SAMPLING< Gathering Vector CPU sampling data with STACK_PCS, AST Time Interval is 10 ms.B This command shows that vector CPU sampling data is collectedC with stack PCs, that the sampling interval is 10 milliseconds,7 and that the AST Time Interval is 10 milliseconds. 2 VERIFY PCA Command4B Displays whether command input is being echoed to the terminal.= Input verification is enabled with the SET VERIFY command. Format SHOW VERIFY 3 Examples PCAC> SHOW VERIFY Not verifying commandsB The SHOW VERIFY command shows that command input verification is disabled. 2 VPC_SAMPLING Collector CommandC Displays whether a collection of vector program counter sampling data is enabled. Format SHOW VPC_SAMPLING5 3 Examples PCAC> SHOW VPC_SAMPLING> Gathering vector PCA sampling data with /STACK_PCS, AST Timer Interval is 10 ms.A This command shows that vector PC sampling data is collectedC with stack PCs, that the sampling interval is 10 milliseconds,8 and that the AST Timer Interval is 10 milliseconds. 2 WINDOW PCA CommandD Displays the names and definitions of all defined screen windows.? Screen windows are either predefined or defined with the SET#6 WINDOW command. Format SHOW WINDOW 3 Qualifiers /ALL5 Displays all PCA-defined and user-defined windows. ww f1 SPAWN PCA Command= Spawns a subprocess so you can temporarily suspend the PCA= session to run another program or to execute DCL commands. Format SPAWN [dcl-command] 2 Parameters dcl-command: Specifies a DCL command. If you specify the dcl-commandB parameter, a subprocess 7 is created which executes the specifiedC DCL command. Control is returned to the PCA session when the DCL command terminates.C If you omit the dcl-command parameter, the SPAWN command createsB a subprocess and attaches the terminal to that process. You canC then enter DCL commands at the terminal. When you log out of theD subprocess or attach back to the parent process, you can continue your PCA session.@ If the DCL command you specify includes a semicolon, you mustC8 enclose the command in quotation marks. Otherwise, the semicolon< can be mistaken for a PCA command separator. To include aD quotation mark inside the string, enter two consecutive quotation marks. 2 Description@ The SPAWN command acts the same as the DCL SPAWN command. You? can use it to break out of the PCA session to edit files, toC read mail, or to do any other tasks you would normally do at DCL. level, all without ending your PCA session. 2 Qualifiers9 /NOWAITC Specifies that PCA should not wait for the subprocess to finish.B You can then enter additional PCA commands while the subprocessB is running. When the subprocess eventually completes, a messageD is displayed on your terminal. In general, you should not use theC /NOWAIT qualifier if the spawned subprocess prompts for input or( displays much output on the terminal. 2 Examples PCAC> SPAWN MAIL You have 1 new message. MAIL> READ\NEW . . . M:AIL> EXIT5 %PCA-I-RETURNED, control returned to process CARRELL PCAC>A This command spawns a subprocess that runs the MAIL program.< When you exit from MAIL, you return to the original PCA session. PCAC> SPAWN $ TYPE MUMBLE.DAT . . . $ LOGOUT? Process CARRELL_1 logged out at 29-FEB-1985 14:10:43.555 %PCA-I-RETURNED, control returned to process CARRELL PCAC>B This command spawns a subprocess. Since you did not specify aA DCL command on the ;SPAWN command, the subprocess prompts forD DCL commands. When you log out of the subprocess, you return to the PCA session. ww f 1 TABULATE Analyzer CommandD Processes performance or coverage data and displays the processed> data in tabular form. The TABULATE command accepts the sameA qualifiers and parameters as the PLOT command, and it displays? the same information as the PLOT command, but in the form of tables instead of histograms.< Format( TABULATE [nodespec [,nodespec...]] 2 Parameters nodespecD Specifies a program location. Node specifications specify how theC table should be partitioned into buckets. See HELP Nodespecs for) information about node specifications. 2 DescriptionC See PLOT for a full discussion of the PLOT and TABULATE commands and their qualifiers. 2 Examples" PCAA> TABULATE PROGRAM BY ROUTINED This command tabulates program counter =sampling data by defaultC since no data-kind qualifier is specified. The resulting table> has one entry for each routine in the program. Each entryB shows the number of program counter values collected from the@ corresponding routine, what percentage this is of the totalC number of PC values collected, and how wide the 95% confidence interval is.2 PCAA> TABULATE/COUNTERS/SOURCE MODULE FOO BY LINE@ This command tabulates exact execution counts for each lineA > in module FOO. (This assumes that such execution counts wereB collected in the data file.) The /SOURCE qualifier causes theB text of each source line to be shown next to the table entry.- PCAA> TABULATE/PAGE_FAULTS TIME BY 100 MSECS> This command generates a table showing the number of pageA faults in each 100-millisecond time interval since the start= of the collection run. The intervals represent CPU time.? Inspection of this table may reveal page faulting ? peaks atC various times during program execution. Such peaks often occurD when a program switches from one phase of execution to another;A the new phase typically requires a different set of code and1 data pages from those in the previous phase.+ PCAA> TABULATE/IO_SERVICES FILE_KEY BY KEYA This command creates a table showing the number of RMS calls@ that performed I/O using no key, a primary key, a secondary@ key, or a higher-order key. Keys are used to @access indexed@ sequential files. Primary key access is more efficient thanA secondary key access. Thus, if more I/O is done on secondaryC keys than primary keys, I/O may go faster if the key positions are switched. ww f1 TYPE PCA Command@ Specifies which lines of source code to display in the source window. Format6 TYPE [[modname\]line-number[:line-number]][,...] 2 Parameters modname? Specifies the nAame of a module. Indicates that the lines are? contained in that module. The default is the current module. line-number> Defines the line or range of lines to display in the sourceA window. Must be expressed as a decimal integer (the default is 1) 2 Description? The TYPE command allows you to view a line or range of lines? in your source code. The lines are displayed on the terminal? screen. To use the TYPE command, you may have to establish a< source Bdirectory search list with the SET SOURCE command.@ Modname without any line numbers will display the first line.A If you provide only one line number, the corresponding line of? source code with its line number is displayed. Also, becauseC the default line number is the number for the line following theD last line displayed, you can display the next line by issuing theB TYPE command without a line number and then pressing the RETURND key. By repeating this sequence, you can Cread through your source program one line at a time. 2 Examples PCAC> TYPE COBOLTEST\160,22:24 module COBOLTEST 160: START-IT-PARA. module COBOLTEST8 22: 02 SC2V2 PIC S99V99 COMP VALUE 22.33.8 23: 02 SC2V2N PIC S99V99 COMP VALUE -22.33.9 24: 02 CPP2 PIC PP99 COMP VALUE 0.0012.C This command displays lines 160 and lines 22 through 24 in the module COBOLTEST. ww f 1 UNDEFINE PCA ComDmand8 Command keyword for the commands UNDEFINE/COMMAND andA UNDEFINE/KEY. Deletes command definitions established with theB DEFINE/COMMAND command, and deletes key definitions established with the DEFINE/KEY command. Format! UNDEFINE/COMMAND parameters UNDEFINE/KEY parameters 2 Parameters parameters% Depend on the qualifier specified. 2 /COMMAND PCA CommandB Deletes command definitions established with the DEFINE/COMMAEND command. Format1 DELETE/COMMAND symbol-name[,symbol-name...] 3 Parameters symbol-nameC Specifies the name of a command symbol whose definition is to beC deleted. This symbol name must have been defined with a previous DEFINE/COMMAND command. 3 Description9 The UNDEFINE/COMMAND command is used to delete command< abbreviations the DEFINE/COMMAND command establishes. TheB UNDEFINE/COMMAND command and the DELETE/COMMAND command perfo!Frm the same function. 3 Examples PCAC> UNDEFINE/COMMAND FOO, FEEC This command undefines the command definitions for symbols FOO and FEE. 2 /KEY PCA CommandC Deletes key definitions established with the DEFINE/KEY command. Format UNDEFINE/KEY [key-name] 3 Parameters key-name= Specifies the name of the key whose definition you want to delete. 3 Description? The UNDEFINE/KEY command deletes key defiGnitions established@ with the DEFINE/KEY command. The UNDEFINE/KEY command and the0 DELETE/KEY command perform the same function. 3 Qualifiers /ALL? Specifies that all key definitions in the specified state be? deleted. If you use the /ALL qualifier, do not specify a keyB name. If you do not specify a state, all key definitions in theA current state are deleted. Use the /STATE qualifier to specify one or more states. /LOG /LOG /NOLOGHB Controls whether a log message is displayed indicating that theB specified key definition has been deleted. The default is /LOG. /STATE /STATE=(state-name [,...]) /NOSTATEB Specifies the names of the states under which the specified key? definitions are to be deleted. If you specify only one state> name, you can omit the parentheses. A state name can be any# appropriate alphanumeric string.? If you omit the /STATE qualifier or if you use /NOSTATE, ke y0 definitions in the current state are deleted. 3 Examples PCAC> UNDEFINE/KEY KP7B This command undefines the key definitions for the keypad key+ KP7 (the 7 key on the numeric keypad).ww