CalculateFields

Performs numeric calculations on fields and evaluates the result.

Syntax

bool CalculateFields (string Equation, string DecimalDigits, string PreserveStatus)

Parameters

Equation: Type: String; The equation that is the basis for the calculation. You can use a Field object's name or numeric values with any arithmetic operator (+,-,*,/,^). To use a Field object's name, surround the field name with single quotation marks ('). An empty value is treated as a "0".

DecimalDigits: Type: String; The number of decimal places to limit the logical comparison. If left blank, or invalid, the number will default to the value for the current locale.

PreserveStatus: Type: String; Can be True or False to indicate if he status of all associated fields if the calculation fails should be updated based on success or failure of the operation. If not provided, or invalid, the value will default to False.

Smart parameters are supported for all parameters.

Returns

True if the expression evaluates to True.
False if the expression evaluates to False or the expression is not valid (For example, a field's value is not numeric).

Level

Page or Field level.

Details

Calculates the equation entered as a parameter. The equation can contain field names which will use the field's value at runtime. The equation can contain mathematical operations +, -, *, and /. A single equality can also be performed such as =, ˂, =˂, =>, >, and ˂>.

If the equation contains a Boolean equality, the action will determine if the equation evaluates to true or false If the result is false, then status of the fields will be set to "1", allowing them to be reviewed by a following task such as a verification operator. The equation should be specified so that two sides of the equation can be evaluated to determine if the entire equation is correct.

Note: If the result does not match the equation's result, dependent fields (fields involved in the equation) will receive a Failed status and will appear pink in the applicable field of the Client's Verification panel.

If the results of a previously failed CalculateFields call are corrected by a user, such that the calculation no longer returns false, dependant fields that were set to status Failed by the CalculateFields action will be updated to status Pass. It is likely that dependent fields could have their statuses updated through other rules and actions. So it is important when configuring your application to properly stage, and sequence your validations action logic to work in tandem with the CalculateFields action.

It is important to note that smart parameters are supported for all parameters. Smart parameters use special characters such as "+". To use a "+" in an equation, it is necessary to specify the text so it is not interpreted as a special character. This can be achieved using the @STRING or @CHR smart parameters as shown in the example.

If the equality calculation equation is successful, the action returns true. If the equation is not satisfied, the action returns false and also sets a corresponding error message in the standard Message variable that is used by clients to display in verification panels when a rule check fails. The message is set on the DCO that is calling this action, so it is typically useful to call this action on the DCO object that is being checked so the message is associated with the same object. Typically this would be called on a field object which needs to pass this validation test.

If the specified equation does not contain an equality operation, then the resulting value will be calculated and stored in the text value of the current field object. If called on a page level object, then the calculated value will be stored in a DCO variable called CalculateField and the action will return true.

Example 1

CalculateFields("@STRING('SubTotal' + 'Shipping' + 'Tax' = 'Total')", "2", "False")

This example sums the "SubTotal", "Shipping" and "Tax" fields and checks to see if the total of the three fields equals the value in the "Total" field. If they are not the same, then the status will be changed to "1" for each of the fields.

The above example places the entire expression into the "@STRING" smart parameter keyword to prevent any pre-processing of the expression, particularly the + signs within the expression, which would otherwise be first interpreted as smart parameter operators, changing the evaluated expression.

Example 2

CalculateFields("('SubTotal' +@CHR(43)+ 'Shipping' +@CHR(43)+ 'Tax') - '0.05' = 'Total'", "2", "False")

This example is similar to the above example, but also includes a hard coded value within the equation. The smart parameter @CHR(43) evaluates to a plus sign. Because the parameter is supports smart parameters, the + will be interpreted as a smart parameter and change the input string. This technique will resolve to a + in the final equation like this: ('SubTotal' + 'Shipping' + 'Tax') - '0.05' = 'Total'.

The above example takes an alternate approach by using @CHR(43) to insert the + sign into the expression.

To check for a 'tolerance' use two actions in sequence like this:

CalculateFields("@STRING(('Wages' + 'Interest' + 'Unemployment') > =('Gross'- '.05'))", "2", "False") 
CalculateFields("@STRING(('Wages' + 'Interest' + 'Unemployment') < =('Gross'+ '.05'))", "2", "False")

The example will calculate fields twice and allow the range of values. If both tests pass, then they will both return True. If either test fails, the action will return false and set the status of the field to "1" indicating there is a problem with the field.

Example 3

CalculateFields("'SubTotal' +@CHR(43)+ 'Shipping' +@CHR(43)+ 'Tax')", "0", "False")

This example will sum the values of the "SubTotal", "Shipping" and "Tax" fields and stores the result in the text value of the current field, or if called on a page object, the value will be stored in a variable called "CalculateFields". This calculated value can be accessed by subsequent actions.

CalculateFields("'SubTotal' * '2')", "0", "False")

This example finds the value of the SubTotal field and multiplies it by 2 and stores the result.

Some numeric operators used for field calculations are also used as smart parameter tokens. When a parameter allows smart parameters, the parameter will always be processed for smart parameter tokens first. The @STRING() token is a common way to pass these values without interpretation. If an action is not processing correctly, it is likely due to a numeric symbol being processed as a smart parameter. Check the action log to see if the evaluation statement is built as expected and adjust the action parameters as required.