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.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

Warning Processors: Input and Output

Warning processors read XML input from stdin and write XML or HTML output to stdout. This section describes the formats and semantics of these inputs and outputs.

Overview

The following table summarizes the input and output for the various warning processor commands.

Command Input on stdin Output on stdout
install none Optional.
Any output produced on stdout will be interpreted as a display script.
begin
retry		 An XML <post> element.
(XML input: automatic, interactive)		 Optional.
An XML <changes> element, representing changes to be applied to the user-editable fields of the processed warnings. (XML output: automatic, interactive)
Interactive application only: may instead emit an HTML document, representing form fields to be used for collecting additional information.
commit
rollback
abort
analysis_transition		 none not permitted

Automatic Application

Automatically-applied warning processors read XML input from stdin and write XML output to stdout, as shown in the following diagram.

diagram: warning processor input and output in auomatic mode

XML Input: Automatic Application

The schema for XML input to automatically-applied warning processors is shown below.

<!-- 'post' is top-level element -->
<post
  hubaddr="host:port"          
  warning_count="num_warnings"     <!-- always 1 for automatic application -->  
  interactive="is_interactive"     <!-- 0 for automatic application -->
  
    <env> see env definition </env>

    <warnings>
        <!-- In automatic application there is exactly one 'warning' element.  --> 
        <warning ...> see warning definition </warning>
    </warnings>
</post>

XML Output: Automatic Application

The schema for XML output from automatically-applied warning processors is shown below.

<!-- 'changes' is top-level element -->
<changes>
    <change> see change definition </change>
    [<change> ... </change>]
<changes>

Interactive Application

Interactively-applied warning processors read XML input from stdin and write either XML or HTML output to stdout, as shown in the following diagram.

diagram: warning processor input and output in interactive mode

How Interactive Application Works

Interactively-applied warning processorscan obtain additional information by outputting HTML form fields to be presented to the user and submitted back to the hub. The process works as follows.

  1. The warning processor takes XML input I, performs processing, and writes HTML output to stdout.
  2. The hub creates a <form> element containing this HTML and presents the form to the user in the Web GUI.
  3. The user fills out and submits the form.
  4. The hub generates new XML input Inew, where:
  5. The warning processor is run in a new transaction with input Inew.

XML formdata and userdata

The XML <formdata> and <userdata> elements allow additional information to be stored and used by interactively-applied warning processors.

<formdata> Used to pass the processor information submitted by an HTML form. This allows processors to obtain user input interactively.

Included in XML input: if and only if the processor transaction was triggered by submitting the form arising from a previous transaction's HTML output.

XML sub-elements: correspond to the fields of the HTML form. The sub-element names correspond to the name/id attributes of the form fields; the value of each sub-element is the string value submitted in the corresponding field.
<userdata> Allows the warning processor to preserve information across multiple interactive invocations from the same user session on the hub.

Included in XML input: for all interactively-applied processors.

XML sub-elements: correspond to the values currently stored for the user's hub session. Initially there are no values stored. Thereafter, elements are added/updated whenever the XML output includes a non-empty <userdata> element. There can be an arbitrary number of sub-elements, with arbitrary names and string values.

XML Input: Interactive Application

The XML input for interactive application has several important differences from the input for automatic application.

<!-- 'post' is top-level element -->
<post
  hub_addr="host:port"             <!-- required -->      
  user_name="invoking_user_name"   <!-- only specified if interactive=1 -->        
  user_email="invoking_user_email" <!-- only specified if interactive=1 -->   
  warning_count="num_warnings"     <!-- required -->      
  interactive="is_interactive"     <!-- required. 1 for interactive application -->
  
    <!-- See the notes on userdata.
    The 'userdata' element can have an arbitrary number of sub-elements, 
    with arbitrary  names and string values. -->        
    <userdata>                  
        <userdata_label1> userdata_value_str1 </userdata_label1>
        ...
        <userdata_labelm> userdata_value_strm </userdata_labelm>
    </userdata>

    <!-- See the notes on formdata.
    The 'formdata' element is present if and only if the current transaction was 
    triggered by submitting an HTML form output by a previous transaction.  -->        
    <formdata>                     
        <formdata_label1> formdata_value1 </formdata_label1>
        ...
        <formdata_labeln> formdata_valuen </formdata_labeln>
    </formdata>

    <env> see env definition </env>

    <warnings>
            <!-- In interactive application there are one or more 'warning' elements.  --> 
        <warning ...> see warning definition </warning>
        [<warning> ... </warning>] 
    </warnings>
</post>

XML Output: Interactive Application

The XML output for interactive application differs from the output for automatic application in that it can include a <userdata> element.

<!-- 'changes' is top-level element -->
<changes>
    <!-- See the notes on userdata. -->
    <userdata> 
        <userdata_label1> userdata_value_str1 </userdata_label1>
        ...
        <userdata_labelm> userdata_value_strm </userdata_labelm>
    </userdata>
        
    <change> see (output) change definition </change>
    [<change> ... </change>]
<changes>

HTML Output: Interactive Application

Interactively-applied warning processors can obtain additional information by outputting HTML form fields to be presented to the user and submitted back to the hub.

The HTML output should:

XML Element Details

The following element definitions are abstracted from the XML input and output descriptions above (Interactive, Automatic).

<!-- === Input definitions === -->

<!-- 'env' specifies the sets of available values from which warning priority, 
     state, finding, and owner are drawn.
     'id' attributes on 'priority', 'state', 'finding', and 'user' elements
     are available if and only if the warning processor's display script 
     includes the following comment: '# CSONAR_WP_CAPABILITY:PROPERTY_IDS' -->
<env>
    <priorities>
        <!-- number of 'priority' elements is unbounded -->
        <!-- EITHER -->  
        <priority> priority_value </priority>
        <!-- OR -->  
        <priority id="priority_id"> priority_value </priority>
        <!-- END EITHER/OR -->  
        [<priority ...> ... </priority>]
    </priorities>

    <states>
        <!-- number of 'state' elements is unbounded -->
        <!-- EITHER -->  
        <state> state_value  </state>
        <!-- OR -->  
        <state id="state_id"> state_value </state>
        <!-- END EITHER/OR -->  
        [<state ...> ... </state>]
    </states>

    <findings>
        <!-- number of 'finding' elements is unbounded -->
        <!-- EITHER -->  
        <finding> finding_value  </finding>
        <!-- OR -->  
        <finding id="finding_id"> finding_value </finding>
        <!-- END EITHER/OR -->  
       [<finding ...> ... </finding>]
    </findings>

    <users>
        <!-- number of 'user' elements is unbounded -->
        <!-- EITHER -->  
        <user> user_value  </user>
        <!-- OR -->  
        <user id="user_id"> user_value </user>
        <!-- END EITHER/OR -->  
        [<user ...> ... </user>]
    </users> 
</env>

<warning
  report_id="warning_group_id"                 <!-- required -->  
  instance_id="warning_instance_id"            <!-- required -->  
  warningclass="warning_class"                 <!-- required -->  
  filename="warning_file"                      <!-- required -->  
  line_number="warning_line"                   <!-- required -->  
  procedure="warning_procedure"
  priority="warning_priority"                  <!-- required -->  
  state="warning_state"                        <!-- required -->  
  finding="warning_finding"                    <!-- required -->  
  owner="warning_owner"
  language="file_language"                     <!-- required -->  
  modified="warning_modified"                  <!-- required -->  
  fingerprint="warning_fingerprint"            <!-- required -->  
  score="warning_score"                        <!-- required -->  
  rank="warning_rank"                          <!-- required -->  
  detected="warning_detected"                  <!-- required -->  
  firstdetected="warning_firstdetected"        <!-- required -->  
  instance_url="warning_report_page_url"
  report_url="group_rep_warning_report_page_url" >

    <project 
      name="project_name"                      <!-- required -->  
      url="project_page_url"                   <!-- required -->  
     />

    <analysis 
      id="analysis_id"                                        <!-- required -->  
      name="analysis_name"                                    <!-- required -->
      analysis_machine="analysis_launchd_machine"             <!-- required -->  
      analysis_install_path="analysis_launchd_installation"   <!-- required -->  
      analysis_address="analysis_launchd_address"             <!-- required -->
      analysis_username="analysis_launchd_system_user_id"     <!-- required -->
      analysis_pretty_username="analysis_launchd_system_user" <!-- required -->  
      url="analysis_page_url"                                 <!-- required -->  
    />

    <listing>
        <!-- EITHER -->  
        <procedure ...> see procedure definition </procedure>
        <!-- OR --> 
        <file ...> see file definition </file> 
        <line ...> see line definition </line> [ <line ...> ... </line>]
        [<file ...> ... </file> <line... > ... </line> ... ]
        <!-- END either/or -->
    </listing>

    <notes>
    <!-- zero or more 'change' elements -->  
        <change ... > see (input) change definition </change>
        [ <change ...> ... </change> ... ]</notes>
</warning>

<!-- procedure definition -->
<procedure>
</procedure>

<!-- file definition -->
<file name="file_name" sfid="file_instance_id" sfhash="file_hash"  />

<!-- line definition -->
<line number="line_num">
    <span
      comment=""     
      grayout=""      
      keyword=""     
      macro=""       
      preprocessor="" 
      linksfid=""     
      linkline=""    
      include=""      
      mclose="" > 
        <content> content_string </content> 

        <expansion expanded="..."> 
            <file> see file definition </file> 
            <line> see line definition </line> 
           [<line> ... </line>] 
        </expansion> 
    </span>
</line>

<!-- Note that the output XML schema also has a 'change' element (jump)-->
<!-- Number of 'property_changes' elements is unbounded. -->
<change 
  user="..."          <!-- required -->
  date="..."          <!-- required -->
  import_user="..."
  import_date="..."
  import_property_conflict="..."
  import_owner_conflict="...">
    <property_changes 
      property="..."  <!-- required -->
      from="..."
      to="..."        <!-- required -->
    >
    </property_changes>
    [ <property_changes ...> </property_changes>]
    <comment> comment_text </comment>
</change>


<!-- === Output definitions === -->

<!-- Note that the input XML schema also has a 'change' element (jump)-->
<change>
    <!-- The 'warnings' sub-element specifies the warnings to which the
    change will be applied. It must contain either a comma-separated list of
    warning group ids, or the word "all". This element is required. -->
    <warnings> warnings_string </warnings>
                
    <!-- The remaining sub-elements specify the new settings for the
    specified warnings. These sub-elements are all optional. -->
    <priority> priority_string </priority>
    <state> state_string </state>
    <finding> finding_string </finding>
    <owner> owner_string </owner>
    <note> note_string </note>
</change>

Other Warning Processor Sections

The following sections contain further information about warning processors.

How Warning Processors Work Describes the components and behavior of a warning processor.
Warning Processors Shipped With CodeSonar Describes the example warning processors and explains how to customize and install them.
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.
 

To report problems with this documentation, please visit https://support.codesecure.com/.