Formula syntax

JReport formula syntax is a syntax with simple flow control and other statements. The Formula Editor is where you write your formula statements. You should follow JReport formula syntax when writing formulas.

In this syntax, sequence and selection control structure are supported. You can use it to control the execution of the statements. In this syntax, a parameter can be used as variable, and its value can be used in computation or making decisions. Since the value of the parameter is input before the report is run, the report can respond to user input and generate different results.

Statements

The statement is the smallest executable unit in the syntax. A SQL procedure is a sequence of statements. Statements are separated by semicolon (;). There are many kinds of statements, such as declare statement, expression statement, assignment statement, if-else statement, and return statement.

Declare statement

The declare statement is used to declare variables.

Syntax: VariableType VariableName;
Example: String sql;

This statement declares a local String type variable called sql.
Syntax: global VariableType VariableName;
Example: global integer i;

This statement declares a global Integer type variable called i.

Expression statement

The expression statement is used to calculate the value of an expression.

Assignment statement

The assignment statement is used to calculate the expression on the right side of assignment operator and assign the value to the variable on the left side.

Syntax: Variable = Expression

The type of value of expression must be compatible with the type of the variable.

Example: total = amount * price

In this example, where the total, amount and price are declared variable. The statement calculate the "amount * price" and assign the value to "total".

If - else statement

The if-else statement provides conditional control of an action. Normally, the statements are executed one by one sequentially. The if-else statement enables alternative actions that depend on the evaluation result of the expression.

Syntax:

if (expression) { statement(s);} or if (expression) { statement(s);} else { statement(s);}

Where, the expression must be a logical expression and have a Boolean value. The if clause checks the condition presented by the logical expression. If the condition is true, the statement following the if will be executed. Otherwise, the statement following the else will be executed.

Example:

If (score >= 60) { return "PASS";} else { return "FAIL";}

In this example, if the score is greater than or equal to 60, the result is pass, otherwise the result is fail.

Return statement

The return statement is used to stop the execution of procedure and return a value if necessary. The return statement is the last statement executed.

Syntax: return or return expression;

The expression will be calculated before the procedure returns.

Example: return results;

For statement

The for statement provides a compact way to iterate over a range of values.

Syntax:

for (initialization; termination; increment) { statement; };

for (initialization; termination; increment) statement;

The initialization is an expression that initializes the loop - it's executed once at the beginning of the loop. The termination expression determines when to terminate the loop. This expression is evaluated at the top of each iteration of the loop. When the expression evaluates to false, the loop terminates. Finally, increment is an expression that gets invoked after each iteration through the loop. All these components are optional.

Examples:

integer i=0, j=0;
For(i=0;i<100;i=i+1){ 
    j=j+1;
};
return j;

integer i=0, j=0;
For(i=0;i<100;i=i+1) j=j+1;
return j;

Both examples will return 100 as the result.

integer siteint=0; 
string stite="&_isMultiple_jrs.param$Site=true"; 

if(@P_int==0) then 
    stite=stite+"&jrs.param$Site=%07" 
else {
    for(siteint=0;siteint<@P_int;siteint=siteint+1) 
    stite= stite+"&jrs.param$Site=" + @P_int 
}; 
return stite;

While statement

The while statement is used to continually execute a block of statements while a condition remains true.

Syntax:

while (expression) do { statement; };

while(expression) do statement;

First, the while statement evaluates expression, which must return a Boolean value. If the expression returns true, then the while statement executes the statement(s) associated with it. The while statement continues testing the expression and executing its block until the expression returns false.

Example:

integer i=0; 
While(i<100) do { 
    i=i+1; 
}; 
return i; 
 
Or
integer i=0; 
While(i<100) do i=i+1; 
return i;

Both examples will return 100 as the result.

Note: JReport Designer provides another statement that is similar to the while statement - the do-while statement.

syntax:

do { statement(s); } while (expression);

do statement while(expression);

Instead of evaluating the expression at the top of the loop, do-while evaluates the expression at the bottom. Thus the statements associated with a do-while are executed at least once.

Example:

integer j=0; 
Do { 
    j=j+1;} 
while(j<100); 
return j; 

Or
integer j=0; 
Do j=j+1 while(j<100); 
return j;

Both examples will return 100 as the result.

Select statement

The select statement is usually used in the case that the value of a single variable may determine one of a number of different choices.

A select statement is given a variable and compares its value to all cases in the switch; if there is a case that matches the value, all statements in the matching case are executed. If none match, and a default is given, all statements following the default keyword are executed.

Syntax:

select (variable name){ case expression_1: statement case expression_2: statement ... default: statement };

The expression_1 and expression_2 should be variables or constants. The statement in each should be a single statement or multi-statement (compound statement). When multi-statement is used, they must be enclosed by {}.

Notes:

The value of the select is only evaluated one time even when a case modifies the tested value.
No break statement is required, the logic flow does not continue through the following case statements.

Examples:

integer i = 0 ; string j = 'a'; 
i = @"Customers_Customer ID";
select(i) {
    case 1: j='bb' 
    case 2: j='cc'
    default: j ='dd'
};
return j;

string state="",result="";

if (IsNull(@Customer_State)) then
    state="Others"  
else 
    state = @Customer_State; 

select (state) {
    case  "BC","ID","MT","WA":result="Northwest" 
    case  "CA","AZ","TX","NM":result="Southwest" 
    case  "ME","MA","NH","NY":result="Northeast" 
    case  "FL","NC","GA","SC":result="Southeast" 
    default: result="Rest of Country" 
}; 
return result;

Expression

The expression is a combination of values, operators and functions that produce a result. The value in the expression can be a literal value or a variable, while the operator defines the operation between values; the function is used to perform an action and return a value.

Value

The value specified in an expression can be a literal value or a variable value. JReport formula syntax supports seven data types of value. See the section Data type for details.

Literal value

The Literal Value is a value that is used exactly as it is displayed. A literal value represents a value such as a Number, String, or Date. For example, "Name", 98.6...

Variables

A variable is a named storage unit used to store a value. The identifier (name) of variable can be used to refer to the value of the variable or refer to the storage space of the variable. In an expression, the identifier is used to refer to the value, and in assignment statement, the identifier on the left is used to refer to the storage space.

Undeclared variables
The undeclared variables include parameter, DBField, special field and summary defined in the catalog. They can be used as a variable in a formula.
Declared variables
Another type of variable which must be declared in a declare statement before use. The declared variable is a real variable and can be assigned in the assignment statement. There are two kinds of declared variables:
- Local Variable: Variable which is only valid in the formula where it is declared.
- Global Variable: Variable which is valid in all the formulas once it is declared.

Report level global variable

To control the formula more flexibly, JReport offers you one more global variable scope to operate besides component level global variable. That is report level global variable. You can use "report" as the keyword to define the global variable in a formula.

For the two levels of global variable, the following definitions will help you distinguish them:

Component level: Its lifetime is the same as the component's lifetime. In its lifetime, whenever a formula is executed, the variable will be executed if it is used in the formula.
Report level: Its lifetime is the same as the report's (primary report) lifetime. Even in different components (using same data source), the same report level global variable will have only one instance. The report level variable can be passed to different components (using same data source). The components include banded objects, tables, charts, tabulars, crosstabs, and subreports (including many layers of subreports).

When using the keyword "global" to define a global variable in a formula, if you add no words before the keyword, the global variable is on the component level; if you add "report" before the keyword, the global variable will be a report level global variable.

Example

This example uses the report global variable to do a calculation in the report. First, create three formulas based on the report global variable as follows:

Formula1: report global number a =0;

Formula2: a = a+1;

Formula3: return a;

Then use them in one report including two BandedObjects(BandedObject1 and BandedObject2) in the same dataset as follows:

Insert Formula1, Formula2, Formula3 to the BandedObject1(15 records) as follows:
BandedHeader:Formula1

DetailPanel:Formula2

BandedFooter:Formula3 - returns 15.
Then insert Formula2 and Formula3 to the BandedObject2(25 records) as follows:
DetailPanel:Formula2

BandedFooter:Formula3 - returns 40.

Notes:

For nested data containers, report level global formulas may lead to an unexpected result where the formula is not calculated until the end of the group or report. If you add PageNumber in the formula's definition, the calculation will be in sequential order as viewed in the template and the generated result will be the one expected. For more information, see Formula levels.
Although one report can have two or more data sources, report level global variable cannot span across data sources, otherwise the formula will not run correctly, thus, even the report global variables with the same variable name in different data sources are different in one report.
If there is a report level global variable report global integer g, and it is used both in the primary report and subreport, then this variable g can communicate with each other.
If you want to calculate the record number of the subreport and primary report separately, you can define a different report level variable from the primary report, but if one subreport is inserted into one primary report more than once you will be unable to correctly use the variable separately, in such circumstance, you can change the report level variable into component level variable to solve the problem.

Operator

An operator is a symbol that indicates an operation to be performed on values. The JReport procedure language has several classes of operators, including math, comparison and logical operators. For detailed information about operator, see the section Operators in this chapter.

Function

Functions return a value as its result. JReport formula syntax provides many built-in functions. You can refer to the section Built-in functions for detailed information about function.