Copyright © 1996-2002 Rational Software Corporation. All rights reserved.

Rational, the Rational logo, Purify, 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++, Windows, Windows NT, Developer Studio, Visual Studio, .Net and Microsoft are trademarks or registered trademark 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 Purify 2002.05.20 for Windows

---

TABLE OF CONTENTS

---

1. What's new in Purify?
2. Requirements
3. Installing Purify
4. Known problems
   • Interaction with other applications
   • Instrumenting programs
   • Running programs
   • Working with messages
   • Purify user interface
5. Contacting Technical Support

Back to Top

New in Purify 2002.05.20:

• Purify is now fully integrated with the Microsoft Visual Studio .NET IDE, enabling developers to detect run-time errors without having to leave the IDE. A standalone GUI is also provided. Both managed and unmanaged code are supported but detection of errors in mixed mode applications can only be done for one type of component at a time. Debugging of managed code with Purify engaged is fully supported within the IDE.
  
  
• The default mechanism for reporting call stack detail has been modified to only display entries for which debug information is available. This helps eliminate many system level functions from consuming space on the stack. For users who want to see all the call stack data that is available, a checkbox (Show maximum call stack detail) is provided on the Errors and Leaks tab.

• Support has been added for Sun JDK1.4 (both the client and server versions).
  
  
• A preview version of an ASP.NET profiling monitor (AspNetMon.exe) is included in this release. This monitor enables Purify memory profiling for managed code running in the context of ASP.NET or as a Web Service.

  The monitor is implemented as a Windows system tray icon. To start the monitor, first ensure that the Purify install directory (typically C:\Program Files\Rational\Purify) is in the SYSTEM path, then run AspNetMon.exe. After the monitor is started, a small traffic light icon appears in the system tray area of the Windows taskbar. The red light indicates profiling is disabled for all PurifyPlus products. The green light indicates profiling is enabled for one of the products (Purify, Quantify, or Coverage). Hover the mouse cursor over the monitor icon to view the current monitor status (enabled or disabled), and the product name for which profiling is enabled (Purify, Quantify, or Coverage).

  To change the monitor status, right-click the monitor icon in the system tray. A popup menu displays the following choices:

  • ASP.NET Monitoring Disabled
  • Enable ASP.NET Monitoring for Quantify
  • Enable ASP.NET Monitoring for Coverage
  • Enable ASP.NET Monitoring for Purify

  Choose "ASP.NET Monitoring Disabled" to disable profiling for all PurifyPlus products, or choose "Enable ASP.NET Monitoring for " to enable profiling for one of the products.

  Once started, the monitor will continue to run until the operating system is rebooted. To start the monitor automatically, place a shortcut to AspNetMon.exe in the startup folder of the All Users > Start Menu.

  In order to obtain data for your ASP.NET application, you need to either take a snapshot from the Purify GUI or disable the monitor as described above.
  
  

• The /AllowDialogOnAssert option has been added. This option can be used to specify whether to allow the Assert dialog to be displayed for program execution errors. By default, the Assert dialog is not displayed. Instead, a message is displayed in the Purify error view indicating an assert was triggered.

New in Purify 2002.05.00:

• Support has been added for .NET Beta 2 applications. In the case of managed applications, Purify can collect memory profiling data. In the case of unmanaged applications, Purify can collect error and coverage data. To collect Purify data while running a .NET application from within Visual Studio.NET, select the Tools->Run Purify menu item before running the application.

  Because .NET is still a beta product and will continue to evolve after the release of Purify, please visit the Rational .NET Solution Center for access to the most up-to-date information regarding Rational's support of .NET.

• Support has been added for users who do not have permission to write to the Program Files directory or the directory containing the program under test. Refer to the online help for details on enabling this feature. Look under Contents -> Reference Information -> File Locations.

• Support has been added for the Visual C++ .NET compiler.

• Support has been added for Windows XP Professional.

• Support for Sun JDK1.3.1 has been enhanced to include support for the Hotspot version of the VM.

• Preliminary support has been added for Sun JDK1.4.

• Support has been added for Java applications running within a number of Application Servers. For details, visit the Rational Software Technical Support web page, go to the Solutions Knowledge Base and enter "j2ee Purify" in the search window.

