Insra is a Graphical User Interface (GUI) for displaying error messages generated by Insure++. The messages are summarized in a convenient display, which allows you to quickly navigate through the list of bug reports and violation messages, suppress messages, invoke an editor for immediate corrections to the source code, and delete messages as buegs are fixed. In this section:

The Insra GUI

Menu Bar

The menu bar contains options for manipulating files, messages, and finding online help regarding the Insra GUI.

File

• Choose Load... to open a file for inspection through Insure++.
• Choose Save to save the currently open file.
• Choose Save as to save a file under a new name and location.
• Choose Save ASCII to save a file in ASCII (text) format  
• Choose Save As ASCII to save a file in ASCII (text) format under a new file name and location.
• Choose Run to choose and run an executable file.
• Choose Exit to leave the Insra GUI.

Messages

• Choose Prev or Next to navigate the messages.
• Choose Delete to remove a message from the list.
• Choose Clear All to clear all messages from the list.
• Choose Sort to sort among the messages in the list.
• Choose Suppress to suppress selected messages in the list.
• Choose Debug to activate the Visual Studio window and start debugging the process within it to the point of execution where an error has occurred (Windows only).

Help

• Choose Overview: About Insra to access online help about the Insra GUI.
• Choose Documentation to access the Insure++ online documentation.
• Choose Insra Toolbar to access online help about the Insra GUI toolbar.
• Choose Sending Messages to Insra to access online help about sending messages to Insra.
• Choose Suppressing Messages to access online help about suppressing messages in Insra.
• Choose Viewing Source Files to access online help about viewing source files from the Insra.
• Choose Troubleshooting to access online help about troubleshooting tips for the Insra GUI.
• Choose About to display your version of Insra, as well as Parasoft contact information.

Toolbar

The toolbar contains options for viewing, navigating through, and suppressing messages.

• Click Previous and Next to scroll through messages.
• Click Delete to remove selected messages as you fix bugs.
• Click Suppress to suppress the errors detected by Insure++.
• Click Sort messages by order (time) reported, error category, or directory and file.
• Click Stop to stop the selected active connection.
• Click Docs to open the online documentation.

Message Header Area

The message header area contains session headers and message headers for programs currently connected to Insra, as shown in the following graphic:

Session Header

When the first error is detected for a particular compilation or execution, a session header is sent to Insra. The session header includes the following information:

• Compilation/execution
• Source file/program
• Host on which the process is running
• Process ID

Message Header

There are several types of message headers. Messages generated by Insure++ include:

• Error Category. For example: LEAK_SCOPE.
• File name
• Line number

Message headers will also appear for various summary reports generated by Insure++. These reports are generated using options in the Reports tab of the Insure++ Control Panel. See Report Summaries for more information. Double-clicking on a message header will open up the message window for the error or summary report selected.

Status Bar

During compilation/runtime, Insure++ makes a connection to Insra each time an error is detected. The status bar reports the number of error messages currently displayed and the number of active connections. An active connection is denoted by a yellow star to the left of the session header. A connection remains active as long as the program is compiling/running. Insra will not allow you to delete a session header as long as its connection remains active, and you may not exit Insra until all connections have been closed.

Message Window

The message window opens when you double-click on a message header. This window contains the error message or summary report for the selected message header, as shown in the following graphic:

Message Window Toolbar

The following buttons are available in this window:

• Click Previous and Next to scroll through the main Insra window, keeping the message window populated.
• Click Documentation to open the online documentation using your default browser. 

Error Messages

Insure++ error messages include:

• Line of source code where the error occurred.
• Explanation of the error detected.
• Stack traces for quick reference to the original source.

The stack traces are “live” and can be clicked once to launch an editor for viewing and correcting the indicated line of code. For more information, see Viewing Source Files.

All messages sent to Insra are marked with a special icon. Refer to the following table for a brief description of each icon.

Sending Messages to Insra (Windows)

By default, all Insure++ compile-time and runtime messages are sent to Insra. Each time an error is detected, Insure++ attempts to establish a connection to Insra. If Insra is not yet running, it will automatically start. Once the connection is established, a session header and all corresponding message headers will be reported in the order they were detected. Each new compilation or program, with its own session header and messages, will be displayed in the order in which it connected to Insra.

