Calc Scripts for Mere Mortals

Gary Crisci

Morgan Stanley

Edward Roske

interRel Consulting

BACKGROUND

Types Of Calculations

• Outline consolidations

– Unary operators + - * / %

– Relies on hierarchy

• Member formulas

– Allows complex calculations

– Can use functions and conditional processing

• Calculation scripts

– Override outline operations

– Offer most control3

Calculation Order

• Two basic categories

– Outline order

• Dense

• Sparse

– Dimension order

4

Calculation Order – All Dimensions

• First, Accounts

• Second, Time

• Third, all remaining dense dimensions

• Fourth, all remaining sparse dimensions

• Last, Two-pass calculations

5

WHAT IS A CALC SCRIPT?

What is a Calc Script?

• Series of commands, equations, and

formulas that control calculation of the

database

• Text files with a .CSC extension

7

/* Creates Initial Budget */

SET UPDATECALC OFF;

CLEARDATA Budget;

Budget = Actual * 1.1;

CALC ALL;

Why Use a Calc Script?

• Define calc order

• Calculate a subset of data

• Clear or copy data

• Calculate formulas not in outline

• Perform multiple-pass calculations

• Create and use temporary variables

8

Calc Script Editor

• Choice of the Essbase XTD Analytic

Services Calc Script Editor or another text

editor

• If you use another editor:

–Save file with .csc extension

–Easier to perform some functions

• Find/Replace

• See more lines of the script

• Printing options

• Can “mix and match”9

Calc Script Editor• Has a number of functions built in

• Command buttons simplify entries

• Validation function to detect errors

• Color-coding to show types of entries

• Auto-complete and auto-argument insert

10

Simplest Calc Script

• Default calc script

• Aggregates dimensions in outline

• Calculates formulas in outline

• Performs time balancing

• Uses intelligent calculation

11

CALC ALL;

Calc Script Syntax

• End each function/command with a

semicolon

• Enclose member names with spaces in

“double quotes”

• Start comments with /*

• End comments with */

• Not case-sensitive

12

/* Increase Opening Inventory */

“Opening Inventory” =

“Opening Inventory” * 1.1;

SIMPLE CALCULATIONS

Calculating Single Members

• To calculate a member based on the

aggregation or formula in the outline:

• To override the default formula:

14

Profit = Profit * 2;

Variance;

Calculating Dimensions

• Aggregate all dimensions and calculate all formulas:

• Aggregate one dimension and calculate its formulas:

• Aggregate a sparse dimension:

15

CALC ALL;

CALC DIM (dimension);

AGG (dimension);

Intelligent Calculation

• If enabled through database settings, it will

be on by default in a calc script

• To turn intelligent calculation off:

• To turn intelligent calculation on:

16

SET UpdateCalc Off;

SET UpdateCalc On;

Calculate a Subset of Data

• Calculate all of the database except a

portion:

• Only calculate a portion of the database:

17

CALC ALL Except DIM|MBR (list);

FIX (member list)

commands;

ENDFIX

Cross-dimensional Operator ->

• Points from current member to another

member

• Sets budget sales equal to actual sales *

1.1:

18

FIX (Budget)

Sales = Sales->Actual * 1.1;

ENDFIX

Try to Limit Cross-Dims

• Using cross-dimensional operator:

• Faster, easier to maintain:

19

FIX (Sales)

Budget = Actual * 1.1;

ENDFIX

FIX (Budget)

Sales = Sales->Actual * 1.1;

ENDFIX

Define Calc Order

• By default, dimensions are calced in this order:

– Accounts

– Time

– Remaining dense dimensions in outline order

– Remaining sparse dimensions in outline order

• Override this by using CALC DIM or AGG:

20

CALC DIM (Product, Market);

or

AGG (Product, Market);

Clear Data

• Clear entire database:

• Clear non-input blocks:

• Clear a specific member:

• Clear dynamic calc and store members:

21

CLEARBLOCK All;

CLEARBLOCK NonInput;

CLEARDATA member;

CLEARBLOCK Dynamic;

Clearing Data

• Clear a subset of the database based on a

sparse dimension:

