In the report settings, you choose to examine either the upstream (fan-in) assignments that contribute to the value of the variable or the downstream (fan-out) statements that are impacted by the assignments to the variable. Which choice to make depends on what you're trying to accomplish.
The choice you make is indicated in the header file of the report:
The report then lists the results for each variable. Each variable-specific section shows the assignments and statements related directly to that variable. With the report configured to Show Contributing Statements (Fan-in), here is the corresponding section for the global variable gv in the above sample code:
In the section for a variable, the statements involving the variable are organized, first by category of use, then by containing function, then by the usage itself, displayed as the line number and source code snippet of where the actual statement occurs.
In this section for gv, in the Direct Assignments category, is a list of every statement where the value of gv is directly set. At the containing function/location level, you can see that gv is initialized at the file level, and is also directly set in func2. And at the usage statement level, within func2, gv is set at three lines (20, 26 and 28).
For each of these usage statements being reported, any directly related statements in the data flow are displayed.
Consider the direct assignment of gv at line 28, where "gv = ret + x;". Because this report has been configured to show fan-in, the subsection for line 28 is named Contributing Statements and displays upstream dependencies. There are two variables, ret and x, that contribute to value assigned to gv at this line, and the Contributing Statements subsection lists the statements where the values of each of those variables are set.
Here is the section for the same variable when the report is configured to Show Impacted Statements (Fan-out):
While the section for gv has the same organization (category of use > location of use > usage statement), different statements (and correspondingly different categories of use) are reported. In Contributing Statements mode, the report lists all ways the variable is used (right hand-side of assignments, parameter passing, or conditions). For each usage, the Contributing Statements subsection that follows shows where the values come from which are either assignments or parameter passing.
For Impacted Statements mode, the opposite is displayed. The report lists assignments and parameter passing; for each reported usage, an Impacted Statements subsection that follows lists all the ways the variable is used.
The categories are not completely different, there is some overlap between the two modes, but because of the flow direction, certain types are not meaningful.
The file-level Direct Assignment of gv at line 1 provides an example of how the subsection changes depending upon which mode is selected. When Show Impacted Statements is selected, this assignment has an associated subsection. As the usage of gv at line 1 is a simple initialization, there are no Contributing Statements. But because gv is used in the code, the report lists each of the downstream statements where gv is directly used, because these statements are effected by the initialization.
Categories of Use
Comparison to Calculation TreeThe Variable Dependencies report and the Calculation Tree tool are closely related. Both determine and display the calculations that effect the value of the variable. Both offer the choice of analyzing the upstream data flow (Show Contributing Statements) or tracking the downstream flow (Show Impacted Statements). The Variable Table display of the Calculation Tree in particular resembles the Variable Dependencies report.
Because the Calculation Tree focuses on one specific variable in your software, typically at a specific line in the source code, there are a couple of significant ways in which the report and the tool differ.
When the right-click menu in the File Editor is used to invoke the Calculation Tree from a specific line in the source code, all the data flow dependency analysis is done with respect to that specific statement. In contrast, for a given variable, the Variable Dependencies analyzes all possible starting points. It is these starting points that are listed under Usage, and organized by category and function location. The full list of usage entries may itself be valuable in studying a variable. To use the report to study a specific usage, find the statement of interest, and examine the Contributing Statements or Impacted Statements subsection that follows it.
The limited scope of the Calculation Tree focus permits display of the full hierarchy of the data flow for the target statement or variable, transitively tracking assignments across the full chain of variables leading into or out from the target. With the Variable Dependencies report, where all usage statements are reported for all variables, the Contributing Statements or Impacted Statements subsection for each usage statement is necessarily limited to the directly effected statements.
As a result, tracking the data flow transitively across variables can involve examining the sections in Variable Dependencies for related variables. A given related variable can be identified through the source code snippet displayed in the Contributing Statements or Impacted Statements subsection. Moving to the section for that related variable is aided by the report window's symbol-based and string-based search functions.
Even with these aids, this process can be cumbersome if you limit your analysis to using just the Variable Dependencies report. First using the Variable Dependencies report to identify any assignments of interest, and then launching the Calculation Tree to examine such assignments in detail is the quickest and easiest approach to exploring full transitive data flows in your software.