DECset________________________________________ Release Notes for DIGITAL PCA Version V4.6 November 1998 These are the release notes for DIGITAL Performance and Coverage Analyzer V4.6 on OpenVMS Alpha and OpenVMS VAX. These release notes contain important general information, new and changed features, current restrictions, and documentation notes. Operating System and Version: OpenVMS VAX, Versions 6.2 - 7.2 OpenVMS Alpha, Versions 6.2 - 7.2 DECwindows Motif, Versions 1.2-3 - 1.2-5 Software Version: DECset for OpenVMS, Version V12.3 Software Version: DIGITAL Performance and Coverage Analyzer for OpenVMS, Version V4.6 Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ November 1998 While DIGITAL and EDS believe the information included in this publication is correct as of the date of publication, it is subject to change without notice. Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from DIGITAL, an authorized sublicensor, or the identified licensor. Digital Equipment Corporation or EDS makes no repre- sentation that the interconnection of its products in the manner described in this document will not infringe existing or future patent rights, nor do the descriptions contained in this document imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. Copyright © Digital Equipment Corporation 1992, 1998. All Rights Reserved. Copyright © Electronic Data Systems Limited 1994, 1998. The following are trademarks of Digital Equipment Corporation: DEC Ada, DEC BASIC, DEC C, DEC C++, DIGITAL COBOL, DECdocument, DECnet, DEC Pascal, DECset, DECwindows, DIGITAL, DIGITAL Fortran, OpenVMS, VAX, VAX BLISS-32, OpenVMS Cluster, VAX DOCUMENT, and the DIGITAL logo. All other trademarks and registered trademarks are the property of their respective holders. This document was prepared using VAX DOCUMENT, Version 2.1. ________________________________________________________________ Contents Preface.................................................. v 1 General Information 1.1 Introduction.................................... 1-1 1.2 Associated Documents............................ 1-1 1.3 Installation.................................... 1-2 1.3.1 Documentation ................................ 1-2 1.3.2 Performance Hints ............................ 1-2 1.3.3 Installation Requirements .................... 1-2 2 New Features 2.1 New Features in PCA V4.6........................ 2-1 3 Problems Fixed 4 Known Problems 4.1 OpenVMS Alpha systems........................... 4-2 4.2 OpenVMS VAX systems............................. 4-2 5 Restrictions 5.1 Collector....................................... 5-1 5.1.1 DECwindows ................................... 5-3 5.1.2 OpenVMS Alpha systems ........................ 5-3 5.1.3 OpenVMS VAX systems .......................... 5-3 5.1.4 User Routines ................................ 5-4 5.2 Analyzer........................................ 5-4 5.2.1 DECwindows ................................... 5-4 iii 5.2.2 OpenVMS VAX systems .......................... 5-5 5.3 DECwindows...................................... 5-5 6 Reporting Problems and Suggestions Tables 1 Conventions Used ............................. vi iv ________________________________________________________________ Preface These release notes characterize DIGITAL Performance and Coverage Analyzer (PCA) V4.6 on the OpenVMS Alpha and OpenVMS VAX operating systems. These notes contain information that either supplements or supersedes the information in the DECset documentation set. Intended Audience These release notes are intended for any user or system manager who needs information on PCA for the OpenVMS platform. Document Structure These release notes are organized as follows: o Chapter 1 contains general information about this release. o Chapter 2 contains a description of the new features. o Chapter 3 describes all problems resolved by the current release. o Chapter 4 describes all outstanding issues in the current release. o Chapter 5 describes all restrictions. o Chapter 6 describes how to report problems. v Sending DIGITAL Your Comments We welcome your comments on these release notes or on any other pieces of documentation. See Chapter 6 for details on how to contact DIGITAL with your comments. Conventions Table 1 lists the conventions used in these notes Table_1_Conventions_Used__________________________________ Convention__________Description___________________________ $ A dollar sign ($) represents the OpenVMS DCL system prompt. In interactive examples, a key name enclosed in a box indicates that you press a key on the keyboard. Ctrl/x The key combination Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key, for example, Ctrl/Y or Ctrl/Z or a pointing device button. boldface text Boldface text represents the introduction of a new term. monospace boldface Boldface monospace text represents text user input in interactive examples. italic text Italic text represents book titles, parameters, arguments, and information that can vary in system messages (for example, Internal error number). UPPERCASE Uppercase indicates the name of a command, routine, the name of a file, the name of a file protection code, or the abbreviation of a system privilege. (continued on next page) vi Table_1_(Cont.)_Conventions_Used__________________________ Convention__________Description___________________________ lowercase Lowercase in examples indicates that you are to substitute a word or value ____________________of_your_choice._______________________ vii 1 ________________________________________________________________ General Information 1.1 Introduction The information in these release notes pertain to DIGITAL Performance and Coverage Analyzer (PCA) V4.6. DIGITAL suggests that you upgrade your environment incrementally with each new release but there is no technical requirement to do so. It is recommended that you review the release notes for each version because they capture important release-oriented information and advise you of changes between versions. DIGITAL Performance and Coverage Analyzer (PCA) V4.6 is a minor release. 1.2 Associated Documents The documentation for DIGITAL Performance and Coverage Analyzer has been revised for this release. This revision corrects errors, enhances descriptions, and describes all new functionality. For more information on the DIGITAL Performance and Coverage Analyzer refer to the following documents: o DECset OpenVMS VAX V12.3 Software Product Description o DECset OpenVMS Alpha V12.3 Software Product Description o DECset Guide to Detailed Program Design for OpenVMS Systems o Using DECset for OpenVMS Systems o Guide to DIGITAL Performance and Coverage Analyzer for OpenVMS Systems o DIGITAL Performance and Coverage Analyzer for OpenVMS Reference Manual General Information 1-1 o DIGITAL Performance and Coverage Analyzer for OpenVMS Command-Line Interface Guide o DECset Installation Guide for OpenVMS Systems o DECset Cookbook New with this release is the "DECset Cookbook". This document contains technical articles giving instructions on the use of DECset components in particular situations. This document is provided online in PostScript format and can be found in: SYS$SYSROOT:[SYSHLP.EXAMPLES.DECSET]DECSET_COOKBOOK.PS 1.3 Installation 1.3.1 Documentation The installation guide for PCA is contained within the DECset Installation Guide for OpenVMS Systems. 1.3.2 Performance Hints DIGITAL recommends the following if the DECwindows interface is used, the following figures are approximate and are the minimum recommendations. o Modify the user's WSQUOTA to 512. o Modify the user's WSEXTENT to 3100. 1.3.3 Installation Requirements o To use the PCA Motif interfaces you must have previously installed OpenVMS DECwindows Motif Version 1.2-3 or higher. o PCA must be re-installed after an OpenVMS upgrade as the PCA collector links against the system. OpenVMS Alpha systems o Prerequisite version of OpenVMS Alpha is Version 6.2 or higher. 1-2 General Information o For a new installation of PCA the following is required: Global Pagelets 3500 Global Sections 10 Disk Blocks 40000 OpenVMS VAX systems o Prerequisite version of OpenVMS VAX is Version 6.2 or higher. o For a new installation of PCA the following is required: Global Pages 1400 Global Sections 10 Disk Blocks 23000 General Information 1-3 2 ________________________________________________________________ New Features The following is a brief summary of enhancements added to the DIGITAL Performance and Coverage Analyzer (PCA). 2.1 New Features in PCA V4.6 There are no new features in this release of PCA. New Features 2-1 3 ________________________________________________________________ Problems Fixed o Bugs 193, 194: SET SERVICE/STACK and SET IO_SERVICE /STACK no longer corrupts values on the stack (PCA V4.5 on OpenVMS Alpha V7.1). Problems Fixed 3-1 4 ________________________________________________________________ Known Problems o Bug 32: Source line with multiple PC ranges can cause misreporting. The Analyzer does not properly assign the PC ranges to Source line with multiple PC ranges. In fact, it simply ignores all ranges after the first. This occurs much more frequently on Alpha system than on VAX systems due to the more extensive optimizations performed by the RISC system compilers. The net result is that data points will be assigned to the summary line: Data count not in defined buckets: for "BY LINE" plots which are not assigned to that summary line for "BY MODULE" plots. For COUNTER and COVERAGE data the problem can be safely ignored. It simply means that the Collector put a breakpoint down multiple times for the same line. For other data it means that the attribution of those data points cannot be determined at a granularity smaller than a routine. And if the percentage is very large, the analysis of the data becomes suspect. Compiling the program /NOOPTIMIZE will greatly reduce the occurances of this behavior in most cases. o Bug 106: The PCA Analyzer command TABULATE/CHAIN_NAME /ALPHABETICAL does not properly sort long call chain names. Known Problems 4-1 4.1 OpenVMS Alpha systems o Bug 160: I/O system services (and probably system services) are charged against the wrong line on Ada tasking programs on OpenVMS Alpha. o Bug 172: Prior to OpenVMS Alpha V7.0 PCA incorrectly marks lines as covered when collecting COUNTERS BY LINE. 4.2 OpenVMS VAX systems o Bug 83: PCA data corruption occurs with FORTRAN statement functions. o Bug 112: The PCA Collector locks up when calling user routines which call system services not written in C after intercepting a system service. 4-2 Known Problems 5 ________________________________________________________________ Restrictions 5.1 Collector o PCA cannot gather data from any user program which calls SYS$EXIT directly or indirectly from its own exit handler, because it will not allow the Collector to close its data file correctly. Issuing SYS$EXIT from an exit handler will suppress the execution of the remaining exit handlers of that mode. Since PCA's exit handler runs after the user's exit handler, PCA's exit handler does not run at all in this situation, and the data file is not closed properly. As a result, the data gathered is lost. Two RTL routines that we know call SYS$EXIT are LIB$RUN_PROGRAM and LIB$DO_COMMAND. o The Collector is not AST re-entrant during program exit. PCA's exit handler cleans up and closes the data file. If an AST should fire during that time, the program's behavior is unpredictable. To avoid this situation, the user program should make sure there are no pending ASTs. o PCA does not gather system service or I/O system service data for user code which is called between a call to a system service and its return. o When both system service interception and random sampling data with stack PCs is being gathered, unnamed PCs in P0 space may appear in call chains. These will appear as hex addresses. These addresses may be caused by PCA's system service interception because the "real" system service vector has been relocated. Restrictions 5-1 o User programs must not use event flags which have not been allocated by LIB$GET_EF. If a user program uses event flags which are being used concurrently by PCA the results of both the user program and PCA will be unpredictable. o Users whose programs utilize the OpenVMS run-time library (RTL) heap storage management routines should be aware that PCA also utilizes these routines for dynamic memory allocation. PCA allocates memory from its own zones, so there will be no interaction between PCA and user programs which use either their own zones or the default zone. User programs should perform operations only on those VM zones which they create or the default zone. If a user program deletes or resets the zones used by PCA the results will be unpredictable. The data collected by PCA will be incomplete and possibly corrupted, indeterminate error messages may be issued, and the process may appear to hang. It is important to be aware that LIB$FIND_VM_ZONE and LIB$FIND_VM_ZONE_64 may return identifiers for zones which were not created by the user program, including those created by PCA. Any user program which calls these routines must take care not to modify, reset, or delete zones it did not create. It should also be noted that PCA is still executing at the time user program exit handlers are invoked; therefore, the above warnings also pertain to exit handlers. o PCA does not correctly correlate stack PCs collected for services or IO services when PROGRAM_ADDRESS BY LINE is selected and the program is not compiled /NOOPTIMIZE as multiple adjacent but non overlapping DSTs describe the system service call line. The workaround is to compile the program /NOOPTIMIZE. o Programs which use the LBR$ routines must use only the library index returned by LBR$OPEN in subsequent calls to other LBR$ routines. Because PCA uses these routines to access help libraries, a program which makes assumptions about the value of the library index 5-2 Restrictions may fail unexpectedly and/or corrupt the PCA help library when run with PCA. An example of incorrect programming technique is assuming that the first library opened by the user program will be assigned an index = 1. 5.1.1 DECwindows o Switching a context from the DECset Environment Manager does not have any effect on the execution environment of currently invoked PCA collector sessions. o PCA uses DECwindows help to allocate, access and control the PCA help in DECwindows, as a result the library index is never deallocated. The user program must therefore ensure that a conflict does not occur with PCA by not assuming anonymous usage and using LBR$INI_CONTROL to allocate a library index for subsequent library operations. 5.1.2 OpenVMS Alpha systems o Codepath data cannot be collected. o Vector data cannot be collected. o When using PCA to analyze FORTRAN programs on OpenVMS Alpha systems, the clauses BY LINE and BY CODEPATH can not be used in conjunction with nodespecs which cover addresses containing alternate entry points (defined by the FORTRAN ENTRY statement). We expect this restriction to be removed in a future release of PCA. 5.1.3 OpenVMS VAX systems o PCA does not gather system service or I/O system service data for nested system service calls (e.g. system services calls in an action routine called from CLI$DCL_PARSE). o Unaligned access fault data cannot be collected. Restrictions 5-3 o PCA may generate errors analyzing PLI programs compiled with the /CHECK qualifier. The workaround is to compile the program without /CHECK before running it with PCA. 5.1.4 User Routines o PCA will not call, or invoke, your user routine image if it is linked with warnings or errors. o You must define a logical name to access the user routine image if it is not found in SYS$SHARE. o 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 glossary of the DIGITAL Performance and Coverage Analyzer for OpenVMS Reference Manual). If written in some other languages, it may have the effect of locking up PCA. Examples are provided in PCA$EXAMPLES. 5.2 Analyzer o The Analyzer sometimes runs out of virtual memory for very large plots (on the order of 100,000 buckets). o PCA cannot merge PCA data files with different image names. o PCA cannot merge PCA data files with identical image names and different image identifiers, link times or link identifiers except using MERGE/ANC. Only coverage- set information from the input PCA data file that can be validated by codepath information from both the input and output PCA data files will be added to the coverage-set table of the output PCA data file. 5.2.1 DECwindows o No graphical print support is available, however, text versions of histograms can be printed using the "Save Chart" button. 5-4 Restrictions o After choosing either the Histogram or Table from the Annotation sub-menu of the View menu, you hit the Apply button to get your selection reflected in the current chart. o If it is necessary to use Set Language for source viewing, because an error occurred when trying to view source with the right arrow VIEW button, it will be necessary to use the Apply button before being able to VIEW source again. 5.2.2 OpenVMS VAX systems o PCA cannot merge an SPM performance data file with a PCA data file that has previously collected data for a Shareable image. 5.3 DECwindows o There is currently no customization of the user preferences. Restrictions 5-5 6 ________________________________________________________________ Reporting Problems and Suggestions Depending on the nature of the request or problem and the type of support you have, you can call DIGITAL if your software contract or warranty agreement entitles you to telephone support. Review the SPD and Warranty Addendum for an explanation of warranty. If you encounter a problem during the warranty period, report the problem preferably using electronic means such as DSNlink. In the United States, customers can call the DIGITAL Customer Support Center at 1-800-354- 9000. In addition, DIGITAL now provides access to Web Information and Support (WIS), a new electronic delivery application that allows you to submit electronic service requests, access databases, download patch kits, transfer files from DIGITAL, and connect to global notes conferences via the World Wide Web. If you are an entitled service customer with access to the Web, you can now use your favorite browser to connect to electronic services through an easy-to-use, graphical interface. If you are already a DIA user, you can gain access to WIS by: 1. Opening http://www.service.digital.com/wis. 2. In the United States, clicking on the words "United States". 3. Entering your DIA Access ID and password. WIS and DIA use the same underlying account and directory on the DIGITAL Customer Support Center host system. Reporting Problems and Suggestions 6-1 If you are not already registered for DIA, you can register for a WIS account by contacting your Customer Support Center or local DIGITAL representative. This method should also be used to make requests for additional features or modifications to existing features. When submitting a report, please include the following information: o The versions of PCA and the OpenVMS operating system being used. o The problem reduced to as small a size as possible trying not to overlook any details. If the problem is with the PCA Collector: o Does the program run GO/NOCOLLECT? o Does the program run with the OpenVMS debugger? o If Counters, Coverage, or Events are involved, does the program behave properly when breakpoints are put in the same locations with the OpenVMS debugger? o Please supply the version of the compiler(s) used. o Files needed to build the program, including build procedures. If the problem is with the PCA Analyzer: o The .PCA file involved o The sources referenced by the .PCA file o A PCA initialization file to reproduce the problem. o Any stack dumps that occurred, if applicable. o All files should be submitted on machine-readable media (magnetic tape, floppy diskette, or tape cassette). If an error occurs while you are running PCA and you have reason to believe that the error is due to a problem in PCA, and you have a support contract, contact your DIGITAL support representative. Otherwise, contact your DIGITAL account representative or your authorized reseller. This 6-2 Reporting Problems and Suggestions method should also be used to make requests for additional features or modifications to existing features in PCA. When reporting a problem, please include the following information: o The versions of PCA and the OpenVMS operating system being used. o As complete a description of the problem as possible, trying not to overlook any details. o The problem reduced to as small a size as possible. o All file should be submitted on machine-readable media (magnetic tape `*preferred`*, floppy diskette, or tape cassette). o Any stack dumps that occurred, if applicable. Reporting Problems and Suggestions 6-3