Readme

Insure++ automatically integrates with Visual C++ 6.0 and 5.0. After installation, an Insure++ toolbar will appear when you start Visual C++, containing the following buttons:

Instrument File

Insure++ Build

Insure++ Rebuild All

Insure++ Stop Build

Insure++ Execute

Insure++ Control Panel

Insra - Insure++ Report Analyzer

Inuse - Insure++ Heap Viewer

TcaView - Total Coverage Analysis

Note that the first four buttons correspond to the buttons under the "Build" heading of DevStudio. The only difference is that your files will be instrumented by Insure++ and linked against Insure libraries.

All of the above commands can also be accessed in the tools menu of Visual C++.

InsureSpy Integrated Debugging

This feature enables the user to get runtime error-detection from Insure++ while running in the Microsoft Debugger (MSDEV.EXE). This feature is available for Developer Studio Versions 5.0 and 6.0.

When insure is installed, running an instrumented executable (an .exe file that is built with Insure++) through the debugger will automatically invoke the integrated version of InsureSpy. No special settings are required for this behavior. When running a NON-INSTRUMENTED executable through the debugger, the default behavior is that InsureSpy is NOT invoked, i.e., the debugger operates as it did before Insure was installed. Sometimes it is desirable to invoke the integrated InsureSpy on non-instrumented executables.

Examples:

Minimal error detection is desired without rebuilding the application and integrated debugging is desired. Note: This reason is applicable on Windows NT/2000, but not on Windows 95/98. See section "Operating Systems and Interface Type Differences".
The instrumented module is a component such as a DLL or OCX which is loaded into a non-instrumented executable and integrated debugging is desired.

In these cases, the integrated InsureSpy can be invoked by selecting:
Automatic InsureSpy Integrated Debugging
from the General Page of the Insure++ Control Panel. When this box is checked, all executables that are started in the Debugger will be run through the integrated InsureSpy. Note that JIT debugging is not affected. Also note that this option does not affect running InsureSpy outside of the Debugger (running by the blue "!" on the toolbar, selecting file->run from insra, or calling InsureSpy or inject explicitly from the command-line or from Image file execution options).

Setting a Breakpoint at Runtime Errors

When using the InsureSpy Integrated Debugging feature, you can set a breakpoint at _Insure_trap_error under Edit->Breakpoints in DevStudio. This will cause the debugger to hit a breakpoint whenever Insure++ finds an error, so you can examine variables and step through with the debugger.

Operating System and Interface Type Differences

Insure++ offers two types of interfaces for runtime error-detection:

tqi interfaces: a more minimal set of interfaces and patching technique
tql interfaces: a more comprehensive set of interfaces and patching technique

On Windows NT/2000, both interfaces are available, the user can switch back and forth by selecting the appropriate interface type on the Config Page of the Insure++ Control Panel. On Windows NT/2000, it is generally more desirable to use the tql interfaces for the most comprehensive error-detection. However, in unusual circumstances, the patching technique may produce undesired side-effects at runtime. When this occurs, and the problem is not traceable to source code in the users application, try running in tqi mode first. Fix the bugs that are reported in tqi mode, then re-run the application in tql mode.

On Windows 95/98 the tql modes are not available. This is due to limitations fundamental to the Windows 95/98 architecture. Also, the Inuse module and Intermediate Code Instrumentation are not available on Windows 95/98. For maximum use of Insure++ runtime error- detection in tql mode, running on Windows NT/2000 is recommended.

Note: Compile-time bugs reported by Insure++ are not dependent on which interface type is used or which operating system is used.

Command Line

Insure can be run from the command line as well. When using nmake, just have

CPP=insure.exe
LINK32=inslink.exe

Creating an Insure Configuration

When building large projects with Insure++, it is desirable to make an "Insure" configuration of your project. This allows you to switch back and forth between instrumented and non-instrumented versions of your program without recompiling all your source files.

Here is how to make a new configuration:
In Microsoft Developer Studio, select Build->Configurations.

DevStudio will select a default output directory for this configuration. However, change it by selecting Project->Settings.

You can now switch back and forth between the "Debug" and "Insure" configurations without rebuilding your project.

Precompiled Headers

Insure++ supports the use of precompiled headers. However, here are some subtleties to be aware of.

In a project WITHOUT precompiled headers, if all the object files are up to date and non-instrumented, a single file can be instrumented, then the project can be relinked using insure++ build. However, if precompiled headers are used, and all the object files are up to date but non-instrumented, then instrumenting a single file will cause the precompiled header to be instrumented. This touches the time-stamp on the precompiled header, so all the object files are now out of date with respect to the precompiled header. When an insure++ build is done, a full rebuild will be triggered.

One solution to this is to create an Insure Configuration (See "Creating an Insure Configuration") that uses precompiled headers. Another solution is to not use precompiled headers. The recommended solution is to have an Insure Configuration and to disable precompiled headers for the Insure Configuration. (This solution is not possible in some MFC AppWizard generated projects, which are designed to only be built with pre-compiled headers.)

Running Your Program

For run-time error detection on both instrumented and non-instrumented programs, always run with InsureSpy. Pick one of the following ways.

From within DevStudio, select Insure++ Execute, which is the blue "!" button on the Insure++ toolbar.
From within DevStudio, select "Go" or press "F5" to run through the debugger. If the executable is instrumented with Insure++, an integrated version of InsureSpy will automatically be invoked in the Microsoft Debugger. To use the integrated InsureSpy with a non-instrumented program this way, simply select "Automatic InsureSpy Integrated Debugging" from the "General" tab of the InsurePanel.
From Insra, select: File -> Run.
Browse for the executable and it will be run with InsureSpy. The messages will automatically be sent to Insra.
From the command line, the "bin.Win32" directory of your Insure++ installation will need to be on your PATH. Then type:
```
	insurespy foo
```
This will run foo.exe with insurespy. This version uses Message Boxes. A text-only version is called inject. It is run like this:
```
	inject foo
```

Note: To perform runtime error detection on Windows 95, programs must be built with Insure++. For the most thorough error detection for both instrumented and non-instrumented programs, build and run on Windows NT/2000.

COM objects, Services, and Child Processes

Some applications must be invoked in atypical ways. For example, Services may be executed by the service control manager. ActiveX controls may be loaded into other executables spawned automatically. Child processes may be executed by calls to CreateProcess from parent processes.

In these cases, the "Image File Execution" can be used on Windows NT/2000 to run the program through insurespy. In the Insure++ Control Panel, on the Advanced Page, enter your executable name (without a path) under "Image File Execution Options: Executable". Select InsureSpy.exe for the debugger. If you wish to use InsureSpy integrated in the Microsoft debugger, select msdev.exe instead of InsureSpy.

Note: This mechanism is provided by the Windows NT/2000 operating system. The window into this mechanism provided in the Insure++ Control panel is for your convenience. If you prefer, you can alter the registry keys directly:

When you are done debugging the executable with Insure++, be sure to remove the executable name from the list, or InsureSpy.exe will be invoked every time that executable runs.

When debugging a Windows Service with Insure++, allow the service to interact with the desktop. This is a checkbox for service option in the service control manager. Also, because the Windows service will be running as a system process, you must have [Insure++_Install_Dir]/bin.Win32 on your system PATH environment variable. It is not sufficient to have it on your user PATH environment variable.

Tip: The Image File Executions options can have strange behavior when invoked on executables with spaces in the path names. For less headaches, use directory names that do not contain spaces for executables that are debugged with this mechanism.

See also [Insure++ Install dir]/examples/service_demo.txt for an example of running Insure++ on an Windows Service application.

Using TCA (Total Coverage Analysis)

After running your instrumented program, a file called tca.log is created in the directory from where the program is run. This file keeps track of coverage information.

To read this file from our TCA GUI, choose "TcaView" under the startup menu, then open the tca.log file located in the directory where you ran your program.

To read this file from the command line, type:

To get a list of command line tca options, just type:

Using Inuse (Runs on Windows NT/2000 only)

To use Inuse to see a graphic display of how your program uses dynamic memory, compile your program without insure. Then click on:

Start -> Programs -> Insure++ -> Inuse

The Inuse GUI will appear. From the GUI, click on:

File -> Run

Then browse for the executable that you built with Visual C++. At this point you should be able to view your program's memory from within Inuse.

Windows CE Development

Insure++ now supports the Windows CE Development on Windows NT/2000. To use this feature, build your project with insure on a configuration that is targeted for the Windows CE emulator. (Remote debugging Windows CE devices is not currently supported.) Run the application under InsureSpy using the "Insure Execute" button or by using the Microsoft debugger, automatically invoking the integrated version of InsureSpy.

Before running your Windows CE project under InsureSpy, disable "leak search" and "leak sweep" on the Config Page of the Insure++ Control Panel. Running with "leak search" and "leak sweep" on may cause access violations under the Windows CE emulator.

When using the TCA tool on Windows CE projects, the tca.log file will be stored in the same directory as the running executable, which will be the emulation directory.
Example: C:\Program Files\Windows CE Platform SDK\wce\emul\hpc\tca.log

Obtaining and Installing a Product License

Click on:

Start -> Programs -> Insure++ -> InsurePanel -> Password This will display, among other things, your Machine Id.

To obtain a permanent product license, provide the Machine Id to your Parasoft Account Representative or the Parasoft Sales Department at:

phone: (888) 305-0041 or, send the Machine Id in an email message to:

license@parasoft.com

Contacting Technical Support

To report problems with or suggestions for Insure++, contact ParaSoft Technical Support at:

Contacting ParaSoft

USA Headquarters
2031 South Myrtle Ave
Monrovia, CA 91061
Phone: (888) 305-0041
Fax: (626) 305-9048
Email: info@parasoft.com
Web Site: http: //www.parasoft.com

ParaSoft France
Tel: +33 (0) 1 60 79 51 51
Fax: +33 (0) 1 60 79 51 50
Email: info@parasoft-fr.com

ParaSoft Germany
Tel: +49 (0) 78 05 95 69 60
Fax: +49 (0) 78 05 95 69 19
Email: info@parasoft-de.com

ParaSoft UK
Tel: +44 171 288 66 00
Fax: +44 171 288 66 02
Email: info@parasoft-uk.com