Sending Messages to Insra (Unix)

By default, all Insure++ output is sent to stderr. Add the following line to your .prsc file to redirect messages to Insra:

insure++.report_file insra

This will redirect both compile-time and run-time messages to Insra.

The following option will only send runtime messages to Insra, but compile-time messages will continue to be sent to stderr:

insure++.runtime.report_file insra  

The following option will only send compile-time messages to Insra, but runtime messages will continue to be sent to stderr:

insure++.compile.report_file insra  

Add the following option  With insure++.report_file insra in your .psrc file, each time an error is detected, Insure++ attempts to establish a connection to Insra. If Insra is not yet running, it will automatically start. Once the connection is established, a session header and all corresponding message headers will be reported in the order they were detected. Each new compilation or program, with its own session header and messages, will be displayed in the order in which it connected to Insra.

Viewing and Navigating

Message headers sent to Insra are denoted by a specific icon (see Error Messages). The body of the currently selected message is displayed in a separate message window. Double-click the message header to view the message itself. The message header area and the message window are both resizable, and scroll bars are also available to access text that is not visible. Currently active messages become inactive when they are deleted or suppressed.

Selecting an Editor

In addition to the location of the source file, Insra must also know the name of your editor and the command line syntax in order to display the correct file and line from the original source code.

Windows

Insra obtains this information by reading the Advanced Option value:

visual [editor_command]

This value may contain the special tokens %f and %l, which represent the file name and line number, respectively.

You can also specify your preferred editor by selecting the appropriate option in the Reports tab of the Insure++ Control Panel.

Unix 

Insra obtains this information by reading the .psrc option value: 

insra.visual [editor_command]

This value may contain the special tokens %f and %l, which represent the file name and line number, respectively.

The command will then be executed to load the file into your editor. It is most important to include the full path of any binary that lives in a location not pointed to by your PATH environment variable. If the variable has not been set, vi will be used by default.

Some editors are not X applications and must be run in a terminal window. vi requires the following command in order to lead the file successfully:

insra.visual xterm -e vi +%l %f

Other editors (for example, Emacs) do not require an external terminal program, such as xterm, when configured for use as an X application. In this case, the command string should be similar to the following:

insra.visual emacs +%l %f

Most implementations of vi and Emacs appear to be sensitive to the order of the line number and file name command line arguments, requiring the line number to precede the file name.

Deleting Messages

Once error messages have been read and analyzed, the user may wish to clear them from the window. The Delete button on the Insra toolbar allows you to remove error messages from the display as errors are corrected in your code. A message or an entire session may be removed from the display by selecting an entry in the message header area and clicking the Delete button. A message can also be deleted by selecting Messages> Delete from the menu bar.

Suppressing Messages

You can suppress (turn off) error messages that you do not want Insure++ to generate.

Windows

You can access suppress error messages from the Suppressions Control Panel. This panel is accessible from the Reports tab of the Insure++ Control Panel. You can also click Suppress in the Insra toolbar when Insra contains messages. Both methods prevent future messages of the suppressed error category from displaying, but messages already displayed will not be deleted.  Also see Suppressing Error Messages.

Unix

The Suppressions window allows you to insert, modify, and delete suppression options for Insure++ error messages. Click Suppress in the Insra toolbar to open the Suppressions Window. The window toolbar contains the following options:

• Click the Previous and Next arrows to choose suppression options.
• Click the Up and Down arrows to move the currently selected suppression option up or down in the order of options. Because Insure++ follows suppression options from top to bottom, the order in which they are listed affects the outcome of the suppression (see Working with Insure++ Reports).
• Click Delete to delete the currently selected suppression option.
• Click Insert to insert a new suppression option below the currently selected option. If you had an error message selected when you pressed the Suppress button on the Insra GUI, a suppression option for that particular error message will be inserted. Otherwise, the default suppression option (suppress all error messages) will be inserted. 
• Click Save to writes all the suppression options that have been marked as persistent into the specified .psrc files (see below). Saved suppression options will take effect the next time you use Insure++.
• Click Help to open the online documentation.
• Click Close to close the suppression window.

