README.TXT Copyright (C) 1996-2000 Rational Software Corporation. All rights reserved. Rational, the Rational logo, Purify, Rational Visual Test, and ClearQuest are trademarks or registered trademarks of Rational Software Corporation in the United States and in other countries. Visual C++, Windows NT, Developer Studio, 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 2001.03.00 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 ----------------------------------------------------------------- 1. What's new in Purify? ----------------------------------------------------------------- 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. ----------------------------------------------------------------- 2. Requirements ----------------------------------------------------------------- * Intel Pentium processor * Microsoft Windows NT 4.0 with Service Pack 3 or greater * 32 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 NT. Purify for Windows supports: Architecture: Win32 programs only Compilers: Visual C++ (6.0) Note: Purify, 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. 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. ----------------------------------------------------------------- 3. Installing Purify ----------------------------------------------------------------- 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 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. * 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, 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. ----------------------------------------------------------------- 4. Known problems ----------------------------------------------------------------- * Interaction with other applications * Instrumenting programs * Running programs * Working with messages * Purify user interface 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. 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 ----------------- * 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] ----------------------------------------------------------------- 5. 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 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. 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.