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

Running a program with Purify

More information? For an explanation of how Purify uses debug and relocation data for error checking and coverage monitoring, 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 Developer 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 succinct 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, doing 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.