• Clear a subset of the database based on a

dense dimension:

22

FIX (“Fruit Soda”, “Texas”)

CLEARBLOCK ALL;

ENDFIX

CLEARDATA Actual->Sales;

Copy Data

• Copy all values for one member to

another:

• Copy a subset of values:

23

FIX (Sales, COGS)

DATACOPY Actual TO Budget;

ENDFIX

DATACOPY Actual TO Budget;

Copy Data cont.

• Another way to copy a subset of values:

• Still another way to copy a subset of

values:

24

FIX (Sales, COGS)

Actual = Budget;

ENDFIX

FIX (Actual)

Sales = Sales->Budget;

COGS = COGS->Budget;

ENDFIX

Multi-pass Calculations

• Use to perform goal-seeking or

simultaneous equations (circular

references)

• Example of a simultaneous equation:

25

LOOP(30)

Bonus = Profit * .1;

Profit;

ENDLOOP;

Create and Use Temporary Variables

• Create initial budget based on a value

stored in a variable:

26

VAR BudgetInc = 0.1;

SET UPDATECALC OFF;

FIX (Sales, COGS)

Budget = Actual * (1 + BudgetInc);

ENDFIX

CALC ALL;

CALCULATION STRATEGIES

Calc Scripts for Mere Mortals

Calculation Commands

• Limited number of true calculation

commands

– Not functions – they are in another chapter

– Not “Set” statements – they are covered

under optimization

28

Agg

• Syntax

– AGG(Dimname, Dimname,…);

• Summary

– Aggregates dimension(s) according to the

outline operators

– Member formulas are ignored

– Very fast

• Fewer than 6 levels

29

Calc All

• Syntax

– Calc All;

• Summary

– Calculates all dimensions in the database

– Uses default calculation order

– This is typically the default calc

– Very efficient

– Can add “Except” to remove

dimensions/members

30

Calc Dim

• Syntax

– Calc Dim(DimName, DimName,…)

• Summary

– Calculates the dimensions that are listed

– All dense dimensions are calculated first in the order

they appear

– Sparse dimensions are calculated last - also in the

order they appear

– If you need a different order, use multiple Calc Dim

commands

– Includes member formulas

31

ClearBlock

• Syntax

– ClearBlock ALL | UPPER | NONINPUT |

DYNAMIC

• Summary

– Designed to clear blocks by removing index

entries

– Within a FIX block, may only clear a portion of

a block

– Options for which types of block to clear

32

ClearData

• Syntax

– ClearData MemberName;

• Summary

– Designed to set a member value to #Missing

– Works within a fix

33

ClearBlock vs. ClearData

• ClearBlock is designed to clear an entire

block

– At least a large portion of the block

• No Member name, just block type

• ClearData is designed to clear a member

– Usually before it is recalculated

• In many cases either one will work

34

DataCopy

• Syntax

– DataCopy MemberName TO MemberName;

• Summary

– Copies data from one member to another

– All intersections are included

– Great for copying versions

– Will create blocks if they do not exist

35

If/Else/ElseIf/EndIf

• Syntax

– IF (condition) ElseIf/Else EndIf;

• Summary

– Condition must be if parenthesis

– In a calc script, associate with a member

name

– Does really matter which member name

– Each If must end with EndIf

– Most effective on dense members

36

Fix/EndFix

• Synatx

– Fix(MemberNames, Functions Etc.) ENDFIX

• Summary

– Used to focus or limit a calculation

– Most effective on sparse members

– Used extensively

37

Exclude/EndExclude

• Synatx

– Exclude(MemberNames, Functions Etc.)

EndExclude

• Summary

– Used to do everything except a few members

on a calculation

– Most effective on sparse members

– New in 9.3

38

Loop/EndLoop

• Syntax

– Loop (integer, break) EndLoop;

• Summary

– Causes a block of code to be repeatedly

executed

– The integer determines the number of times

the loop runs

– The break value allows early exit

– Although it is a loop, its not a true

“programming loop”39

Using Commands

• Need to combine commands with

functions

• Execute in the order they are written

• None by itself is that useful

• Used together, they provide a powerful

tool set to apply business rules to the

