Calc Scripts for Mere Mortals

Gary Crisci Edward Roske

Morgan Stanley 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 control
 Calculation Order
• Two basic categories
– Outline order
• Dense
• Sparse
– Dimension order
 Calculation Order – All Dimensions
• First, Accounts
• Second, Time
• Third, all remaining dense dimensions
• Fourth, all remaining sparse dimensions
• Last, Two-pass calculations
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
/* 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
 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”
 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
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
/* 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:
Variance;

• To override the default formula:

Profit = Profit * 2;
 Calculating Dimensions
• Aggregate all dimensions and calculate all formulas:
CALC ALL;

• Aggregate one dimension and calculate its formulas:

CALC DIM (dimension);

• Aggregate a sparse 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:
SET UpdateCalc Off;

• To turn intelligent calculation on:

SET UpdateCalc On;
 Calculate a Subset of Data
• Calculate all of the database except a
portion:
CALC ALL Except DIM|MBR (list);

• Only calculate a portion of the database:

FIX (member list)
commands;
ENDFIX
 Cross-dimensional Operator ->
• Points from current member to another
member
• Sets budget sales equal to actual sales *
1.1:
FIX (Budget)
Sales = Sales->Actual * 1.1;
ENDFIX
 Try to Limit Cross-Dims
• Using cross-dimensional operator:
FIX (Budget)
Sales = Sales->Actual * 1.1;
ENDFIX

• Faster, easier to maintain:

FIX (Sales)
Budget = 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:
CALC DIM (Product, Market);

or

AGG (Product, Market);

 Clear Data
• Clear entire database:
CLEARBLOCK All;

• Clear non-input blocks:

CLEARBLOCK NonInput;

• Clear a specific member:

CLEARDATA member;

• Clear dynamic calc and store members:

CLEARBLOCK Dynamic;
 Clearing Data
• Clear a subset of the database based on a
sparse dimension:
FIX (“Fruit Soda”, “Texas”)
CLEARBLOCK ALL;
ENDFIX

• Clear a subset of the database based on a

dense dimension:
CLEARDATA Actual->Sales;
 Copy Data
• Copy all values for one member to
another:
DATACOPY Actual TO Budget;

• Copy a subset of values:

FIX (Sales, COGS)
DATACOPY Actual TO Budget;
ENDFIX
 Copy Data cont.
• Another way to copy a subset of values:
FIX (Sales, COGS)
Actual = Budget;
ENDFIX

• Still another way to copy a subset of

values:
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:
LOOP(30)
Bonus = Profit * .1;
Profit;
ENDLOOP;
 Create and Use Temporary Variables
• Create initial budget based on a value
stored in a variable:

VAR BudgetInc = 0.1;

SET UPDATECALC OFF;
FIX (Sales, COGS)
Budget = Actual * (1 + BudgetInc);
ENDFIX
CALC ALL;
Calc Scripts for Mere Mortals

CALCULATION STRATEGIES
 Calculation Commands
• Limited number of true calculation
commands
– Not functions – they are in another chapter
– Not “Set” statements – they are covered
under optimization
 Agg
• Syntax
– AGG(Dimname, Dimname,…);
• Summary
– Aggregates dimension(s) according to the
outline operators
– Member formulas are ignored
– Very fast
• Fewer than 6 levels
 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
 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
 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
 ClearData
• Syntax
– ClearData MemberName;
• Summary
– Designed to set a member value to #Missing
– Works within a fix
 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
 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
 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
 Fix/EndFix
• Synatx
– Fix(MemberNames, Functions Etc.) ENDFIX
• Summary
– Used to focus or limit a calculation
– Most effective on sparse members
– Used extensively
 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”
 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
 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”);
 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
 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
 Function Categories
• Conditional • Allocation
• Boolean • Forecasting
• Relationship • Statistical
• Calculation Operators • Date and Time
• Mathematical • Miscellaneous
• Member Set • Custom Defined
• Range and Financial
 Calculation Operators
• Nothing too exciting
• +-*/%
• Use parenthesis to control order of
operations
 Conditional
