README.TXT Copyright (C) 1997-2000 Rational Software Corporation. All rights reserved. Rational, the Rational logo, PureCoverage, PowerCov, Rational Visual Test, and ClearQuest are trademarks or registered trademarks of Rational Software Corporation in the United States and in other countries. Visual C++, Visual Basic, Windows NT, Developer Studio, and Microsoft are trademarks or registered trademarks of the Microsoft Corporation. All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies. U.S. Registered Patent Nos. 5,193,180 and 5,335,344 and 5,535,329. Licensed under Sun Microsystems Inc.'s U.S. Pat. No. 5,404,499. Other U.S. and foreign patents pending. README for PureCoverage for Windows, 2001.03.00 ----------------------------------------------------------------- TABLE OF CONTENTS ----------------------------------------------------------------- 1. What's new in PureCoverage? 2. Requirements 3. Installing PureCoverage 4. Notes 5. Known problems * Interaction with other applications * Instrumenting programs * Running programs 6. Contacting Technical Support ----------------------------------------------------------------- 1. What's new in PureCoverage? ----------------------------------------------------------------- New in PureCoverage, version 2001.03.00: * Sun's JDK release 1.3 is now supported. However, because it was released so late in the PureCoverage Beta cycle there are changes from the pre-release versions that must be dealt with manually for now. To use 1.3 you need to do the following: 1. Update the Java.policy file in the %JAVA_ROOT%\jre\security folder to include the following (assumes d:/tools/java/jdk1.3 is %JAVA_ROOT%): grant { permission java.lang.RuntimePermission "loadLibrary.PureJVMPI"; permission java.io.FilePermission "d:/tools/java/jdk1.3/jre/lib/ext/x86/PureJVMPI.dll", "read"; }; 2. Copy PureJVMPI.dll into %JAVA_ROOT%\jre\lib\ext\x86 folder 3. Make sure this directory is included in the path in front of the PureCoverage product directory. You can also remove PureJVMPI.DLL from the product directory and place it into the x86 folder (see p.2). 4. Make sure that Rational.jar is copied into %JAVA_ROOT%\jre\ext folder and you have this folder in your CLASSPATH environment variable. 5. Start your applet. Use cstart or set _JAVA_OPTIONS=-XrunPureJVMPI:Coverage New in PureCoverage, version 2000.02.10: * Java support has been added for Java2 compliant JVMs. You can now use PureCoverage to get function-level information using Sun's JDK release 1.2.2 and 1.3 (tested in pre-release) and other compatible JVMs. Note: A file called Profile.ini has been added to the PureCoverage product directory to control the pre-filtering of system methods. Refer to this file for details on adding additional filters. * Improved performance and reliability. New in PureCoverage 6.5: * Support has been added for comparing the PureCoverage data of two separate runs of an executable. * Improved compatibility with IIS and other services. * Default instrumentation behavior has changed for modules which have no associated debug information. These modules are now instrumented in "exclude" mode by default. This improves both instrumentation and run-time performance. * PureCoverage is integrated with Rational Robot 7.1, a Rational functional testing tool. You can use PureCoverage together with Robot scripts to collect coverage data for an application under test. From the "Tools > GUI Playback Options > Diagnostic Tools" tab, select "Rational PureCoverage". See your Rational Robot documentation for more details. New in PureCoverage 6.0.1: * The following problems have been corrected: * When PureCoverage was run under Rational SQA Robot and Rational Test Factory it was possible, in certain circumstances, for PureCoverage to use excessive processor time while handling redundant messages from the Application Under Test (AUT). This resulted in SQA Robot timing out while waiting for the AUT to respond. * When PureCoverage was run from the Visual C++ toolbar, some instrumented applications would fail if PureCoverage was installed in the default location. * PureCoverage did not install correctly on French Windows NT. New in PureCoverage 6.0: * Support for Visual C++ 6.0 and Visual Basic 6.0. Note that applying changes to a running instrumented program, using "Edit & Continue" in VC6 is not supported. * Support for collecting coverage data from VB6 programs run directly within the VB6 shell. The new "Engage PureCoverage Integration" tool in VB6 allows you to collect coverage data from programs without first making an executable. This method also helps focus the coverage data on your VB code, avoiding the complexity of compiled executables. * You can now select a function, procedure, or method with low coverage and automatically submit it as a coverage regression to ClearQuest, Rational's change request management tool. Simply highlight the function, procedure, or method name and select "Submit ClearQuest Defect" from the shortcut menu. PureCoverage uses an initialization file, Schema_coverage.ini, to map coverage data and other information to the relevant fields of the ClearQuest defect submit form. This mapping is based on the ClearQuest sample schema 'Default_App'. If you have edited the sample schema or have created a custom schema, you must modify the schema_coverage.ini file to ensure that data is correctly entered in the submit form. To modify the .ini file, follow the instructions included in Schema_coverage.ini, located in the PureCoverage product directory. * PureCoverage is integrated with Visual Test 6.0, Rational's functional testing tool. You can collect coverage data from applications run with Visual Test scripts and send the data back to the script for immediate logging and analysis. Use the "Run Visual Test Scripts with PureCoverage" tool in the PureCoverage toolbar in Developer Studio or Visual Test, or add "coverage" to the "Run" command in your test scripts. See your Visual Test documentation for more details. * Visual Studio integration. At install time, you can choose to install PureCoverage's addin for Visual Studio 6.0. The addin allows you to display PureCoverage's windows within Visual Studio. To enable this feature, select PureCoverage > Settings > Embed PureCoverage Views from within Visual Studio. * Visual Basic integration. At install time, you can now choose to install the PureCoverage addin for Visual Basic. You will find a new toolbar in Visual Basic that lets you directly control PureCoverage. Note that this addin requires Visual Basic 5 Service Pack 3 or later; older Visual Basic 5 installations will display a message at startup to disable the addin dll. Your current Visual Basic Service Pack level is displayed in the Visual Basic 5 splash screen. Service Packs can be freely downloaded at http://msdn.microsoft.com/vstudio/sp/. * Java. The Java virtual machine distributed with Visual Studio 6.0 beta-2 (Msjava.dll version 2613) does not work with PureCoverage. This is corrected in later versions. The latest release of the virtual machine and SDK is available at http://www.microsoft.com/java/download.htm. * PureCoverage now supports merging different executables. This is useful when attempting to determine the coverage of DLLs that are used by multiple programs. ----------------------------------------------------------------- 2. Requirements ----------------------------------------------------------------- * PC-compatible system, Pentium processor * Microsoft Windows NT 4.0 with Service Pack 3 or later * 32MB RAM required, 64MB RAM recommended * Approximately 25MB free disk space * 150MB minimum swap space recommended Notes: * You will need additional disk space to accommodate a growing cache directory as you run PureCoverage on more programs. * PureCoverage does not support checked builds of Windows NT. PureCoverage supports: Architecture: Win32 programs only Compilers: Microsoft Visual C++ (6.0) Note: PureCoverage, version 2000.02.10 was the last release to support Visual C++ 5.0. There are no known incompatibilities with this release but it is not being actively tested. Microsoft Visual Basic (6.0sp3) Note: PureCoverage, version 2000.02.10 was the last release to support Visual Basic 5.0. There are no known incompatibilities with this release but it is not being actively tested. Interpreters: Microsoft Visual Basic (6.0sp3) Microsoft virtual machine for Java The version for Msjava.dll should be 2828 or later. This is the version installed by PureCoverage, unless a later version is already installed. The latest release of the virtual machine and SDK is available at: http://www.microsoft.com/java/download.htm Debuggers: Microsoft Visual C++, WinDBG, NTSD Debug formats: COFF, CV4 Debug files: Debug data can be placed in .exe, .pdb, or .dbg files. PureCoverage can also use .map files, if available. ----------------------------------------------------------------- 3. Installing PureCoverage ----------------------------------------------------------------- To install PureCoverage: 1. Verify that your swap space is set to at least 150MB, the minimum recommended. 2. Run Setup.exe and follow the onscreen instructions. Notes: * You are installing a licensed Rational Software product. The product you have purchased includes either a node-locked or floating license. Please refer to the instructions in the Startup License Key Certificate (included in the product package) for installing a startup license key to get started using the product. For detailed information about Rational Software licensing and how to work with node-locked and floating licenses, please refer to the Rational License Key Administrator online Help (Licadmin.hlp), available by clicking the Help button in the Rational License Key Administrator. * The Rational Solutions for Windows install disk includes numerous Rational Software products. However, the startup license key you received can be used to run only the product you purchased. If you would like to install and evaluate other Rational Software products that are available on the install disk but that you have not purchased, please contact Rational Software. * If you have licensing questions and problems and you can't find the solution in the License Key Administrator online Help, please contact Licensing Support. For contact information, look up "contacting" in the Rational License Key Administrator online Help index. * PureCoverage must be installed after Visual C++, Visual Basic, and Visual Test in order for it to install an integration with these tools. If you installed one of these tools after PureCoverage, simply re-install PureCoverage to get the integration. * PureCoverage can be installed as part of Rational Suite DevelopmentStudio. When you do a custom install of Rational Suite DevelopmentStudio, and you choose to install only PureCoverage, Rational Software Setup installs additional components that are not used by PureCoverage. For example, SQL Anywhere. * To uninstall a previous copy of PureCoverage, double-click the Add/Remove Programs icon in the Control Panel and uninstall PureCoverage. The uninstall program removes all of the files associated with the PureCoverage installation. If you do not do an uninstall, but instead install a new version of PureCoverage over the previous version, be sure to delete all files in the PureCoverage cache directory first. Your application and its modules must be reinstrumented after installation to operate correctly with the current release of PureCoverage. ----------------------------------------------------------------- 4. Notes ----------------------------------------------------------------- * To monitor Visual C++ or Visual Basic controls, or Java applets, launched from Microsoft Internet Explorer 4.0 with the Active Desktop "shell integration" installed, you must specify the "-new" argument. You can specify "-new" in Command-line arguments in the Run Program dialog or from the command line. For example, to monitor controls or Java applets from the command line, type respectively: coverage iexplore.exe -new cstart iexplore.exe -new The "-new" argument causes a new Iexplore.exe process to start and be instrumented (for Visual C++ and Visual Basic 5 only) before monitoring your control or applet. Without this argument, the control or applet is run by the current desktop explorer and no coverage data is collected. * For Visual Basic programmers: When monitoring native-code programs, keep in mind that the Microsoft Visual Basic 5.0 native-code compiler currently does not: * Encode any information about a procedure's arguments. Consequently, PureCoverage displays the argument list as (...) in all cases. * Retain project and sub-project information about procedures. Consequently, if you have a main project called MyVBProject and a sub-project called VBHello, and it defines a procedure called HiWorld, PureCoverage displays the name as VBHello.HiWorld(...), rather than as MyVBProject.VBHello.HiWorld(). * When you add PureCoverage to the Visual J++ 1.1 Tools menu and open the class file as a project, you must specify $(ProjectName) $(ProjectArgs) in the Arguments list. * The HTML Files (*.htm, *.html) option in the Select Program dialog does not apply to JavaScript, ActiveX components, VBScript, and HTML code. This option applies only to Java applets. * Online Help is available by selecting Help > Help Topics or Help > Help Index. To access context-sensitive help for a command, window, or dialog control, click the help icon in the toolbar or in the dialog and then click the command, window, or control. You can also press F1 to display help. ----------------------------------------------------------------- 5. Known problems ----------------------------------------------------------------- * Interaction with other applications * Instrumenting programs * Running programs Interaction with other applications ----------------------------------- * There is a known problem with VC6 when migrating from VC5 where it leave a VC5 signature in the .pdb file when building from the command line. PureCoverage sees this file as corrupt and cannot read the symbols from it. To work around the problem, delete the .pdb file for the application and re-build. * PureCoverage does not work correctly when dlls are injected into a process via the AppInit_DLLs registry key because it fails to instrument the injected libraries. In order for PureCoverage to work correctly, the application which uses the key must be uninstalled and the system must be rebooted. The utility ComSpyNT is known to use this registry key. * Applying changes to a running instrumented program, using "Edit & Continue" in VC6 is not supported. * There are compatibility problems between PureCoverage and applications that use SetWindowsHook() and SetWindowsHookEx(). PureCoverage disables the SetWindowsHook() APIs when instrumenting and running programs. This is to avoid hooking uninstrumented programs with DLLs instrumented by PureCoverage. For workarounds to this, please contact Rational Software's Technical Support. [21155] * In rare instances, PureCoverage fails to find DLLs or OCXs required by LoadLibraries. Try adding the module's directory to your PATH environment variable. [34919] * You cannot use the stdin/stdout redirection request, as in test.exe < test.txt, when you instrument and run programs using the Run Program dialog. [00254, 23822, 33100] * In PureCoverage'd programs, argv[0] is set to the instrumented file name. You can specify a name for the instrumented file in the Settings for "exename" dialog (executable settings) if your program depends on a specific value for argv[0]. [00281] * The PureCoverage integration with Microsoft Developer Studio is not compatible with Java workspaces. To collect coverage data for Java code, use the standalone PureCoverage interface. Instrumenting programs ---------------------- * When you copy a DLL that you want to instrument into your working directory, also copy any related .pdb, .dbg, or .map files. This ensures that PureCoverage's function and procedure names are as informative as possible. * Modules built from assembly code might not instrument correctly by default if they do not follow standard calling conventions. For assistance in such cases, contact Rational Software's Technical Support. * PureCoverage appends the instrumentation log to the _pure.log file in the same directory as the program. If an error occurs, the log information can also be in the _pure.tmp file. * PureCoverage does not reinstrument files in the following situations: * A .pdb file is supplied after a .dll or .exe file has been instrumented. When you rerun the program, PureCoverage does not reinstrument the .pdb file. * You swap two .dlls that have the same name and the same creation time, such as a debug version and a production version. The "new" .dll is not instrumented, because an identically-named file with the same timestamp already exists in the PureCoverage cache directory. In each case, you can work around the problem by deleting the instrumented files to force reinstrumentation. [20035] * For information about creating a cache directory shared among multiple developers, contact Rational Software's Technical Support. [21788] * PureCoverage does not support Universal Naming Convention (UNC) names for the cache directory setting. Instead, map a network drive to specify a cache directory on a remote machine. [23872] Running programs ---------------- * For Visual Basic source files last edited with VB5.0sp1 or earlier (including the VB5 samples), a change in the VB compiler means that annotations in the annotated source file can be offset by as many as 7 lines. If this occurs, edit and save the file with a more recent version of VB5 or VB6 and rebuild your project. * For Visual Basic 6.0 projects and p-code, PureCoverage does not list the source files in which no procedures are executed (i.e. those with 0% procedure coverage). These files are listed for VB6 native-compiled executables. * In Visual Basic 6.0, multi-line statements using the underscore '_' line continuation character cause annotations in the annotated source file to be offset by a number of lines equal to the number of continuations present. * If you receive the following message: "Shared memory exhausted. Saving data and disabling collection.", your application might require more shared memory than PureCoverage has allocated by default. You can increase the size of this shared memory by using the option "-runtime-data-size=" (default value is 0x04000000 (64MB)). This can be set in Additional options in the Settings for "exename" dialog (executable settings). * PureCoverage appends the run-time log to the file _pure.log in the same directory as the program. * On occasion, PureCoverage might experience an internal error. These errors are displayed in the Messages tab in the Run Summary window as PureCoverage internal errors. Please follow the onscreen instructions and submit any PureCoverage internal errors you receive to Rational Software's Technical Support. ----------------------------------------------------------------- 6. Contacting Technical Support ----------------------------------------------------------------- If you have a technical problem and you can't find the solution in online Help, you can contact Technical Support. North America: Rational Software 18880 Homestead Road Cupertino, CA 95014 voice: (800)433-5444 fax: (408)863-4001 email: support@rational.com Europe and Middle East: Rational Software Beechavenue 30 1119 PV Schiphol-Rijk The Netherlands voice: +31 (0)20 454 6200 fax: +31 (0)20 454 6201 email: support@europe.rational.com Japan: Nihon Rational Software, SAISEI Ikedayama, Bldg. 2F, 5-10-25 Higashi-Gotanda, Shinagawa-ku, Tokyo 141-0022, Japan voice: 03-5423-3611 fax: 03-5423-3622 email: support@japan.rational.com Australia and Asia Pacific: Rational Software Corporation Pty Ltd, Zenith Centre, Level 13, 821 Pacific Highway, Chatswood NSW 2067, Australia voice: 02- 9419-0111 fax: 02- 9419-0123 email: support@apac.rational.com If you email, include the license information that appears in the "Help->About Rational PureCoverage" dialog along with the PureCoverage log file. Before you call: 1. Note the sequence of events that led to the problem and any program messages or error messages displayed. 2. Have your license key and customer number ready and, if possible, the product running on your computer. Note: * If you have licensing questions and problems and you can't find the solution in the License Key Administrator online Help, please contact Licensing Support. For contact information, look up "contacting" in the Rational License Key Administrator online Help index.