Tool Mentor:  Detecting Run-Time Errors Using Rational Purify and Rational PurifyPlus (Windows) 

Purpose

This tool mentor provides an overview of how to use Rational Purify to find run-time errors in Visual C/C++ programs. This tool mentor is applicable for use with systems running Microsoft Windows. 

PurifyPlus is a Rational product that includes Purify functionality.

To learn more about Purify, read Getting Started with Rational Purify. 

For step-by-step information about using Purify, see the Purify online Help.

Related Rational Unified Process information:

• Activity: Perform Unit Tests, refer to the section titled "Execute Unit Test"
• Activity: Implement Test
• Activity: Evaluate Test

Overview

Purify detects run-time errors, including memory leaks, both in your own code and in the components your software uses, even when you don't have the source code. It reports memory errors such as array bounds errors, access through dangling pointers, uninitialized memory reads, memory allocation errors, and memory leaks, so that you can resolve them before they do any damage. Purify can also report how thoroughly you have tested your code for errors, if you have Rational PureCoverage on your system. 

Tool Steps

To test a program using Purify:

1. Instrument and run the program with Purify to collect error and coverage data
2. Analyze the Purify error data
3. Correct the errors and rerun the program

To ensure that you have Purify'd your entire program, take one more step:

4. Analyze the Purify coverage data to find untested code

1. Instrument and run the program with Purify to collect error and coverage data 

The first step in Purify'ing your code is to instrument and run your program.

In Microsoft Visual Studio, engage Purify. If you have PureCoverage on your system, set Purify to collect coverage data. Then run the program that you want to Purify. Or, if you are not using Purify integrated with Visual Studio, just run the program in Purify. Purify instruments your code in preparation for detecting errors and collecting coverage data.

Purify provides a default level of instrumentation for each component, but you can use the PowerCheck tab in the settings dialogs to set the level of instrumentation you want. You can also set options to control how Purify handles error data. For example, you can specify whether Purify records and displays Uninitialized Memory Copy (UMC) messages, and you can specify the length of call stacks recorded for errors and allocations.  

During instrumentation, Purify makes copies of the executable and its associated modules, and uses Object Code Insertion (OCI) technology to insert into the code the instructions it uses to detect errors and monitor coverage. Purify shows you its progress as it instruments the executable file and modules.

After instrumentation, Purify starts the instrumented program. As you exercise the program, Purify displays a Data Browser window with an Error View tab that contains detailed diagnostics about the run-time errors it detects.

When you exit the program, Purify reports memory leaks. You can specify additional settings to have Purify also report memory and handles in use at exit.

Tip: In addition to using Purify interactively, you can also incorporate Purify into your test scripts, makefiles, and batch files for automated testing.

For more information, look up the following topics in the Purify online Help index:

•  instrumenting
• running programs
• powercheck
• scripts

2. Analyze the Purify error data 

The second step in Purify'ing your code is to analyze the Purify error data.

By default, the error view initially displays only the first line of each message. This condensed outline format makes it easy to scan the messages, quickly identify critical errors, and assess the state of the program. You can expand the outline to see more detailed diagnostic information.

Using this error view information, you can identify, understand, and eliminate hard-to-find memory access errors and memory leaks. You can also examine the source code, if debug and relocation data was available when you instrumented the program. Because Purify detects access errors at the point where they occur, and displays this information in the error view, you can easily track and eliminate these errors.

A large program can generate hundreds of error messages, therefore Purify provides filters to hide messages and help you focus quickly on the most critical errors.

Tip: If you have incorporated Purify into your test scripts, makefiles, and batch files, you can automatically save error messages to an ASCII text file. 

For more information, look up the following topics in the Purify online Help index:

• scripts
• error messages
• error view
• filters

3. Correct the errors and rerun the program 

The third step in Purify'ing your code is to correct the errors and rerun the program.

To correct errors, double-click the line where the error occurs. Purify opens your source code in your editor at the exact location of the error, ready for correction.

After you correct and rebuild the program, you can verify your correction by rerunning the updated program and comparing the new results to the previous run. Repeat the cycle of instrumenting and running, analyzing, and correcting until your program runs clean.

You can use the Navigator window to switch between the two runs, and keep track of all the runs you're working with. You can also save error view data as a Purify data file, to share with colleagues who have Purify.

For more information, look up the following topics in the Purify online Help index:

• source code
• saving data

4. Analyze the Purify coverage data to find untested code 

If you collected coverage data for the program runs, you can also find the parts of your code that you have not Purify'd, and improve your testing coverage so that you find all of the errors in your program, wherever they occur.

When you exit your program, Purify displays the coverage data in the Module View, File View, and Function List View tabs of the Data Browser window. These tabs show information such as the number of functions and lines hit and missed by your tests, as well as the percentage of functions and lines hit and missed. If debug line data is available and you monitored your code at line level, you can also use the Annotated Source window to analyze coverage for functions line by line.

Purify automatically filters out coverage data that is less interesting, such as data from system libraries, before displaying coverage data. You can create your own filters to hide additional data that you do not want to see, so that you can focus on what's important to your analysis.

By default, Purify automatically creates an Auto Merge entry on the Navigator window, so that you can easily analyze the total coverage of the program over multiple runs. You can also merge specific runs yourself to see the cumulative effect of selected runs.

When you find weak spots in your coverage, rerun your program and test all of the important parts, or revise your makefiles or test script to do a more thorough job. You can now have the confidence that errors are not lurking somewhere in the code that you failed to test, waiting to cause unexpected problems.

Tip: You can use /Coverage and related options to collect coverage data with Purify during automated testing. 

For more information, look up the following topics in the Purify online Help index:

• command line options
• coverage data

Copyright  © 1987 - 2001 Rational Software Corporation

Rational Unified Process