Essbase Calc Script
Essbase Calc Script
Essbase Calc Script
interRel Consulting
Presented by Edward Roske
interRel Consulting
Gary Crisci
Morgan Stanley
In the world of enterprise performance management and business intelligence, centralized business rules and calculations are
www.interrel.com
key to obtaining actionable information to improve business. One of the big advantages of the Essbase solution is the
powerful calculation engine to perform these business rules. Whether it is basic aggregations, complex allocation rules, driver
based business rules, and more, Essbase can address any of these requirements across financial, operational, and other
applications. The way to define these business rules and calculations is through a calc script.
In basic Essbase, you calculations can be achieved via outline consolidations and member formulas (and it is certainly more
(972) 735-8716
A calc script is really just a sequential series of commands, equations, and formulas. It is stored in a standard text file with a
.CSC extension, so you can even open them in Notepad if you want to. Here’s the calc script that will set all of your budget
values to 50% above your actuals:
http://looksmarter.blogspot.com/
/* Creates Initial Budget */
SET UPDATECALC OFF;
CLEARDATA Budget;
Budget = Actual * 1.5;
CALC ALL;
You might have noticed that this calc script actually does a few things beyond just creating the budget, but we’ll get to those
in due time.
There are a lot of reasons to use a calc script. If you’re not happy with the order that Essbase uses to calculate the members
and dimensions, a calc script can easily override the default order. If you don’t want to calculate the entire database, a calc
script can be written to only calculate the current month. If you want to clear data or copy data from one place to another, calc
interRel Consulting
calculation that would make most Excel gurus run home crying to their mommies, you can just tie on your cape and write an
Essbase Calc Script to save the day.
www.interrel.com
There are some definite advantages to using your own text editor. Text editors tend to let you see more lines at once, allow
better find and replace functionality, have better line numbering, and provide greater printing options than Administration
Services’ built-in Calc Script Editor. If you do create your calc script in an external editor, it is very easy to copy and paste the
body into Administration Services, or you can also save your calc script as a text file in the appropriate database directory
(when you do this, remember to save the file with a .CSC extension).
For now, let’s pretend that you’re not a nerd for a second and use Administration Services to create your first calc script.
1. Open Administration Services and drill down below the database to the section named “Calculation Scripts.”
2. Right click on “Calculation Scripts” and choose Create Calculation Script:
(972) 735-8716
http://looksmarter.blogspot.com/
You can also create a calc script by going to the menu and choosing Editors >> Calculation Script Editor.
3. A window will appear called the “Calculation Script Editor”:
interRel Consulting
www.interrel.com
1000 Ballpark Way, Suite 304, Arlington, TX 76011
This editor has three main panes:
1. Outline. This pane helps you to select members from the outline and add them automatically to the calc script being
edited.
2. Functions. This pane lets you select functions and commands and add them to the calc script being edited. The check
(972) 735-8716
boxes above this pane determine if arguments to the functions and commands will be inserted as well.
3. Data entry. This is where you actually type your calc script. While you could live without panes one and two (though
it would be a royal pain), all of the power of calc scripts is entered into pane three.
http://looksmarter.blogspot.com/
The calc editor (as we’ll call it from now on) has a toolbar at the top of the screen just below the menu:
While most of the buttons are the same ones you’d see in fancy Windows applications like Notepad, the rightmost three
icons are calc editor specific. The check mark icon validates the syntax of your calc script. The outline icon associates an
outline with your calc script. You’ll need to do this if you don’t see an outline in the outline pane (pane one, remember?). The
final icon (the green down arrow next to a cash register receipt) runs the calc script that’s open in pane 3. We’re not going to
be using the toolbar for right now, but go right ahead if you’d like to. It’s a free country.
Simplest Calc Script
While it’s small in stature, it’s powerful in nature. This single line will aggregate all of the dimensional hierarchies in your
outline, calculate all of the formulas attached to members, perform time balancing on time balanced members, and does it all
interRel Consulting
CALC ALL;
Calc Script Syntax
www.interrel.com
There are a few simple rules to follow when writing a calc script:
There are many more rules, but these are the important ones that people tend to forget and then wonder for hours why their
calc scripts aren’t working. Here’s a calc script that demonstrates several of those syntax rules:
(972) 735-8716
“Opening Inventory” =
“Opening InVeNtOrY” * 1.1;
http://looksmarter.blogspot.com/
Notice that the first line is a comment and it has the appropriate start and end characters. “Opening Inventory” has a space in
the member name, so it’s surrounded by double quotes. At the end of the entire statement (although not at the end of the
comment), there’s a semicolon. (You can tell the calc script language was written by a programmer, because only
programmers end sentences with semicolons;) Finally, observe that the second instance of Opening Inventory uses wacky
cases just to show you that calc scripts are indeed not case-sensitive (unless you have explicitly told Essbase to behave
otherwise).
Simple Calculations
One of the simplest calculations you can perform is to tell Essbase to do the calculation for a single member. In a production
system, this is the leanest, meanest calc script you can write, and is used when you want the script to finish in the quickest
possible time.
Calculate Single Members
interRel Consulting
have to do is spell the member name and add a semicolon:
Variance;
www.interrel.com
How do you think you’d modify the calc script to calculate both Variance and Variance %? Hopefully it’s something like this:
Variance;
“Variance %”;
The technique of specifying a member name on a line by itself can be applied to members that do not have formulas but do
have members aggregating into them. Imagine that we have just loaded data in Sample.Basic to the great state of Texas. Now
we want to roll-up the Texas numbers to the top of the Market dimension:
South;
Market;
The nice thing about this script is that it doesn’t bother rolling up totals that haven’t changed. There’s no Texas in the North
(thankfully) so we know we don’t need to modify the totals for North.
(972) 735-8716
It’s also possible to temporarily override the formula in the outline for a member. Let’s return to our earlier example where
we were an evil budget manager trying to set our budgets slightly higher than our actuals so no one could ever meet their
numbers. To do this in a calc script, we just set up an equation with Budget on the left-side of the equal sign:
http://looksmarter.blogspot.com/
Budget = Actual * 1.5;
This script will set the budget to be 50% greater (notice that we’re multiplying times 1.5) than actuals. If you’re really in need
of a raise, you could set the profit of your company to double what it should be:
Profit = Profit * 2;
Forgetting that the above calc script is probably illegal (thanks, Senator Sarbanes, wherever you are), it is interesting in that it
puts the member “Profit” on both sides of the equation. It’s also useful to understand that every time you run it Profit will
Intelligent Calculation
interRel Consulting
Before we go any further, you have to learn the command to turn off intelligent calculation. Intelligent calculation allows
Essbase to remember which blocks in the database need to be calculated based on new data coming in, and which haven’t
been impacted (and don’t need calculation). Intelligent calculation is wonderful when you’re running a default calc.
But (there is always a “but”) intelligent calculation is the devil’s work when you’re running a calc script. Think about the
www.interrel.com
budget calc script from earlier:
The good news is that you don’t have to turn off intelligent calculation for the entire database: you can just tell Essbase to
ignore it during the calc script with this command:
If you want to turn Intelligent Calc on again later in the script (maybe you want a “CALC ALL” command at the end of your
script to calculate just the dirty blocks), include the command SET UPDATECALC ON; and everything past that point will
(972) 735-8716
work “intelligently. We recommend that you include the command to turn intelligent calculation off at the top of every calc
script. If there’s a case where you actually want to use it, go ahead and remove the line on a case-by-case basis. Leaving it out
is courting disaster (and take it from a guy who dated disaster back in high school: you don’t want to be courting her).
Calculate Entire Dimensions
http://looksmarter.blogspot.com/
As we’ve already mentioned, there’s a simple command that you can include in a calc script that tells Essbase to evaluate all
your member formulas and do all of your outline aggregation. While “CALC ALL” is great and powerful, there are times
when you only want to calculate specific dimensions. For instance, what would we do if we just wanted to calculate
Sample.Basic’s Product dimension? We have a new command for this called “CALC DIM” (short for calculate dimension):
This line calculates the Product dimension doing both outline aggregation (such as rolling all the Colas up into the parent
value) and member formulas, if they exist for members in that dimension. If we want to calculate multiple dimensions using
this command (say, Market and Product), just separate them with commas:
interRel Consulting
Remember how we said that “CALC DIM” not only does aggregation but also member formulas? Well, how many member
formulas are there in the Market and Product dimensions? That’s right - none, so “CALC DIM” is wasting time looking for
formulas that you know aren’t there. For dimensions that don’t have formulas, there’s a faster command that only does
aggregation:
www.interrel.com
AGG (Market, Product);
“AGG” can only be used on sparse dimensions. If you have a dense dimension with no formulas that you only want to
Calculate a Subset of Data
While calculating entire dimensions makes you feel very powerful, sometimes you just want to calculate a portion of the
database. For instance, let’s say you just updated your budgets but you didn’t touch actuals. How could you ignore the Actual
member? Well it turns out that there’s an optional argument to the “CALC ALL” command called “EXCEPT”. You use it to
calculate everything except specific dimensions (DIM) or members (MBR). If we didn’t want to calculate actuals, we’d say:
It’s also possible to list multiple members. Say that we didn’t want to calculate Texas and New York (no offense to either
state). We’d list the members separated by commas:
(972) 735-8716
CALC ALL EXCEPT MBR (Texas, “New York”);
http://looksmarter.blogspot.com/
If there’s an entire dimension you don’t want to calculate, replace “MBR” with “DIM”:
The “CALC ALL EXCEPT…” method from above is really used to do the majority of a database and not just a smidgen, so
we need a new command: “FIX” and its sister command “ENDFIX”.
If we just want to calculate a specific member, we put this in double quotes after the “FIX” as such:
interRel Consulting
“FIX” and “ENDFIX” are called sandwich commands because one command is like the top layer of bread and the other as the
bottom with lots of things thrown in between. For instance, we could choose to calculate a few specific accounts:
www.interrel.com
FIX (“Texas”)
Op_Income;
Margin;
ENDFIX
Let’s say you only loaded budgets to next year (which for our purposes, we will call “NY”) for both the states above. Here’s
one way to accomplish that by nesting one “FIX” within another:
(972) 735-8716
FIX (“New York”, “Texas”)
FIX (NY)
Op_Income;
Margin;
ENDFIX
http://looksmarter.blogspot.com/
ENDFIX
While this is a valid method, two “FIX”es are not necessary. You can list members from multiple dimensions within one
“FIX” command, and this is the traditional way to do it:
Using “FIX” commands on sparse dimensions will speed up the performance of your calculations, because it limits the
Point to Another Member
interRel Consulting
While you’re inside a “FIX” command, blocks outside are ignored. What if you want to refer to values from blocks that aren’t
being retrieved into memory? Surely there must be a way, you cry out of quiet desperation. Stop your incessant bawling,
because there is indeed a way. It’s called the cross-dimensional operator. There is no “cross-dimensional operator” symbol on
your keyboard. You type this in by pressing dash followed by a greater than symbol. Its job is to point to another member in
the database and it looks like this:
www.interrel.com
->
FIX (“Texas”)
Net_Rev = Net_Rev->“New York”;
ENDFIX
What exactly is this doing? On the right-side of the equation, we told Essbase to get the value from net revenue for the New
York. The left-side of the equation told it to put the result in net revenue, but which net revenue? Well as you see from the
“FIX”, we told Essbase to only calculate the Texas, so it will put the value into net revenue for the Texas.
Whenever possible, try to avoid cross-dimensional operators. They’re unseemly and slow. For instance, if we had to add
another account, we would have to include it within the “FIX”:
(972) 735-8716
FIX (“Texas”)
Net_Rev = Net_Rev->“New York”;
Op_Expense = Op_Expense->“New York”;
http://looksmarter.blogspot.com/
ENDFIX
We could remove the need for the cross-dimensional operator (called “cross-dim” for short) by pivoting the customer and
account dimensions. That is, we’ll put the account dimension in the “FIX” and the customer dimension inside the “FIX”:
This is much easier to read, and more flexible as well. It’s obvious now that we’re focusing on two specific accounts and
It is also possible to string cross-dims together to point to more and more specific intersections in the database:
interRel Consulting
FIX (“Texas”, CY)
Net_Rev = Net_Rev->NY->“New York”;
ENDFIX
www.interrel.com
Net_Rev->NY->”New York” is called a “member combination. This is how the on-line documentation refers to the
intersections of members via cross-dimensional operators.
Clear Data
The first line (as no doubt you’ll recall from a few pages ago) tells Essbase to operate on all blocks in the database and not
just the dirty blocks. The second line tells Essbase to clear all the blocks in the database.
This script will run extremely quickly, and when it’s finished, it will certainly appear that your database is empty, but if you
look closely, it’s not. Look out on your server’s hard drive and you’ll see that the .PAG file still exists. The reason that
(972) 735-8716
“CLEARBLOCK” runs like a paparazzi after Angelina Jolie is that all it does is blank out the index entries: the pointers to the
corresponding blocks in the page file. Since it can no longer find the blocks, they might as well be blank.
A powerful way to use “CLEARBLOCK” is within a “FIX” statement. We want to blank out our Sample.Basic budget so that
we can try again (our last attempt at the budget was horrendous, let’s be honest), so we write this script:
Remember that “CLEARBLOCK” will clear out entire blocks by removing the pointers, but in Sample.Basic, Budget is in the
Scenario dimension and Scenario is a dense dimension. Since Budget is in every block in the database? Does it remove all the
blocks? No, “CLEARBLOCK” is smart enough to only clear out index entries when the entire block is not being “FIX”ed on.
In cases where just a portion of a block needs to be cleared, “CLEARBLOCK” will read the blocks into memory, clear out the
necessary slices, and write the blocks back out to the page file. As such, “CLEARBLOCK” when used inside a “FIX” on a
dense dimension is noticeable slower.
If you want to blank out a specific dense member, there’s a simpler way than including a “CLEARBLOCK” inside a “FIX”
interRel Consulting
CLEARDATA Budget;
The “CLEARDATA” command allows you to specify a single member (in our case, budget). Do not use this on a sparse
member, because the “CLEARBLOCK” command will always be faster. It is also possible to use a cross-dim operator on the
www.interrel.com
right-side of a “CLEARDATA” command. If we wanted to clear out only our sales budget, we could write:
CLEARDATA Budget->Sales;
CLEARDATA Actual;
CLEARDATA Budget;
This will result in multiple passes through your database since Essbase will not know to clear your data from actual and
budget during a single pass. In this case, go back to using the “CLEARBLOCK” command within a “FIX”:
(972) 735-8716
ENDFIX
At various times, you’ll want to make sure that all of the aggregated blocks in your database are cleared. For instance, if
you’re about recalculate all of the totals in your database, it’s faster if Essbase doesn’t have to read the old totals into memory
http://looksmarter.blogspot.com/
before writing out the new ones. There is an argument you can use in place of “All” called “Upper”:
CLEARBLOCK Upper;
This command will clear all of the upper-level blocks in your database. As before with the “All” argument, “CLEARBLOCK
Upper” can be used within a “FIX” statement. A related argument is “NonInput”:
CLEARBLOCK NonInput;
interRel Consulting
There’s one other way to clear data. You can set a member equal to #Missing:
Budget = #Missing;
www.interrel.com
While this is valid syntax (and we’ve even seen a few sub-par consultants use it), it’s just weird. Stick to “CLEARBLOCK”
or “CLEARDATA”.
Copying Data
“Texas”=“New York”;
This equation copies the Oracle conference data over to the Hyperion conference data. Depending on the settings in your
database, this method may or may not create blocks. The way to be sure you create all necessary blocks is by using the
“DATACOPY” command. It takes two arguments: a member to copy the data from and a member to copy the data to. This
command accomplishes the same thing as the line of code above, but with added comfort that there will be no block creation
hijinx:
DATACOPY “Texas” TO
“New York”;
(972) 735-8716
Both of these methods can be used within a FIX command. Do not use multiple “DATACOPY” commands on dense
members:
In the case of Sample.Basic, this calc script will actually cause two passes through the database since Time is a dense
dimension. In this case, the first method of setting one member equal to another would be better.
IF and Its Other Brother, ENDIF
You learned earlier how easy it is to use the “IF…ENDIF” sandwich commands (technically, they’re functions, but since they
don’t start with @, we like to think of them as commands) inside of a member formula. As a refresher, let’s say we wanted to
interRel Consulting
IF (Defect_Prod_Count = Tot_Prod_Count)
Headcount = 0;
ENDIF
www.interrel.com
Now since this is attached to the Headcount member, it’s technically not necessary to specify “Headcount =” on the third line.
As a matter of policy, we don’t tend to include it, because if the “Headcount” member gets renamed, the member formula
reference to it will not rename. As such, we’d write the formula like this:
Now, if you just type this into a calc script and verify it, you’ll get the following message:
“Error: 1012061 The CALC command [IF] can only be used within a CALC Member Block”
First of all, note that the error message calls “IF” a command, so we were right all along about it not being a real function, on-
line documentation be damned. To translate the error message into semi-English, “IF” can only be used in a member formula.
“Uh, oh,” you say, “but I want to do IFs in a calc script. Is now the time for ritual suicide?”
While it may indeed be, don’t do it over this, because there’s a simple work-around: create a temporary member formula
(972) 735-8716
within your calc script that contains the needed “IF”. You do this by specifying the member that you want to assign the
temporary formula and then include the formula in parentheses. For example:
Headcount
http://looksmarter.blogspot.com/
(
IF ((Defect_Prod_Count = Tot_Prod_Count))
0;
ENDIF
)
Notice “Headcount” at the top and the parentheses surrounding the “IF…ENDIF”. Voila! The calc script will now validate
and run successfully.
Functions
Everything we’ve done up to this point has been focused around using the calculation commands. There are also at least 135
functions that let you do most of the interesting things that Microsoft Excel functions can do (like absolute values, statistical
deviations, and internal rate of return calculations) and many things that Excel functions can not (like return the parent value
interRel Consulting
understood (like “Boolean”). Some, like the mysterious “Miscellaneous” category, are not.
Boolean functions return true or false (@ISMBR). Relationship functions are used to lookup values at intersections elsewhere
in Essbase. Generally, the value being looked up is in the same database, but it doesn’t have to be (the extremely helpful but
slightly slow “@XREF” functions looks to other databases). One of the common needs is to look at the value at a parent
member (@PARENTVAL). Mathematical functions perform standard arithmetic type calculations such as absolute value,
integer, and factorial. The “@VAR” function used in Sample.Basic to calculate variances is, for no apparent reason, a
www.interrel.com
mathematical function. While simple statistical functions like maximum and minimum are found in the Mathematical
category, advanced statistical functions get their own category: Statistical. Member Set functions simply return lists of
members. These are commonly used in “FIX” commands. Say that we wanted to focus on just aggregating products in the
East region. Rather than hard-code all the members in “East,” we could use a member set function called “@CHILDREN”.
Range functions (sometimes called “Financial” functions just to be contrary) operate on a range of members. The most
commonly used range function is “@PRIOR” which looks to earlier members in the outline and “@NEXT” which looks to
Custom-defined functions are whatever you want them to be. It is possible to write your own functions in Java, register them
with Essbase using the MaxL “create function” command, and call them from a calc script as if they were part of the native
language.
(972) 735-8716
Where Do We Go From Here?
Learning everything there is to know about calc scripts would take several years, we’re fairly certain. Rather than drag this
white paper on any further, we’ll point you in the right place for further information: the Essbase Technical Reference. From
http://looksmarter.blogspot.com/
within Administration Services, click on Help>>Information Map. When this comes up, click on Technical Reference to be
taken to a bounty of detailed, look-up information:
interRel Consulting
of the calculation functions contain examples showing you how to use them. While they’re not in depth, they’re plentiful, so
maybe that makes up for it.
Conclusion
www.interrel.com
All types of calculations are possible with Essbase (block storage option databases) using calc scripts. While there is a
learning curve, even mere mortals can perform complex allocations across multiple dimensions or calculate the financial
impact of changes to key drivers and metrics. This whitepaper has introduced you to the basic concepts of calc scripts and
your next step is to get into Essbase and start calculating!