Editing Suppression Options (Unix)

An individual suppression option consists of the following parts:

• Suppress/Unsuppress: This field specifies whether the error message listed is to be suppressed (as indicated by a speaker with an X through it) or unsuppressed (indicated by a speaker with no X through it). Double-clicking on the field toggles between suppressing and unsuppressing the error message.
• Persistence: This field specifies whether the suppression option will be saved to the .psrc file under which it is listed. Double-clicking this field toggles it from persistent (the field is checked) to temporary (the field is disabled). Options marked as persistent will be added to the appropriate .psrc files when the save button is clicked. Options marked as temporary will be discarded. Options with an X in this field cannot be made persistent, either because they are hardwired or because the file in which it is placed is not writable. New options are marked as persistent by default.
• Item: Double-clicking this field allows you to type in the name of the error message you would like to suppress or unsuppress. You can use a wildcard (*) to match all error messages and also suppress and unsuppress by error category and context. 
• File: Double-clicking this field allows you to type in the file for which you would like to suppress or unsuppress messages. Entering a blank field will insert a * which will match all files.
• Note: You may use this field to enter your own notes regarding the suppression option listed.

Configuration (.psrc) Files

The headers in the window show the various locations in which .psrc files reside. Insra will display the suppression options as read from each file under the appropriate header. When you add a new option using the Insert button, it will be inserted below the currently selected option. You can then move it into the file in which you would like it saved or mark it as temporary by double-clicking the persistence field.

There are two special locations where suppression options may reside other than actual .psrc files: hardwired options and command line options. Hardwired options are set internally by Insure++ and cannot be permanently changed. They can be edited and/or removed in the window temporarily, however. 

Command line options are passed using the -Zop and -Zoi options on the Insure++ command line. These options, like hardwired options, cannot be made persistent, but can be moved into a .psrc file if you decide that you want to make them permanent. See Configuration Options (psrc) for additional information.

The Kill Process

When an active connection is selected, pressing the Kill button will stop the selected compilation or execution.

Viewing Sources

You can view the corresponding source file and line number for a particular error message by double clicking any line of the stack trace displayed in the message window. In most cases, the file and line number associated with a given message have been transmitted to Insra. If Insra is unable to locate the source file, a dialog box will appear requesting that you indicate the correct source file.

Saving and Loading Messages to a File

All current messages can be saved to a file by choosing File> Save or File> Save As from the menu bar. A dialog box allows you to select the destination directory and name of the report file. Report files have the default extension .rpt. After a report file name has been selected, subsequent File> Save selections save all current messages into the report file without prompting for a new filename. You can load a previously saved report file by selecting File> Load from the menu bar. 

Insra Settings Preferences (Unix)

You can modify Insra's appearance with .psrc configuration options:

insra.body_background_color [White|color]

Specifies the color used for the message body area background. The default is white.

insra.body_font [Fixed|font]

Specifies the font used for the message body text. The default is fixed.

insra.body_height [number of rows]

Specifies the starting height of the message window in number of rows of visible text. The default is 8.

insra.body_text_color [Black|color]

Specifies the color used for the message body text. The default is black.

insra.body_width [columns of text]

Specifies the starting width of the message window in number of columns of visible text. The default is 80, but if this value is set to a different value than header_width, then the larger value will be used.

insra.browser [firefox|alternative browser]

Specifies the name of the browser to use alog with the Docs button or the Help> Documentation menu item. The default is firefox. The entry for alternate browser can be the name of a browser in your PATH, a symlink, or the full path to another browser. For example, insra.browser opera configures Insra to open help in Opera.

insra.button_style [Round|square]

Specifies the shape of buttons that will be shown on toolbars. The default is round.

insra.coloured_shadows [on|off]

Specifies if round button shadows will be re-colored with the color of the application background. The default is on.

insra.expose_on_message [on|off]

