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 control

Calculation Order
• Two basic categories
– Outline order
• Dense • Sparse

– Dimension order

Calculation Order – All Dimensions • • • • • First. all remaining sparse dimensions Last. all remaining dense dimensions Fourth. Two-pass calculations . Accounts Second. Time Third.

WHAT IS A CALC SCRIPT? .

What is a Calc Script? • Series of commands. Budget = Actual * 1. CLEARDATA Budget. and formulas that control calculation of the database • Text files with a . .1. CALC ALL.CSC extension /* Creates Initial Budget */ SET UPDATECALC OFF. equations.

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 .

csc extension –Easier to perform some functions • Find/Replace • See more lines of the script • Printing options • Can “mix and match” .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 .

• • • • • 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 Calc Script Editor 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 a sparse dimension: AGG (dimension). • Aggregate one dimension and calculate its formulas: CALC DIM (dimension). .

. 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.Intelligent Calculation • If enabled through database settings.

ENDFIX . • Only calculate a portion of the database: FIX (member list) commands.Calculate a Subset of Data • Calculate all of the database except a portion: CALC ALL Except DIM|MBR (list).

Cross-dimensional Operator -> • Points from current member to another member • Sets budget sales equal to actual sales * 1. ENDFIX .1: FIX (Budget) Sales = Sales->Actual * 1.1.

ENDFIX • Faster.1.1.Try to Limit Cross-Dims • Using cross-dimensional operator: FIX (Budget) Sales = Sales->Actual * 1. ENDFIX . easier to maintain: FIX (Sales) Budget = Actual * 1.

