How to use Selective Instrumentation with Purify on Windows

Technote (FAQ)


How do you use the selective instrumentation (SI) feature in IBM Rational PurifyPlus, Rational Purify, Rational PureCoverage, or Rational Quantify?


Selective Instrumentation allows you to instrument a select group of modules instead of instrumenting an entire application. Although the functionality is similar to SI for Quantify and PureCoverage, there are some additional steps and considerations that apply specifically to Purify only.


Enabling and Using Selective Instrumentation

To enable selective instrumentation (SI), follow these steps:

  1. Add the following system-wide environment variable:

    1. Select Start > Settings > Control Panel > System. On the Advanced tab, select Environment Variables.

    2. Click New under "System variables".

    3. Set "Variable Name" equal to IBM_RATIONAL_PURIFY_ENABLE_SELECTIVE.

    4. Set "Variable Value" equal to 1.

  2. Rebuild the target modules with the static version of the C Runtime (CRT).

    Purify manipulates memory in a way that can only be handled properly by instrumented modules. In order for SI to function properly, you must isolate the CRT heap being used by instrumented modules. The recommended way to achieve heap isolation is by building all modules that you plan to instrument with a static CRT. This ensures that each instrumented module has its own isolated CRT heap.

    Switching to a static CRT can pose problems for modules that share CRT resources. See the MSDN article, Potential Errors Passing CRT Objects Across DLL Boundaries, linked under Related URL for additional information.

    If you need to share CRT resources or you are otherwise unable to rebuild your modules with a static CRT, see the "Dynamic CRT Workaround" section at the end of this technote.

    To use the static version of the CRT, replace /MD or /MDd with /MT (release) or /MTd (debug). This change needs to be made on all compile lines for the target module and all static libraries linked into the target module.

    The change can also be made through the Visual Studio IDE:

      Select   Project  > Properties  > C/C++  > Code Generation  > Runtime Library:  "Multi-threaded" or "Multi-threaded Debug"

      The change should be made at the root configuration level for the target module and all static dependencies. It is not necessary to change the build settings for modules that are not instrumented.

      If you need to use /MT or /MTd with a module that links with MFC, then you also need to use the static version of the MFC libraries: Select Project > Properties > General > Use of MFC: "Use MFC in a Static Library"

3. Verify that you have the recommended build options set:

4. Selectively instrument the target modules:

    1. Start the Purify GUI

    2. Select Settings > Default Settings > PowerCheck > Selected Modules > Configure

    3. Add the target modules to the list

    4. Set each module's Instrumentation State to "Permanent"

    5. Click OK to instrument the selected modules

5. Run your application as you normally would outside of Purify. When an instrumented module is loaded, Purify will automatically start collecting data.

Dynamic CRT Workaround

It is highly recommended that you use a static CRT with SI, however, this is not always possible. Heap isolation can also be achieved through careful use of the dynamic debug CRT.

    1. All instrumented modules must link with the debug version of the dynamic CRT (/MDd).

    2. All uninstrumented modules must use a different CRT (/MD, /MTd, or /MT).

    If you are using Visual Studio 2003 or 2010 - 2012, the debug CRT (ex: msvcrt71d.dll, msvcr100d.dll, or msvcr110d.dll) and its corresponding pdb must be copied to your application directory and selectively instrumented along with your target modules. Your application must load this copy of the CRT instead of the System32 version. This will happen as long as the previously mentioned modules are copied to your application directory.

    If you are using Visual Studio 2005 or 2008, you should do the following:

    1. Start your application under a debugger and set a breakpoint inside the module of interest (Purify should not be involved at this point).

    2. After the breakpoint is hit, go to the modules window and note the exact location of the loaded CRT libraries. The directory name should look something like the following:

    3. Selectively instrument (in permanent mode) the module or modules of interest and the CRT library or libraries in the directory, found in step 2.

    4. Run the application.

Important Notes

  • Debug assertion failures received during an SI run may indicate that the CRT usage guidelines have not been met.

  • The use of SI without adhering to the CRT usage guidelines is not supported.

  • To see a viewlet on using Selective Instrumentation, go to this IBM Education Assistant module.

  • For more information on using selective instrumentation with your application, contact IBM Rational Support.

Related information

Potential Errors Passing CRT Objects Across DLL Boundar
A simplified Chinese translation is available

Cross reference information
Segment Product Component Platform Version Edition
Software Development Rational PureCoverage Instrumentation Windows 7.0.1, 7.0
Software Development Rational Purify Instrumentation Windows 7.0.1, 7.0
Software Development Rational Quantify Instrumentation Windows 7.0.1, 7.0

Document information

More support for:

Rational PurifyPlus family

Software version:

7.0, 7.0.1

Operating system(s):


Reference #:


Modified date:


Translate my page

Content navigation