New in Purify 2001A.04.00:

• Support for profiling memory usage in Java has been enhanced to include detail for Java objects. You can now drill down into the allocated memory for a function to see the objects it comprises and the relationships between different objects. Refer to the "Purify for Java" section of the online Help for details.

• Purify 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.

• Purify now recognizes the JAVA_HOME user environment variable. If Purify was unable to detect the JVM you want to use for memory profiling, set JAVA_HOME to point to the JVM home directory and Purify will default to it.

• Sun JDK 1.3 support has been enhanced to eliminate the manual step for specifying the Classic version of the VM. Purify will now add this option automatically.

New in Purify 2001.03.00:

• Support has been added for profiling the memory usage of Java applications. Via the Run Dialog, users can select the 'Profile memory usage(for Java)' radio button to request that Purify gather memory allocation statistics. Prior to selecting the feature, users should select their JVM of choice via the JVM tab in the Settings > Preferences dialog. Support is provided for both the Microsoft and Sun JVMs.

  In addition to pin-pointing methods that consume excessive amounts of memory, Purify can also help isolate functions that retain object references unnecessarily. Using the snapshot button, which can be used to record a memory profile of an application, a user can create memory snapshots both before and after a critical section of code. The Purify Diff facility can then be used to show a call graph of the allocation differences. The 'focus on subtree' capability can then be used to drill down on specific areas of interest.

  In order to filter out uninteresting data, Purify provides a 'pre-filtering' mechanism for Java classes. When using the Sun JVM, a special [PreFilters] section can be added to the profile.ini file. Classes listed in this section will be excluded from the profiling data.

  Sun's JDK release 1.3 is supported. However, because it was released late in the Purify 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 be aware that Sun has changed the default VM to their HotSpot VM. For now, Purify works only with the Classic VM. To use the Classic VM you need to use the "-classic" option (e.g. "java.exe -classic foo"). You'll have to insert this manually in the Run dialog's Command-line Arguments edit field if you use 1.3.

New in Purify, version 2000.02.10:

• Improved performance and reliability.

New in Purify 6.5:

• Support has been added for the collection of memory errors and coverage data from a single run of an executable. This feature is available within Purify if a valid PureCoverage license has been installed. When running Purify from the command line, the feature can be activated by specifying the /coverage option. From within the Purify Window, the feature is activated by default. It can be can be deactivated by unchecking the "Collect coverage data" check box in the Run dialog.

• Default message filtering has been improved to help reduce informational output, allowing critical errors to be seen more easily. For details, consult the Purify Filter Manager.

• Purify is integrated with Rational Robot 7.1, a Rational functional testing tool. You can Purify applications run with Robot scripts and send errors detected by Purify back to the script for immediate logging and analysis. From the "Tools > GUI Playback Options > Diagnostic Tools" tab, select "Rational Purify" or "Rational Purify with Coverage". See your Rational Robot documentation for more details.

• Improved compatibility with IIS and other services.

New in Purify 6.0.1:

• Purify incorrectly instrumented wcsdup(), causing some Unicode applications to fail. This has been corrected.

New in Purify 6.0:

• Support for Visual C++ 6.0. Note that applying changes to a running Purify'd program, using "Edit & Continue" in VC6 is not supported.

• You can now select an error detected by Purify and automatically submit it as a defect to ClearQuest, Rational's change request management tool. Simply highlight the error and select "Submit ClearQuest Defect" from the shortcut menu.

  Purify uses an initialization file, schema_purify.ini, to map error 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_purify.ini file to ensure that data is correctly entered in the submit form. To modify the .ini file, follow the instructions included in schema_purify.ini, located in the Purify product directory.

• Purify is integrated with Visual Test 6.0, Rational's functional testing tool. You can Purify applications run with Visual Test scripts and send errors detected by Purify back to the script for immediate logging and analysis. Use the "Run Visual Test Scripts with Purify" tool in the Purify toolbar in Developer Studio, or add "purify" to the "Run" command in your test scripts. See your Visual Test documentation for more details.

New in Purify 5.1:

• Purify can now run completely within Microsoft Developer Studio, integrating seamlessly with your debugging environment. To enable this feature, check the Purify > Settings > Embed Error Views menu item in Developer Studio. Purify's online help is also now available in Developer Studio's InfoView tab.

• The performance of instrumented programs has been significantly improved, making Purify faster than ever.

Back to Top

• Intel Pentium processor
• One of the following Operating Systems
  • Microsoft Windows NT 4.0 with Service Pack 6a or greater
  • Microsoft Windows 2000
  • Microsoft Windows XP Professional
• 256 Mb RAM recommended
• Approximately 35 Mb free disk space
• 100Mb minimum swap space recommended

Notes:

• You will need additional disk space to accommodate a growing cache directory as you Purify more programs.

• Purify does not support checked builds of Windows.

• Purify for Windows supports:

  Architecture:	Win32 programs only
  Compilers:	Microsoft Visual C++ 6.0, including the Visual C++ 6.0 Processor Pack Microsoft Visual C++ .NET
  Interpreters:	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:	Visual C++, WinDBG, NTSD
  Debug formats:	COFF, CV4
  Debug files:	Debug data can be placed in .exe, .pdb, or .dbg files. Purify can also use .map files, if available.

Back to Top

To install Purify:

1. Verify that your swap space is set to at least 100Mb, 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 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.

• Purify must be installed after Visual C++ and Visual Test in order for it to install an integration with these tools. If you installed one of these tools after Purify, simply re-install Purify to get the integration.

• Purify 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 Purify, Rational Software Setup installs additional components that are not used by Purify. For example, SQL Anywhere.

• To uninstall a previous copy of Purify for Windows NT, double-click the Add/Remove Programs icon in the Control Panel and uninstall Purify. The uninstall program removes all of the files associated with the Purify installation.

  If you do not do an uninstall, but instead install a new version of Purify over a previous version, be sure to delete all files in the Purify cache directory first. Your application and its modules must be reinstrumented after installation to operate correctly with the current release of Purify.

Back to Top

• Interaction with other applications
• Instrumenting programs
• Running programs
• Working with messages
• Purify user interface

Interaction with other applications

• Within Visual Studio .NET, the File->Save As menu item is currently disabled for Purify data files. To save a Purify data file using something other than the default name, the File->Save menu item should be used. This will bring up a save dialog that will allow the name to be changed.

• 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. Purify 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.

• Purify 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 Purify 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 Purify'd program, using "Edit & Continue" in VC6 is not supported.

• Purify does not work correctly when you run a Java application using Netscape Communicator. If Netscape hangs while you are instrumenting and running your application, turn off JIT Java compiling. To turn off JIT Java compiling, rename JIT3230.dll (Netscape 3.0) or JIT3240.dll (Netscape 4.0), located in the Program\Java\bin or Program\Java directory.

• During installation, Purify reads certain Microsoft Developer Studio registry values. However, these registry values aren't written to the registry until after Developer Studio is run for the first time. Therefore, you must run Microsoft Developer Studio before Purify can install the Developer Studio integration. [34649]

• When instrumenting controls run inside Microsoft's Internet Explorer 4.0, and Active Desktop "shell integration" is installed, you must supply the "-new" argument to iexplore.exe. This causes a new, instrumented, iexplore process to start and run your control. Without this argument, your control is run by the already-running desktop explorer which is not instrumented, so no error detection will be performed. e.g. purify iexplore.exe -new

• There are compatibility problems between Purify and applications that use SetWindowsHook() and SetWindowsHookEx(). Often these compatibility problems can be solved by using Purify's minimal instrumentation for the hook DLL.

  The SetWindowsHookEx() API is disabled in instrumented programs. This is to avoid hooking uninstrumented programs with Purify'd DLLs. For workarounds to this, please contact Rational Software's Technical Support. [21155]

• 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 Purify command line interface instead. [00254, 23822]

• In Purify'd programs, argv[0] is set to the instrumented filename. 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]

• Purify now 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.

• In rare instances, Purify fails to find DLLs required by LoadLibraries. Try adding the executable directory to your PATH environment variable. [23669, 19924]

• When you run a Purify'd program under a debugger, "First-chance exceptions" or access violations are displayed. You can safely ignore these messages.

• SetErrorMode() suppresses all system-level message boxes, including the Windows NT 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. [20215]

• Purify assigns a default debugger based on the default AeDebug Debugger entry in the Registry. If you do not have Microsoft Developer Studio installed, it's possible that the registered program will not support full debugging.

Instrumenting programs

• Purify does not support the use of the NB05 debug data format in modules. You can use the cvpack utility program, included with Microsoft Developer Studio, to update the debug information for use with Purify. 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.

• 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 Purify's messages are as informative as possible. [20531]

• Purify does not indicate whether it located and instrumented a DLL's corresponding .pdb file. If debug data is missing, Purify does not display source file names or line numbers. In this situation, copy the .pdb file into the same directory as the DLL, delete the cached version of the DLL from the Purify cache directory, and reinstrument the DLL. [22591, 20035]

• Purify fails to instrument files in the following situations:
  • A .pdb file is supplied after a .dll or .exe file has been instrumented. When you rerun the program, Purify 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 Purify cache directory.

  • Instrumented .dll and .exe files that are located outside of the Purify cache directory are not deleted when you install a new version of Purify. When you run a program that uses one of those files, Purify 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]

• Purify 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

• Due to a synchronization problem within the Japanese Language Pack on Windows XP, Purify 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.

• 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.

• When Purify processes very large numbers of errors, focus is dedicated to the current error view. To help reduce message traffic, select Settings > Default Settings and, in the Errors and Leaks tab, ensure that "Show first message only" is selected. This is the default setting. [20596]

• Purify does not report Memory Leak (MLK) messages for UNLOCKED moveable memory. If memory is unlocked, Purify considers it unallocated. Purify reports a Free Memory Read (FMR) or Free Memory Write (FMW) when an application locks, unlocks, and then accesses a block of memory. This functionality will be added in a future release.

• By default, Purify supports five concurrently-running copies of any given program. If you try to start a sixth copy, you receive an error that PureRT.dll failed to initialize. For information and workarounds, contact Rational Software's Technical Support. [22268]

• It is not recommended that you copy parts of a program at runtime into VirtualAlloc'd memory, and then try to execute it. Purify considers the copied code to be part of the data section, and does not instrument it. [22784, 00200]

• Purify does not apply filters attached to a library (DLL) until the library is loaded. [23183]

• 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.

• On occasion, Purify might experience an internal error. These errors are displayed in error views as Purify internal errors. Please follow the onscreen instructions and submit any Purify internal errors you receive to Rational Software's Technical Support.

Working with messages

• On occasion, Purify does not display the correct Exception address on the first line of an EX* message. To see the correct address, expand the message. [36954]

• On occasion, Purify does not report Freeing Mismatched Memory (FMM) messages when an array is deleted without the square brackets, [ ]. [20141]

• When Purify reports a Beyond Stack Read (BSR) or Beyond Stack Write (BSW) message, it does not report how far beyond the stack it is. [23424]

• When Purify counts the number of bytes or handles returned by the following Purify API functions, it does not exclude bytes or handles reported in related messages (MLK, MPK, MIU, HIU) that have been filtered: PurifyAllLeaks, PurifyNewLeaks, PurifyClearLeaks, PurifyAllInuse, PurifyNewInuse, PurifyClearInuse, PurifyAllHandlesInuse, and PurifyNewHandlesInuse. [23430]

• If you compile your application with both optimization and debug flags, Purify might point to the wrong line in your source code. [22522]

Purify user interface

• When you are working in the Navigator window and you open and close dialogs, sometimes the item you had selected in the Navigator no longer has the focus. Re-select the item. [22116]

• You cannot scroll beyond 145 characters in a line in an Error View window. To see text beyond 145 characters, copy the line and paste it into another application. [23296]

Back to Top

If you have a technical problem and you can't find the solution in online Help, you can contact Technical Support.

The Americas:
       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

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 Purify" dialog along with the Purify log file.

Before you call:

1. Note the sequence of events that led to the problem and any program messages or error view messages displayed.

2. Have your license key and customer number ready and, if possible, the product running on your computer.

• 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.