Market). . Market).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 CALC DIM (Product. or • Override this by using CALC DIM or AGG: AGG (Product.

• Clear non-input blocks: CLEARBLOCK NonInput. .Clear Data • Clear entire database: CLEARBLOCK All. • 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”. ENDFIX • Clear a subset of the database based on a dense dimension: CLEARDATA Actual->Sales. . “Texas”) CLEARBLOCK ALL.

Copy Data • Copy all values for one member to another: DATACOPY Actual TO Budget. ENDFIX . COGS) DATACOPY Actual TO Budget. • Copy a subset of values: FIX (Sales.

COGS = COGS->Budget.Copy Data cont. COGS) Actual = Budget. ENDFIX . • Another way to copy a subset of values: FIX (Sales. ENDFIX • Still another way to copy a subset of values: FIX (Actual) Sales = Sales->Budget.

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

• Summary – Aggregates dimension(s) according to the outline operators – Member formulas are ignored – Very fast • Fewer than 6 levels .…). Dimname.Agg • Syntax – AGG(Dimname.

• 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 All • Syntax – Calc All.

Calc Dim • Syntax – Calc Dim(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 . DimName.

may only clear a portion of a block – Options for which types of block to clear .ClearBlock • Syntax – ClearBlock ALL | UPPER | NONINPUT | DYNAMIC • Summary – Designed to clear blocks by removing index entries – Within a FIX block.

• Summary – Designed to set a member value to #Missing – Works within a fix .ClearData • Syntax – ClearData MemberName.

just block type • ClearData is designed to clear a member – Usually before it is recalculated • In many cases either one will work . ClearData • ClearBlock is designed to clear an entire block – At least a large portion of the block • No Member name.ClearBlock vs.

• Summary – Copies data from one member to another – All intersections are included – Great for copying versions – Will create blocks if they do not exist .DataCopy • Syntax – DataCopy MemberName TO MemberName.

associate with a member name – Does really matter which member name – Each If must end with EndIf – Most effective on dense members . • Summary – Condition must be if parenthesis – In a calc script.If/Else/ElseIf/EndIf • Syntax – IF (condition) ElseIf/Else EndIf.

Functions Etc.) ENDFIX • Summary – Used to focus or limit a calculation – Most effective on sparse members – Used extensively .Fix/EndFix • Synatx – Fix(MemberNames.

Exclude/EndExclude • Synatx – Exclude(MemberNames.) EndExclude • Summary – Used to do everything except a few members on a calculation – Most effective on sparse members – New in 9. Functions Etc.3 38 .

break) EndLoop. its not a true “programming loop” .Loop/EndLoop • Syntax – Loop (integer. • 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.

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 .

. –Multiple members can be listed –Member set functions can also be used • Example – @IDESCENDANTS(“2003”).Not Commands But… • A member name by itself –Calculates the member formula if present –Calculates outline rollup if there is no formula • Example – East.

) –Okay.95.Assignment Statements • Assign a value to a member • Example –Budget = 0. –Budget = Budget * 0. • There are other math operators –More later • Every command ends with a semicolon (. 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. so use with caution . group the member names in parenthesis – One pass for each group in parenthesis – Not usually what you want.

Function Categories • • • • • • • Conditional Boolean Relationship Calculation Operators Mathematical Member Set Range and Financial • • • • • • Allocation Forecasting Statistical Date and Time Miscellaneous Custom Defined .

Calculation Operators • Nothing too exciting • +-*/% • Use parenthesis to control order of operations .

!= • Can combine with And. >=. <=. <. Or and Not .Conditional • Typically used within an “If” command • >. <>.

• More traditional functions – @ISACCTYPE @ISANCEST @ISCHILD @ISDESC @ISGEN @ISIANCEST @ISICHILD @ISIDESC @ISIPARENT Boolean @ISISIBLING @ISLEV @ISMBR @ISPARENT @ISSAMEGEN @ISSAMELEV @ISSIBLING @ISUDA • Typically used in “If” Statement • Returns True/False .

Relationship Functions • Returns Values • Frequently used to get other values in database @ANCESTVAL @ATTRIBUTEBVAL @ATTRIBUTESVAL @ATTRIBUTEVAL @CURGEN @CURLEV @GEN @LEV @MDANCESTVAL @MDPARENTVAL @PARENTVAL @SANCESTVAL @SPARENTVAL @XREF .

Mathematical Functions • Most functions available @ABS @AVG @EXP @FACTORIAL @INT @LN @LOG @LOG10 @MAX @MAXS • @MIN @MINS @MOD @POWER @REMAINDER @ROUND @SUM @TRUNCATE @VAR @VARPER .

Member Set Functions • Returns a List of Member Names @ALLANCESTORS @ANCEST @ANCESTORS @ATTRIBUTE @CHILDREN @CURRMBR @DESCENDANTS @GENMBRS @IALLANCESTORS @IANCESTORS @ICHILDREN @IDESCENDANTS @MERGE @PARENT @ILSIBLINGS @RANGE @IRSIBLINGS @IRDESCENDANTS@RDESCENDANTS @RELATIVE @ISIBLINGS @REMOVE @LEVMBRS @RSIBLINGS @LIST @SIBLINGS @LSIBLINGS @UDA @MATCH @WITHATTR @MEMBER @XRANGE .

• Accepts a range of members instead of individual members @ACCUM @AVGRANGE @COMPOUND @COMPOUNDGROWTH @CURRMBRRANGE @DECLINE @DISCOUNT @GROWTH @INTEREST @IRR @MAXRANGE @MAXSRANGE @MDSHIFT Range and Financial Functions @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 .

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 .

Not. etc. .IF Statements • Conditional processing is often needed to process business rules • Can include complex conditions – And. Or.

• Use #Missing for test • True is treated as 1 and false is 0 . < = etc.What You Can Check For • Most common are – Members • Specific members • MemberSet comparisons • Use boolean functions – Values • >.

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 .

FIX works best on sparse dimension members • Old saying “Fix on Sparse. 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.To If or FIX • Generally. 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 .

not processed by a calc script • Except outline calculations – Frequent cause of calculation problems • Example IF (Budget > 100) Actual = 50.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. ENDIF – Assumes Scenario is sparse .

– SET CREATENONMISSINGBLK ON|OFF.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. .

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 .

add to the test data set to make sure everything is working properly .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.

every intersection is processed unless the calculation is focused . not AND‟s • Dynamic Calc runs after Batch Calc – Dynamic calc members do not make good counters • Referring to the wrong block – Remember.Typical Issues • Intelligent Calc – Prevents blocks from being calculated • FIX on too few or too many members – Nested FIX‟s are OR‟s.

"200"))).” 82 . The result set will have the descendants of “East” and “Central” – CALC ALL EXCEPT MBR(@ILDESCENDANTS(@LIST("100". 0) • Returns all the descendents for the members(till level 0) in „Market‟ dimension which are associated to attribute „Major Market‟. • Calculate the entire database except for the descendants of the members “100” and “200” including the base members.New Calc Script Function – 11x – @LDESCENDANTS(@LIST("100". "Major Market")). "200". 0) • Returns all the descendents for the members “100”. "300"). “200” and “300” – @LDESCENDANTS(@LIST(@UDA(Market.

If this shift goes beyond the right most member an empty string “” • The default value of N is set to zero. – Generate a member name string based on the relative position of the focus member.New Calc Script Function – 11x • @SHIFTSIBLING – Returns the nth previous member as a string. 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. If this shift goes beyond the left most member then return an empty string (“”) • N > 0 the next sibling after N relative shift. • . – Values N can assume: • N = 0 the base member itself • N < 0 the previous sibling after N relative shift.

This is equivalent of calling @SHIFTSIBLING with 1 as the value for optional argument N. If the input member is the right most member then return “”.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. .

• Note: $ is reserved for environment variables. enclose it in quotation marks. use a leading $ sign: DATAEXPORT "File" "." $ENV_FILE. – If a member name begins with $.• Helpful in export calc scripts • Use environment variables • $ is used to indicate environment variables Environment Variables in Calc Scripts – 11x • To use environment variables in a calc script. .

Thanks for your time Gary Crisci Morgan Stanley Edward Roske interRel Consulting .