This chapter shows you how to use Purify in Microsoft Visual Studio. But you can also use Purify independently of Visual Studio. Read "Using Purify standalone" and "Testing with Purify's command-line interface."

Running a program with Purify

More information? For information about building programs with debug and relocation data, look up debug data in the Purify online Help index.

Click to enlarge

Purify instruments each module at a default instrumentation level, but you can customize the instrumentation level to provide more or less detail for special cases.

More information? For an explanation of instrumentation levels and how to use them, read "Customizing instrumentation". For more detail, look up instrumenting in the Purify online Help index.

As you exercise your program, Purify detects run -time errors and memory leaks and displays them in an Error View tab in the Purify Data Browser window.

 

More information? Look up error view in the Purify online Help index.

Note: If you're debugging client/server and multi-process applications, you can debug several processes and see the error reports for each running application simultaneously. To do this, run each process in a separate instance of Visual Studio with Purify engaged. Alternatively, you can use the standalone Purify user interface. See " Using Purify standalone ".

Purify displays error and warning messages about run-time errors and memory leaks, and informational messages about the progress of your program's execution.

Click to enlarge

When you exit the program, Purify reports memory leaks. In addition to memory leaks, you can set Purify to report memory in use at exit and handles in use at exit.

An error often repeats many times in a program, particularly if it occurs inside a loop. To provide a concise overview of a program's errors, Purify by default displays each error message only once, the first time an error occurs, and then updates a counter whenever the error repeats.

         


Click to enlarge

A large program can generate hundreds of messages. To focus on the most critical error messages quickly, create filters to hide all other messages from the display.

You can filter messages individually, or you can filter them based on their type and source. Consider hiding all informational messages, for example, or all messages originating from a specific file.

Click to enlarge

Once created, error filters apply to the current run and to all future runs of the program until you disable them. Disabling a filter causes hidden messages to be redisplayed in the error view.

Click to enlarge

Analyzing Purify error data

You can expand Purify messages to pinpoint where errors occur and to obtain diagnostic information for understanding why they occur.

Here's an example of an expanded ABW (array bounds write) error message:

Click to enlarge

The level of detail provided in call stacks depends on the availability of debug and relocation data. Even if you build your program in release mode, you can still get the highest possible level of detail. For more information, look up debug data, release builds in the Purify online Help index.

You can customize the format of Purify's messages. For example, you can increase the number of lines of source code that are displayed, or include instruction pointers and offsets to make locating errors easier.

More information? Look up preferences, source code in the Purify online Help index.

Correcting errors

Purify makes it easy to correct errors.

Click to enlarge

To make sure that you find errors in your code wherever they occur, use Purify to monitor code coverage each time you run your program. With Purify's coverage feature, you can check that you're exercising all your code, especially those parts that have recently been added or modified.

Purify displays coverage data in views that you can sort to find the largest gaps in your testing.

Click to enlarge

Purify can also display line-by-line coverage information marked directly on a copy of your code in an Annotated Source window. The color of each line of code indicates whether it is tested, untested, or partially tested, so that you can tell at a glance where you need to tighten up your testing.

Click to enlarge

Based on the coverage data, refine your approach to exercising your code to make sure you are testing all the critical lines and functions. If you are testing manually, try different menu commands, or enter new values for variables. If you are testing automatically, revise or add test scripts.

When you are satisfied that you've made good progress in eliminating errors, and that you can exercise the parts of your program that most need testing, rebuild. Then rerun the program under Purify.

After rerunning your corrected program, you can easily compare runs to verify your corrections. Purify's Navigator window, which you can display from the Purify View menu, helps you keep track of multiple runs and multiple programs.

Click to enlarge

Saving Purify data

• Purify data files (.pfy,.pcy). The file extension Purify uses depends on whether you are saving error data alone, or error and coverage data. You can save merged coverage data to PureCoverage data files (.cfy).
• ASCII text files (.txt). You can process this data with scripts or use it in spreadsheet and word-processing applications.

Purify uses one of the following error-checking instrumentation levels as the default for each module, depending on the module's size and the availability of debug and relocation data:

• Precise instrumentation provides full run-time error detection, to pinpoint problems in any part of your program.
• Minimal instrumentation improves Purify's performance while providing a basic level of error detection.

For coverage monitoring, Purify uses one of the following levels as the default:

• Line-level instrumentation, which reports line-by-line coverage data
• Function-level instrumentation, which improves performance but reports only function-by-function coverage data

            

Click to enlarge

You can override the default and specify the level for each module to meet your own requirements.

Click to enlarge

Try using the Precise error level for the most critical modules in your program and the Minimal level for the others. Later, you can change the Minimal level to Precise for a thorough check of the other modules

Purify's just-in-time debugging support provides instant access to your debugger when you need to solve tough problems. Click to enable Break on Error. Purify now stops your program just before an error executes so that you can debug it. You can also run a Purify'd program directly under the debugger.

       

Click to enlarge

To quickly debug only the most critical errors in your program, use Break on Error together with Purify filters. First, filter out all the less critical messages, then enable Break on Error. Purify breaks only for the unfiltered messages. When you're ready to debug the remaining errors, just disable the filters.

When you don't need all of Microsoft Visual Studio's resources, you can use Purify standalone. Purify's independent user interface provides the same error-detection and coverage capabilities as when you use Purify integrated with Visual Studio.

To start Purify as a standalone application, double-click and then click Run in the Purify Welcome Screen to display the Run Program dialog.

       

Click to enlarge

Purify instruments your code and displays the results in a Data Browser window.

Using Purify's command-line interface, you can use Purify with existing makefiles, batch files, and Perl scripts. For example, if you have a test script that runs a program, you can easily modify the script to instrument and run the program. To do this, change the line that runs Exename.exe to:

purify Exename.exe