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 '%%'.
Note: For Quantify and PureCoverage, the saved filename is also changed when using the QuantifySaveData() and CoverageSaveData() APIs respectively.
The monitor is implemented as a Windows system tray icon. To start the monitor, run AspNetMon.exe (typically found in C:\Program Files\Rational\Common). 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 <productName>" 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 (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 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.
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.
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. Rational is actively working with Microsoft to better understand and identify a fix for 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".
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 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.
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.
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:
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.
| 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. | ||
| 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:
|
||
| 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.
|
||
| 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 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:
|
| 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:
where <Product> is one of Purify, Quantify or PureCoverage. where <Basename of EXE> is the basename of your service executable (e.g. foo is the basename of foo.exe.) |
| 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:
where <Product> is one of Purify, Quantify or PureCoverage. |
| 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 PurifyPlus Family Web site.
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: