Variables and Totals

A variable is defined once for the whole report, in the <variables> element of the report definition. In the Designer, select Report  Variables…​ and edit the variables in the table of the dialog (columns ID, Expression, Function, Scope, and Init Value).

Invoices, ledgers, and long lists often need three kinds of totals on every page: the total of the current page, the running balance up to the end of the page, and the balance carried over from the previous page at the top of the next page. With the timing rules above, all three need only two variables:

The PageTotalsAndBalanceInProductlist.xml demo report prints the running balance of the value column in the detail, in the page footer, and in the page header. The page_total_example.xml demo does the same in a grouped product list, and prints the grand total in the footer of a constant (%CONST) group. The following example is based on these demos, extended with a page total variable. Geometry and font attributes are omitted.

Suppose the first page holds rows with the values 10, 20, and 30, and the next row (40) does not fit. The report then prints:

The printWhen expression of the brought-forward field hides it on the first page, where there is nothing to bring forward. The same technique works for counts (COUNT) and for group level running totals: a Group scope variable printed in the page header shows the running total of the current group up to the end of the previous page.

A group total is a Group scope variable that is reset by its group. Since the reset happens after the group footer is printed, the footer shows the total of the whole group, and the next group starts from the initial value again. The GroupFunc.ncr demo, for example, sums the col0 column by month:

For nested groups, define one variable for each level, each with the same expression, and let every group reset only its own variable. The groups of a detail are nested in the order in which they are listed: the first group is the outermost one. When an outer group changes, all of the inner groups are closed too, so the inner footers are printed first (and reset their variables), then the outer footer. The group_simple_totals.xml demo uses a constant outer group for the grand total and an inner group for the subtotals:

The resetVariables attribute is a comma-separated list, so one group can reset several variables, for example a sum and a count of the same group (resetVariables="sum_price,count_items"). A variable must not be listed in an outer group only, or the inner footers would show the accumulated value of the outer group.

Other useful patterns:

In special cases, the regular aggregation is not enough: you may want to add an extra amount to a total, subtract a value under a condition, or restart a counter in the middle of a group. For this purpose, the report engine contains a variable modifier (the NCReportVariableModifier class), which changes the current value of a variable directly.

The modification lines are written into the conditional formatting code of a Label or a Field (see Conditional Formatting). A line that starts with $V{ is not a style definition but a variable modification, in the following form:

The available operators are:

The expression on the right side can contain data source, parameter, and variable references, and it is evaluated by the script engine, so it can be a constant, a reference, or a script expression such as $D{price}*$D{qty} or ($D{discount}>0 ? 1 : 0). A COUNT variable is set to the integer part of the result.

The modification is executed when the item is printed: each time the section that contains the item is rendered and the item’s print condition (Print only when expression is true) is true. Therefore the print condition of the item acts as the condition of the modification. The new value is visible for the items rendered after the modifying item in the same section, and for all later sections. The variable’s own aggregation continues from the modified value at the next row.

The Variable-Modify-By-CondFormat-Demo.xml demo report has three Report scope variables. The label in the detail section changes its font weight conditionally, and also adds 2 to the v3 variable in every row:

The v2 and v3 variables sum the same column, but because the label is rendered before the v3 field, the v3 column shows the running sum plus 2 for every row printed so far (in the n-th row, v2 + 2 * n).

Keep the following rules in mind:

System variables are values provided by the report engine itself, such as the page number, the current date, or the name of the application. They are read-only and do not need to be defined. A system variable can be used:

With the $V{} syntax, the name is first looked up among the report’s own variables, so a user variable with the same name hides the system variable. The names are case-sensitive. An unknown name returns the text #VAR#.

The following table lists all of the system variables recognized by the report engine.