Understanding Calculation Understanding Calculation ScriptsScripts

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 Advantages of Calculation ScriptsScripts

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 CommandsSome Calculation Commands

CALC ALLCALC ALL CALC AVERAGE CALC AVERAGE IF IF ENDIFENDIF ELSEIFELSEIF ELSEELSE FIX..ENDFIX FIX..ENDFIX LOOP...ENDLOOPLOOP...ENDLOOP CLEARDATA CLEARDATA UPDATECALCUPDATECALC

CALC ALLCALC ALL CALC ALLCALC ALL

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

SyntaxSyntaxCALC ALLCALC ALL [EXCEPT DIM ( [EXCEPT DIM (dimListdimList) | MBR () | MBR (mbrListmbrList)]; )]; where:where:

EXCEPT Defines an exception list of dimensions or members that are to EXCEPT Defines an exception list of dimensions or members that are to be excluded from the calculation.be excluded from the calculation.

DIM Single-dimension specification.DIM Single-dimension specification. dimListdimList Optional comma-delimited list of dimensions. Optional comma-delimited list of dimensions. MBR Single-member specification.MBR Single-member specification. mbrListmbrList Optional comma-delimited list of members, member set Optional comma-delimited list of members, member set

functions, or range functions.functions, or range functions.

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

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

CALC AVERAGE CALC AVERAGE CALC AVERAGECALC AVERAGE

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

SyntaxSyntaxCALC AVERAGE;CALC AVERAGE;

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

ExampleExampleCALC AVERAGE; CALC AVERAGE;

IFIF IFIF

Performs conditional tests within a formula. Using the IF statement, you 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 can define a Boolean test, as well as formulas to be calculated if the test returns either a TRUE or FALSE value. returns either a TRUE or FALSE value.

SyntaxSyntaxIF( IF( conditioncondition ) ) statementstatement ; [ ELSEIF... ; [ ELSEIF...statementstatement | ELSE... | ELSE...statementstatement]]ENDIF; ENDIF; where:where:

conditioncondition Formula or function that returns a Boolean value of TRUE (a Formula or function that returns a Boolean value of TRUE (a nonzero value) or FALSE (a zero value). nonzero value) or FALSE (a zero value).

statementstatement Operations to be performed depending on the results of the Operations to be performed depending on the results of the test. test.

ExampleExampleIF( @ISMBR(@DESCENDANTS(Europe)) OR IF( @ISMBR(@DESCENDANTS(Europe)) OR @ISMBR(@DESCENDANTS(Asia)) ) Taxes = "Gross Margin" * "Foreign @ISMBR(@DESCENDANTS(Asia)) ) Taxes = "Gross Margin" * "Foreign Tax Rate"; ELSE Taxes = "Gross Margin" * "Domestic Tax Rate"; ENDIF; 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 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 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 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 current cell does not include a member from one of those groups, then the domestic tax rate is used for the tax calculation. the domestic tax rate is used for the tax calculation.

ENDIFENDIF ENDIFENDIF

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

SyntaxSyntaxENDIF; ENDIF;

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

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

ELSEIF(@ISMBR(@DESCENDANTS(South)) ) Marketing = Marketing ELSEIF(@ISMBR(@DESCENDANTS(South)) ) Marketing = Marketing * .9; * .9; ELSE Marketing = Marketing * 1.1; ELSE Marketing = Marketing * 1.1; ENDIF; ENDIF;

FIX..ENDFIXFIX..ENDFIX FIX...ENDFIXFIX...ENDFIX

The FIX...ENDFIX command block restricts database calculations to a subset The FIX...ENDFIX command block restricts database calculations to a subset of the database. All commands nested between the FIX and ENDFIX of the database. All commands nested between the FIX and ENDFIX statements are restricted to the specified database subset. statements are restricted to the specified database subset.

SyntaxSyntaxFIXFIX ( (fixMbrsfixMbrs) ) COMMANDSCOMMANDS ; ;ENDFIXENDFIX where:where:

fixMbrsfixMbrs A member name or list of members from any number of database A member name or list of members from any number of database dimensions. dimensions.

fixMbrsfixMbrs can also contain: can also contain: 1.1. AND/OR operators. Use the AND operator when all conditions must be AND/OR operators. Use the AND operator when all conditions must be met. met. Use the OR operator when one condition of several must be met. Use the OR operator when one condition of several must be met. 2.2. Member set functions, which are used to build member lists based on Member set functions, which are used to build member lists based on other other members. members.

COMMANDSCOMMANDS The commands you want to be executed for the duration of the The commands you want to be executed for the duration of the FIX. FIX.

ExampleExampleThe following example fixes on the children of East and the members on the 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.Market dimension that have a UDA (User-Defined Attribute) of New Mkt.FIX (@CHILDREN(East) OR @UDA(Market, "New Mkt")) FIX (@CHILDREN(East) OR @UDA(Market, "New Mkt"))

LOOP...ENDLOOPLOOP...ENDLOOP LOOP...ENDLOOPLOOP...ENDLOOP

The LOOP...ENDLOOP command block specifies the number of times to iterate The LOOP...ENDLOOP command block specifies the number of times to iterate calculations. All commands between the LOOP and ENDLOOP statements are calculations. All commands between the LOOP and ENDLOOP statements are performed the number of times that you specify. performed the number of times that you specify.

SyntaxSyntaxLOOP (LOOP (integerinteger, [, [breakbreak])])COMMANDSCOMMANDS ; ;ENDLOOP ENDLOOP where:where:

integerinteger The integer constant that indicates the number of times to execute the The integer constant that indicates the number of times to execute the commands contained in the loop block.commands contained in the loop block.

breakbreak Optional parameter used to break the iterative process of a loop. Optional parameter used to break the iterative process of a loop. breakbreak must be must be the name of a temporary variable (VAR). Setting the value of the variable to 1 during 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. the execution of the loop causes the loop to break at the beginning of its next iteration.

COMMANDSCOMMANDS Those commands that you want to be executed for the duration of the Those commands that you want to be executed for the duration of the LOOP. LOOP.

ExampleExample

In this example, the LOOP command finds a solution for Profit and Commission. This 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 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 needed to evaluate Commission, and Commission is needed to calculate Profit. This example thus provides a model for solving simultaneous formulas.example thus provides a model for solving simultaneous formulas. LOOP(30) LOOP(30) Commission = Profit * .15; Commission = Profit * .15; Profit = Margin - "Total Expenses" - Commission; Profit = Margin - "Total Expenses" - Commission; ENDLOOP; ENDLOOP;

CLEARDATA CLEARDATA CLEARDATACLEARDATA

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

SyntaxSyntaxCLEARDATACLEARDATA mbrNamembrName;;where:where:

mbrNamembrNameAny valid single member name or member combination, Any valid single member name or member combination, or a function that returns a single member or member or a function that returns a single member or member combination.combination.

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

ExampleExample

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

SET UPDATECALCSET UPDATECALC SET UPDATECALCSET UPDATECALC

Turns intelligent calculation on or off. Turns intelligent calculation on or off.

SyntaxSyntaxSET UPDATECALCSET UPDATECALC ON | OFF; ON | OFF;where:where:

ON Analytic Services calculates only blocks ON Analytic Services calculates only blocks marked as dirty . The default setting is ON. You marked as dirty . The default setting is ON. You can change this default using the can change this default using the UPDATECALCUPDATECALC TRUE | FALSE setting in the essbase.cfg file. TRUE | FALSE setting in the essbase.cfg file.

OFF Analytic Services calculates all data blocks, OFF Analytic Services calculates all data blocks, regardless of whether they have been updated. regardless of whether they have been updated.

ExampleExampleSET UPDATECALC ON;SET UPDATECALC ON;SET UPDATECALC OFF; SET UPDATECALC OFF;