database

40

Not Commands But…

• A member name by itself

–Calculates the member formula if present

–Calculates outline rollup if there is no formula

• Example

–East;

–Multiple members can be listed

–Member set functions can also be used

• Example

–@IDESCENDANTS(“2003”);

41

Assignment Statements

• Assign a value to a member

• Example

–Budget = 0;

–Budget = Budget * 0.95;

• There are other math operators

–More later

• Every command ends with a semicolon (;)

–Okay, there are exceptions but most do

42

More on Member Names

• All the members are calculated at once if

possible

• To force multiple passes of the database,

group the member names in parenthesis

– One pass for each group in parenthesis

– Not usually what you want, so use with

caution

43

Function Categories• Conditional

• Boolean

• Relationship

• Calculation Operators

• Mathematical

• Member Set

• Range and Financial

• Allocation

• Forecasting

• Statistical

• Date and Time

• Miscellaneous

• Custom Defined

44

Calculation Operators

• Nothing too exciting

• + - * / %

• Use parenthesis to control order of

operations

45

Conditional

• Typically used within an “If” command

• >, >=, <, <=, <>, !=

• Can combine with And, Or and Not

46

Boolean• More traditional functions

–@ISACCTYPE@ISANCEST@ISCHILD@ISDESC@ISGEN@ISIANCEST@ISICHILD@ISIDESC@ISIPARENT

• Typically used in “If” Statement

• Returns True/False

47

@ISISIBLING@ISLEV@ISMBR@ISPARENT@ISSAMEGEN@ISSAMELEV@ISSIBLING@ISUDA

Relationship Functions

• Returns Values

• Frequently used to get other

values in database@ANCESTVAL@ATTRIBUTEBVAL@ATTRIBUTESVAL@ATTRIBUTEVAL@CURGEN@CURLEV@GEN

48

@LEV@MDANCESTVAL@MDPARENTVAL@PARENTVAL@SANCESTVAL@SPARENTVAL@XREF

Mathematical Functions

• Most functions

available@ABS@AVG@EXP@FACTORIAL@INT@LN@LOG@LOG10@MAX@MAXS

49

• @MIN@MINS@MOD@POWER@REMAINDER@ROUND@SUM@TRUNCATE@VAR@VARPER

Member Set Functions

• Returns a List of Member Names

50

@ALLANCESTORS@ANCEST@ANCESTORS@ATTRIBUTE@CHILDREN@CURRMBR@DESCENDANTS@GENMBRS@IALLANCESTORS@IANCESTORS@ICHILDREN

@IDESCENDANTS@ILSIBLINGS@IRSIBLINGS@IRDESCENDANTS@ISIBLINGS@LEVMBRS@LIST@LSIBLINGS@MATCH@MEMBER

@MERGE@PARENT@RANGE@RDESCENDANTS@RELATIVE@REMOVE@RSIBLINGS@SIBLINGS@UDA@WITHATTR@XRANGE

Range and Financial Functions• Accepts a range of members instead of

individual members

51

@ACCUM@AVGRANGE@COMPOUND@COMPOUNDGROWTH@CURRMBRRANGE@DECLINE@DISCOUNT@GROWTH@INTEREST@IRR@MAXRANGE@MAXSRANGE@MDSHIFT

@MINRANGE@MINSRANGE@NEXT@NEXTS@NPV@PTD@PRIOR@PRIORS@RANGE@SHIFT[PLUS|MINUS]@SLN@SUMRANGE@SYD@XRANGE

Allocations Functions

• Only two functions in this category

– Allocate

– MDAllocate

• Used in simple situations to allocate an

amount down to lower levels

52

Forecasting Functions

• Similar to what you may have used in

Excel• @MOVAVG@MOVMAX@MOVMED@MOVMIN@MOVSUM@MOVSUMX@SPLINE@TREND

53

Statistical Functions

• Most common are available• @CORRELATION@COUNT@MEDIAN@MODE@RANK@STDEV@STDEVP@STDEVRANGE@VARIANCE@VARIANCEP

54

Date and Time

• Just one to convert strings to a date

– @ToDate

55

Miscellaneous

