Version 2003.06.00
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.
Now consider the case where the format specifier is used:
purify /save-data=foo%d.pfy foo.exe
In this case the first run would create foo0.pfy. The second run would create foo1.pfy.
The specifier can also include a width value which determines the number of characters for the numeric value
added to the filename. Consider the following:
purify /save-data=foo%3d.pfy foo.exe
In this example, the output files generated for the first two runs will be foo000.pfy and foo001.pfy.
If the '%' character is not followed by the width (optional) value and the letter 'd', the '%' is dropped and the trailing characters are retained. To generate a filename that contains an explicit '%', use '%%'.
The monitor is implemented as a Windows system tray icon. To start the monitor, first ensure that the Rational common directory (typically C:\Program Files\Rational\Common) 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:
Choose "ASP.NET Monitoring Disabled" to disable profiling for all PurifyPlus products, or choose
"Enable ASP.NET Monitoring for
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 (or Quantify or PureCoverage) GUI or disable the monitor as described above.
Additional product documentation is available in the following locations:
The following sections outline the supported platforms and installations requirements for this version of the Rational PurifyPlus Family of products.
| Item | Hardware Requirements and Recommendations | ||
|---|---|---|---|
| Operating Systems |
|
||
| Hardware |
|
||
| Disk Space to Install |
|
||
| Additional Disk Space (needed to accommodate instrumentation cache) |
|
||
| Item | Software Requirements and Recommendations | ||
| Integrations with 3rd Party Applications | Compilers
|
||
Debuggers
|
|||
| IDEs and Application Servers | Integrated Development Environments
|
||
Deployment Application Servers
|
|||
| Run-time Environments |
|
||
| 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:
|
||
The Rational Setup Wizard removes earlier versions of Rational products (including Rational licenses) from your desktop. You or your system administrator must see the Rational Suite Upgrade Guide in theRational 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.
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.
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.
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.
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.
This section identifies special considerations for using the Rational PurifyPlus Family of products with other products, including Rational products and third-party software 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.
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.
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.
Purify does not support Sun JVM 1.3.0 HotSpot. The profiling interface implementation within that JVM 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.
There are stability problems with this JVM that affect memory profiling with Purify. These problems have been resolved in JVM 1.3.1_01.
| 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:
|
||
| 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. | ||
| 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. | ||
| 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 is a known problem in Visual Studio .NET that is targeted to be fixed in Visual Studio .NET 2003. Although the official version is not yet released, tests conducted against the Final Beta have been successful. |
| Debugging | PurifyPlus | RATLC00369792 | Within Visual Studio .NET, 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. |
| 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). |
There are no known documentation issues at this time.
| 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 Suite Web site: http://www.rational.com/products/pqc
If you have questions about installing, using, or maintaining this product, contact Rational Technical Support as follows:
| Your Location | Telephone | Facsimile | |
| North America |
(800) 433-5444 (408) 863-4000 |
(781) 676-2460 |
support@rational.com |
| Europe, Middle East, Africa | + 31 (0) 20 4546 200 |
+31 (0) 20 4545 202 |
support@europe.rational.com |
| Asia Pacific | +61 2 9419 0111 |
+61 2 9419 0123 |
support@apac.rational.com |
When you contact Rational Technical Support, please be prepared to supply the following information: