Understanding Calculation Scripts

Calculation Scripts


A calculation script contains a series of calculation commands, equations, and
formulas. You use a calculation script to define calculations other than the calculations
that are defined by the database outline.

Calculation scripts are text files. Using Calculation Script Editor, you can create
calculation scripts by:

Typing the contents of the calculation script directly into the text area of the script
editor
Using the user interface features of the script editor to build the script
Creating the script in the text editor of your choice and pasting it into Calculation
Script Editor.

When you save a calculation script, it is given a .csc extension by default. If you run a
calculation script from Essbase Administration Services or from Essbase Spreadsheet
Services, it must have a .csc extension. However, since a calculation script is basically a
text file, you can use MaxL or ESSCMD to run any text file as a calculation script.


Advantages of Calculation Scripts

You need to write a calculation script if you want to do any of the following:

Use the FIX command to calculate a subset of a database.
Change the calculation order of the dense and sparse dimensions in a database.
Perform a complex calculation in a specific order or perform a calculation that requires
multiple iterations through the data. For example, some two-pass calculations require a
calculation script.
Perform a currency conversion.
Calculate member formulas that differ from formulas in the database outline.
Formulas in a calculation script override formulas in the database outline.
Use an API interface to create a custom calculation dynamically.
Use control of flow logic in a calculation; for example, if you want to use the IF
ELSE ENDIF or the LOOP ENDLOOP commands.
Clear or copy data from specific members.
Define temporary variables for use in a database calculation.
Force a recalculation of data blocks after you have changed a formula or an accounts
property on the database outline.
Control how Analytic Services uses the Intelligent Calculation feature when calculating
a database.



Understanding the Rules for Calculation
Script Syntax

End each formula or calculation script command with a semicolon (;), as shown in this
example: CALC DIM(Product, Measures);
Enclose a member name in double quotation marks (" ") if that member name
contains spaces; for example,
"Opening Inventory" = "Ending Inventory" - Sales + Additions;
If you are using an IF statement or an interdependent formula, enclose the formula in
parentheses to associate it with the specified member. For example, the following
formula is associated with the Commission member in the database outline:
Commission
(IF(Sales < 100)
Commission = 0;
ENDIF;)
End each IF statement in a formula with an ENDIF statement. For example, the
previous formula contains a simple IF...ENDIF statement.
If you are using an IF statement that is nested within another IF statement, end each
IF with an ENDIF statement;
You do not need to end ELSE or ELSEIF statements with ENDIF statements;
End each FIX statement with an ENDFIX statement;







Understanding Calculation Commands



Controlling the Flow of Calculations



You can use the following commands to manipulate the flow of calculations.







You can also use the IF and ENDIF commands to specify conditional calculations.



Declaring Data Variables

You can use the following commands to declare temporary variables and, if required,
to set their initial values. Temporary variables store the results of intermediate
calculations.






Values stored in temporary variables exist only while the calculation script is running.
You cannot report on the values of temporary variables.

Variable and array names are character strings that contain any of the following
characters:
Alphabetic letters: a through z
Numerals: 0 through 9
Special characters: $(dollar sign), # (pound sign), and _ (underscore)



Adding Comments


You can include comments to annotate calculation scripts. Analytic Services ignores
these comments when it runs the calculation script.

To include a comment, start the comment with /* and end the comment with */.
Consider the following comment:
/* This is a calculation script comment
that spans two lines.*/

Some Calculation Commands

CALC ALL
CALC AVERAGE
IF
ENDIF
ELSEIF
ELSE
FIX..ENDFIX
LOOP...ENDLOOP
CLEARDATA
UPDATECALC




CALC ALL
CALC ALL
Calculates and aggregates the entire database based on the database outline.

Syntax
CALC ALL [EXCEPT DIM (dimList) | MBR (mbrList)];
where:
EXCEPT Defines an exception list of dimensions or members that are to be excluded
from the calculation.
DIM Single-dimension specification.
dimList Optional comma-delimited list of dimensions.
MBR Single-member specification.
mbrList Optional comma-delimited list of members, member set functions, or range
functions.

Description
This command calculates and aggregates the entire database based on the database
outline. The order in which dimensions are processed depends on the definitions of
the various dimension in the database outline.

Example
CALC ALL; CALC ALL EXCEPT DIM(Product);

CALC AVERAGE

CALC AVERAGE
Calculates all members tagged in the database outline as time balance Average
All other member calculations are ignored during this process.

Syntax
CALC AVERAGE;

Notes
This command calculates the members based on the dimension tagged as accounts
only; it does not do a Time Series calculation on the dimension tagged as time.

Example
CALC AVERAGE;

IF

IF
Performs conditional tests within a formula. Using the IF statement, you can define a
Boolean test, as well as formulas to be calculated if the test returns either a TRUE or
FALSE value.

Syntax
IF( condition ) statement ; [ ELSEIF...statement | ELSE...statement]
ENDIF;
where:
condition Formula or function that returns a Boolean value of TRUE (a nonzero value)
or FALSE (a zero value).
statement Operations to be performed depending on the results of the test.

Example
IF( @ISMBR(@DESCENDANTS(Europe)) OR
@ISMBR(@DESCENDANTS(Asia)) ) Taxes = "Gross Margin" * "Foreign Tax
Rate"; ELSE Taxes = "Gross Margin" * "Domestic Tax Rate"; ENDIF;
This test checks to see if the current cell includes a member that is a descendant of
either the Europe or Asia members. If it does, the formula calculates the taxes for the
member based on the foreign tax rate. If the current cell does not include a member
from one of those groups, then the domestic tax rate is used for the tax calculation.

ENDIF

ENDIF
Marks the end of an IF command sequence. The ENDIF command can be used only
in conjunction with IF or IF ... ELSEIF statements.

Syntax
ENDIF;

Example
The following example is based on the Sample Basic database. This calculation script
tests to see if the current member in the Market dimension is a descendant of West or
East. If so, Analytic Services multiplies the value for Marketing by 1.5. The calculation
script then tests to see if the current member is a descendant of South. If so, Analytic
Services multiplies the value for Marketing by .9. If the current member is not a
descendant of West, East, or South, Analytic Services multiplies the value for
Marketing by 1.1.

IF (@ISMBR(@DESCENDANTS(West))
OR @ISMBR(@DESCENDANTS(East)) ) Marketing = Marketing * 1.5;

ELSEIF(@ISMBR(@DESCENDANTS(South)) ) Marketing = Marketing * .9;
ELSE Marketing = Marketing * 1.1;
ENDIF;
FIX..ENDFIX
FIX...ENDFIX
The FIX...ENDFIX command block restricts database calculations to a subset of the
database. All commands nested between the FIX and ENDFIX statements are
restricted to the specified database subset.

Syntax
FIX (fixMbrs)
COMMANDS ;
ENDFIX
where:
fixMbrs A member name or list of members from any number of database dimensions.
fixMbrs can also contain:
1. AND/OR operators. Use the AND operator when all conditions must be met.
Use the OR operator when one condition of several must be met.
2. Member set functions, which are used to build member lists based on other
members.
COMMANDS The commands you want to be executed for the duration of the FIX.

Example
The following example fixes on the children of East and the members on the Market
dimension that have a UDA (User-Defined Attribute) of New Mkt.
FIX (@CHILDREN(East) OR @UDA(Market, "New Mkt"))
LOOP...ENDLOOP
LOOP...ENDLOOP
The LOOP...ENDLOOP command block specifies the number of times to iterate calculations. All commands
between the LOOP and ENDLOOP statements are performed the number of times that you specify.

Syntax
LOOP (integer, [break])
COMMANDS ;
ENDLOOP
where:
integer The integer constant that indicates the number of times to execute the commands contained in the loop
block.
break Optional parameter used to break the iterative process of a loop. break must be the name of a temporary
variable (VAR). Setting the value of the variable to 1 during the execution of the loop causes the loop to break
at the beginning of its next iteration.
COMMANDS Those commands that you want to be executed for the duration of the LOOP.

Example

In this example, the LOOP command finds a solution for Profit and Commission. This operation is done as a
loop because Profit and Commission are interdependent: Profit is needed to evaluate Commission, and
Commission is needed to calculate Profit. This example thus provides a model for solving simultaneous
formulas.
LOOP(30)
Commission = Profit * .15;
Profit = Margin - "Total Expenses" - Commission;
ENDLOOP;


CLEARDATA

CLEARDATA
Clears data values from the database and sets them to #MISSING.

Syntax
CLEARDATA mbrName;
where:
mbrNameAny valid single member name or member combination, or a function that
returns a single member or member combination.

Notes
CLEARDATA does not work if placed in an IF statement.

Example

CLEARDATA Budget; clears all Budget data. CLEARDATA Budget->Colas; clears
only Budget data for the Colas product family.

SET UPDATECALC

SET UPDATECALC
Turns intelligent calculation on or off.

Syntax
SET UPDATECALC ON | OFF;
where:
ON Analytic Services calculates only blocks marked as dirty .
The default setting is ON. You can change this default using the
UPDATECALC TRUE | FALSE setting in the essbase.cfg file.
OFF Analytic Services calculates all data blocks, regardless of
whether they have been updated.

Example
SET UPDATECALC ON;
SET UPDATECALC OFF;