How Warning Processors Work

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.0p0 Hot Tips

CONFIDENTIAL

CodeSecure Inc

How Warning Processors Work

This section describes the components and behavior of a warning processor.

Overview
Warning Processor Transactions
Properties
Required Commands
Other Warning Processor Sections

Overview

Every warning processor must accept the following commands: install, begin, commit, rollback, retry, and abort. Processors that are to be installed in Automatic mode must also accept the analysis_transition command. Command details are provided below.

The life cycle of a warning processor then proceeds as follows.

The user follows the procedure for installing the warning processor on the hub, specifying several properties:
- the warning processor executable E,
- a label for the warning processor,
- the installation mode.
The hub invokes the processor's install command.
E install
If this command produces output on stdout, the output is used as the warning processor's display script.
The hub applies the warning processor when triggered to do so.
There are two application modes, each with its own triggering conditions.
- interactive application: users trigger application interactively.
  All installed warning processors are available for interactive application, regardless of installation mode.
  - From Warning Report: users can trigger processor application to a single warning.
  - With Change Multiple Warnings: users can trigger processor application to an arbitrary set of warnings.
- automatic application: the hub applies the warning processor in response to actions performed by analyses.
  Only warning processors installed in Automatic mode are available for automatic application.
  - When an analysis submits a warning to the hub, the hub applies the warning processor to that warning.
  - When an analysis transitions to a new state, the hub invokes analysis_transition:
    E analysis_transition analysis_id old_state new_state
  If there are multiple Automatic mode warning processors installed on the hub, they are applied simultaneously.
Processor application to a warning or set of warnings takes place in a transaction constructed from begin, commit, rollback, retry, and abort. The processor receives input on stdin and produces output on stdout: for details, see Warning Processors: Input and Output.
The user can uninstall the warning processor at any time. Otherwise, go to step 3.

Diagram: Warning processor installation and application

diagram: warning processor installation and invocation

Warning Processor Transactions

Processor application to a warning or set of warnings takes place in a transaction constructed from begin, commit, rollback, retry, and abort.

The transaction uses the two-phase commit protocol (for details, see Wikipedia: Two-phase commit protocol).

The hub is the coordinator.
Each warning processor session is a cohort, and the hub additionally has its own built in cohorts.

The mapping between warning processor commands and the two-phase commit protocol is shown in the following table.

Warning Processor Command	Two-Phase Commit Protocol Phase
begin / retry	Phase 1. The command return code (process exit code) determines the yes/no vote submitted by the processor session.
commit	Phase 2 (success).
rollback	Phase 2 (failure).
abort	none

diagram: a warning processor transaction

Properties

A warning processor installed on the hub has the following basic properties.

Installation Mode

Each warning processor is installed in one of two modes: Automatic or Interactive. The installation mode controls the set of available application modes:

Installation Mode	Available Application Mode(s)
Interactive	interactive application only
Automatic	both automatic application and interactive application

Display Script

If the install command produces output on stdout, the hub will record this output as the warning processor's display script.

For both automatic application and interactive application, comments in the display script are used to determine whether the XML input to the processor should include id attributes on certain elements.
For interactive application only, the display script is also evaluated (as Python, in a scope described in Authoring Warning Processors: Display Scripts) to determine how to present the processor in the Warning Report page.
Unless specifically overridden by a display script, the warning processor is presented as a checkbox that is labeled with the processor label and is always available.

For implementation guidelines, see Authoring Warning Processors: Display Scripts.

Label

The user specifies a label for each warning processor at installation time. This label is used to identify the processor in the Web GUI.

Executable

The executable that the hub will run when it invokes the warning processor.

A unique numerical identifier for the processor.

Required Commands

Command	Invoked	Requirements and Notes
install	When the processor is installed on the hub.	If the install command writes any output to stdout, the CodeSonar hub will consider this to be the warning processor's display script.
analysis_transition analysis_id old_state new_state	When the analysis transitions to a new state.	Can only be invoked during automatic application (that is, only if the warning processor is installed in Automatic mode).
begin trans_id	Every time the warning processor is applied to a warning or set of warnings.	The hub will write an XML document to stdin; the warning processor should process this, and emit any changes to the warnings as an XML document on stdout. Returns 0 on success and non-0 on failure.
commit trans_id	If the transaction succeeds	The warning processor should use this invocation to perform any necessary bookkeeping tasks. The hub will not write anything to stdin, and the processor should not write anything to stdout.
rollback trans_id	If the transaction fails.	There are a number of reasons that a transaction may fail: some examples are power outage, hub database deadlock, or failure of this or another warning processor. If the transaction fails because because of hub database issues (such as deadlock, or a race condition between two warning processors), no changes are applied to any warnings. The hub will invoke rollback trans_id, then invoke either retry trans_id or abort trans_id, depending on how many times the transaction has already been tried. The warning processor should use this invocation to perform any necessary bookkeeping tasks. The hub will not write anything to stdin, and the processor should not write anything to stdout. Note that if errors occur because of problems such as power loss, there will be no opportunity to apply the rollback command.
retry trans_id	After rollback trans_id, if the transaction hasn't previously failed too many times.	The hub will write an XML document to stdin; the warning processor should process this, and emit any changes to the warnings as an XML document on stdout. Returns 0 on success and non-0 on failure. In many cases retry functionality will be identical to that for begin.
abort trans_id	After rollback trans_id, if the transaction has previously failed too many times.	If the warning processor transaction fails too many times, the transaction will abort. The hub will not write anything to stdin, and the processor should not write anything to stdout.

Other Warning Processor Sections

The following sections contain further information about warning processors.

Warning Processors Shipped With CodeSonar	Describes the example warning processors and explains how to customize and install them.
Warning Processor Input and Output	Describes the formats and semantics of warning processor inputs and outputs.
Authoring Warning Processors	Outlines the requirements for creating a CodeSonar warning processor.
Authoring Python Warning Processors	Explains how to use the csonar_utils Python package to create custom warning processors.
csonar_utils API documentation	Describes the key components of the csonar_utils Python package.