• The catch-all category

–@CALCMODE@CONCATENATE@SUBSTRING@NAME

56

Calc Scripts for Mere Mortals

ADVANCED TOPICS

Using Functions

• Frequently, functions are nested or used

as parameters for another function

• Functions are prefixed with “@”

• Parameters are separated by commas

• Used in many places

– Right of “=“

– FIX statements

– IFs etc.

58

Focusing Calculations

• Two most common methods

– Fix

– If

• Other methods:

– CrossDim operator

– MemberSet functions

– Relationship functions

– Variables

59

FIX

• FIX limits the members that are processed

• Most effective when used on members of

sparse dimensions

• Only blocks that meet the Fix criteria are

processed

– Remaining blocks are simply skipped

• Typical uses

– Only calculate one scenario

– Limit calc to current year60

More on FIX

• FIX works properly on dense members

• May result in all blocks being processed

• All statements between the FIX and

ENDFIX are executed as a block

• FIX statements can be nested

• Multiple members from the same

dimension are treated as “or”

– In other words, all members will be processed

61

What You Cannot Do With FIX

• You cannot assign values to a member

that is included in the FIX statement

– Actually, values cannot be assigned to any

member from a dimension in the FIX

statement

– Example

Fix(Sales)

Sales = 100;

ENDFIX

– Would result in an error

62

FIX On

• Members from one or more dimensions

• Can list specific member names

• Can include member set functions

• Can include AND and OR

– Use AND to get the intersection of two or

more functions

– Caution on empty sets

63

IF Statements

• Conditional processing is often needed to

process business rules

• Can include complex conditions

– And, Or, Not, etc.

64

What You Can Check For

• Most common are

– Members

• Specific members

• MemberSet comparisons

• Use boolean functions

– Values

• >, < = etc.

• Use #Missing for test

• True is treated as 1 and false is 0

65

Syntax for IF

• Place condition in parenthesis

• Associate with a member

– Doesn‟t matter which member

– MemberName (

• If (condition)

– Statements

• EndIf )

– Not required for member formulas

66

More on IF

• Can have ElseIf (condition)

• Can Have Else

• Can have both

• Still terminate with single EndIf

– Be sure to include ;

• All ElseIF/Else conditions have to remain

within parenthesis for the member

association

67

To If or FIX

• Generally, If works best on dense dimension

members

– Particularly when ElseIF or Else are included

• Block is only brought into memory once and all related

conditions are processed

• Fix would bring block in multiple times

• Conversely, FIX works best on sparse dimension

members

• Old saying “Fix on Sparse, If on dense”

– If you‟re dense, fix on sparse?

• There are always exceptions68

Other Method to Focus Calculations

• “Cross Dim” operator

– Allows reference to specific cells

– Frequently in another block

– Technique for complex allocations

• Relationship functions

– Can be used to get a value from another part of the

database

• Example is @ParentVal(…)

• MemberSet functions

– Return member names

– Can be used to calculate those members or in a Fix/If69

Loops

• Can use the Loop/EndLoop to repeatedly

execute calc commands

• Not designed to increment variables and

reference different members

• Used to solve goal seeking problems

70

Why Create Blocks• Often need blocks that do not exist

– Typically when performing allocations

• Actually, one of the most challenging aspects of writing

calc scripts

– If a block does not exist, not processed by a calc script

• Except outline calculations

– Frequent cause of calculation problems

• Example

IF (Budget > 100)

Actual = 50;

ENDIF

– Assumes Scenario is sparse

71

Ways to Create Blocks

• There are basically four methods to create

blocks:

– Load data

– Calculate the database

– Use the DataCopy command

– Place a sparse member on the left side of an

assignment statement

• Must not set equal to a constant

• SET CREATEBLOCKONEQ ON|OFF;

– SET CREATENONMISSINGBLK ON|OFF;

72

Organizing Calc Scripts

• Most calc scripts have common parts or

sections

– Housekeeping

– Initial Calculation

– Mainline Rollup

– Back Calc

73

Housekeeping

• The calculation environment is established

– Intelligent calculation is turned on/off

– Other Set commands are issue

• Variables are declared

