Rational® PurifyPlus Family Release Notes

Version 2003.06.00

Legal Notices Information


Scope

These release notes provide information critical to installing and using Rational PurifyPlus Family products, including the list of supported platforms and known issues with this release.

Members of the PurifyPlus Family include:

References to PurifyPlus in these release notes applies to Purify, Quantify and PureCoverage.

Contents

What's New in This Release
Product Documentation
Hardware/Software Information
Installation, Upgrading, and Licensing
Installation Information
Installation Issues
Upgrades
Licensing
Compatibility Issues
With Rational Products
With Third-Party Products
Restrictions and Guidelines on Using the Rational PurifyPlus Family of products
Known Issues in This Release
Documentation Updates
Additional Information
Contacting Rational Technical Support

What's New in This Release

Product Documentation

Additional product documentation is available in the following locations:

Hardware/Software Information

The following sections outline the supported platforms and installations requirements for this version of the Rational PurifyPlus Family of products.

Table 1 Desktop Requirements and Recommendations
Item
Hardware Requirements and Recommendations
Operating Systems
  • Microsoft Windows XP Professional, No Service Pack, Service Pack 1
  • Microsoft Windows 2000 Professional, Service Pack 2, 3
  • Microsoft Windows 2000 Server, Service Pack 2, 3
  • Microsoft Windows 2000 Advanced Server, Service Pack 2, 3
  • Microsoft Server 2003 Standard Edition, RC2
  • Microsoft Server 2003 Enterprise Edition, RC2
  • Microsoft Windows NT 4.0 Workstation, Service Pack 6a + SRP (Security Rollup Package, Q299444)
Hardware
  • Pentium III, Pentium 4, Xeon
  • 500 MHz or higher
  • 256 MB RAM required, 512 MB RAM recommended;
    more memory generally improves responsiveness
  • Swap space: 2 x physical memory
  • 600 X 800 X 256-color video resolution, or higher; high color or true color recommended
  • Microsoft Mouse or compatible pointing device
Disk Space to Install
  • Rational PurifyPlus - 140 MB
  • Rational Purify - 100 MB
  • Rational Quantify - 100 MB
  • Rational PureCoverage - 100 MB
Additional Disk Space

(needed to accommodate instrumentation cache)
  • Depends on the number and size of .exe and .dll files being instrumented. As a rough guide, expect instrumented modules to be 50% bigger than the original module.
Item
Software Requirements and Recommendations
Integrations with 3rd Party Applications
Compilers
  • Microsoft Visual C++ 6.0 with Visual Studio 6.0 Service Packs 3, 4, 5
  • Microsoft Visual C++ 6.0 Processor Pack
  • Microsoft Visual Basic 6.0 with Visual Studio 6.0 Service Packs 3, 4, 5
  • Microsoft Visual C++ .NET
  • Microsoft Visual C# .NET
  • Microsoft Visual Basic .NET
  • Microsoft Visual C++ .NET 2003, RC3
  • Microsoft Visual C# .NET 2003, RC3
  • Microsoft Visual Basic .NET 2003, RC3
Debuggers
  • Microsoft Visual Studio 6.0 Service Packs 3, 4, 5 (Debug format: COFF, CV4) (Debug Files: .exe, .pdb, .dbg, .map)
  • Microsoft Visual Studio .NET (Debug Format: COFF, CV4, CLR) (Debug files: .exe, .pdb)
  • Microsoft Visual Studio .NET 2003, RC3 (Debug Format: COFF, CV4, CLR) (Debug files: .exe, .pdb)
IDEs and Application Servers
Integrated Development Environments
  • Microsoft Visual Studio 6.0 Service Packs 3, 4, 5
  • Microsoft Visual Studio .NET
  • Microsoft Visual Studio .NET 2003, RC3
  • IBM WebSphere Application Developer 5.0
Deployment Application Servers
  • Apache Jakarta Tomcat 4.x
  • BEA WebLogic 6.x, 7.x
  • IBM WebSphere 4.x, 5.x
  • Microsoft IIS 5.0, 6.0
Run-time Environments
  • Sun JVM 1.2.2, 1.3.0 Classic, 1.3.0 HotSpot (Quantify and Coverage only) 1.3.1 Classic, 1.3.1_03 HotSpot, 1.4.0 Client, 1.4.0 Server
  • IBM JVM 1.3.0
  • Microsoft JVM 3310, 3805
  • Microsoft .NET Framework, No Service Pack, Service Pack 1
  • Microsoft .NET Framework 1.1, RC3