• Typically used within an “If” command
• >, >=, <, <=, <>, !=
• Can combine with And, Or and Not
 Boolean
• More traditional functions
– @ISACCTYPE @ISISIBLING
@ISANCEST @ISLEV
@ISCHILD @ISMBR
@ISDESC @ISPARENT
@ISGEN
@ISSAMEGEN
@ISIANCEST
@ISSAMELEV
@ISICHILD
@ISIDESC @ISSIBLING
@ISIPARENT @ISUDA

• Typically used in “If” Statement

• Returns True/False
 Relationship Functions
• Returns Values
• Frequently used to get other
values in database
@LEV
@ANCESTVAL @MDANCESTVAL
@ATTRIBUTEBVAL @MDPARENTVAL
@ATTRIBUTESVAL @PARENTVAL
@ATTRIBUTEVAL @SANCESTVAL
@SPARENTVAL
@CURGEN @XREF
@CURLEV
@GEN
 Mathematical Functions
• Most functions
available
@ABS
• @MIN
@AVG @MINS
@EXP @MOD
@FACTORIAL @POWER
@REMAINDER
@INT @ROUND
@LN @SUM
@LOG @TRUNCATE
@LOG10 @VAR
@VARPER
@MAX
@MAXS
 Member Set Functions
• Returns a List of Member Names
@ALLANCESTORS @IDESCENDANTS @MERGE
@ANCEST @ILSIBLINGS @PARENT
@ANCESTORS @IRSIBLINGS @RANGE
@ATTRIBUTE @IRDESCENDANTS@RDESCENDANTS
@CHILDREN @ISIBLINGS @RELATIVE
@CURRMBR @LEVMBRS @REMOVE
@DESCENDANTS @LIST @RSIBLINGS
@GENMBRS @LSIBLINGS @SIBLINGS
@IALLANCESTORS @MATCH @UDA
@IANCESTORS @MEMBER @WITHATTR
@ICHILDREN @XRANGE
 Range and Financial Functions
• Accepts a range of members instead of
individual members
@ACCUM @MINRANGE
@AVGRANGE @MINSRANGE
@COMPOUND @NEXT
@COMPOUNDGROWTH @NEXTS
@CURRMBRRANGE @NPV
@DECLINE @PTD
@DISCOUNT @PRIOR
@GROWTH @PRIORS
@INTEREST @RANGE
@IRR @SHIFT[PLUS|MINUS]
@MAXRANGE @SLN
@MAXSRANGE @SUMRANGE
@MDSHIFT @SYD
@XRANGE
 Allocations Functions
• Only two functions in this category
– Allocate
– MDAllocate
• Used in simple situations to allocate an
amount down to lower levels
 Forecasting Functions
• Similar to what you may have used in
Excel
• @MOVAVG
@MOVMAX
@MOVMED
@MOVMIN
@MOVSUM
@MOVSUMX
@SPLINE
@TREND
 Statistical Functions
• Most common are available
• @CORRELATION
@COUNT
@MEDIAN
@MODE
@RANK
@STDEV
@STDEVP
@STDEVRANGE
@VARIANCE
@VARIANCEP
 Date and Time
• Just one to convert strings to a date
– @ToDate
 Miscellaneous
• The catch-all category
– @CALCMODE
@CONCATENATE
@SUBSTRING
@NAME
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.
 Focusing Calculations
• Two most common methods
– Fix
– If
• Other methods:
– CrossDim operator
– MemberSet functions
– Relationship functions
– Variables
 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 year
 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
 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
 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
 IF Statements
• Conditional processing is often needed to
process business rules
• Can include complex conditions
– And, Or, Not, etc.
 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
 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
 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
 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 exceptions
 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/If
 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
 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
 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;
 Organizing Calc Scripts
• Most calc scripts have common parts or
sections
– Housekeeping
– Initial Calculation
– Mainline Rollup
– Back Calc
 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
 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
 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
 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
 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
 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
 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
 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
 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”
82 including the base members.”
 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 Edward Roske

Morgan Stanley interRel Consulting