Compaq_DECset_for_OpenVMS_____________________ Compaq Performance and Coverage Analyzer for OpenVMS Version 4.7 Release Notes August 2000 These release notes for the Compaq Performance and Coverage Analyzer for OpenVMS Version 4.7 software contain important general information, new and changed features, current restrictions, and documentation notes. Operating System and Version: Compaq OpenVMS VAX Operating System, Versions 6.2, 7.1, 7.2 Compaq OpenVMS Alpha Operating System, Versions 6.2, 7.1, 7.2-1 Compaq DECwindows Motif for OpenVMS, Versions 1.2-4 - 1.2-5 Software Version: Compaq DECset for OpenVMS, Version 12.4 Compaq Performance and Coverage Analyzer for OpenVMS, Version 4.7 Compaq Computer Corporation Houston, Texas __________________________________________________________ © 2000 Compaq Computer Corporation © Electronic Data Systems Corporation 2000 COMPAQ, VAX, VMS, the Compaq logo, and the DIGITAL logo Registered in U.S. Patent and Trademark Office. DEC Ada, DECforms, DECnet, DECset, DECwindows, eXcur- sion, OpenVMS, and PATHWORKS are trademarks of Compaq Information Technologies Group, L.P. Microsoft, Visual C++, Windows, Windows 95, Windows 98, Windows 2000, and Windows NT are trademarks of Microsoft Corporation. Motif is a registered trademark of The Open Group. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies. Confidential computer software. Valid license from Compaq, EDS, or authorized sublicensor required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. Neither Compaq nor EDS shall not be liable for technical or editorial errors or omissions contained herein. The information in this publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ OR EDS BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ OR EDS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT, OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY. The limited warranties for Compaq and EDS products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty. 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 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-4 5.1.4 User Routines ................................ 5-4 5.2 Analyzer........................................ 5-4 5.2.1 DECwindows ................................... 5-5 5.2.2 OpenVMS VAX systems .......................... 5-5 5.3 DECwindows...................................... 5-5 iii 6 Reporting Problems and Suggestions iv ________________________________________________________________ Preface These release notes characterize the Version 4.7 release of the Compaq Performance and Coverage Analyzer for OpenVMS (PCA) software. These notes contain information that either supplements or supersedes the information in the Compaq DECset for OpenVMS documentation set. Intended Audience These release notes are intended for any user or system manager who needs information about PCA on either of the Compaq OpenVMS Operating System platforms (VAX or Alpha). 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 Compaq Your Comments We welcome your comments on these release notes or any other documentation. See Chapter 6 for details on how to contact Compaq with your comments. Conventions The following conventions are used in these release notes. __________________________________________________________ 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. lowercase Lowercase in examples indicates that you are to substitute a word or value ____________________of_your_choice._______________________ vi 1 ________________________________________________________________ General Information 1.1 Introduction The information in these release notes pertain to the Compaq Performance and Coverage Analyzer for OpenVMS (PCA) Version 4.7 software. Compaq 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. PCA Version 4.7 is a minor release. 1.2 Associated Documents The following documents contain information related to PCA. Note however, that for the Compaq DECset for OpenVMS Version 12.4 release, only the software product descriptions, installation guide, and component product release notes have been updated. o Compaq DECset for OpenVMS VAX Software Product Description o Compaq DECset for OpenVMS Alpha Software Product Description o 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 o DIGITAL Performance and Coverage Analyzer Command-Line Interface Guide General Information 1-1 o Compaq DECset for OpenVMS Installation Guide The DECset engineering team has also provided the Compaq DECset for OpenVMS Cookbook for an Integrated Product Development Environment. This document comprises a series of technical articles that describe how each of the component applications can be used in different programming environments. This document is available in PostScript (.PS), HTML (.HTML), and ASCII text (.TXT) formats from the following location: SYS$SYSROOT:[SYSHLP.EXAMPLES.DECSET]DECSET_COOKBOOK.* 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 Compaq 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 DECwindows interface for PCA, you must have previously installed the Compaq DECwindows Motif for OpenVMS software Version 1.2-4 or higher. o PCA must be reinstalled after an OpenVMS upgrade as the PCA Collector links against the system. OpenVMS Alpha systems o Prerequisite versions of OpenVMS on Alpha systems are Versions 6.2, 7.1, or 7.2-1. o For a new installation of PCA the following is required: 1-2 General Information Global Pagelets 2500 Global Sections 7 Disk Blocks 40000 OpenVMS VAX systems o Prerequisite versions of OpenVMS on VAX systems are Versions 6.2, 7.1, or 7.2. o For a new installation of PCA the following is required: Global Pages 1200 Global Sections 8 Disk Blocks 23000 General Information 1-3 2 ________________________________________________________________ New Features The following is a brief summary of enhancements added to PCA. Significant changes have been made to the PCA Collector memory management for version 4.7-3. In previous versions of PCA users attempting to collect coverage data by line for large programs would often run out of free memory. In many cases the amount of available memory was limited by PCA, not by process or system quotas. The maximum size of the PCA Collector memory pool has been increased significantly. In almost all cases the maximum size of the memory pool is now limited by the process page file quota (PGFLQUOTA) or the system maximum virtual page count (SYSGEN parameter VIRTUALPAGECNT). In addition, an error which caused PCA to crash with an access violation immediately after a memory allocation failure has been fixed. New Features 2-1 3 ________________________________________________________________ Problems Fixed The following is a list of PCA problems which have been corrected in this release. o ID:192: PCA Collector crashes when collecting coverage data by line for Compaq Fortran for OpenVMS Systems routines with alternate entry points. This problem has been corrected. o ID:204: PCA Collector crashes with ACCVIO after memory allocation failure. This problem has been corrected. o In certain cases, the PCA memory allocation routines would return a packet which was between one and three bytes smaller than requested. This could potentially result in data corruption. This problem has been corrected. o Several problems with reporting errors in the PCA memory allocation routines have been corrected. Problems Fixed 3-1 4 ________________________________________________________________ Known Problems The following is a list of known problems with PCA. o ID: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 ID: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 ID:160: I/O system services (and probably system services) are charged against the wrong line on Compaq Ada tasking programs on OpenVMS Alpha. o ID:172: Prior to OpenVMS Alpha Version 7.0, PCA incorrectly marks lines as covered when collecting COUNTERS BY LINE. 4.2 OpenVMS VAX Systems o ID:83: PCA data corruption occurs with FORTRAN statement functions. o ID: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 The following is a list of restrictions for PCA. 5.1 Collector o PCA cannot gather data from user programs which call SYS$EXIT directly or indirectly from their exit handler. The PCA exit handler makes sure that all data is written to the data file and that the data file is properly closed. This exit handler executes after the completion of all user mode exit handlers declared by the application program. If the PCA exit handler does not execute there may be loss of data or unrecoverable corruption of the data file. When SYS$EXIT is called from within an exit handler no remaining exit handlers in the same access mode will be executed. When an application exit handler calls SYS$EXIT the PCA exit handler does not execute. Users should be aware that the RTL routines LIB$DO_ COMMAND and LIB$RUN_PROGRAM contain calls to SYS$EXIT. PCA can not be used to collect data for programs which call either of these routines in their exit handlers. o The Collector is not AST re-entrant during program exit. The PCA exit handler cleans up and closes the data file. If an AST should occur while PCA is exiting the results are unpredictable. To avoid this situation, the user program should make sure there are no pending ASTs prior to terminating. 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. Restrictions 5-1 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 the PCA system service interception because the "real" system service vector has been relocated. o Unpredictable results can occur if PCA is used to collect data on programs which use unallocated local event flags. During data collection the PCA Collector dynamically allocates local event flags using LIB$GET_EF. Applications which use local event flags without first allocating them in the same manner may use an event flag being used by PCA. If this occurs the results of both the application and PCA are unpredictable. Proper programming practice requires that all local event flags be allocated using LIB$GET_EF or LIB$RESERVE_EF prior to use. o The PCA Collector will fail if the program being analyzed deletes or resets virtual memory (VM) zones belonging to PCA. PCA uses the OpenVMS RTL virtual memory (VM) zone management routines to create two VM zones from which it performs all dynamic memory allocations. PCA makes heavy use of dynamically allocated memory. If an application running with the PCA Collector modifies, resets, or deletes these zones the Collector will not be able to continue executing. This situation can occur when a program obtains the zone identifier for one of the PCA zones by calling LIB$FIND_VM_ZONE or LIB$FIND_VM_ZONE_64. Programmers using these routines must be aware that they may return information on zones not created directly by the program and take precautions to ensure such zones are not modified. 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. 5-2 Restrictions o PCA may not correctly correlate stack PCs collected for system services or IO services when PROGRAM_ADDRESS BY LINE is selected and the program is not compiled /NOOPTIMIZE. The errors occur when multiple adjacent but non-overlapping DSTs describe the program line containing the system service or IO service call. The workaround is to compile the program /NOOPTIMIZE. o Programs which use the LBR$ routines to access libraries must use the library index returned by LBR$OPEN in subsequent calls to other LBR$ routines. Problems have been reported where programs assume the index is a certain value rather than saving the index returned by LBR$OPEN. When the program is run with the PCA Collector the index values may be different if PCA opens help libraries before the program begins execution. 5.1.1 DECwindows o Switching a context from the Compaq DECset Environment Manager for OpenVMS 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. Restrictions 5-3 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. 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 System service routines which are invoked from user- supplied routines 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). Programs written in other languages may cause PCA to hang. Examples user routines 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-4 Restrictions 5.2.1 DECwindows o No graphical print support is available; however, text versions of histograms can be printed using the Save Chart button. 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 following an error while 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 Compaq 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 Compaq Customer Services at 1-800-354-9000. In addition, Compaq 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 Compaq, 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://www1.support.compaq.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 Compaq Customer Services host system. If you are not already registered for DIA, you can register for a WIS account by contacting Compaq Customer Services or local Compaq representative. Reporting Problems and Suggestions 6-1 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: - Does the program run GO/NOCOLLECT? - 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 the same locations with the OpenVMS debugger? - Please supply the version of the compiler(s) used. - Files needed to build the program, including build procedures. If the problem is with the PCA Analyzer: - The .PCA file involved - The sources referenced by the .PCA file - 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 Compaq support representative. Otherwise, contact your Compaq account representative or your authorized reseller. This 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: 6-2 Reporting Problems and Suggestions 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