README for PureCoverage 2001A.04.00 for Windows

README.HTML

Rational, the Rational logo, PureCoverage, PowerCov, Rational Visual Test, Rational Robot, 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, Visual Studio, .Net 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 2001A.04.00 for Windows

What's new in PureCoverage?
Requirements
Installing PureCoverage
Notes
Known problems
Contacting Technical Support

1. What's new in PureCoverage?

New in PureCoverage 2001A.04.00:

PureCoverage automatically detects all installed Java Virtual Machines that are identified in the Windows registry. You can now choose from a list of the detected JVMs in the JVM tab in the Settings > Preferences dialog.
PureCoverage now recognizes the JAVA_HOME user environment variable. If PureCoverage was unable to detect the JVM you want to use for memory profiling, set JAVA_HOME to point to the JVM home directory and PureCoverage will default to it.
Support has been added for "managed" applications in the Microsoft .Net platform. PureCoverage supports applications running on .Net Beta 1. To collect coverage data for these applications, select the "Managed Code" radio button in the "Run Program" dialog.
PureCoverage is integrated into the VS.Net shell. The PureCoverage menu item appears as usual in the VS.Net IDE, however the toolbar is hidden.
Support has been added for reading and displaying coverage trace data formatted in XML. See XMLTrcReader.html in the PureCoverage installation directory for details.
The PureCoverage Interpreter Interface is now publicly available. This set of APIs can be used by third party language vendors for gathering coverage data from their applications and displaying the results in the PureCoverage GUI. See CProf.html in the PureCoverage installation directory for details.
Sun JDK1.3 support has been enhanced to eliminate the manual steps described in the notes for PureCoverage 2001.03.00.

New in PureCoverage 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 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 greater, or Microsoft Windows 2000
32 Mb 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.

PureCoverage for Windows supports:

Architecture:	Win32 programs only
Compilers:	Microsoft Visual C++ (6.0) Microsoft Visual Basic (6.0sp3)
Interpreters:	Microsoft Visual Basic (6.0sp3) Microsoft virtual machine for Java. The version for Msjava.dll should be 2828 or later. The latest release of the virtual machine and SDK is available at: http://www.microsoft.com/java/download.htm Sun JVM 1.2.2 and higher When running on the Pentium 4 with JDK 1.2.2, build 007 is required. Previous versions of 1.2.2 will not run on Pentium 4.
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:

Verify that your swap space is set to at least 150Mb, the minimum recommended.
Run Setup.exe and follow the onscreen instructions.

Notes:

You are installing a licensed Rational Software product. The product you have purchased includes a node-locked, named-user 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, named-user 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   # to profile a control
cstart   iexplore.exe -new   # to profile an applet
```
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 you 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 or a window or dialog control, click the help icon on the toolbar or in the dialog, and then click the control. You can also press F1 to display help for the control.

5. Known problems

Interaction with other applications
Instrumenting programs
Running programs

Interaction with other applications

In order to collect coverage data for applications within Visual Studio.Net, you must include the PureCoverage installation directory in your PATH (typically C:\Program Files\Rational\Coverage).
There is a known problem with VC6 when migrating from VC5 where it leaves 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

PureCoverage does not currently support .NET native-compiled code.
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 <exename>_pure.log file in the same directory as the program. If an error occurs, the log information can also be in the <exename>_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.
- Instrumented .dll and .exe files that are located outside of the PureCoverage cache directory are not deleted when you install a new version of PureCoverage. When you run a program that uses one of those files, PureCoverage uses the existing instrumented version.
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 <exename>_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: +81 03-5423-3611
       fax: +81 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: +61 02-9419-0111
       fax: +61 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:

Note the sequence of events that led to the problem and any program messages or error view messages displayed.
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.

README for PureCoverage 2001A.04.00 for Windows

TABLE OF CONTENTS