Rational Documentation
Adobe Acrobat Reader 4.x or higher required to read online PDF files. Download the free Adobe Acrobat Reader from www.adobe.com.
Language Support
You can install the Rational PurifyPlus Family products on these international operating systems:
  • Simplified or Traditional Chinese
  • Dutch, French
  • German
  • Hebrew
  • Italian
  • Japanese
  • Korean
  • Swedish
All displays, menus, controls, wizards, reports, and user documentation are in U.S. English.
  • If you have a Traditional Chinese, Dutch, Hebrew, or Korean operating system, enter data (such as path names) in U.S. English or the ASCII character set.
  • If you have a Simplified Chinese, French, German, Italian, Japanese, or Swedish operating system, enter data in U.S. English or the native language character set. Regional date, time, currency, and numbering conventions are also supported for both input and output.

Installation, Upgrading, and Licensing

Installation Information

Caution - Before You Install

The Rational Setup Wizard will ask that you remove earlier versions of Rational products (including Rational licenses) from your desktop. You or your system administrator should consult the Rational Suite Upgrade Guide in the Rational Solutions for Windows Documentation CD-ROM before you try to upgrade your Rational products.

In order for PurifyPlus to integrate into IBM WebSphere Application Developer 5.0, both PurifyPlus and the IBM shell must be installed on the same drive.

Installation Issues

Setting Up a Silent Install

If you have earlier Rational products installed on your system, you will see a warning page during your installation. If you are setting up a silent installation, pay particular attention to this message and take steps to ensure that users upgrade all Rational products. Users who install silently will not see this warning message. The message will appear in the user's installation log file, but the user may not remember to look at the log file after completing the installation.

Accessing Microsoft Office Products After Unsuccessful Rational Product Installation

If the installation of Rational PurifyPlus or an individual Rational PurifyPlus Family product fails, you may not be able to start Microsoft Office products. Should this happen, you may receive the following error message: "The feature that you are trying to use is on a network resource that is unavailable."

Restart your computer to resolve this problem.

Rational Installer Incompatible with Windows "Change Journal" Feature

Rational has determined that under certain circumstances file system corruption can result from installing Rational Version 2003 products on Windows 2000 to an NTFS partition that has the Windows "Change Journal" (log) enabled on it. Therefore, the Rational Installer will not install to such partitions. Rational is actively working with Microsoft to better understand, repair, and/or work around the problem. Before installing any Rational Version 2003 product on a computer running Windows 2000, please read Rational Solution 182435434 for the latest information. Alternatively, you can search the Rational Solutions Knowledge Base for the text "Change Journal".

Upgrades

For information about upgrading Rational Suite Products, see the Rational Suite Upgrade Guide on the Rational Solutions for Windows Online Documentation CD-ROM. Or go to http://www.rational.com/support/. Click Upgrades and Patches and select a product to upgrade.

Licensing

If you are using floating licenses, make sure that the license server system is running before you start the Rational License Key Administrator on your desktop. Otherwise, if the License Key Administrator is directed to get a license, it will return an error.

Compatibility Issues

This section identifies special considerations for using the Rational PurifyPlus Family of products with other products, including Rational products and third-party software products.

With Rational Products

Rational produces synchronized releases of all its products. If you install multiple Rational products on a single system, or on multiple systems in the same network environment, they must all be at the same version number. This is necessary because of the tight integration between products.

Rational XDE

Current versions (v. 2003.06.00) of the Rational PurifyPlus Family of products are not compatible with XDE version 1.0 or XDE version 1.1. If either of those products are on your system, you should not install the PurifyPlus Visual Studio .NET integration.

With Third-Party Products

Installing Rational Software in a Windows Terminal Server Environment

You can install and run the Rational PurifyPlus Family of products on a Windows Terminal Server console system as you would on any other supported Windows NT Server or Windows 2000 Server system.

To use Rational products on a Terminal Server client, you must configure your console system to use floating licenses.

Sun JVM 1.3.0 HotSpot

Purify does not support Sun JVM 1.3.0 HotSpot. The JVM Profiling Interface (JVMPI) does not generate consistent memory allocation notifications, making the profiling information unreliable. Quantify and PureCoverage are unaffected by the issue and fully support this JVM.

Sun JVM 1.3.1 HotSpot

PurifyPlus does not support Sun JVM 1.3.1 HotSpot. The JVMPI includes behaviors that are incomptatible with PurifyPlus. These issues were resolved in Sun JVM 1.3.1_03 HotSpot.