Specifies if the Insra GUI will be placed on top of windows stack if it receives a new message. The default is off. This option works only in by-time view mode.

insra.follow_messages [on|off]

Specifies if the main window messages area will be automatically scrolled to follow arriving messages. The default is off. This option works only in by-time view mode.

insra.header_background_color [White|color]

Specifies the color used for the message header area background. The default color is white.

insra.header_font [Fixed|font]

Specifies the font used for the message header text. The default is fixed.

insra.header_height [number of rows]

Specifies the starting height of the message header in number of rows of visible text. The default is 8.

insra.header_highlight_color [LightSteelBlue2|color]

Specifies the color used to indicate the currently selected message or session header in the message header area. The default is LightSteelBlue2.

insra.header_highlight_text_color [Black|color]

Specifies the color used for the text of the currently selected message of session header in the message header area. The default is black.

insra.header_session_color [LightSkyBlue3|color]

Specifies the color used for session header text. The default is LightSkyBlue3.

insra.header_session_text_color [Black|color]

Specifies the color used for session header text. The default is black.

insra.header_text_color [Black|color]

Specifies the color used for message header text. The default color is black.

insra.header_width [number of columns]

Specifies the starting width of the header area in number of columns of visible text. The default is 80, but if this value is set to a different value than body_width, the larger value will be used.

insra.mark_unique [on|off]

Specifies if messages not duplicated across all connections from the same tool has to be marked by special arrow-like icon. The default is on.

insra.port [port_number]

Specifies which port Insra should use to communicate with Insure++ compiled programs. The default is 3255.

insra.sourcepath [dir_path1 dir_path2 ...]

Specifies directories to be searched by Insra to find source files launching editor or showing source lines.

insra.toolbar [on|off]

Specifies whether Insra's toolbar is displayed. All toolbar commands can be chosen from the menu bar. The default is on.

insra.viewmode [by_error|by_file|by_time|off|tool]

Specifies initial view mode. Allows user to override view mode settings made by tools connecting with Insra.

• by_error - Insra GUI is initially set in view-by-error-category mode
• by_file - Insra GUI is initially set in view-by-file mode
• by_time - Insra GUI is initially set in view-by-time mode
• off - Insra GUI is launched with the default view mode (i.e., by-time mode)
• tool - means that view mode will be set by tool that first connects with the Insra GUI. This is the default setting.

insra.visual [editor command]

Specifies how Insra should call an editor to display the line of source code causing the error. Insra will match the %l token to the line number and the %f token to the file name before executing the command. It is important to include the full path of any binary that lives in a location not on your path. Setting this option with no command string disables source browsing from Insra. The default is xterm -e vi +%l %f.

Troubleshooting

The following sections detail the most common errors encountered when using Insra. If you still encounter trouble after trying one of the following solutions, or if you encounter a different symptom from those listed below, contact the Parasoft Quality Consulting department. See Contacting Parasoft for more information.

Insra Does Not Start Automatically

While compiling or running, your program seems to hang when error output is directed to Insra and Insra is not yet running.

Solution for Windows

Run Insra manually in one of the following ways:

• Click the Insra icon in the Insure++ toolbar.
• Choose the Launch Insra command from the Visual Studio 6 Tools menu or the Tools> Insure++> Insure++ Report Analyzer command in Visual Studio 2003 and higher.

Solution for Unix

1. Run Insra manually by typing insra & at the prompt. 
2. Run or compile your program when the Insra window appears. 

Multiple Insra Users on One Machine (Unix)

Messages are lost when more than one user is attempting to send message reports to Insra.

Solution

Each invocation of Insra requires a unique port number. By default, Insra uses port 3255. If you experience collisions (e.g.,, multiple users on one machine) set the insra.port optionn in your .psrc file to a different port higher than 1024. Ports lower than 1024 are officially reserved for suid-root programs and should not be used with Insra.

Source Browsing is not Working

Insra did not find your source editor on the path if you receive one of the following errors:

***Error while attempting to spawn browser execvp failed!  

Warning: unable to open editor

Solution

Make sure that this application is in a directory that is on your path or that you call it with its complete pathname.