Tool Mentor: Using Rational PurifyTM to detect run-time errors
Purpose
This tool guide provides an overview of how to use Purify to find run-time errors in Visual C/C++ programs. To learn more about Purify, read Getting Ahead with Purify. For step-by-step information about using Purify, see the Purify online Help.
Related Rational Unified Process activity: section "Execute Unit Test" in Activity: Perform Unit Tests.
Overview
This Tool Mentor is applicable when running Windows NT 4.0.
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. To test a program using Purify:
To test a program using Purify:
1. Instrument and run the program with Purify to detect
run-time errors 
The first step in Purify'ing your code is to instrument and run your program.
In Microsoft Developer Studio 97 or later, click to engage Purify integration, then run the program whose code you want to check. Or, if you are not using Purify integrated with Developer Studio, just run the program in Purify. Purify instruments your code so that it can perform error detection.
Purify provides a default level of error detection for each component, but you can use the PowerCheck tab in the settings dialogs to set the level of error detection you want. You can also set options to control things such as whether Purify records and displays Uninitialized Memory Copy (UMC) messages and 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 will use to detect errors. Purify shows you its progress as it instruments the executable file and modules.
After instrumentation, Purify starts the program and, as you exercise the instrumented program, displays an Error View window for the run and reports 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 in use and handles in use at exit.
Tip for Testing: 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 scripts in the Purify online Help.
More information? Look up instrumenting, running programs, and powercheck in the Purify online Help index.
2. Analyze the error view messages
The second step in Purify'ing your code is to analyze the error view messages.
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.
With a single click, 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. If debug data was available when you instrumented the program, you can also examine the source code. 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.Because a large program can generate hundreds of error messages, Purify provides filters to 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 a text file (.txt). For more information, look up scripts in the Purify online Help index.
More information? Look up error messages, error view window, and filters in the Purify online Help index.
3. Correct the errors and rerun the program
The third and final 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 (.pfy), to share with colleagues who have Purify.
More information? Look up source code and saving data in the Purify online Help index.