Visual Studio .NET 2003

The PurifyPlus help system will not be integrated within the Visual Studio .NET 2003 IDE by default. In order to integrate the PurifyPlus help, the following steps should be applied:

  1. Run Visual Studio .NET 2003
  2. Search for "Combined Help Collection Manager" using Search from the Help menu.
  3. From the result set, choose "Visual Studio .NET Combined Help Collection Manager".
  4. At the end of the topic text, you will see "Collections available for inclusion in VSCC:". Check the box next to "Rational PurifyPlus".
  5. Click "Update VSCC".
  6. Close all instances of Visual Studio .NET 2003 and Microsoft Document Explorer. When you restart Visual Studio .NET 2003, the VSCC Help collection will be updated to include the Help collections that were checked, and exclude those whose check boxes were cleared.
  7. Restart Visual Studio .NET 2003. Visual Studio will take several minutes to reopen as it updates the VSCC Help.

Rational PurifyPlus help should now be part of the Visual Studio .NET 2003 Combined Help Collection.
Note: These instructions do not apply to versions of Visual Studio .NET prior to the 2003 release.

Restrictions and Guidelines on Using the Rational PurifyPlus Family of products

Table 2 Restrictions and Guidelines
Topic
Applies To
Restriction
AppInit_DLLs PurifyPlus PurifyPlus 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 PurifyPlus 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.
Visual C++ PurifyPlus Applying changes to a running, instrumented program, using "Edit & Continue" in Visual C++ is not supported.
SetWindowsHook PurifyPlus There are compatibility problems between PurifyPlus and applications that use SetWindowsHook() and SetWindowsHookEx(). Often these compatibility problems can be solved by using minimal instrumentation for the hook DLL.

The SetWindowsHookEx() API is disabled in instrumented programs. This is to avoid hooking uninstrumented code from within an instrumented application. For workarounds to this, please contact Rational Software's Technical Support.

Stdin PurifyPlus You cannot use the stdin redirection request, as in test.exe < test.txt, when you instrument and run programs using the Run Program dialog. Use the command line interface instead.
argv[0] PurifyPlus In natively instrumented applications, argv[0] is set to the instrumented filename. You can specify a name for the instrumented file in Settings>Executable Settings>Files>Instrumented File Name, if your application depends on a specific value for argv[0].
Debug Data PurifyPlus PurifyPlus does not support the use of the NB05 debug data format in modules. You can use the cvpack utility program, included with Microsoft Visual Studio, to update the debug information for use with PurifyPlus. To do this, make a backup copy of the module, then run cvpack on the module. It will rewrite the module in place with the new debug information.
Instrumentation PurifyPlus The instrumentation of files fails to happen in the following situations:
  • A .pdb file is supplied after a .dll or .exe file has been instrumented. When the application is re-run, the .pdb file is not reinstrumented.
  • Two .dlls that have the same name and the same creation time are swapped, 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 cache directory.
  • Instrumented .dll and .exe files that are located outside of the cache directory are not deleted when a new version of PurifyPlus is installed. When an application that uses one of these files is run, the existing instrumented version is used.
In each case, the problem can be resolved by deleting the instrumented files to force reinstrumentation.
Cache directory PurifyPlus PurifyPlus does not support Universal Naming Convention (UNC) names for the cache directory setting. Instead, a network drive should be mapped to specify a cache directory on a remote machine.
VirtualAlloc PurifyPlus PurifyPlus does not support VirtualAlloc regions that contain executable code. The code is considered to be part of the data section, and is not instrumented.
Relocations PurifyPlus PurifyPlus requires relocation data in order to provide source line information for an instrumented application. To ensure an application contains the necessary relocations, the Visual C++ linker option /FIXED:NO should be used when building an executable.
Hand-coded Assembly PurifyPlus PurifyPlus does not support modules that include hand-coded assembly. To ensure proper behavior, these modules should be instrumented in Exclude mode.
Japanese Language Pack PurifyPlus Due to a synchronization problem within the Japanese Language Pack on Windows XP, PurifyPlus must change the default keyboard setting for instrumented programs from Japanese to English. Before doing this, a dialog box will be displayed requesting consent to do so.
WebSphere and Japanese filenames PurifyPlus There is an issue with WebSphere Studio Workbench 2.0 and WebSphere Studio Application Developer 5.0 where filenames with Japanese characters in them are not always handled correctly. Exporting a file with Japanese characters in the name to a .zip file will corrupt the name in the .zip file. Creating a Java class with Japanese characters in the name will create a file but fail to add the class name to the file.