• Comments describing the purpose of the

calc script are entered

– Use /* and */ for comments

74

Key Set Commands

• Set AggMissg ON | OFF

– Controls if #Missing values are aggregated

– If all children and #Missing, parent is et to #Missing

• Upper level step-on

– Caution needed if values loaded at upper levels

• SET MSG ERROR | WARN | INFO | SUMMARY

| DETAIL | NONE;

– Detail lists each block being processed

– Good for debugging

– Generates a large log and is slow

75

Initial Calculation

• This is where business rules are applied

• Frequently include allocations

– This usually requires a partial database rollup

• There may be many calculation blocks

with FIX statements

– Or If statements

• Typically the most complex portion of the

calc script

76

Mainline Calculation

• This is the rollup of the database

• May be focused

– e.g. FIX(Actual)

• Regardless, this is the major rollup of the

database

77

Back Calc

• This is where two-pass members and any

other members requiring special treatment

are handled

• Often requires recalculation of all or most

of the blocks

• Corrects percentages and ratios that may

have been summed

78

Testing Calc Scripts

• The following methodology works well:

– Use a test database

– Create test data in Excel

• Keep it on its own sheet

– Clear the database

– Use Lock & Send to load test data

– Run the calc from Excel

– Retrieve onto a test sheet

79

More on Testing

• Best to know expected outcome before retrieving

• Can create a calc script to clear the database

– Minimizes switching between Excel and App Manager

• The key is small amounts of data which allows short test

cycles

– Many people test with large amounts of data resulting in long

cycles and inability to get many tests in per day

• When initial testing is complete, add to the test data set

to make sure everything is working properly

80

Typical Issues

• Intelligent Calc

– Prevents blocks from being calculated

• FIX on too few or too many members

– Nested FIX‟s are OR‟s, not AND‟s

• Dynamic Calc runs after Batch Calc

– Dynamic calc members do not make good counters

• Referring to the wrong block

– Remember, every intersection is processed unless

the calculation is focused

81

New Calc Script Function – 11x

– @LDESCENDANTS(@LIST("100", "200", "300"), 0)

• Returns all the descendents for the members “100”, “200”

and “300”

– @LDESCENDANTS(@LIST(@UDA(Market, "Major

Market")), 0)

• Returns all the descendents for the members(till level 0) in

„Market‟ dimension which are associated to attribute „Major

Market‟. The result set will have the descendants of “East”

and “Central”

– CALC ALL EXCEPT

MBR(@ILDESCENDANTS(@LIST("100", "200")));

• Calculate the entire database except for the descendants of

the members “100” and “200” including the base members.”82

New Calc Script Function – 11x• @SHIFTSIBLING

– Returns the nth previous member as a string.

– Generate a member name string based on the relative position of the focus member.

• Syntax

– @SHIFTSIBLING (mbrName, [N])

– mbrName: Name of base member

– N: Optional argument to specify by what position to shift the sibling in the outline order.

– Values N can assume:• N = 0 the base member itself

• N < 0 the previous sibling after N relative shift. If this shift goes beyond the left most member then return an empty string (“”)

• N > 0 the next sibling after N relative shift. If this shift goes beyond the right most member an empty string “”

• The default value of N is set to zero.

New Calc Script Function – 11x

• For shifting one member

– @PREVSIBLING(mbrName)

• Returns the previous sibling for the input member. If the input

member is the left most member then return “”; This is

equivalent of calling @SHIFTSIBLING with -1 as the optional

argument N

– @NEXTSIBLING(mbrName)

– Returns the next sibling for the input member. If the

input member is the right most member then return “”.

This is equivalent of calling @SHIFTSIBLING with 1

as the value for optional argument N.

Environment Variables in Calc Scripts –

11x• Helpful in export calc scripts

• Use environment variables

• $ is used to indicate environment variables

• To use environment variables in a calc script, use a

leading $ sign:

DATAEXPORT "File" "," $ENV_FILE;

• Note: $ is reserved for environment variables.

– If a member name begins with $, enclose it in quotation marks.

Thanks for your time

Gary Crisci

Morgan Stanley

Edward Roske

interRel Consulting