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 bugs 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.

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 by running the insra.exe file located in the <INSURE_INSTALL>/bin directory.

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.