There is no known workaround to this problem. The use of Japanese characters in these scenarios should be avoided.

Application timeouts PurifyPlus For applications that are experiencing timeout problems when instrumented with PurifyPlus, there are a couple things to try:
  • Run the application again
    This can help for applications that dynamically load libraries. The load time can be increased when instrumenting with PurifyPlus because each of the loaded libraries must be instrumented the first time through. Subsequent runs will be faster because the instrumented files will be cached.
  • Use the -api-timeout-factor option
    This option can be used to increase the timeout value for APIs (such as WaitForSingleObject) by multiplying the existing value by the timeout factor given in the option.
    As an example, to increase the timeout value by a factor of 10, specify
    -api-timeout-factor=10
    in Settings>Executable Settings>Files>Additional Options.
Eclipse Class Loader PurifyPlus PurifyPlus does not work with the Eclipse class loader when attempting to collect profiling information at the line level. The error message that will be seen at run time is the following:

java.lang.NoClassDefFoundError: Rational/QProfJ

To circumvent this problem, you must collect profiling information at the function level. This can be done as follows:

For Purify: In Settings>Executable Settings>Power Check, set the Default Profile Level to function.
For PureCoverage: In Settings>Executable Settings>Power Check, set the Default Coverage Level to function.
For Quantify: In Settings>Executable Settings>Power Check, set the Default Measurement Level to function.

SetErrorMode Purify SetErrorMode() suppresses all system-level message boxes, including the Windows Application Error message box. If you enable Purify's Break On Error for a program that calls SetErrorMode(), Purify displays the access error in the Error View window, but the Application Error message box does not appear and the program continues to run.
Debugging Purify Purify assigns a default debugger based on the default AeDebug Debugger entry in the Registry. If you do not have Microsoft Visual Studio installed, it's possible that the registered program will not support full debugging.
Unlisted source files PureCoverage 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 natively-compiled executables.

Known Issues in this release

Table 3 Known Issues
Topic
Applies To
Defect Number
Description
Debugging PurifyPlus RATLC00031747 When debugging a managed application from within Visual Studio .NET, setting breakpoints and single-stepping will not work if PurifyPlus is engaged. This problem is unique to Visual Studio .NET. Debugging works as expected in Visual Studio .NET 2003, RC3.
Debugging PurifyPlus RATLC00369792 Within Visual Studio .NET and Visual Studio .NET 2003, the PurifyPlus engage button does not work for unmanaged applications. In order to run an unmanaged application with PurifyPlus engaged, the Run menu item should be selected for one of the PurifyPlus Family products. As an example, to run an unmanaged application with Purify engaged, select PurifyPlus>Purify>Run. In order to debug an unmanaged application with Purify engaged, the application must be run from the standalone Purify GUI with Run under the debugger checked in the Run dialog. It is currently not possible to debug an unmanaged application with PureCoverage or Quantify engaged.
Instrumenting java.exe, javaw.exe PurifyPlus RATLC00512789 When instrumenting java.exe or javaw.exe in order to collect run-time data on native code, PurifyPlus fails to find jvm.dll. To circumvent this problem, add the directory containing jvm.dll along with the PurifyPlus cache directory to the user PATH environment variable.
Selective instrumentation and ASP.NET PurifyPlus RATLC00370331 Using PurifyPlus to selectively instrument ASP.NET applications does not work. The options necessary to enable this feature are not properly passed to the running application. This problem can be circumvented by setting a system environment variable. For Purify, this can be accomplished with the following:

PURIFYOPTIONS=sys_ini_filename="<User Profile>\Application Data\Rational\Purify\purifyw_pure.ini"

Where <User Profile> is the system-returned location for the Windows user profile directory.

Broken XDE functionality PurifyPlus RATLC00239418 Uninstalling PurifyPlus can break functionality in Rational XDE. If after uninstalling PurifyPlus, you see the XDE error "Modeler Error" or if you are unable to publish a model, do the following to restore the functionality:
  1. Open a command prompt window.
  2. Change the directory to the folder where RatShellps.dll is installed (typically C:\Program Files\Rational\RCSI\1.x\bin).
  3. Register the dll with the following command:
    regsvr32 RatShellps.dll
Extra PurifyPlus session with XDE Tester PurifyPlus RATLC00371993 When PurifyPlus is used with XDE Tester, an extra PurifyPlus session is initiated for the browser that displays the XDE Tester log. To suppress this session, edit the profile.ini file in the PurifyPlus directory (typically C:\Program Files\Rational\PurifyPlus). In the CommandLineStopList section add the line:
XDETesterPat=log.htm
Profiling .NET application running as a Service PurifyPlus RATLC00031871 In order to correctly profile a .NET application running as a Windows Service, perform the following steps:
  1. set COR_ENABLE_PROFILING=1
  2. set COR_PROFILER={679367E3-FC39-11D3-8A11-00105A2A1490}
  3. set PURE_MONITOR_ENABLE=<Product>
    where <Product> is one of Purify, Quantify or PureCoverage.
  4. set PURE_MONITOR_TARGET_PATTERN=<Basename of EXE>
    where <Basename of EXE> is the basename of your service executable (e.g. foo is the basename of foo.exe.)
  5. Reboot your machine
Uinstall does not remove .NET integration PurifyPlus RATLC00372000 When PurifyPlus is uninstalled, the .NET integration is not completely removed. To clean out the remaining PurifyPlus menus and toolbar entries, run devenv /setup.
ASPNetMon does not work with ASP.NET 2003 PurifyPlus RATLC00446505 PurifyPlus is unable to collect profiling information through the ASPNetMon utility for Microsoft ASP.NET 2003. As a workaround, perform the following steps:
  1. set COR_ENABLE_PROFILING=1
  2. set COR_PROFILER={679367E3-FC39-11D3-8A11-00105A2A1490}
  3. set PURE_MONITOR_ENABLE=<Product>
    where <Product> is one of Purify, Quantify or PureCoverage.
  4. set PURE_MONITOR_TARGET_PATTERN=aspnet_wp
  5. Reboot your machine
JNI Quantify RATLC00369104 When profiling native code invoked through Java's JNI interface, the Java runtime may throw an exception and abort. This is a known problem that can be worked around by specifying the Quantify option /profiler-runtime-flags=4 when instrumenting the native code. This may cause the Descendant time for functions that return back through JNI to appear larger than normal. The function time, however, will still be correct.
Data Set operations Quantify RATLC00369110 Data set operations such as focus and delete subtree data can change F and F+D times or even eliminate certain functions that have annotated source. Currently all the data collected at line level is NOT changed during data set operations (it reflects the totals over the entire dataset).

Documentation Updates

There are no known documentation issues at this time.

Additional Information

Table 4 Product Notes
Topic
Applies To
Note
Debug data PurifyPlus PurifyPlus has a limited ability to display symbolic and line level information if it can not find the associated debug data for a given module. 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 messages and profiling detail are as informative as possible. To verify that the debug data has been found and instrumented, check the module instrumentation dialog (Settings>Executable Settings>PowerCheck>Modules to Instrument>Configure).
Custom Allocators Purify Purify supports some custom memory allocators. Custom versions of new and malloc may initialize memory or increase the size of allocations. Custom allocation schemes that do their own sub-allocation are also supported. The function prototypes and calling conventions of overloaded new, malloc, calloc, realloc, delete, and free must match the standard allocators. In addition, it is still important to match new/delete and malloc/free calls.
First chance exceptions Purify When you run an application instrumented with Purify under a debugger, "First-chance exceptions" or access violations are displayed. These messages can safely be ignored.
Object Reference Data Purify In the Object List View of the Data Browser (for Java code), the Object + Reference (O+R) column does not list data by default. Since the O+R calculation is potentially time-consuming, it is an optional calculation. To force the system to make this calculation, display the Object details view: Right click in the Object reference graph pane and select the Line Scale Factors->Linear or the Line Scale Factors->Logarithmic menu item.
Stock Sample Purify Purify provides the source files to build a sample program, the Stock program. The Stock program contains intentional errors. If you try to run the program outside of Purify or a debugger, the program might crash.

Additional product information is available at the Rational PurifyPlus Family Web site.

Contacting Rational Technical Support

If you have questions about installing, using, or maintaining this product, contact Rational Technical Support as follows:

Your Location Telephone Facsimile E-mail
North America

(800) 433-5444
(toll free)

(408) 863-4000
Cupertino, CA

(781) 676-2460
Lexington, MA

support@rational.com
Europe, Middle East, Africa

+ 31 (0) 20 4546 200
Netherlands

+31 (0) 20 4545 202
Netherlands

support@europe.rational.com
Asia Pacific

+61 2 9419 0111
Australia

+61 2 9419 0123
Australia

support@apac.rational.com

When you contact Rational Technical Support, please be prepared to supply the following information: