Calc Script 651

Calc Scripts
2002 Hyperion Solutions Corporation. All rights reserved. Hyperion, Essbase, Hyperion Analyst, Hyperion Enterprise, Hyperion Pillar and Hyperion Reporting are registered trademarks of Hyperion Solutions Corporation. Hyperion Solutions, the Hyperion H logo, whats going on, Hyperion Activity Based Management, Hyperion Allocations Manager, Hyperion Analyzer, Hyperion Application Link, Hyperion Customer Interaction Center, Hyperion Enterprise Reporting, Hyperion Financial Management, Hyperion Integration Server, Hyperion Objects, Hyperion Performance Scorecard, Hyperion Planning, Hyperion Reports, Hyperion Sessionizer, Hyperion Spreadsheet Add-in, Hyperion Spreadsheet Toolkit and Hyperion Web Site Analysis are trademarks of Hyperion Solutions Corporation. All other trademarks and company names mentioned are the property of their respective owners. Microsoft is a registered trademark and Windows is a trademark of Microsoft Corporation. IBM, DB2, Lotus, and 1-2-3 are registered trademarks of International Business Machines Corporation. All other brand and product names are trademarks or registered trademarks of their respective holders. No portion of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the purchasers personal use, without the express written permission of Hyperion Solutions Corporation. Notice: The information contained in this document is subject to change without notice. Hyperion Solutions Corporation shall not be liable for errors contained herein or consequential damages in connection with the furnishing, performance, or use of this material. Hyperion Solutions Corporation 1344 Crossman Avenue Sunnyvale, CA 94089 Hyperion Essbase XTD Calc Scripts / 6.5.1 / 10.18.02
Table of Contents
Preface ......................................................................................................... i
Welcome to Hyperion Essbase XTD Calc Script Training! ....................................................... i Course Structure.................................................................................................................................... i What is in the Manual .................................................................................................................... i Conventions ..........................................................................................................................................ii
1 Introduction .......................................................................................... 1-1

Learning Essbase ...............................................................................................................................1-2 Syntax ...........................................................................................................................................1-2 Concepts.......................................................................................................................................1-2 Usage ............................................................................................................................................1-2 Techniques ...................................................................................................................................1-2 Optimization ...............................................................................................................................1-2 Creativity .....................................................................................................................................1-3 Class Overview..................................................................................................................................1-3 Reviewing calculation architecture ..........................................................................................1-3 Building calc scripts ...................................................................................................................1-3 Using calc scripts ........................................................................................................................1-3 Exercise 1-1 Hook, Line and Sinker Company ..........................................................................1-4 Building an OLAP system .........................................................................................................1-4 Unit Summary ...................................................................................................................................1-5
2 Calculation Architecture ..................................................................... 2-1

Types of Calculation .........................................................................................................................2-2 Outline calculations....................................................................................................................2-2 Calc scripts...................................................................................................................................2-2 Outline Calculations .........................................................................................................................2-3 Default Calculation ...........................................................................................................................2-4 Default Calculation Characteristics ................................................................................................2-8 Minimizes Physical Passes Through the Database ................................................................2-8 Allows Users with Access to Specific Calc Scripts to Run the Default Calc ......................2-8 Calc Script Calculations....................................................................................................................2-9 Contents of calc scripts ..............................................................................................................2-9 Reasons for calc scripts ..............................................................................................................2-9 Functions and commands that work only in scripts .............................................................2-9 Calculation Order............................................................................................................................2-10 Data storage ...............................................................................................................................2-10 Dimension types .......................................................................................................................2-10 Dense and Sparse Dimensions ......................................................................................................2-10
Table of Contents
Hyperion Essbase Calc Scripts
Dense dimensions.....................................................................................................................2-10 Sparse dimensions ....................................................................................................................2-10 Dimension tags..........................................................................................................................2-10 Block and Index Structure..............................................................................................................2-11 Generations and Levels ..................................................................................................................2-12 Block Types ......................................................................................................................................2-13 Input blocks ...............................................................................................................................2-13 Non-input blocks ......................................................................................................................2-13 Level zero blocks.......................................................................................................................2-13 Upper-level blocks....................................................................................................................2-13 Calculation Order............................................................................................................................2-14 Dense Calculations..........................................................................................................................2-14 Sparse Calculations .........................................................................................................................2-15 Calculation Order: Dense Dimensions.........................................................................................2-16 Calculation Order: Sparse Dimensions ........................................................................................2-17 Calculation Order: Dynamic Calc Versus Batch .........................................................................2-18 Calculation order exceptions .........................................................................................................2-19 Two-Pass Calculation .....................................................................................................................2-21 Calculation passes ....................................................................................................................2-21 Exercise 2-1: Review Class Files ....................................................................................................2-22 Unit Summary .................................................................................................................................2-24
3 Calculation Script Environment ......................................................... 3-1

Introducing Calc Scripts ...................................................................................................................3-2 Components of calc scripts........................................................................................................3-2 Calc Script Editor and online Help ..........................................................................................3-2 Commands and functions .........................................................................................................3-3 Using Calc Script Editor ...................................................................................................................3-4 Calc Script Editor ........................................................................................................................3-5 Associating an Essbase Outline ................................................................................................3-5 Inserting Functions (Using the Function Button) ..................................................................3-6 Checking the Syntax and Saving and Running the Calc Script ...........................................3-7 Using Essbase Documentation ......................................................................................................3-10 Inserting Functions (From on-line Help) ..............................................................................3-11 Exercise 3-1: Explore Calc Script Editor and Online Help ........................................................3-12 Reviewing Essbase Data Using Spreadsheet Add-in.................................................................3-14 Exercise Procedures..................................................................................................................3-14 Exercise 3-2: Running Calc Scripts................................................................................................3-16 Calc Script Basics.............................................................................................................................3-18 Member Calculations ...............................................................................................................3-18
Hyperion
Table of Contents
Arithmetic Operators ...............................................................................................................3-19 Adding In-line Documentation ..............................................................................................3-20 Introduction to Calc Script Commands and Functions .............................................................3-21 Calc Script Command Categories ..........................................................................................3-21 Essbase Functions Categories .................................................................................................3-22 Exercise 3-3: Member Calculations and Mathematical Operators ...........................................3-28 Unit Summary .................................................................................................................................3-31
4 Calculation Script Commands............................................................ 4-1

Calc Member Blocks..........................................................................................................................4-2 Focusing Calculations.......................................................................................................................4-3 Focusing Calculations Using Fix...Endfix ...............................................................................4-3 Focusing Calculations Using Conditional Statements ..........................................................4-3 Focusing Calculations Using the Cross-Dimensional Operator ..........................................4-3 Calc Script Commands .....................................................................................................................4-4 Summary of Calc Script Commands ..............................................................................................4-4 Detailed Description of Calc Script Commands ...........................................................................4-6 & ....................................................................................................................................................4-6 AGG ..............................................................................................................................................4-7 ARRAY .........................................................................................................................................4-8 CALC ............................................................................................................................................4-9 CALC ALL .................................................................................................................................4-10 CALC DIM.................................................................................................................................4-11 CALC (others) ...........................................................................................................................4-13 CCONV ......................................................................................................................................4-14 CLEARBLOCK ..........................................................................................................................4-15 CLEARDATA ............................................................................................................................4-16 DATACOPY ..............................................................................................................................4-17 FIX / ENDFIX ...........................................................................................................................4-18 IF / ELSE / ELSEIF / ENDIF .................................................................................................4-19 LOOP/ENDLOOP....................................................................................................................4-22 SET ..............................................................................................................................................4-24 SET AGGMISSG........................................................................................................................4-25 SET CACHE...............................................................................................................................4-26 SET CALCHASHTBL...............................................................................................................4-27 SET CALCPARALLEL .............................................................................................................4-28 SET CALCTASKDIMS .............................................................................................................4-30 SET CLEARUPDATESTATUS................................................................................................4-32 SET FRMLBOTTOMUP ...........................................................................................................4-34 SET LOCKBLOCK ....................................................................................................................4-35
Hyperion
Table of Contents
SET MSG ....................................................................................................................................4-36 SET NOTICE..............................................................................................................................4-37 SET UPDATECALC .................................................................................................................4-39 SET UPTOLOCAL ....................................................................................................................4-40 VAR.............................................................................................................................................4-41 Exercise 4-1: Focus Calculations using Fix / EndFix .................................................................4-42 Exercise 4-2: Focus Calculations using If / Else / Endif ...........................................................4-43 Exercise 4-3: Focus Calculations using Cross-Dimensional Operators ...................................4-44 Unit Summary ...........................................................................................................................4-45
5 Math Functions .................................................................................... 5-1

Transforming Values with Math Functions ..................................................................................5-2 Math Function Parameters...............................................................................................................5-3 Summary of Math Functions ...........................................................................................................5-3 Detailed Description of Math Functions........................................................................................5-5 @ABS.............................................................................................................................................5-5 @AVG ...........................................................................................................................................5-6 @EXP.............................................................................................................................................5-7 @FACTORIAL.............................................................................................................................5-8 @INT .............................................................................................................................................5-9 @LN, @LOG, @LOG10 .............................................................................................................5-10 @MAX, @MAXS, @MIN and @MINS ....................................................................................5-11 @MOD ........................................................................................................................................5-12 @POWER....................................................................................................................................5-13 @REMAINDER .........................................................................................................................5-14 @ROUND ...................................................................................................................................5-15 @SUM .........................................................................................................................................5-16 @TRUNCATE ............................................................................................................................5-17 @VAR..........................................................................................................................................5-18 @VARPER ..................................................................................................................................5-19 Exercise 5-1: Using Math Functions .............................................................................................5-20 Unit Summary .................................................................................................................................5-21 ............................................................................................................................................................5-24
6 Boolean Functions............................................................................... 6-1

Testing for Values Using Boolean Functions ................................................................................6-2 Boolean Function Parameters ..........................................................................................................6-2 Summary of Boolean Functions ......................................................................................................6-3 @ISACCTYPE ..............................................................................................................................6-5 @ISANCEST, @ISANCEST........................................................................................................6-6 @ISCHILD, @ISICHILD.............................................................................................................6-7
Hyperion
Table of Contents
@ISDESC, @ISIDESC ..................................................................................................................6-8 @ISGEN ........................................................................................................................................6-9 @ISLEV .......................................................................................................................................6-10 @ISMBR......................................................................................................................................6-11 @ISPARENT, @ISIPARENT ....................................................................................................6-12 @ISSAMEGEN ..........................................................................................................................6-13 @ISSAMELEV............................................................................................................................6-13 @ISSIBLING, @ISISIBLING .....................................................................................................6-14 @ISUDA .....................................................................................................................................6-15 Using Logical Connectors with Boolean Functions ...................................................................6-16 Exercise 6-1: Using Boolean Functions.........................................................................................6-17 Unit Summary .................................................................................................................................6-18 ............................................................................................................................................................6-21
7 Member Set Functions ........................................................................ 7-1

Generating Lists Using Member set Functions .............................................................................7-2 Member Set Function Parameters...................................................................................................7-2 Summary of Member Set Functions ...............................................................................................7-3 @ALLANCESTORS ....................................................................................................................7-6 @ANCEST ....................................................................................................................................7-7 @ANCESTORS ............................................................................................................................7-8 @ATTRIBUTE..............................................................................................................................7-9 @CHILDREN.............................................................................................................................7-10 @CURRMBR ..............................................................................................................................7-11 @DESCENDANTS....................................................................................................................7-12 @GENMBRS ..............................................................................................................................7-13 @IALLANCESTORS.................................................................................................................7-14 @IANCESTORS.........................................................................................................................7-15 @ICHILDREN ...........................................................................................................................7-16 @IDESCENDANTS...................................................................................................................7-17 @ILSIBLINGS ............................................................................................................................7-18 @IRDESCENDANTS................................................................................................................7-19 @IRSIBLINGS ............................................................................................................................7-21 @ISIBLINGS...............................................................................................................................7-22 @LEVMBRS ...............................................................................................................................7-23 @LIST ..........................................................................................................................................7-25 @LSIBLINGS..............................................................................................................................7-26 @MATCH...................................................................................................................................7-27 @MEMBER.................................................................................................................................7-29 @MERGE....................................................................................................................................7-30
Hyperion
Table of Contents
@PARENT..................................................................................................................................7-31 @RANGE....................................................................................................................................7-32 @RDESCENDANTS .................................................................................................................7-33 @RELATIVE ..............................................................................................................................7-35 @REMOVE .................................................................................................................................7-36 @RSIBLINGS .............................................................................................................................7-37 @SIBLINGS ................................................................................................................................7-38 @UDA .........................................................................................................................................7-39 @WITHATTR ............................................................................................................................7-40 @XRANGE .................................................................................................................................7-43 Exercise 7-1: Applying Member Set Functions ...........................................................................7-44 Unit Summary ...........................................................................................................................7-45
8 Relationship Functions ....................................................................... 8-1

Using Relationship Functions .........................................................................................................8-2 Relationship Function Parameters..................................................................................................8-2 Summary of Relationship Functions ..............................................................................................8-3 @ANCESTVAL ...........................................................................................................................8-4 @ATTRIBUTEBVAL ...................................................................................................................8-5 @ATTRIBUTESVAL ...................................................................................................................8-7 @ATTRIBUTEVAL .....................................................................................................................8-9 @CURGEN.................................................................................................................................8-10 @CURLEV..................................................................................................................................8-11 @GEN .........................................................................................................................................8-12 @LEV ..........................................................................................................................................8-13 @MDANCESTVAL...................................................................................................................8-14 @MDPARENTVAL ..................................................................................................................8-15 @PARENTVAL .........................................................................................................................8-16 @SANCESTVAL .......................................................................................................................8-17 @SPARENTVAL .......................................................................................................................8-19 @XREF ........................................................................................................................................8-21 How @XREF works ..................................................................................................................8-21 Defining a Location Alias...............................................................................................................8-24 Exercise 8-1: Applying Relationship Function (@ANCESTVAL) ............................................8-26 Exercise 8-2: Applying Relationship Function (@CHILDREN)................................................8-27 Exercise 8-3: Applying Relationship Function (@XREF) ...........................................................8-28 Unit Summary .................................................................................................................................8-30
9 Range and Financial Functions.......................................................... 9-1

Using Range and Financial Functions............................................................................................9-2 Range and Financial Function Parameters ....................................................................................9-2
Hyperion
Table of Contents
Summary of Range and Financial Functions ................................................................................9-3 @ACCUM.....................................................................................................................................9-5 @AVGRANGE.............................................................................................................................9-6 @COMPOUND ...........................................................................................................................9-7 @COMPOUNDGROWTH.........................................................................................................9-8 @CURRMBRRANGE .................................................................................................................9-9 @DECLINE ................................................................................................................................9-12 @DISCOUNT.............................................................................................................................9-14 @GROWTH................................................................................................................................9-15 @INTEREST ...............................................................................................................................9-16 @IRR ...........................................................................................................................................9-17 @MAXRANGE ..........................................................................................................................9-19 @MAXSRANGE ........................................................................................................................9-20 @MDSHIFT................................................................................................................................9-22 @MINRANGE ...........................................................................................................................9-23 @MINSRANGE .........................................................................................................................9-24 @NEXT .......................................................................................................................................9-26 @NEXTS .....................................................................................................................................9-27 @NPV..........................................................................................................................................9-28 @PRIOR ......................................................................................................................................9-29 @PRIORS....................................................................................................................................9-30 @PTD ..........................................................................................................................................9-31 @SHIFT.......................................................................................................................................9-32 @SLN ..........................................................................................................................................9-33 @SUMRANGE...........................................................................................................................9-34 @SYD ..........................................................................................................................................9-35 Exercise 9-1: Applying Range Functions (@PRIOR) ..................................................................9-36 Exercise 9-2: Applying Financial Functions (@IRR) ...................................................................9-37 Unit Summary .................................................................................................................................9-38
10 Allocation Functions ....................................................................... 10-1

Using Allocation Functions ...........................................................................................................10-2 Common Parameters ......................................................................................................................10-2 Summary of Allocation Functions ................................................................................................10-5 @ALLOCATE ............................................................................................................................10-6 @MDALLOCATE .....................................................................................................................10-8 Exercise 10-1: Applying Allocation Functions ..........................................................................10-10 Unit Summary ...............................................................................................................................10-11
11 Forecasting Functions .................................................................... 11-1

Using Forecasting Functions .........................................................................................................11-2
Hyperion
Table of Contents
Forecasting Function Parameters..................................................................................................11-2 Summary of Forecasting Functions ..............................................................................................11-3 @MOVAVG ...............................................................................................................................11-4 @MOVMAX ...............................................................................................................................11-6 @MOVMED ...............................................................................................................................11-8 @MOVMIN ..............................................................................................................................11-10 @MOVSUM .............................................................................................................................11-12 @MOVSUMX...........................................................................................................................11-14 @SPLINE ..................................................................................................................................11-15 @TREND ..................................................................................................................................11-17 Exercise 11-1: Applying Forecasting Functions ........................................................................11-21 Unit Summary ...............................................................................................................................11-22
12 Statistical Functions........................................................................ 12-1

Generating Lists Using Statistical Functions...............................................................................12-2 Statistical Function Parameters .....................................................................................................12-2 Summary of Statistical Functions .................................................................................................12-3 @CORRELATION.....................................................................................................................12-4 @COUNT ...................................................................................................................................12-6 @MEDIAN .................................................................................................................................12-7 @MODE......................................................................................................................................12-9 @RANK ....................................................................................................................................12-11 @STDEV ...................................................................................................................................12-13 @STDEVP.................................................................................................................................12-15 @STDEVRANGE.....................................................................................................................12-17 @VARIANCE ..........................................................................................................................12-19 @VARIANCEP ........................................................................................................................12-21 Exercise 12-1: Applying Statistical Functions ...........................................................................12-23 Unit Summary ...............................................................................................................................12-24
13 Date and Time Functions ................................................................ 13-1

Using Date and Time Functions....................................................................................................13-2 @TODATE .................................................................................................................................13-3 Exercise 13-1: Applying the Date & Time Function ...................................................................13-5
14 Miscellaneous Functions ................................................................ 14-1

Using Miscellaneous Functions.....................................................................................................14-2 Summary of Miscellaneous Functions .........................................................................................14-2 @CALCMODE ..........................................................................................................................14-3 @CONCATENATE.................................................................................................................14-11 @NAME....................................................................................................................................14-12
Hyperion
Table of Contents
@SUBSTRING..........................................................................................................................14-13
15 Tips, Tricks and Techniques........................................................... 15-1

Calc Script Design Considerations ...............................................................................................15-2 IF or FIX......................................................................................................................................15-2 Dense calculations before sparse calculations ......................................................................15-2 Two-pass calculations ..............................................................................................................15-2 Intelligent Calcs.........................................................................................................................15-2 Blocks on equations ..................................................................................................................15-2 Approaching Calc Scripts Solutions .............................................................................................15-3 Business problem ......................................................................................................................15-3 Affected data .............................................................................................................................15-3 Rollup considerations ..............................................................................................................15-3 Individual calculations ............................................................................................................15-3 Communication ........................................................................................................................15-3 IF vs FIX ............................................................................................................................................15-4 Exercise 15-1: Isolating Data Using IF or FIX ..............................................................................15-5 Exercise 15-1b: Isolating Data Using IF or FIX............................................................................15-7 Simpler is Usually Better................................................................................................................15-8 Exercise 15-2: Allocations.............................................................................................................15-10 Exercise 15-3: Product Share Analysis .......................................................................................15-12 Unit Summary ...............................................................................................................................15-14
A Suggested Answers ............................................................................A-1

Possible Solutions .......................................................................................................................... 1
B Essbase Outlines ................................................................................B-1

Sample - Basic ................................................................................................................................... B-2 Calc - HLandS1 ................................................................................................................................. B-5 Calc - HLandS2 ............................................................................................................................... B-11 Calc - COGS .................................................................................................................................... B-17
Hyperion
Table of Contents
10
Hyperion
Preface
Welcome to Hyperion Essbase XTD Calc Script Training!
Before you begin, please take a moment to review this section. The preface presents an overview of: How the class is structured An explanation of the writing conventions used in this manual
Course Structure
What is in the Manual

This manual is your guide and reference to learning fundamental tasks and concepts for creating Calc Scripts. It contains: Step-by-step procedures Hands-on exercises Written reviews to check your understanding
H H H H H H H H H
The Hyperion Essbase XTD Calc Script (Calc Scripts) training is a 2-day, instructor-led training class. In this course, the instructor presents a topic conceptually by explaining its purpose, demonstrating how it works and guiding the students through the exercise. This explain and do procedure has proved to be a successful method.
A list of the manuals components:

A Table of Contents for easy reference A Preface containing: An overview of what is in the manual A description of the writing conventions Chapters containing: An introductory objectives page Step-by-step procedures for referencing during and after class Detailed descriptions for each Essbase Calc Script command and function Exercises that encourage you to practice what was just presented A Check Your Understanding section to reinforce concepts An appendix containing suggested solutions for the exercises
Preface
Conventions
Certain formatting styles are used in this manual to help the student better understand the subject matter and the step-by-step procedures. This section details these conventions. The descriptions of the individual functions and commands will demonstrate parameters passed to the commands. If the parameter is enclosed in square brackets [], this indicates that the parameter is optional. If two parameters are separated by the filter symbol |, this indicates one item or the other. Common parameters, which appear in many of the commands or functions for a particular section are described in the beginning of the chapter for that command/function type. Individual sections are noted with a helvetica/bold heading, as in this example:
Setting User Defaults

Step-by-step procedures begin with the steps graphic and a heading that defines the procedure, such as:
ii
H H H H H H H H
To set user defaults:

Tables are used to define software components, as in this example:
Accounts Accounts store and identify data for each name and category in Hyperion Enterprise. Accounts are organized into Account Groups such as income statement, balance sheet, etc. Accounts can contain two levels of subaccount detail. Periods represent a specific segment of time for each data category based on that categorys frequency.
Time Periods
Screen captures appear frequently and further clarify a topic. Notes, prefaced by , provide related information, tips, common mistakes or cautions about the current topic. Exercises appear throughout the chapter to reinforce a new concept or task. Some exercises contain two separate versions:
Hyperion
Preface
Since most of the exercises for this course require the creation of Calc Scripts, they are presented as combined versions, indicated with the Express/Local icon,
The end of each exercise is indicated by an end of exercise icon, . Throughout the step-by-step procedures and exercises, a different font is used to accentuate text. The following rules apply: For Windows procedures, text to be typed, options to be selected, names of files and modules and menu selections appear in Helvetica, Narrow Bold, as in the following examples: Select Clear Profile. To clear the profile, click Yes. For UNIX or DOS procedures and for Calc Script examples, text to be typed appears in Courier, as in the following example: Change to the /home/essbase/app directory.
Hyperion
H H H H H
1) 2) 1)
The step-by-step procedures present the action to be performed. When needed, a result follows. This action/result format confirms the procedure and reinforces the student of the correct action. When available, icons are used to help identify an object or task, as in this example: Click Properties, .
The letter x is used to refer to the drive letter in file names. For example, the file is located in the directory, x:\Program Files. Your instructor will provide the appropriate drive letter for x. Keystrokes that are combined, such as pressing the Ctrl + Enter keys, appear as follows: [Ctrl] + [Enter] In the example above, you would press the Enter key while holding down the Ctrl key.
iii
Preface
iv
Hyperion
1
Introduction
Chapter Objectives
By the end of this chapter, you will be able to: Describe the process an application designer or database administrator follows when learning an application such as Essbase XTD Preview course content, course objectives and course activities Describe the organization, Hook Line and Sinker, which is used in the exercises for the course
Introduction
Learning Essbase
When learning an application such as Essbase, you follow a set of steps. These steps follow the natural progression in learning any complex system. In many ways, learning Essbase is like learning any language.
Creativity Optimization Techniques Usage Concepts Syntax
Syntax
You learn the combination of words, or the syntax, of Essbase to identify the parts of the system.
Concepts
You relate words by learning about Essbase concepts. The combination of Essbase syntax and concepts provides you with the basic building blocks for creating an Essbase solution.
Usage
The ability to conceptualize solutions is referred to as usage. This course is designed to provide usage examples.
Techniques
After you are comfortable with syntax, concepts, and usage, you concentrate on learning the techniques of using Essbase. As you improve your techniques, your application of Essbase improves accordingly.
Optimization
Perhaps one of the most important steps in learning Essbase is how to optimize the techniques that make up an application. Most users learn these optimization techniques from more expert users; others must learn them by trial and error.
1-2
Hyperion
Introduction
One of the strengths of using Essbase is that you can build a scalable online analytical processing (OLAP) system. A small efficient system usually retains optimum performance when scaled to a larger environment with more users and more data.
Creativity
After you have mastered syntax, concepts, usage, techniques,and optimization, you can develop your own creative approaches. Although classroom training helps foster creativity, it is experience in building applications that enables you to do so effectively. The only way you can be creative is through mastering the basics.
Class Overview
During this class, you explore the various uses of calculations, and, by working with various examples, you acquire techniques that you can use in your working environment.
Reviewing calculation architecture

You begin by reviewing calculation architecture in Essbase databases. Because you are already familiar with the syntax and concepts of outline calculations, you concentrate on the architecture of a database to determine how calculations proceed.
Building calc scripts

Not all calculations can be achieved with an outline calculation. You now look at the basics of building a calc script: using the editor, testing and debugging scripts. You also explore a variety of built-in functions provided by Essbase.
Using calc scripts

Throughout the class, you examine solutions to common analytical database problems. You develop and test calc scripts that provide appropriate results and efficient database operations.
Hyperion
1-3
Introduction
Exercise 1-1 Hook, Line and Sinker Company

In this exercise, you review the history and description of the Hook, Line and Sinker Company. This company forms the framework for the practical exercises presented throughout the course. Hook, Line and Sinker Company began as a sideline for walnut farmer Claude Smith in West Point, California. Smith became famous throughout Calavares County in the 1930s for his excellent lures, which he sold through the local general store, Sierra Mercantile. As the fame of Smith's lures spread throughout northern California, his nephew Bob decided to start a company to market not only lures, but a wide variety of fishing tackle to sporting goods stores. By the early 1950s, the original company incorporated as Hook, Line and Sinker Company and became a wholesaler of fishing tackle throughout the United States to premium sporting goods outlets. By 1985, it was clear that Hook, Line and Sinker could no longer operate as a small, family-owned business. The company invested in PCs to control inventory, sales, and costs. Within five years, it was clear that these standalone systems were no longer adequate to manage the ever-growing business. A client-server solution was implemented with some success. However, by 1998 the next generation of Smiths believed that they needed greater control and started looking for analytical tools that could help Hook, Line, & Sinker manage its business more successfully. One of the third generation of Smiths decided to invest in a new breed of system: an OLAP system.
Building an OLAP system

In working with a consultant, the following immediate analytical needs were identified: product mix market share cost adjustment forecast and budgeting cost allocation The management of Hook, Line, & Sinker realized that these were only the beginning of their analytical requirements. Their search for a tool that would take advantage of existing data and for additional analysis led them to choose Essbase.
1-4
Hyperion
Introduction
Unit Summary
The process of learning Essbase follows a pattern common to that of learning most systems. As you master each learning levelsyntax, concepts, usage, and techniques, you progress towards the ultimate goal of efficiently and accurately calculating a database. To provide accurate data, appropriate data transformation, and maintainability of data, you must consider a variety of factors. The basic goal of this course is to provide practical tools that will assist you in building a successful Essbase layer in an OLAP system. Efficient and accurate calculations provide required data manipulation. Using the builtin functionality of Essbase reduces development time and processing time. During this course, you use the Hook, Line and Sinker (HLandS) database for exercises. The database has a dual purpose. It provides a reasonable, real-world example of a moderately complex Essbase database. It enables experimentation with various calc scripts.
Hyperion
1-5
Introduction
1-6
Hyperion
2
Calculation Architecture
Chapter Objectives
By the end of this chapter, you will be able to: Describe the two types of calculations (outline and calc script) available in Essbase XTD Explore data storage options that affect calculation order List the levels of calculation order Explore the need for two-pass calculations and describe the differing behavior when used in outline calculations and calc scripts Review the sample database that is used during class exercises
Types of Calculation
Hyperion Essbase provides two basic methods of calculation. Outline calculations are placed directly in the outline, and usually are run by invoking a default calc script. Calc scripts are generally more specific, calculating a portion of the database or performing special analytical tasks.
Outline calculations
Outline calculations are the simplest method of calculating the database. Outline calculations are dependent on the structure of the database outline. You use outline calculations when the database has been updated, data must be consolidated, and formulas must be recalculated. Outline calculations are invoked through a default calc script. When working with large databases, you can use an alternative default calc script to aggregate only those portions of the database that have been updated.
The default calculation simply runs through the outline. If Intelligent Calculation is invoked, however, the calculation is limited to calculate for updated data, only.
Calc scripts
You use calc scripts for more specialized calculations. These include calculating a portion of the database, or performing calculations using commands that do not work in the outline. In conjunction with outline settings, a calc script uses a combination of functions, commands and formulas to answer a specific question.
2-2
Hyperion
Outline Calculations
Outline calculations are based on relationships between members in the database outline and on any formulas that you have attached to members in the outline. For example, the values stored for New York, Massachusetts, Florida, Connecticut and New Hampshire are added (aggregated) to calculate the total for East. Each region - East, West, South and Central - are in turn rolled up to calculate the total for Market. It is best to place calculations in the outline, where possible, for the following reasons: They are easier to understand in the outline than in a calc script. If the calculations can be expressed as unary relationships in the outline hierarchy using outline consolidation operators (+, -, /, *, %), they execute much faster than in formulas. There is no significant difference in efficiency between formulas in the outline and formulas in a calc script.
Hyperion
2-3
Default Calculation
The default calculation for a database is CALC ALL. CALC ALL calculates the database by evaluating the outline from top to bottom, executing rollups and formulas in the order in which they are encountered. The execution order is automatically optimized by Essbase when CALC ALL is used. You run the default calculation from an Application Manager menu, from Esscmd or from a calc script containing the command CALC ALL.
To connect to the Essbase Server:

1) 2) Ensure Hyperion Essbase OLAP Server and Hyperion Essbase Application Manager are running. To connect to the server from the Essbase Application Manager main menu, select Server / Connect. In the Essbase System Login window, select the desired Server, and type a valid Username and Password. Click OK. The server window displays:
3)
To calculate a database in Essbase Application Manager:

1) 2) Connect to the Essbase Server. In the Server window, select the Application from the drop-down list. The databases for the selected application display in the Databases list. In the database list, select the database to be calculated.
3)
2-4
Hyperion
Hyperion Essbase Calc Scripts 4)
From the main menu, choose Database / Calculate. The Calculate Database window displays:
5)
Select the Calc Script that you want to execute. To choose the default calculation, select (Default). Click OK. A status window displays during the computation. When the calculation completes, the status window disappears.
You may specify any calc script as the default calculation. If you use a specific script rather than CALC ALL, you use Essbase Application Manager or Esscmd to set the script as the default.
To view the default calc settings:

1) 2) Connect to the Essbase Server. In the Server window, select the Application from the drop-down list. The databases for the selected application display in the Databases list. In the database list, select the database to be calculated.
3)
Hyperion
2-5
Calculation Architecture 4)
From the Essbase Application Manager main menu, choose Database / Set Default Calc. The Set Default Calc window displays:
The default calculation can be either a stored calc script procedure, identified by the Use Calc Script Object option; or the calc script that is stored in the text box associated with the Use String option.
From the Set Default Calc window, you can select one of two ways to change the default calc script. You may type an alternate calc script in the text box associated with the Use String option, or you may select an existing calc script file.
To change the default calc settings by typing in a new calc script:

1) 2) 3) From the Set Default Calc window, select Use String. Type commands into text box associated with the Use String option in the Set Default Calc window. Click OK.
To change the default calc settings by selecting an existing calc script:

1) 2) From the Set Default Calc window, select Use Calc Script Object. From the drop-down list, select the calc script that you wish to use as the default calc script.
2-6
Hyperion
Hyperion Essbase Calc Scripts 3) Click OK.
If you use a calc script object in place of the default calc, the calc script is copied into the text box. If you change the original calc script, the calc script in the Set Default Calc window is not automatically updated.
Hyperion
2-7
Default Calculation Characteristics

You need to understand the behavior of a default calculation and consider performance.
Minimizes Physical Passes Through the Database

Even when two-pass calculations are specified, Essbase attempts to perform calculations in a single pass of the database. The following chart summarizes the number of passes for each combination of dimensions tagged as Accounts and each tagged as Time:
Accounts Dense Sparse Dense Dense (and is the only dense dim) Dense Sparse Sparse Time None None Dense Sparse Sparse Sparse Sparse Passes 1 2 1 1 2 2 2
Allows Users with Access to Specific Calc Scripts to Run the Default Calc
Users who have calc access (the ability to run calc scripts) also have access to the default calc. If you do not want users to calculate the database using the default calc script, create a default calc script that contains only a single semicolon (;). This prevents users from actually calculating the database and does not cause an error. You may want to prevent users from calculating the full database because of time and performance factors, as well as because of data consistency considerations.
2-8
Hyperion
Calc Script Calculations

Calc scripts let you to control precisely the method and order of calculations. You can calculate only a portion or all of the data. You can calculate specific outline rollups or formulas in a calc script. You can control the order in which calculations are performed. You can also evaluate and control the effects your calc script has on block I/O.
Contents of calc scripts

A calc script can be very simple, containing only a single statement, such as CALC ALL, or a single function that is not available in an outline calculation, such as CCONV. Many calc scripts, however, contain a series of steps that are dictated by logical tests or by the calculation of subsets of data.
Reasons for calc scripts

You should use calc scripts instead of outline calculations in the following situations: Complex logic is required Calculations focus on a subset of the database Specific analytical functions are required Infrequently used calculations, such as year-end processing, that require standard scripts are needed
Functions and commands that work only in scripts

Some functions are not valid in an outline, particularly functions that calculate only a portion of the database: Currency conversion using Hyperion Essbase Currency Conversion Iterative processing, such as solving simultaneous equations Data management commands, such as DATACOPY and CLEARBLOCK The FIX command, used to calculate subsets of data Temporary variables
Hyperion
H H H H H H H H H
2-9
Calculation Order
Default calculation order is dependent on how data is stored in the database.
Data storage
To predict calculation order, you must understand how Essbase stores data. The next few pages present a review of the basic concepts of data storage. These concepts are vital to understanding both outline calculations and calc scripts.
Dimension types
You also review the order in which Essbase calculates each dimension type: Dense calculations Sparse calculations
Dense and Sparse Dimensions

When an Essbase database is designed, a crucial issue is the designation of dimensions as dense or sparse.
Dense dimensions
When you examine data, you see that some dimensions are likely to contain large amounts of data. For example, every product sold has sales information, cost of goods sold information, and related expense. Therefore, the dimension that contains the members of Sales, COGS and Expenses would be a likely candidate to tag as Dense. Data blocks are made up of dense dimensions. Also, these dimensions tend to be fairly static.
Sparse dimensions
Sparse dimensions are used when the demographics of data is likely to be thinly spread. For example, you may not sell every product in every region. Thus, a product dimension and a market dimension would likely be sparse in this scenario. Index nodes are made up of sparse dimensions. Sparse dimensions tend to change more frequently than dense dimensions.
Dimension tags
Two special types of dimensions are tagged as Accounts and Time. They have special processing characteristics, such as Dynamic Time Series and Expense Reporting.
2-10
Hyperion
Block and Index Structure

Essbase uses two types of internal structures to store and access data: data blocks index blocks
Hyperion
H H
The data block contains data cells (the actual values). Data cells are defined by the dense dimensions of the database combinations. The number of cells in each block equals the product of all stored members of dense dimensions. To specify data blocks, each block has an associated index node, which corresponds to the blocks combination of sparse members. As Essbase processes data, through calculations, data loads or data retrievals, index nodes and data blocks are read from a disk and brought into memory. You can use various Essbase settings to define the amount of memory allocated for processing index nodes and data blocks.
2-11
Generations and Levels

Essbase vocabulary uses two methods for referencing the position of a member within a hierarchy: generation level.
2-12
H H
Generations are numbered from the top of the hierarchy, with the dimension name being Generation 1. Levels are numbered from the bottom of the branches of the hierarchy, with the lowest level being Level 0. Level 0 (leaf level) members have no members below them. Hierarchies, such as the example above, can be asymmetric. Therefore, an upper-level member such as East may be Level 2 when traversing the branch to cities (New York City, Albany, and Buffalo). But, it becomes Level 1 when traversing the branch to the states that have no city members: Massachusetts, Florida, Connecticut and New Hampshire. The order of calculation within a dimension follows the level numbering. Each dimension branch, starting at Level 0, is calculated up to the highest level. After all lower levels of a hierarchy are calculated, the dimension name, if it is not tagged as Label Only, is consolidated.
Hyperion
Block Types
Block types are determined by the way in which the block was created and by the level of the sparse combination members that define the block.
Input blocks
Input blocks are created by loading data to cells in the block; for example, a data load with rules or a spreadsheet lock and send. Input blocks can be level zero or upper-level blocks.
Non-input blocks
Non-input blocks are created through calculations. For example, the block East->Cola was created during a sparse calculation process. Before calculation, the block did not exist. Therefore, all data in the block is the result of calculation.
Level zero blocks

Level zero blocks correspond to level zero members of sparse dimensions. For example, New York->Cola is a level zero block because New York and Cola are leaf-level members of their respective sparse dimensions, Markets and Products.
Upper-level blocks
Upper-level blocks correspond to one or more sparse members that are not level zero. Markets->Cola is an upper-level block. Although Cola is a zero level member from the Products dimension, Markets is the top member of the Markets dimension. Thus, Markets->Cola is considered upper-level.
Hyperion
2-13
Calculation Order
When you perform a default calculation (CALC ALL) on your database, Essbase calculates dimensions in a predetermined order. If a database includes a dimension tagged as Accounts and a dimension tagged as Time and if formulas are applied to members on the Accounts dimension, Essbase calculates in the following order: First, the dimension tagged as Accounts, whether dense or sparse Second, the dimension tagged as Time, whether dense or sparse Third, other dense dimensions (in the order that they are displayed in the database outline) Fourth, other sparse dimensions (in the order that they are displayed in the database outline) Fifth, two-pass calculations (if selected in the database settings) Note: Two-pass calculations are sometimes calculated when the Accounts dimension is calculated.
Dense Calculations
Dense members are calculated first when using CALC ALL. Dense combination cells inside each block are then calculated and filled. Dense calculations proceed one block at a time until all existing blocks are calculated.
2-14
Hyperion
Sparse Calculations
In a default calc, after dense dimensions have been calculated for all existing blocks, sparse dimensions are calculated to consolidate level zero blocks into newly created upper-level blocks. Because all data cells in the original level zero blocks have been calculated, the newly created upper-level blocks (East->Cola) complete calculation in one step.
Each cell in the consolidated block corresponds to the aggregate total of its counterpart cells in the zero level blocks. For example, Jan->Sales->Actual for East->Cola is 30 because Jan ->Sales->Actual for Vermont->Cola is 10 and Jan->Sales->Actual for New York->Cola is 20.
Hyperion
2-15
Calculation Order: Dense Dimensions

In this outline, the numbers indicate the order of calculation. Notice the following: Calculations start at the lowest level of a branch. When the end of a sub-branch is reached, calculations move up to the next level.
For example, for the sample outline, calculations occur in the following order: Within the Margin branch - Sales and then COGS Within the Profit branch - Margin and then Expenses Within the Measures dimension - Profit, then Inventory and then Ratios. Shared members are pointers to a stored value. If you perform a calculation on a shared member, the calculation is actually performed on the data in the stored location. In an outline, it is recommended to place shared members below the physically stored members.
2-16
Hyperion
Calculation Order: Sparse Dimensions

Sparse calculations obey the same sequential rules as dense calculations. One sparse dimension is traversed while one member of another dimension remains constant.
Calculation order for the above outline is as follows:

Anchor Dimension A Cola Traversed Dimension 1 2 3 4 B Root Beer 1 2 3 4 And so on East West South Markets East West South Markets
Hyperion
2-17
Calculation Order: Dynamic Calc Versus Batch

The calculation order of Dynamic Calc members differs from batch (outline) calculation order. Batch calculation order: Dimension with Accounts tag Dimension with Time tag Dense dimensions in outline order Sparse dimensions in outline order Two-pass calculations
Dynamic Calc order: Sparse dimensions Dynamic Time Series calculations Dimension with Accounts tag Dimension with Time tag Dense dimensions in outline order Two-pass calculations
2-18
Hyperion
Calculation order exceptions

If the dimension tagged as Time is sparse and includes Dynamic Time Series members, then the Time dimension is chosen first for the sparse calculation. Because the calculation order of batch calculations differs from the calculation order of dynamic calculations, tagging certain members as Dynamic Calc can create errors. Consider the following outline:
Sparse Dense
A batch calculation first calculates the leaf blocks of the dense dimensions. Then the upper-level blocks (East) are calculated by aggregating along the sparse dimension. The following results are produced:
Batch calculation results were calculated in this order:

1. 2. 3. 4. 5. New York - Total Units Florida - Total Units East - Units per Container East Containers East - Total Units 10*2 = 20 10*1 = 10 10+10 = 20 2+1 = 3 20+10 = 30
If you tag East and Total Units as Dynamic Calc and run a calculation, you will receive different results:
Hyperion
2-19
Since Dynamic Calculation calculates along the sparse dimensions before calculating the order of calculation is:
1. 2. 3. 4. 5. East - Units per Container East - Containers New York - Total Units Florida - Total Units East - Total Units 10+10 = 20 2+1 = 3 10*2 = 20 10*1 = 10 20*3 = 60
Thus, you need to be very careful in deciding when and how to apply Dynamic Calc tags.
You can tag any Dynamic Calc or Dynamic Calc and Store member as two-pass, even if the member is not in a dimension tagged as Accounts.
2-20
Hyperion
Two-Pass Calculation
Two-pass calculation is used when data must be calculated twice: once during rollup and once after rollup is complete. Two-pass calculation is also used when member calculations reference other member calculations that are not yet complete. In the example below, when a two-pass calculation is run, the dimension tagged as Accounts is calculated first. Then, the dimension tagged as Time is calculated and the data is rolled up across the Time dimension.
Calculation passes
During the first pass, calculations made at the lowest level (months) are correct, but the rolled-up calculation for percent is not correct:
Accounts Profit Sales Profit% (NOT tagged as two-pass) Jan 100 1000 10% Feb 100 1000 10% Mar 100 1000 10% Qtr1 300 3000 30%
The second pass corrects the percentage calculation:

Accounts Profit Sales Profit% (tagged as two-pass) Jan 100 1000 10% Feb 100 1000 10% Mar 100 1000 10% Qtr1 300 3000 10%
Two-pass calculations work only on the Accounts dimension. Although you can tag members in other dimensions as two-pass, the tag is ignored.
Hyperion
2-21
Exercise 2-1: Review Class Files

In this exercise, you review the Essbase database outlines used in future exercises. You also review a typical sample spreadsheet used in one exercise. For this exercise, you use the following files:
Database CALC:HLandS1 CALC:HLandS2 CALC:COGS Spreadsheet SS_Demo.xls
1) 2) 3)
Ensure that the Essbase OLAP server is running. Start Essbase Application Manager. From the Essbase Application Manager main menu, select Server / Connect. The Essbase System Login dialog displays. In the Server textbox, type Localhost. In the Username field, type Trnadmin. In the Password field, type hyperion. Click OK. The Localhost server window displays. In the Application field, select CALC. From the list of available databases, select HLandS1. Click Open. Expand each of the dimensions to obtain an understanding of the structure of the HLandS1 database. Close the HLandS1 outline. From the list of available databases, select HLandS2. Click Open. Expand each of the dimensions to obtain an understanding of the structure of the HLandS2 database. The major difference between these two outlines is the design of the Scenario and Time dimensions. HLandS2 also contains a few more members in the Accounts dimension, particularly under Statistics. HLandS2 also contains an attribute dimension (IntroDate). Close the HLandS2 outline.
4)
5) 6) 7) 8) 9) 10)
11)
2-22
Hyperion
Hyperion Essbase Calc Scripts 12) 13)
From the list of available databases, select COGS. Click Open. Expand each of the dimensions to obtain an understanding of the structure of the COGS database. The COGS database is much simpler that HLandS1 and HLandS2. It contains the (percentage) cost of goods for each product. It is used for one exercise that applies the @XREF function. Close the COGS outline.
14)
Review a Typical Excel Workbook

Each exercise uses an associated Excel workbook that usually includes: A sheet containing data used to initially populate the Essbase database. A sheet containing the layout of the data that to be retrieved after executing the Calc Script you created to match the requirement for this exercise.
15) 16) 17)
Launch Microsoft Excel. Open the Excel workbook: SS_Demo found in the <x>:\Hyperion\Essbase\App\Calc directory. select the Lock&Send tab. After clearing the database, you use Essbase / Lock and Essbase / Send to initialize the databases content. select the Calc&Retrieve tab. You use Essbase / Calculate to run your Calc Script. You use Essbase / Retrieve in this worksheet to obtain the updated data and to confirm the correct operation of your Calc Script. Close the Excel workbook.
18)
19)
Hyperion
2-23
Unit Summary
You must understand the structure of the Essbase database and the order in which the database is calculated before you can understand calculations. The simplest form of database calculations are those contained in the database outline. Outline calculations consist of database consolidations and member calculations. These calculations are used to ensure that the databases present consistent data to all users. An Essbase database is made up of dense and sparse dimensions. Dense dimensions contain data, and sparse dimensions act as index pointers to the data blocks of the dense dimensions. A dimension is often hierarchical in nature. You can use either of two methods to describe the calculation position in the hierarchy. Generations start at the top of the outline and count forward or down, moving from left to right. Levels work in the opposite direction, moving from right to left. The lowest level of the hierarchy-the leaf level-is Level 0. As you move up the hierarchy, the number increases. The Generation and Level positions are used frequently in calc scripts. The order of calculation is determined by dimension type. Dense dimensions are calculated before sparse dimensions. A dimension tagged as Accounts is calculated first; a dimension tagged as Time is calculated second. All remaining dense dimensions are calculated in the order in which they appear in the outline, followed by sparse dimensions.
2-24
Hyperion
Check Your Understanding

Now that you have completed the chapter, check your understanding by responding to the following questions: 1) What is the default calculation order when performing a database consolidation?
2)
When would you use a calc script instead of the default calc?
3)
Why would you use Two-pass calculation?
Hyperion
2-25
2 Calculation Architecture Check Your Understanding Solutions

1)
What is the default calculation order when performing a database consolidation? If a database includes a dimension tagged as Accounts and a dimension tagged as Time and if formulas are applied to members on the Accounts dimension, Essbase calculates in the following order: First, the dimension tagged as Accounts, whether dense or sparse Second, the dimension tagged as Time, whether dense or sparse Third, other dense dimensions (in the order that they are displayed in the database outline) Fourth, other sparse dimensions (in the order that they are displayed in the database outline) Fifth, two-pass calculations (if selected in the database settings) When would you use a calc script instead of the default calc? You should use calc scripts instead of outline calculations in the following situations: Complex logic is required. Calculations focus on a subset of the database. Specific analytical functions are required. Infrequently used calculations, such as year-end processing, that require standard scripts are needed. Why would you use Two-pass calculation? Two-pass calculation is used when data must be calculated twice: once during rollup and once after rollup is complete. Two-pass calculation is also used when member calculations reference other member calculations that are not yet complete.
2)
3)
2-26
Hyperion
3
Calculation Script Environment
Chapter Objectives
By the end of this chapter, you will be able to: Describe the reasons for using calc scripts Demonstrate how to use the Calc Script Editor and online Help to build calc scripts Describe the use of member calculations and arithmetic operators List the types of commands and functions available to create calc scripts Create and execute a simple calc script Add in-line documentation to a calc script
Introducing Calc Scripts

As powerful as outline calculations are, they do not take full advantage of the OLAP strengths of Hyperion Essbase. Outline calculations provide a baseline for all analysis activities, ensuring that every user starts with the same data. Calc scripts extend the analytical functionality of Essbase beyond the pro forma report that is presented when viewing a simple Essbase spreadsheet. You create calc scripts to solve more complex and unusual analytical problems, to calculate specific portions of the database and to develop business scenarios that are not used in every day reporting.
Components of calc scripts

The Essbase calc script language possesses many of the calculation components with which programmers are familiar. The language provides not only for a variety of calculation functions but also for a variety of Boolean tests and for program control (if-tests and looping). With the exception of a few commands and looping, all functions and calculations that are used in calc scripts can also be used in an outline. Calc scripts and outline calculation work together. If an outline consolidation is in a calc script, it will be used, for example. The greatest challenge the new Essbase programmer faces is thinking multidimensionally. Programmers who have worked with C++, Java, or Fortran can draw an analogy to multidimensional arrays. Relational database programmers must always remember that they are not working with a flat structure. Rather, they are working with a polyhedron that has as many sides as there are dimensions in the database outline.
Calc Script Editor and online Help

You can create calc scripts using Notepad or any text processor. Hyperion Essbase Application Manager provides a tool called the Calc Script Editor, which is invoked from Essbase Application Manager. To simplify the process, the Calc Script Editor provides lists of database dimensions and members as well as lists of functions and commands. It also provides a syntax checker. Online Help provides access to appropriate syntax, examples of each function and a description of the command usage. By cutting and pasting from online Help, you further simplify the creation of calc scripts.
3-2
Hyperion
Commands and functions

Calc script commands include the following subcategories: Commands that control calculation, from calculating an entire database to calculating a single dimension Data isolation commands that specify a portion of the database to be calculated Data management commands that allow for copying data, clearing blocks, and clearing an entire database Environmental commands that control output to the log, manage the calculation environment, and optimize calculations
Calc script functions usually begin with an @ sign and include the following subcategories: Boolean functions that test for member relationships Member set functions that return a list of members Relationship functions that return a value based on the current position of a calculation Range functions that return a single value after performing a calculation, such as sum, on a range of values Math functions that perform a variety of mathematical operations Calc scripts also provide a full range of operators and connectors.
These commands and functions are studied in detail throughout this course.
Hyperion
3-3
Using Calc Script Editor

Calc Script Editor is accessed from Essbase Application Manager.
Creating a New Calc Script:

1) From the server window of the Hyperion Application Manager, select the application and database.
2) 3)
Click Calc Script
Click New. The Calc Script Editor window displays:
Opening an Existing Calc Script:

1) From the server window of the Hyperion Application Manager, select the application and database.
2)
Click Calc Script . The names of the existing calc scripts display in the Calc Scripts list. From the Calc Scripts list, select the name of the Calc Script to be opened. Click Open.
3)
4)
3-4
Hyperion
The Calc Script Editor window displays.The selected calc script is in the edit area:
Calc Script Editor

Calc Script Editor minimizes typing by providing the capability to select from: Lists of dimensions and members for the associated Essbase outline. Buttons that, when clicked, include most common unary operators:
Associating an Essbase Outline

When editing a calc script, you may select the outline with which to associate the calc script. Once associated, the selected outlines dimensions and members display in the appropriate lists (at the bottom half of the Calc Script Editor window). Clicking on an item in the Member list will copy it to the edit area.
Hyperion
H H H H H H H
A button that accesses the complete list of commands and functions:
Cut, copy, paste and undo:
Other functionality on the Calc script toolbar include:
Open, save and print: Check the calc script syntax: Associate an outline with the Calc Script
3-5
Associating a Hyperion Essbase Outline:

1) In the Calc Script Editor window, click the Associate button from the main menu, select Options / Associate Outline. The Associate Server Outline Object window displays: , or
The default selections are to use the application and database that was created with. 2) 3) If necessary, select the Server, Application and Database. Click OK. The outlines dimension display in the Dimension list of the Calc Script Editor window.
Selecting Items from the Associated Outline:

1) In the Dimensions list of the Calc Script Editor window, select the dimension that contains the item (dimension or member) to be copied to the edit area. If necessary, expand the dimensions definition in the Members list to reveal the item that you wish to include. Select the item in the Members list. The selected item is copied to edit area at the current cursor position.
2)
3)
Inserting Functions (Using the Function Button)

There is a large variety of commands and functions that can be included in a calc script. Instead of memorizing and typing in these commands, they may be selected for inclusion.
3-6
Hyperion
Inserting Commands and Functions:

1) In the Calc Script Editor window, click Functions The Function Templates window displays: .
2)
From the Categories list, select the category that contains the function or command that you wish to include. The functions of the selected category are displayed in the Templates list. In the Templates list, select the desired function or command. The commands template displays below the Categories list. Depending on the command/function selected, the Insert Arguments check box becomes available. If available, and if you want to include the functions arguments, select Insert Arguments. Click OK. The function / command is added at the cursor position of the edit area in Calc Script Editor window.
3)
4) 5)
Checking the Syntax and Saving and Running the Calc Script
The Calc Script Editor includes the capability to determine if the script contains errors. Once the calc script is saved, it can be run to update the data in the selected Essbase database.
Hyperion
3-7
Checking the Syntax:

1) After you enter the calc script, click Syntax Checker , or from the main menu select Syntax / Check Syntax. A message will display on the Calc script Editors status line to identify the first error encountered. In this example, the semicolon is missing:
No errors will display on the status line if no syntax errors exist in the calc script. 2) To view the next error, select Syntax / Next Error from the main menu. The next error displays on the Calc script Editors status line. No more errors will display on the status line if there are no further syntax errors in the calc script. To view the previous error, select Syntax / Previous Error from the main menu. The previous error displays on the Calc script Editors status line. No more errors will display on the status line if there are no prior syntax errors in the calc script.
3)
Saving an Existing Calc Script:

1) Click the Save button on the toolbar, or from the main menu select File / Save. The updated calc script is saved.
3-8
Hyperion
Saving a New Calc Script:

1) Click the Save button on the toolbar, or from the main menu select File / Save or File / Save As. The Save Server Object dialog displays:
2) 3)
In the Object Name field, type the name that want to which you want to save the calc script. Click OK.
Running a Calc Script (Application Manager):
1) 2) 3)
From the server window, click Calc Script
From the Calc Scripts list, select the Calc Script to be executed. Click Run. The Select Database window displays. Select the Server, Application and Database to be updated. Click OK. The Essbase Operation status message displays while the calc script is running. Once the calc script is completed, the status message dismisses.
4)
Hyperion
3-9
Using Essbase Documentation

Several documentation sources are available to Essbase developers, administrators and users. The easiest way to access the documentation is from the Information Roadmap. This can be accessed from the Windows Start menu, by selecting Programs / Hyperion Solutions / Hyperion Essbase/ OLAP Server Documentation:
The following resources are most useful to you when creating calc scripts: Database Administrator's Guide. This is distributed as HTML for quick on-line reference, and as a PDF for producing a printed copy of the guide. Technical Reference also provides an invaluable on-line resource for obtaining information about Calc Script commands and Essbase functions. The documentation for the Calc Script commands and Essbase functions can be accessed from Hyperion Essbase Application Manager. From the main menu select Help / Calculation Commands or Help / Functions, respectively.
3-10
Hyperion
Inserting Functions (From on-line Help)

The documentation for each function and command includes a description of the syntax. Using Windows copy and paste functions, the syntax of a required statement can be copied from the on-line help into the Calc Script Editors edit area.
Hyperion
3-11
Exercise 3-1: Explore Calc Script Editor and Online Help

In this exercise, you experiment with Calc Script Editor. You use the functions template option in Calc Script Editor to create a line of a calc script. You also use the HTML Help to create another. For this exercise, you use the following files:
Database Calc Script (new) CALC:HLandS1 CSDemo
1) 2) 3)
Start Essbase Application Manager, and connect to the CALC application. From the list of available databases, select HLandS1. Create a new calc script. Associate the calc script with the HLandS1 outline.
4) 5) 6)
Click the Calc Script Editor function button
From the Categories list box of the Function Template, select Functional. From the Templates list box, select Calc Dim. Click OK. The Calc Dim(dimList) statement is copied to the Calc Editor edit area. In the edit area, highlight dimList in the CALC DIM parentheses. select Accounts from the Dimensions list box. select Accounts from the Members list box. The statement in the edit area reads CALC DIM (Accounts) Place the cursor at the end this line (and click). Either type a semicolon, or click the semi-colon button on the toolbar. Press [Enter]. The statement in the edit area reads CALC DIM (Accounts); Switch to HTML Help by selecting Help / Functions, and locate the @VAR function. In HTML Help, copy the syntax of @VAR to the clipboard. In the Calc Script Editor, on a new line, type in Variance =, and then paste the contents from the clipboard.
7)
8)
9)
10)
3-12
Hyperion
Using the Members list box, insert Actual and Budget into the formula in that order. Make sure that punctuation is correct. The statements in the edit area reads: CALC DIM (Accounts); Variance = Var(Actual, Budget); Note: In the database outline, Variance has a formula. This exercise duplicates the Variance formula. However, if the calc script calculated Variance differently, it would override the formula in the outline. Verify the syntax by selecting Syntax / Check Syntax or by clicking the Syntax Checker button on the toolbar.
12)
13) 14)
If there are errors, review your calc script to ensure the syntax and punctuation is correct (according to step 11). Reverify the syntax. Save the calc script as CSDemo.
Hyperion
3-13
Reviewing Essbase Data Using Spreadsheet Add-in

Once the database has been populated and the calc script has been executed, you review the results. There are a number of tools available to retrieve Essbase data.
Exercise Procedures
For the remaining exercises for this course, you use the Spreadsheet Addin with Microsoft Excel to perform many of the steps. Each exercise has a pre-built Excel workbook available. Each workbook has: A worksheet with data required to support the specific exercise. This worksheet is usually named Lock&Send. A worksheet formatted to retrieve specific data from the updated Essbase database. This worksheet is usually named Calc&Retrieve. Possibly, other worksheets used to retrieve selected data.
3-14
H H H H H H H H H
1) 2) 3) 4)
The general process for remaining exercises is: Clear the data in the database. Populate the database with data in a spreadsheet (Lock & Send sheet). Calculate the database using the Calc Script that you create to solve the exercise problem. Retrieve the database results into the spreadsheet (Calc & Retrieve sheet). Compare the results with the expected results. If unexpected results are retrieved, repair the Calc Script and repeat Calculation and Retrieve.
Clearing the Database (Application Manager):

In the server window of Hyperion Essbase Application Manager, select the application and database. From the main menu, select Database / Clear Data / All. Click Yes to the Are you sure...? message. Click OK to the Clear Data confirmation message.
Hyperion
Connecting to the Essbase Database (Spreadsheet Add-in):

1) 2) In the desired worksheet, select Essbase / Connect. In the Essbase System Login window, provide the Server name, Username and Password. Click OK. After connecting to the selected server, a list of all applications and databases available to the user from that server is displayed. Select the appropriate Application/Database combination from the list. Click OK.
3)
Populating the Database (Spreadsheet Add-in):

1) 2) 3) In the desired worksheet, connect to the appropriate Essbase database. Select Essbase / Lock. Select Essbase / Send.
Running a Calc Script (Spreadsheet Add-in):

1) 2) 3) Select Essbase / Calculation. In the Essbase Calculation dialog, select the Calc Script to be run. select Calculate. Click OK at the message stating Your calculation is finished.
Retrieving Essbase Data (Spreadsheet Add-in):

1) 2) In the desired worksheet, connect to the appropriate Essbase database. Click Essbase / Retrieve. (or double-click in an empty cell).
Hyperion
3-15
Exercise 3-2: Running Calc Scripts

In this exercise, you use the calc script created in the previous exercise. You run the calc script and view results in a spreadsheet. You also are introduced to the application log and the messages written to the log during a calculation. For this exercise, you use the following files:
Database Calc Script Spreadsheet CALC:HLandS1 CSDemo SS_Demo.xls
Clear the Essbase Database

1) In Essbase Application Manager, review the calc script CSDemo. It should contain the following statements:
CALC DIM (Accounts); Variance = @VAR (Actual, Budget);
2)
Correct any errors in the calc script if they exist.
Review the Spreadsheet

3) 4) In Microsoft Excel, open SS_Demo from the <x>:\Hyperion\Essbase\App\Calc directory. Select the Lock&Send tab.
Send the Spreadsheet Data to Essbase

5) 6) Connect to the Essbase server and select the Calc:HLandS1 database. Lock and send the data in the Lock&Send sheet to the HLandS1 database.
Run the Calc Script

7) From the Calc&Retrieve sheet, run the CSDemo calc script.
3-16
Hyperion
Retrieve the Updated Data

8) Perform a retrieval from the Essbase database and notice the calculation results. Retrieve data in the Retrieve Variance sheet to check the variance calculation.
Review the Application Log

9) In Essbase Application Manager From the server window, select Application / View Event Log. The View Log File dialog displays. Click Date and in the drop-down list select today's date. Click OK. The Log Viewer window displays. Scroll down to the bottom of the log entries. Find and review the log entry that contains information regarding your calculation. What is the elapsed time for your calculation? _____ seconds. How many blocks were created by this calculation? ______ Blocks. Close the Event Log Viewer window.
10)
11)
12)
Modify and Run the Calc Script

13) Add the following command to the beginning of calc script, CSDemo:
SET MSG SUMMARY;
14)
In Essbase Application Manager, save, close, and run the CSDemo calc script. View the application log once again, and notice how the SET MSG SUMMARY command affects the log entries for the calculation. In Microsoft Excel, close the SS_Demo spreadsheet.
15) 16)
Hyperion
3-17
Calc Script Basics

Member Calculations
If, in a calc script, you reference a member name and follow the name with a semicolon, the named member is calculated.
Syntax
mbrName; (mbrName1, mbrName2); mbrName, mbrName1, mbrName2 - Member defined in the database outline whose results are to be calculated.
Notes
The member is calculated according to the operations defined in the Essbase outline. If the member being calculated is dependent upon lower members that have missing values, these values are treated as zero. In other words, be sure that when calculating, the lower level members have been properly calculated first.
3-18
Hyperion
Arithmetic Operators
The method by which to calculate a member may not be defined in the Essbase outline. The calculation method for the member can be defined in the calc script.
Syntax
mbrName = value1 <operator> value2; mbrName - Member defined in the database outline whose results are to be calculated. value1, value2 - member name within the same dimension as mbrName or constant value. Valid mathematical operators:
+ * / % Adds. Subtracts. Multiplies. Divides. Evaluates percentage. For example, Member1%Member2 evaluates Member1 as a percentage of Member2. Controls the order of calculations and nests equations and formulas.
()
Examples
Sales Tax = Sales * .06; Margin = Net Income / Gross Revenue; Sales Pct = Sales % Total Sales; Ave = (First Value + Second Value + Third Value) / 3;
Hyperion
3-19
Adding In-line Documentation

Comments can be added to your calc scripts to document your logic, or to provide other users with information about the calc script.
Syntax
/* Free form text */ or // Single-line of free form text The free-form text can be anything that you like. When Essbases Calc Script interpreter encounters the opening comment characters, /*, it ignores everything following it until the closing comment characters are encountered. A single comment can be split over multiple lines in the calc script source file using the /* characters. When Essbases Calc Script interpreter encounters the opening comment characters, //, it ignores everything following it on that single line.
Examples
// Sales Tax rate is 6% Sales Tax = Sales * .06; /* Margin is calculated as Net Income divided by Gross Revenue */ Margin = Net Income / Gross Revenue;
3-20
Hyperion
Introduction to Calc Script Commands and Functions

As described earlier, clicking the Calc Script Editor functions button displays the Function Template dialog:
Essbase calc script commands and Essbase functions are listed by specific categories. The categories are introduced here, and a chapter is devoted to the specific commands in each category.
Calc Script Command Categories

The categories that contain Calc Script commands are: Data Declarations Control flow commands Functional Conditionals
Hyperion
H H H H
A command template can be found by selecting its category:

Command AGG ARRAY CALC CCONV CLEARBLOCK CLEARDATA DATACOPY ELSE ELSEIF ENDFIX Select Category Functional Data Declarations Functional Functional Functional Functional Functional Conditionals Conditionals Control Flow
3-21
Command ENDIF ENDLOOP FIX IF LOOP SET VAR
Select Category Conditionals Control Flow Control Flow Conditionals Control Flow Functional Data Declarations
Essbase Functions Categories

The categories that contain Essbase functions are: Boolean Relationship functions Math Member Set Range (Financial) Allocation Forecasting Statistical Date & Time Miscellaneous
3-22
H H H H H H H H H H
A function template can be found by selecting its category:

Function @ABS @ACCUM @ALLANCESTORS @ALLOCATE @ANCEST @ANCESTORS @ANCESTVAL @ATTRIBUTE @ATTRIBUTEBVAL Select Category Math Range (and Financial) Member Set Allocation Member Set Member Set Relationship Functions Member Set Relationship Functions
Hyperion
Function @ATTRIBUTESVAL @ATTRIBUTEVAL @AVG @AVGRANGE @CALCMODE @CHILDREN @COMPOUND @COMPOUNDGROWTH @CONCATENATE @CORRELATION @COUNT @CURGEN @CURLEV @CURRMBR @CURRMBRRANGE @DECLINE @DESCENDANTS @DISCOUNT @EXP @FACTORIAL @GEN @GENMBRS @GROWTH @IALLANCESTORS @IANCESTORS @ICHILDREN @IDESCENDANTS @ILSIBLINGS
Select Category Relationship Functions Relationship Functions Math Range (and Financial) Miscellaneous Member Set Range (and Financial) Range (and Financial) Miscellaneous Statistical Statistical Relationship Functions Relationship Functions Member Set Range (and Financial) Range (and Financial) Member Set Range (and Financial) Math Math Relationship Functions Member Set Range (and Financial) Member Set Member Set Member Set Member Set Member Set
Hyperion
3-23
Function @INT @INTEREST @IRDESCENDANTS @IRR @IRSIBLINGS @ISACCTYPE @ISANCEST @ISCHILD @ISDESC @ISGEN @ISIANCEST @ISIBLINGS @ISICHILD @ISIDESC @ISIPARENT @ISISIBLING @ISLEV @ISMBR @ISPARENT @ISSAMEGEN @ISSAMELEV @ISSIBLING @ISUDA @LEV @LEVMBRS @LIST @LN @LOG
Select Category Math Range (and Financial) Member Set Range (and Financial) Member Set Boolean Boolean Boolean Boolean Boolean Boolean Member Set Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Boolean Relationship Functions Member Set Member Set Math Math
3-24
Hyperion
Function @LOG10 @LSIBLINGS @MATCH @MAX @MAXRANGE @MAXS @MAXSRANGE @MDALLOCATE @MDANCESTVAL @MDPARENTVAL @MDSHIFT @MEDIAN @MEMBER @MERGE @MIN @MINRANGE @MINS @MINSRANGE @MOD @MODE @MOVAVG @MOVMAX @MOVMED @MOVMIN @MOVSUM @MOVSUMX @NAME @NEXT
Select Category Math Member Set Member Set Math Range (and Financial) Math Range (and Financial) Allocation Relationship Functions Relationship Functions Range (and Financial) Statistical Member Set Member Set Math Range (and Financial) Math Range (and Financial) Math Statistical Forecasting Forecasting Forecasting Forecasting Forecasting Forecasting Miscellaneous Range (and Financial)
Hyperion
3-25
Function @NEXTS @NPV @PARENT @PARENTVAL @POWER @PRIOR @PRIORS @PTD @RANGE @RANK @RDESCENDANTS @RELATIVE @REMAINDER @REMOVE @ROUND @RSIBLINGS @SANCESTVAL @SHIFT @SIBLINGS @SLN @SPARENTVAL @SPLINE @STDEV @STDEVP @STDEVRANGE @SUBSTRING @SUM @SUMRANGE
Select Category Range (and Financial) Range (and Financial) Member Set Relationship Functions Math Range (and Financial) Range (and Financial) Range (and Financial) Member Set Statistical Member Set Member Set Math Member Set Math Member Set Relationship Functions Range (and Financial) Member Set Range (and Financial) Relationship Functions Forecasting Statistical Statistical Statistical Miscellaneous Math Range (and Financial)
3-26
Hyperion
Function @SYD @TODATE @TREND @TRUNCATE @UDA @VAR @VARIANCE @VARIANCEP @VARPER @WITHATTR @XRANGE @XREF
Select Category Range (and Financial) Date and Time Forecasting Math Member Set Math Statistical Statistical Math Member Set Member Set Relationship Functions
Hyperion
3-27
Exercise 3-3: Member Calculations and Mathematical Operators

This exercise guides you through creating, testing and modifying a simple calc script to calculate Account members (Pre Tax Profit, using the outline consolidation; and Commission using a simple mathematical operation). You use the Spreadsheet Add-in to review the results. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSSimple SS_Simple1.xls
Clear the Essbase Database

1) In Essbase Application Manager, clear all the data for the specified database.
Review the Spreadsheet

2) In Microsoft Excel, open SS_Simple1 from the <x>:\Hyperion\Essbase\App\Calc directory. Select the Lock&Send tab. Review the contents This sheet contains data to populate Level-0 data items for Actual Pre Tax Profit for selected cities, products and months.
Send the Spreadsheet Data to Essbase

3) Connect to the Essbase server and select the CALC:HLandS1 database. Lock and send the data in the Lock&Send sheet to the HLandS1 database. From the Calc&Retrieve1 worksheet, retrieve the data from the Essbase database. Note that all values for Pre Tax Profit are #Missing.
4) 5)
Create and Run the Calc Script

6) 7) In Essbase Application Manager, connect to the CALC:HLandS1 database. Create a new calc script, and associate it with the HLandS1 outline.
3-28
Hyperion
Hyperion Essbase Calc Scripts 8) 9) 10) 11) 12)
In the new calc script file, add a command to calculate:

Pre Tax Profit;
Verify the calc script, and save it as CSSimple. In Microsoft Excel, click the Calc&Retrieve1 tab of the SS_Simple1.xls spreadsheet. Run the CSSimple calc script. Retrieve the data from the Essbase database. There are now values for Pre Tax Profit. Do they seem to be correct? How was this value arrived at? (Hint - review the data in the Lock&Send sheet.)
Correct and Run the Calc Script

13) In Essbase Application Manager, modify the calc script file to be:
Margin; Total Expenses; Regional Profit; Pre Tax Profit;
14) 15) 16) 17)
Verify and save the calc script. In Microsoft Excel, click the Calc&Retrieve1 tab of the SS_Simple1.xls spreadsheet. Run the CSSimple calc script. Retrieve the data from the Essbase database. Do the Pre Tax Profit value now seem to be correct? (The Pre Tax Profit for Round Bodied Floating in Bridgeport for January 1999 should be 370.814.)
Modify and Run the Calc Script

18) From the Calc&Retrieve2 worksheet, retrieve the data from the Essbase database. Note that all values for Commission are #Missing. In Essbase Application Manager, add the following to the end of the CSSimple Calc Script:
Commission = .1 * Sales;
19)
20) 21)
Verify and save the calc script. In Microsoft Excel, click the Calc&Retrieve2 tab of the SS_Simple1.xls spreadsheet.
Hyperion
3-29
Calculation Script Environment 22) 23) 24) Run the CSSimple calc script.
Retrieve the data from the Essbase database. The commissions, calculated to be 10% of the sales, display. If the expected results are not retrieved, continue to correct and execute the Calc Script, and retrieve the results until they are as expected. Close the Excel spreadsheet (but leave Excel, open).
25)
3-30
Hyperion
Unit Summary
You create calc scripts to perform specific actions on a database or a portion of a database. These actions are not included in the database outline because they are designed to solve a specific analytical task or to make adjustments that do not affect the entire database. Calc scripts are made up of commands, which perform an action; and functions, which return a value. A calc script can contain a single command or function or a variety of commands and functions. A calc script can also contain tests that direct how and under what conditions calculations are performed. Calc scripts can be created using Calc Script Editor in Essbase Application Manager. You can type directly into the editor, or you can select appropriate functions and paste them to the edit window. Online Help provides detailed explanations and examples of functions. Calc script syntax is both simple and powerful. By understanding the structure of a database and the nature of the tasks to be accomplished, you can solve almost any business-related calculation problem.
Hyperion
3-31
3 Calculation Script Environment Check Your Understanding

1)
Now that you have completed the chapter, check your understanding by responding to the following questions: What are advantages of using the Calc Script Editor rather than creating your calc script in a text editor?
2)
Describe what each of the following calc scripts statements do:

a. January;
b.
/* Time dimensions are consolodated */
c.
Profit Pct = Profit % Sales;
3-32
Hyperion
Check Your Understanding Solutions

1) What are advantages of using the Calc Script Editor rather than creating your calc script in a text editor? The Calc Script Editor offers: A mechanism for selecting functions from lists (instead of having to type them) A mechanism for selecting dimensions and measures from the outline definition (instead of having to type them) A syntax verification tool Describe what each of the following calc scripts statements do:
a. January;
2)
Calculates the member January.

b. /* Time dimensions are consolidated */
Places a comment (in-line documentation) in the Calc script.

c. Profit Pct = Profit % Sales;
Calculates a member Profit Pct to be the percent of Profit to Sales.
Hyperion
3-33
3-34
Hyperion
4
Calculation Script Commands
Chapter Objectives
By the end of this chapter, you will be able to: Create a calc member block Describe how to focus calculation areas using FIX...ENDFIX, IF...ENDIF and cross-dimensional operators Describe the basic commands used to create calc scripts Apply these commands to a series of incremental exercises
Calc Member Blocks

The previous chapter outlined two ways that members can be calculated in a calc script: Simply by specifying the member name followed by a semi-colon. Here the calculation defined for that member in the outline is used. By specifying a formula in the calc script. The member is calculated using the formula in the calc script.
4-2
H H
Occasionally, the formula may be too complicated to present as a simple formula. For example, the method to calculate a members value may be conditional depending upon the value of another member. In these situations, a calc member block structure is used.
Syntax
mbrname ( <calculation statement(s)>; );
Example
These two blocks are produce the same results:
Commission ( Sales * .1; ); Commission ( Commission = Sales * .1; );
Notes
Formula for other members may be included within a single calculation block. For example:
Sales ( Sales * .1 Net Sales = Sales * .9; );
Here the calculation of Sales and Net Sales are calculated as a block.
Hyperion
Focusing Calculations
In many analytical situations, you do not want to calculate the entire database. In other analytical situations, you may want to use one set of parameters to calculate a portion of the database and a different set of parameters to calculate another portion. There are three ways to focus calculations: Using the FIX...ENDFIX structure Using conditional statements: IF...ELSE...ELSEIF...ENDIF Using the cross-dimensional operator (->)
Focusing Calculations Using Fix...Endfix

Using the FIX...ENDFIX structure, you can define a fixed range of members within a dimension. FIX...ENDFIX does not perform a calculation; it isolates an area of the database to be calculated.
Focusing Calculations Using Conditional Statements

You can define formulas that use a conditional test or a series of conditional tests to control the flow of calculation. In the simplest form, a conditional statement directs that processing be performed only if a test proves true. More complex statements are built by providing additional actions if a test proves false.
Focusing Calculations Using the Cross-Dimensional Operator

The cross-dimensional operator (->) isolates data values for specific member combinations. For example, you use a cross-dimensional operator to capture a value for January Actual Sales. After you isolate this value, you can perform calculations on the value, such as moving the value to February Actual Sales. You type the cross-dimensional operator by following a hyphen (-) with a greater-than sign (>). Do not leave spaces between the cross-dimensional operator and the member names. It is also available on the Calc Script Editor toolbar.
Hyperion
H H H
Example
SALES (SALES->BUDGET->JANUARY = SALES->ACTUAL->JANUARY;);
The cross-dimensional formula is associated with a calc member block, Sales. The calc member block association is required when a crossdimensional operator is used on the left side of a formula.
4-3
Calc Script Commands

Essbase provides a number of calc script commands to build and store calculation procedures. In general, a calc script command is completed with a semicolon (;). In the Calc Script Editor, Calc Script commands can be selected using the Functions button on the toolbar. Specific Calc Script commands are found in one of four categories: Data Declarations Control flow commands Functional Conditionals
Summary of Calc Script Commands

This table presents a summary of the available calc script commands, which category each is associated with, and a brief description of the commands use. Each command is also described, in detail, in this chapter.
Command & Category Use Prefaces a substitution variable in a calculation script. Calculates database values by simply consolidating the defined parent/child relationships and ignoring all member formulas. Declares one-dimensional array variables. Calculates all or selected subsets of the database. Calculates currency conversions (available if the optional Hyperion Essbase Currency Conversion product is installed.) Clears blocks of data and sets them to #MISSING Clears data values from the database and sets them to #MISSING. Copies a range of data cells to another range within the database. Isolate a subset of the database for further processing.
4-4
H H H H
AGG
Functional
ARRAY CALC
Data Functional
CCONV
Functional
CLEARBLOCK
Functional
CLEARDATA
Functional
DATACOPY
Functional
FIX/ENDFIX
Control
Hyperion
Command IF/ ELSE/ ELSEIF/ ENDIF LOOP/ ENDLOOP SET
Category Conditional
Use Perform Boolean (logical) tests before performing a calculation. Specifies the number of times to repeat a series of calculations. Change the Essbase calculation environment during the execution of the Calc Script. Declares a temporary variable containing a single value.
Control
Functional
VAR
Data
Hyperion
4-5
Detailed Description of Calc Script Commands

&
The & command prefaces a substitution variable in a calculation script. Hyperion Essbase treats any string that begins with a leading & as a substitution variable and substitutes these variables with their values before it parses the calculation script.
Syntax
&variableName; variableName - The name of the substitution variable set on the database.
Example Usage
&CurQtr;
becomes
Qtr1;
if the substitution variable &CurQtr has the value "Qtr1".
4-6
Hyperion
AGG
The AGG command consolidates database values. An AGG command ignores all member formulas; it simply consolidates parent/child relationships.
Syntax
AGG (dimList); dimList - Name of a single dimension or a comma-delimited list of sparse dimensions.
Example
AGG(Market); AGG(Product,Market,Scenario);
Notes
The AGG command is used for a limited set of high-speed consolidations. Although AGG is faster than any of the CALC commands when calculating sparse dimensions, it cannot calculate formulas; it can only perform aggregations based on the database structure. The AGG command aggregates a list of sparse dimensions. The aggregation is based on the hierarchical relationship defined in the database outline. If a member has a customized calculation defined in the outline, the formula is ignored and the result does not match the relationship defined by the database outline. If you want to aggregate a dimension that contains formulas: 1. 2. 3. Calculate any members that are "leaf" members (that is, level 0). Aggregate the dimension, using the AGG command. Calculate all other members with formulas that have not been calculated yet.
When a dimension contains fewer than six consolidation levels, AGG is typically faster than CALC. Conversely, the CALC command is usually faster on dimensions with six or more levels. AGG follows the rules for any defined FIX command.
Hyperion
4-7
ARRAY
The ARRAY command declares one-dimensional array variables.
Syntax
ARRAY arrayVariableName [dimName] = {constList}; arrayVariableName - Comma-delimited list of one or more array variable names. dimName - Dimension whose size determines the size of the array variable. You must surround the dimName with brackets [ ] when using the ARRAY command. constList - list of data values used to initialize the array variable(s). If no initialization is performed, then the array values are set to #MISSING. The order of the values corresponds to the order of the members in the dimension used to define the array.
Example
ARRAY discount[Scenario] = {1, 2, 3, 4};
Which yields an array of 4 entries, with the values 1 through 4 entered in those four entries.
ARRAY discount[Scenario], tmpProduct[Product];
Which yields two arrays, one of 4 members (corresponding to the dimension Scenario, and called discount) and one of 9 members (corresponding to dimension Product, and called tmpProduct).
Notes
Typically, arrays are used to temporarily store variables as part of a member formula. The variables are contained within the calc script and cease to exist after the calculation script ends. The size of the array variable is determined by the corresponding dimension (for example, if dimension Period has 12 members, ARRAY Discount[Period] has 12 members). You can calculate data for an array directly as part of a member formula. As the member formula is processed, each value in the array is assigned as its member is evaluated in the calculation.
4-8
Hyperion
CALC
There are a number of variations of the CALC command. The CALC commands calculate all or selected subsets of the database. Usually, data is loaded into lower levels of the database, and the CALC command uses the outline consolidation formulas to calculate the remaining members. The description and syntax for the CALC commands are presented in three segments: CALC ALL CALC DIM CALC (others)
Hyperion
H H H
The CALC ALL command allows for calculating the entire database.
CALC ALL
Low Level data loaded
The CALC DIM commands allows the user to specify the dimension(s) to be calculated.
The remaining variations of the CALC command (CALC AVERAGE, CALC FIRST, CALC LAST, and CALC TWOPASS) allow for calculation of members that have been assigned specific calculation characteristics.
4-9
CALC ALL
The CALC ALL command calculates and aggregates the entire database based on consolidation attributes and member formulas in the database outline. The order in which dimensions are processed depends on the definitions of the various dimensions in the database outline.
Syntax
CALC ALL [EXCEPT DIM (dimList) | MBR (mbrList)]; EXCEPT - Defines an exception list of dimensions or members that are to be excluded from the calculation. DIM - the exception list is a set of dimensions. dimList - Comma-delimited list of dimensions. MBR - the exception list is a set of members. mbrList - Comma-delimited list of members, member set functions, or range functions.
Example
CALC ALL;
Calculates all members according to the consolidation definitions.

CALC ALL EXCEPT DIM(Product);
Calculates all members, except the Product dimension, according to the consolidation definitions.
Notes
Calculation order is determined by: Type of dimension (Accounts, Time, and user-defined dimensions) Dimension storage type (dense or sparse) Dimension order within the outline
4-10
H H H
Hyperion
CALC DIM
CALC DIM calculates the formulas and consolidations associated with all members of all specified dimensions.
Syntax
CALC DIM (dimList); dimList - Single dimension or comma-delimited list of dimensions to be calculated.
Example
CALC DIM(Dense1,Sparse1,Sparse2,Dense2);
Here, the calculation order would be: Dense1, Dense2, Sparse1, Sparse2. If your dimensions need to be calculated in a particular order, use separate CALC DIM commands (see Notes for efficiency concerns):
CALC CALC CALC CALC DIM(Dense1); DIM(Sparse1); DIM(Sparse2); DIM(Dense2);
Notes
The order of calculations depends on whether dimensions are dense or sparse. All of the dense dimensions are calculated first, in the order that the
dense dimensions appear in dimList. The sparse dimensions are then calculated in the order in which they appear in dimList.
Each CALC DIM statement forces Essbase to make a pass through the database. To minimize the number of passes, list a series of dimensions in a single CALC DIM statement.
Calc Dim (Markets,Accounts);
causes one pass through the database.

Calc Dim (Markets); Calc Dim (Accounts);
causes two passes through the database.
Hyperion
4-11
Although the second example causes two passes through the database, it gives you greater control. In the first example, Accounts is calculated first, no matter where it appears in the list; in the second example, the procedural flow-Markets then Accounts-is followed, meaning that Markets are calculated before Accounts.
4-12
Hyperion
CALC (others)
CALC DIM calculates the formulas and consolidations associated with all members of all specified dimensions.
Syntax
CALC AVERAGE; CALC FIRST; CALC LAST;
CALC TWOPASS;
The CALC AVERAGE command calculates all members tagged in the database outline as time balance Average or Average Non-Missing.
The CALC FIRST command calculates all members tagged in the database outline as time balance First. The CALC LAST command calculates all members tagged in the database outline as time balance Last. All other member calculations are ignored during this process. The CALC TWOPASS command calculates all members tagged in the database outline as two-pass. Note
These commands calculate the members based on the dimension tagged as accounts only; it does not do a Time Series calculation on the dimension tagged as time, for example.
All other member calculations are ignored during the processing of these commands.
Hyperion
4-13
CCONV
CCONV calculates currency conversions. This command is available only if your company has installed the optional Hyperion Essbase Currency Conversion product.
Syntax
CCONV currExchMbr | TOLOCALRATE curType; currExchMbr - Currency name containing the required exchange rate. This is a member from the currency database. TOLOCALRATE - Converts a converted currency back to the original, local rate. curType - Currency type, a member from the CurType dimension in the currency database.
Example
CCONV YEN;
converts all the data values from local currency values (for example, French Francs and US$) to Japanese Yen using the YEN exchange rate from the currency database.
CCONV TOLOCALRATE "Act xchg";
converts all the data values back to the local currencies using the Act xchg currency type from the currency database.
Notes
You convert data values from a local to a common, converted currency using the CCONV currExchMbr command. You can convert the data values back to the original, local currency using the CCONV TOLOCALRATE curType command.
4-14
Hyperion
CLEARBLOCK
The CLEARBLOCK command clears blocks of data and sets them to #MISSING.
Syntax
CLEARBLOCK ALL | UPPER | NONINPUT | DYNAMIC; ALL - Clears all data blocks. UPPER - Clears all consolidated level blocks. NONINPUT - Clears blocks containing values derived from calculations. DYNAMIC - Clears blocks containing values derived from Dynamic Calc And Store member combinations.
Examples
CLEARBLOCK ALL; CLEARBLOCK UPPER; CLEARBLOCK NONINPUT; CLEARBLOCK DYNAMIC;
Notes
CLEARBLOCK is especially useful when you want to optimize the calculation speed of a database. When a database is initially calculated, numerous consolidated level sections (blocks) are created. Subsequent calculations against the same set of data take longer since Hyperion Essbase must pass through these additional data blocks. CLEARBLOCK clears blocks before a calculation occurs. If you use CLEARBLOCK within a FIX command, Hyperion Essbase clears only the data cells within the fixed range, and not the entire block. If you regularly enter data values directly into a consolidated level, the UPPER option overwrites your data. In this case, you should use the NONINPUT option, which only clears blocks that contains calculated values.
Hyperion
4-15
CLEARDATA
The CLEARDATA command clears data values from the database and sets them to #MISSING.
Syntax
CLEARDATA mbrName; mbrName - Any valid single member name or member combination, or a function that returns a single member or member combination. This command is useful when you need to clear existing data values before loading new values into a database. CLEARDATA can only clear a section of a database. It cannot clear the entire database. To clear the entire database, select Database / Clear Data / ALL from the Application Manager main menu. CLEARDATA does not clear blocks, even if all data values in a block are #MISSING. Use CLEARBLOCK if you wish to clear blocks from the database, which can improve performance.
Examples
CLEARDATA Budget;
clears all Budget data.

CLEARDATA Budget->Colas;
clears only Budget data for the Colas product family.
Notes
CLEARDATA does not work if placed in an IF statement.
4-16
Hyperion
DATACOPY
The DATACOPY command copies a range of data cells to another range within the database.
Syntax
DATACOPY mbrName1 TO mbrName2; mbrName1, mbrName2 - Any valid single member name or member combination, or a function that returns a single member or member combination.
Example
DATACOPY Plan TO Revised_Plan;
Notes
This command is useful when you must maintain an original set of data values and perform changes on the copied data set. To reduce typing, if any dimension(s) represented by the members in mbrName1 are not represented in mbrName2, then by default the same member or members from mbrName1 are assumed to exist in mbrName2 to complete the range. The reverse is not true. Any dimension explicitly represented in mbrName2 MUST be represented by another member of the same dimension in mbrName1. The ranges specified by both mbrName1 and mbrName2 must be of the same size. The same dimensions represented by the members that make up mbrName1 must also be present in mbrName2. The size of the copied dimensions must be equal to the destination (TO) size. DATACOPY follows the rules for any defined FIX command.
Hyperion
4-17
FIX / ENDFIX
The FIX structure is used to isolate a subset of the database. When the FIX parameter references sparse dimensions, FIX reduces I/O by evaluating data as it is brought into memory. Data that does not pass the FIX test is not calculated and therefore is not brought into memory.
Syntax
FIX (fixMbrs) Command(s); ENDFIX fixMbrs - A member name or a list of members from any number of database dimensions. Command(s) - The commands that you want executed for the duration of the FIX
Example
FIX (Budget) CALC DIM (Year, Measures, Product, Market); ENDFIX
This calculates Year, Measures, Product and Market dimension for only the Budget scenario.
Notes
All commands between FIX and ENDFIX are executed as a calculation unit. Commands encountered after ENDFIX are performed only when the calculation unit is completed. FIX and ENDFIX do not require semicolons because they do not perform calculations. FIX commands can be nested within other FIX command blocks. fixMbrs can also contain: AND/OR operators. (Use the AND operator when all conditions must be met. Use the OR operator when only one of several conditions must be met.) Member set functions that build member lists based on other members
4-18
Hyperion
IF / ELSE / ELSEIF / ENDIF

The IF conditional statements perform Boolean tests before performing a calculation.
Syntax
mbrName (IF(condition1) statement1;[statement2;] [ELSEIF(condition2) statement3;[statement4;]] [ELSE statement5;[statement6;]] ENDIF) mbrName - Member with which the formula is associated conditions - Formula or function that returns a Boolean value of TRUE (a nonzero value) or FALSE (a zero value) statement1, statement2 - Operations that are to be performed if the IF test returns a TRUE value statement3, statement4 - Operations that are to be performed if the IF test returns a FALSE value and the ELSEIF test returns a TRUE value statement5, statement6 - Operations that are to be performed if all conditional tests returns a FALSE value
Hyperion
4-19
Example
Commission (IF(Sales > 200000) Commission = Sales * .12; ELSEIF (Sales >= 100000) Commission = Sales * .098; ELSE Commission = Sales * .05; ENDIF);
If the value of sales is greater than 200,000, commission is calculated as 12% of Sales. Otherwise, if the value of sales is greater than 100,000, commission is calculated as 9.8% of Sales. Otherwise, commission is calculated as 5% of Sales.
Notes
When you use a conditional formula in a calc script, you must enclose it in parentheses and associate it with a member in the database outline. This is called a calc member block. The IF and ELSEIF statements introduce tests. When an IF test is true, the commands immediately following the test are executed, and control passes to ENDIF. If the test fails, execution falls to the ELSEIF test. If this test is true, the commands immediately following the ELSEIF are executed. Finally, all other circumstances are handled by the commands following the ELSE statement. You should not use a semicolon at the end of an IF command. If you use a semicolon, either an error occurs, or the progression of tests and commands does not execute as expected.
Logical Operators
Conditional statements are often made up using logical (comparison) operators. Valid logical operators include:
> >= < <= == < > or != Is greater than. Is greater than or equal to. Is less than. Is less than or equal to. Is equal to. Is not equal to.
4-20
Hyperion
Compound and complex logical tests can be created by using AND, OR and NOT:
AND Logical AND linking operator for multiple value tests. Result is TRUE if both conditions are TRUE. Otherwise the result is FALSE. Logical OR linking operator for multiple value tests. Result is TRUE if either condition is TRUE. Otherwise the result is FALSE. Logical NOT operator. Result is TRUE if condition is FALSE. Result is FALSE if condition is TRUE.*
OR
NOT
Example
IF ((Sales > 100000) AND (Returns <= 5000)
is true if the value of Sales exceeds 100,000 and the value of Returns does not exceed 5000.
Hyperion
4-21
LOOP/ENDLOOP
The LOOP...ENDLOOP command block specifies the number of times to iterate calculations. All commands between the LOOP and ENDLOOP statements are performed the number of times that specified in the LOOP statement.
Syntax
LOOP (integer, [break]) Command(s); ENDLOOP integer - An integer constant that indicates the number of times to execute the commands contained in the loop block. break - parameter used to break the iterative process of a loop. break must be 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. Command(s) - The commands that you want executed for the duration of the LOOP
Notes
LOOP is a block command that defines a series of commands for repeated execution. As with the FIX command, you can nest LOOP statements, if necessary. The ENDLOOP command ends a LOOP command block. It terminates the LOOP block and occurs after the commands in the LOOP block, but before any other commands. The use of LOOPs is a rare occurrence in Essbase Calculations.
4-22
Hyperion
Example
VAR Break = 0; CALC DIM(MEASURES); LOOP(10,BREAK) PROFIT = SALES - (PROFIT * .10); COMMISSIONS = PROFIT - SALES; PROFIT( IF ((PROFIT <> #MISSING) AND (@ABS(.10*PROFIT-COMMISSIONS) < .001)) BREAK = 1; ENDIF) ENDLOOP
On the first line, the Break variable is set to 0. When tolerance reaches an appropriate point, you set Break to 1. The change causes looping to stop, even if the loop has not made its full 10 iterations. The solution of a simultaneous equation is contained in the loop structure. In the example, Profit is an unknown on both sides of the equation. The first equation, PROFIT = SALES - (PROFIT * 10) uses a substitution method to solve for Profit. A new value of profit is obtained by calculating commission on the old value of profit and subtracting it from sales. The second equation uses the new profit result of the first equation to calculate a new Commission. The conditional statement determines whether the absolute value of the difference of (10% of the new Profit) and Commission are within a tolerance of .001. If so, the Break variable is set to one, and this causes an exit of the loop before the next iteration.
This is a simple example that illustrates the use of a Loop structure. It does not necessarily represent the best Calc Script solution for this particular problem.
Hyperion
4-23
SET
Set commands allow the user to adjust the Essbase calculation environment during the execution of the Calc Script. There are a number of environmental parameters that can be set. SET commands in a calculation script are procedural. The first occurrence of a SET command in a calculation script stays in effect until the next occurrence of the same SET command. A description of each of the parameters for the Set command follows.
4-24
Hyperion
SET AGGMISSG
The SET AGGMISSG command specifies whether Hyperion Essbase aggregates #MISSING values in the database.
Syntax
SET AGGMISSG ON | OFF;
Notes
The default behavior of SET AGGMISSG is determined by the global setting for the database, as described in the Database Administrator's Guide. SET AGGMISSG commands apply to calculating sparse dimensions and not to aggregating.
Hyperion
4-25
SET CACHE
The SET CACHE command specifies the size of the calculator cache.
Syntax
SET CACHE HIGH | DEFAULT | LOW | OFF | ALL; HIGH, DEFAULT, LOW - Levels defining the size of the calculator cache. You set the values of HIGH, DEFAULT and LOW in the essbase.cfg file. If you do not set the value of DEFAULT in the essbase.cfg file, Hyperion Essbase uses a default value of 200,000 bytes. The maximum calculator cache size that you can specify is 200,000,000 bytes. OFF - Hyperion Essbase does not use a calculator cache. ALL - Hyperion Essbase uses a calculator cache, even when you do not calculate at least one full sparse dimension. Hyperion Essbase uses the calculator cache to create and track data blocks during calculation. Using the calculator cache significantly improves your calculation performance. The size of the performance improvement depends on the configuration of your database. You can choose one of three levels. The size of the calculator cache at each level is defined using the CALCCACHE{HIGH | DEFAULT | LOW} settings in the essbase.cfg file. The level you choose depends on the amount of memory your system has available and the configuration of your database. You can specify whether, by default, Hyperion Essbase uses a calculator cache using the CALCCACHE TRUE | FALSE setting in the essbase.cfg file. By default CALCCACHE is set to TRUE. Hyperion Essbase uses the calculator cache providing that: Your database has at least two sparse dimensions. You calculate at least one, full sparse dimension (unless you specify the CALCCACHE ALL option).
You can use this command more than once within a calculation script.
4-26
Hyperion
SET CALCHASHTBL
The SET CALCHASHTBL command optimizes the calculation of large, flat database outlines.
Syntax
SET CALCHASHTBL ON|OFF;
Notes
The default setting is OFF. You can change this setting using CALCOPTCALCHASHTBL=TRUE in the essbase.cfg file. When you enable this feature, Hyperion Essbase uses a hash table to optimize use of the calculator cache for large, flat databases. A large flat database is, for example, a database in which one or members has over 5000 children. Using this feature may significantly improve the performance of a CALC ALL of the database or CALC DIM of the dimension containing the member with over 5000 children. You can set the limit of the hash table using the CALCHASHTBLMEMORY setting in the essbase.cfg file. This feature has no effect if you are using parallel calculation. .
Hyperion
4-27
SET CALCPARALLEL
SET CALCPARALLEL enables parallel calculation in place of the default serial calculation.
Syntax
SET CALCPARALLEL [appname [dbname]] n; appname - Specifies that parallel calculation applies to all databases on the named application. If you specify a value for appname and do not specify a value for dbname, the setting applies to all databases in the specified application. If you do not specify an application, you cannot specify a database, and the setting applies to all applications and databases on the Essbase OLAP Server. dbname - Specifies that parallel calculation applies only to the database named. If you specify a value for dbname but do not include appname, the parameter is ignored and parallel calculation is enabled for all applications and databases on the OLAP Server. n - An integer from 0-4, specifying the number of threads to be made available for parallel calculation. The default value, 0, specifies serial calculation: no parallel calculation takes place. Values 1-4 specifies parallel calculation with 1-4 threads. Values less than 0 return an error. Values greater than 4 are interpreted as 4.
Example
SET CALCPARALLEL 3;
This example enables up to three threads to be used to perform calculation tasks at the same time.
Notes
Essbase analyzes each pass of a calculation to determine whether parallel calculation is possible. If it is not, Essbase uses serial calculation even if CALCPARALLEL is set. A number of features are affected by parallel calculation. If your outline generates many empty tasks, thus reducing opportunities for parallel calculation, consider setting the CALCTASKDIMS configuration setting to increase the number of tasks and to decrease the size of each task identified for parallel calculation.
4-28
Hyperion
Consider setting the value of CALCPARALLEL to one less than the number of available processors. This saves one processor for use either by the operating system or by the Essbase process that writes out dirty blocks from the calculator cache. You can use SET CALCPARALLEL to override a CALCPARALLEL entry in the configuration file. For example you might want to set all applications to use serial calculation, but issue a calculation script command against a single application or database to use parallel calculation.
Hyperion
4-29
SET CALCTASKDIMS
SET CALCTASKDIMS specifies how many of the sparse dimensions in an outline are used to identify potential tasks that can be run in parallel.
Syntax
SET CALCTASKDIMS [appname [dbname]] n; appname - Specifies that SET CALCTASKDIMS applies to all databases on the named application. If you specify a value for appname and do not specify a value for dbname, the setting applies to all databases in the specified application. If you do not specify an application, you cannot specify a database, and the setting applies to all applications and databases on the Essbase OLAP Server. dbname - Specifies that SET CALCTASKDIMS applies only to the database named. If you specify a value for dbname but do not include appname, the parameter is ignored, and parallel calculation is enabled for all applications and databases on the OLAP Server. n - An integer specifying the number of sparse dimensions to be included when Essbase identifies tasks that can be performed at the same time. The default value, 1, indicates that only the last sparse dimension in the outline will be used to identify tasks. A value of 2, for example, indicates that the last and second-to-last sparse dimensions in the outline are used.
Example
SET CALCTASKDIMS Sample Basic 2;
This example specifies that for application Sample and database Basic, the last two sparse dimensions in the outline will be used to identify potential tasks to be performed at the same time during a calculation pass.
Notes
Because each unique combination of members from the selected sparse dimensions is a potential task, the potential number of parallel tasks is the product of the number of members of the selected dimensions. The maximum value is the number of sparse dimensions in the outline. Essbase issues an error if the value is less than 1. A value greater than the number of sparse dimensions in the outline is interpreted as the largest valid value.
4-30
Hyperion
Using the calculator bitmap cache can affect this value. Use this configuration setting only if your outline generates many empty tasks, thus reducing opportunities for parallel calculation. If you do not notice an improvement in performance after raising the value of CALCTASKDIMS, consider returning it to its default value of 1. Sometimes using more task dimensions can generate such a large number of tasks that performance may decrease instead of increase, because the overhead of generating and managing the tasks is too great. You can use SET CALCTASKDIMS to override a CALCTASKDIMS entry in the configuration file. For example you might want to set all applications to use a single dimension for parallel calculation, but issue a calculation script command against a single application or database to use two dimensions.
Hyperion
4-31
SET CLEARUPDATESTATUS
SET CLEARUPDATESTATUS specifies when Hyperion Essbase marks data blocks as clean.
Syntax
SET CLEARUPDATESTATUS AFTER | ONLY | OFF; AFTER - Hyperion Essbase marks calculated data blocks as clean, even if you are calculating a subset of your database. ONLY - Hyperion Essbase marks the specified data blocks as clean but does not actually calculate the data blocks. This does the same as AFTER, but disables calculation. OFF - Hyperion Essbase does not mark the calculated data blocks as clean. Data blocks are not marked as clean, even on a default calculation (CALC ALL;) of your database. The existing clean or dirty status of the calculated data blocks remains unchanged.
Example
The following examples are based on the Sample Basic database. They assume that intelligent calculation is turned on (the default).
SET CLEARUPDATESTATUS AFTER; FIX ("New York") CALC DIM(Product); ENDFIX
New York is a member on the sparse Market dimension. Hyperion Essbase searches for dirty parent data blocks for New York (for example "New York"->Colas in which Colas is a parent member). It calculates these dirty blocks based on the Product dimension and marks them as clean. Hyperion Essbase does not mark the child, Input blocks as clean, because they are not calculated.
Notes
This clean status is used during intelligent calculation. The data blocks in your database have a calculation status of either clean or dirty. When Hyperion Essbase does a full calculation of your database, it marks the calculated data blocks as clean. When a data block is clean, Hyperion Essbase will not recalculate the data block on subsequent calculations, provided that intelligent calculation is turned on.
4-32
Hyperion
To ensure the accuracy of your calculation results, consider carefully the effect of the SET CLEARUPDATESTATUS AFTER command on your calculation. If you do not use SET CLEARUPDATESTATUS, Hyperion Essbase does not mark calculated data blocks as clean when you calculate a subset of your database. Hyperion Essbase marks data blocks as clean only on a full calculation (CALC ALL;) or when Hyperion Essbase calculates all members in a single calculation pass through your database. If you calculate a subset of your database, you may want to use the SET CLEARUPDATESTATUS AFTER command to ensure that the calculated blocks are marked as clean. However, consider carefully the effect of this command on your calculation to ensure that your calculation results are correct.
Hyperion
4-33
SET FRMLBOTTOMUP
The SET FRMLBOTTOMUP command optimizes the calculation of complex formulas on sparse dimensions in large database outlines. This command tells Hyperion Essbase to perform a bottom-up calculation on formulas that would otherwise require a top-down calculation.
Syntax
SET FRMLBOTTOMUP ON|OFF;
Example Notes
The default setting is OFF. You can change this setting by using CALCOPTFRMLBOTTOMUP TRUE in the essbase.cfg file. This command optimizes the calculation of complex formulas on sparse dimensions in large database outlines. You might want to turn on this setting when using the CALC ALL; and CALC DIM; commands to calculate the database. Forcing a bottom-up calculation on a formula may produce results that are inconsistent with a top-down calculation if: The formula contains complex functions (for example, range functions) The formula's dependencies are not straightforward
Before using the SET FRMLBOTTOMUP command in a production environment, be sure to check the validity of calculation results produced when the command is enabled (set to ON).
4-34
Hyperion
SET LOCKBLOCK
The SET LOCKBLOCK command specifies the maximum number of blocks that Hyperion Essbase can address concurrently when calculating a sparse member formula.
Syntax
SET LOCKBLOCK HIGH | DEFAULT | LOW; HIGH, DEFAULT, LOW - Levels defining the number of blocks that Hyperion Essbase can address concurrently.
Notes
You can choose one of three levels. The number of blocks that can Hyperion Essbase can address at each level is defined using the CALCLOCKBLOCK setting in the essbase.cfg file. When a block is calculated, Hyperion Essbase locks the block along with the blocks containing its children. Hyperion Essbase calculates the block and then releases it along with the blocks containing its children. By default Hyperion Essbase allows up to 100 blocks to be locked (addressable) concurrently when calculating a block. This is sufficient for most database calculations. However, you may want to set a number higher than 100 if you are consolidating very large numbers of children in a formula calculation. This setting ensures that Hyperion Essbase can address all the required blocks when calculating a data block and that performance will not be impaired.
Hyperion
4-35
SET MSG
The SET MSG command indicates the level of messaging that you wish to receive / review during your calculations.
Syntax
SET MSG SUMMARY | DETAIL | ERROR | WARNS | INFO | NONE | ONLY; SUMMARY - Displays calculation settings and provides statistics on the number of: Data blocks created, read, and written Data cells calculated
DETAIL - Provides the same information as SUMMARY. In addition, it displays a detailed information message every time Hyperion Essbase calculates a data block. ERROR - Displays only error messages. WARNS - Displays only warning and error messages. INFO - Displays information, warning, and error messages. NONE - Displays no messages during the life of the calculation script. However, because error messages may contain vital information, they are still displayed. ONLY - Instructs Essbase to perform a simulated calculation only. You may disregard any error message during validation that indicates Essbase does not recognize command.
Notes
The SET MSG command applies only to the calculation script in which it is used. SET MSG SUMMARY causes a processing overhead of approximately 1% to 5%, depending on the database size. SET MSG DETAIL is useful for testing your database's consolidation path. It causes a high processing overhead and therefore should be used during test calculations only.
4-36
Hyperion
SET NOTICE
The SET NOTICE command monitors the progress of your calculation by providing completion notices at intervals during the calculation.
Syntax
SET NOTICE HIGH | DEFAULT | LOW; HIGH, DEFAULT, LOW - Levels defining the frequency and number of completion notices.
Notes
You can set the values of HIGH, DEFAULT, and LOW using the CALCNOTICE setting in the essbase.cfg file. If you do not set the value of DEFAULT in the essbase.cfg file, Hyperion Essbase uses a default value of 10, which provides 10 completion messages at 10% intervals during the calculation. You can specify the number of notices for each level using the CALCNOTICE setting in the essbase.cfg file. The interval between notices is approximate. Hyperion Essbase measures the interval by taking the number of data blocks already calculated as a percentage of the total number of possible data blocks in your database. For example, if there are 10,000 possible blocks and you specify 5 notices, Hyperion Essbase notifies you when the calculation approximately reaches block 2000, 4000, 6000, 8,000 and 10,000. However, if only the blocks 1,000 - 4,000 exist, then Hyperion Essbase displays only two notices. For partial calculations and calculations with multiple passes through your database, the interval between completion notices is very approximate. Completion notices do not significantly reduce the calculation performance, except when used with a very small database.
Hyperion
4-37
Example
If the essbase.cfg file contains the following settings:
CALCNOTICEHIGH 50 CALCNOTICEDEFAULT 20 CALCNOTICELOW 5
then, in the calc script:

SET NOTICE HIGH;
displays 50 completion notices at 2% intervals.

SET NOTICE DEFAULT;

SET NOTICE LOW;
4-38
Hyperion
SET UPDATECALC
The SET UPDATECALC command turns intelligent calculation on and off.
Syntax
SET UPDATECALC ON | OFF; ON - Hyperion Essbase calculates only blocks marked as dirty OFF - Hyperion Essbase calculates all data blocks, regardless of whether they have been updated.
Notes
Using intelligent calculation, Hyperion Essbase calculates only dirty blocks, such as updated data blocks and their dependent parents. Therefore, the calculation is very efficient. All data blocks in the database are marked as either clean or dirty. If a data block is clean, then Hyperion Essbase knows that the block does not need to be recalculated. By default, all data blocks are marked as clean after a full calculation of the database but not after a partial calculation of the database. If required, you can change this default behavior using the SET CLEARUPDATESTATUS command in your calculation script.
Hyperion
4-39
SET UPTOLOCAL
The SET UPTOLOCAL command restricts consolidations to those parents with the same defined currency.
Syntax
SET UPTOLOCAL ON | OFF;
Notes
The default is OFF. For example, all cities in France use the franc (FF) as the unit of currency. Therefore, all children of France, such as the cities Paris, Nancy, and Avignon, consolidate to France. Consolidation stops at this level, however, because Europe also contains countries that use other currencies. The following database outline example illustrates this situation:
If you want to consolidate values above this level, you must use CCONV to convert the values to a master rate before consolidating. SET UPTOLOCAL ON has no effect on databases with no currency definitions.
4-40
Hyperion
VAR
The VAR command declares a temporary variable that contains a single value.
Syntax
VAR varName [= value]; varName - Name of the temporary variable. value - parameter that declares the data value.
Notes
You can also use a single VAR command to declare multiple variables by supplying a comma-delimited list of variable names. The name of the variable cannot duplicate a database member name. If a value is not declared, it is set to #MISSING. VAR commands can only be assigned values within a member calculation or when VAR is declared.
Example
VAR Target = 1200;
Declares a variable Target and initializes it to 1200.

VAR Break1, Break2, Break3;
Declares three variables Break1, Break2, Break3and initializes them to #Missing.
Hyperion
4-41
Exercise 4-1: Focus Calculations using Fix / EndFix

In this exercise, you use the FIX command to create a calc script to change sales values in the Budget scenario for the Albany and Buffalo markets for Jan 1999. Increase their sales by 15%. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSFix SS_Fix.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS1 database. Using the FIX command, create a new calc script that changes Budget Sales values for the Albany and Buffalo markets for Jan 1999. The Sales are increased by 15%. Save the calc script, calling it CSFix. Open the SS_Fix spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS1 database. From the Calc&Retrieve sheet, run the CSFix calc script. Perform a retrieval and notice the calculation results. Note: Because this is a custom spreadsheet designed for the exercise, you may see an Essbase message alerting you to unknown member names. Select No to suppress additional messages. Then set your global options to not display unknown member names. Ensure that the differences between the Essbase calculated sales and the spreadsheet calculated sales are zero. Formulas are included within the Calc&Retrieve sheet to assist you. From Essbase Application Manager, view the application log. Verify that the database calculated only the sales values for Albany, Buffalo, Budget, and Jan 1999. Close the spreadsheet.
3) 4) 5)
6)
7)
8)
4-42
Hyperion
Exercise 4-2: Focus Calculations using If / Else / Endif

In this exercise, you use an IF statement to calculate commission based on margin percent. If margin percent is greater than 15 percent, the commission is 10% of sales. If margin percent is less than or equal to 15%, the commission is 8% of sales. For this exercise, you use the following files:
Database Calc Script Calc Script (new) Spreadsheet CALC:HLandS1 CSDemo CSIF SS_IF.xls
1)
From Essbase Application Manager, clear all data from the HLandS1 database. Open the CSDemo calc script. Save the calc script as CSIF. Remove the line that does the variance calculation. Add a block to calculate the commission. Use an IF statement to calculate commission based on margin percent. If margin percent is greater than 15%, the commission should be 10% of sales. If margin percent is less than or equal to 15%, the commission should be 8% of sales. Save the calc script as CSIF. Open the SS_IF spreadsheet. Lock and send the data in the Lock&Send sheet into the HLandS1 database. From the Calc&Retrieve sheet, run the CSIF calc script. Perform a retrieval and notice the calculation results. Ensure that the commission is being calculated correctly. If not, revise the calc script and rerun the calculation. Close the spreadsheet.
2) 3) 4)
5) 6) 7)
8) 9)
Hyperion
4-43
Exercise 4-3: Focus Calculations using Cross-Dimensional Operators

In this exercise, you use cross-dimensional operators within a calc script to calculate Budget Sales for Feb 1999 as a 10% increase of the Jan 1999 Budget Sales values. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSXDim SS_X_Dim.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS1 database. Create a new calc script that uses cross-dimensional operators within a calc script to calculate Budget Sales for Feb 1999 as a 10% increase on the Jan 1999 Budget Sales values. Save the calc script, calling it CSXDim. Open the SS_X_Dim spreadsheet. Lock and send the data in the Lock&Send sheet into the HLandS1 database. From the Calc&Retrieve sheet, run the CSXDim calc script. Perform a retrieval and notice the calculation results. Ensure that Feb 1999 sales values are calculated correctly. Spreadsheet calculations are included in the Calc&Retrieve sheet to facilitate data verification. Ensure that the "Excel Calculation" results are identical to the "Feb 1999" results. Close the spreadsheet.
3) 4) 5) 6)
7)
4-44
Hyperion
Unit Summary
Calc member blocks treat a series of member computations as single block of calculations. Essbase provides a number of commands that are used to create calculation scripts. There are four categories of Calc Script commands: Data Declarations Control flow commands Functional Conditionals
Hyperion
H H H H
Data Declaration commands are used to declare, and set the initial values of, temporary variables. Examples are ARRAY and VAR. Control Flow commands are used to iterate a set of commands or to restrict the commands' effect to a specified subset (partition) database. The FIXENDFIX command can be used to restrict a calculation to a particular member or members, while the LOOPENDLOOP command allows you to repeat a command as necessary. Conditional commands let you to control which formulas are executed within a given member calculation, and test conditions and calculate a formula based on the success or failure of the test. These commands are composed of the IF...ELSEIF...ELSE...ENDIF structure Functional commands allow you to consolidate an entire database or focus on a single dimension or a single member. These include the CALC, CLEARBLOCK, CLEARDATA and DATACOPY commands. Also included in the Functional commands are the SET commands, which allow you to define the calculation environment parameters.
4-45
4 Calculation Script Commands Check Your Understanding

1)
Now that you have completed the chapter, check your understanding by responding to the following questions: For each of the following commands, identify the type of command (Data Declaration, Control flow, Functional or Conditional)
Command VAR FIX IF CALC SET Command Type
4-46
Hyperion

1) For each of the following commands, identify the type of command (Data Declaration, Control flow, Functional or Conditional)
Command VAR FIX IF CALC SET Command Type
Data Declaration Control flow Conditional Functional Functional
Hyperion
4-47
4-48
Hyperion
5
Math Functions
Chapter Objectives
By the end of this chapter, you will be able to: Describe and demonstrate mathematical functions used in Calc Scripts Apply these mathematical functions to a series of incremental exercises
Math Functions
Transforming Values with Math Functions

The mathematical functions used in calc scripts include many of the standard mathematical operations. These functions return a numeric result that is based on supplied member values. Math functions can be broken into three basic categories: Simple arithmetic operations, such as: absolute values rounding, truncation variance calculation factorial
5-2
H H H H H H H H
More complicated arithmetic operations, such as: logarithms and exponentiation modulus arithmetic
Those that perform operations on lists, such as: summation and averaging selecting maximum or minimum value
When performing statistical and financial manipulations, use Essbase functions rather than formulas where possible. Limiting scripts to Essbase functions ensures that all calc scripts use the same method, thus promoting consistency of data across the application.
More complicated mathematically oriented functions are available in the Statistical Functions and in the Range (and Financial) Functions.
Hyperion
Math Functions
Math Function Parameters

There are common parameters associated with the various math functions:
expression Member name or mathematical expression that generates a numeric value. Members from the same dimension whose results are to be calculated. Comma-delimited list of members, variable names, functions, and numeric expressions, all of which return numeric values. Used in conjunction with an expList, this parameter indicates how missing and zero values are to be processed. SKIPNONE - Includes in the operation all values specified in expList regardless of their content SKIPMISSING - Ignores all #MISSING values SKIPZERO - Ignores all 0 values SKIPBOTH - Ignores all 0 and #MISSING values
mbrName1, mbrName2 expList
SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH
Summary of Math Functions

This table summarizes the Math Functions. Each function is also described, in detail, in this chapter.
Function @ABS @AVG @EXP Used to calculate The absolute value of number. The average of all values in a list. The value of e (the base of natural logarithms) raised to a power. The factorial of number. The next lowest integer value of number. The natural logarithm (base e). The logarithm calculation to a specified base. The base-10 logarithm. The maximum value all values in a list. The maximum value all values in a list. @MAXS enables skipping of #MISSING and 0 values.
@FACTORIAL @INT @LN @LOG @LOG10 @MAX @MAXS
Hyperion
5-3
Math Functions
Function @MIN @MINS
Used to calculate The minimum value all values in a list. The minimum value all values in a list. @MINS enables skipping of #MISSING and 0 values. The modulus of a division operation of mbrName1 divided by mbrName2. The modulus is the remainder for an integer quotient. The value of the specified expression raised to power. The value of the decimal portion of expression. The value rounded to a specified number of digits. The summation of all the values in a list. The integer portion of expression. The difference between two values. The percent difference between two values.
@MOD
@POWER @REMAINDER @ROUND @SUM @TRUNCATE @VAR @VARPER
5-4
Hyperion
Math Functions
Detailed Description of Math Functions

@ABS
@ABS returns the magnitude of the expression as a positive number.
Syntax
@ABS (expression) In some cases, you perform a test that yields either a positive or a negative value, when the only important factor is the magnitude of the number itself.
Example
ABS = @ABS(Value);
This yields the following result: Value 6.8 5.3 -0.4 -0.7 -5.3 -6.8 Abs 6.8 5.3 0.4 0.7 5.3 6.8
Usage
A common use of @ABS is to test for tolerances. In the example, you are testing the result of a simultaneous equation. Whether the resulting tolerance is negative or positive is unimportant in this test.
Hyperion
5-5
Math Functions
@AVG
The @AVG() function calculates and returns the average of all values in a list.
Syntax
@AVG (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
West=@AVG(SKIPNONE,California:Nevada);
This example produces the following results: Cola California Oregon Washington Utah Nevada West 678 160 130 130 76 234.8 Diet Cola 145 150 #MI 170 #MI 93
5-6
Hyperion
Math Functions
@EXP
The @EXP() function returns the exponent of a specified expression; that is, the value of e (the base of natural logarithms) raised to the power of the specified expression.
Syntax
@EXP (expression)
Example
The following example is based on a variation of Sample Basic:
EXP = @EXP(Value);
This example produces the following results: Value 10.7 3.6 1 0.5 -0.5 EXP 44355.6 36.59823 2.718282 1.648721 0.606531
Note If the expression is less than -700 or greater than 700, Essbase returns #MISSING.
Hyperion
5-7
Math Functions
@FACTORIAL
The @FACTORIAL() function returns the factorial of expression. The factorial of a number is equal to 1*2*3*...* number.
Syntax
@FACTORIAL(expression)
Examples
Fact = @FACTORIAL(Value);
This example produces the following results: Value 10.7 3.6 1 0.5 -0.5 Fact 362880 36.59823 1 1 #Missing
Notes
If the expression is larger than 189 or less than zero, Essbase returns #MISSING. If the expression is non-integer, Essbase calculates the factorial value for the integer portion of the expression.
5-8
Hyperion
Math Functions
@INT
The @INT() function returns the next lowest integer value of expression.
Syntax
@INT (expression)
Example
Int = @INT(Value);
This yields the following result: Value 6.8 5.3 -0.4 -0.7 -5.3 -6.8 Int 6 5 -1 -1 -6 -7
Hyperion
5-9
Math Functions
@LN, @LOG, @LOG10

The @LN, @LOG and @LOG10 functions are used to calculate and return logarithm values. The @LN() function returns the natural logarithm (base e) of the specified expression. The @LOG10() function returns the logarithm (base 10) of the specified expression. The @LOG() function returns the logarithm (for the specified base) of the specified expression.
Syntax
@LN (expression) @LOG10 (expression) @LOG (expression, [base]) base (optional for LOG() function) - Single member specification, member combination, or numeric expression. If the base is omitted, Essbase calculates the base-10 logarithm of the specified expression. @LOG(Sales) is equivalent to @LOG10(Sales).
Example
LN_val = @LN(Value); LOG10_val = @LOG10(Value); LOG_val = @LOG(Value, 2);
This example produces the following result: Value .1 100 1000 0 -10 LN_val -2.30259 4.60517 6.907755 #Missing #Missing LOG10_val -1 2 3 #Missing #Missing LOG_val -3.32193 6.643856 9.965784 #Missing #Missing
Notes
If expression less than or equal to 0, Essbase returns #MISSING. If the value of base is #MISSING, less than or equal to 0, or close to 1, the @Log() function returns #MISSING.
5-10
Hyperion
Math Functions
@MAX, @MAXS, @MIN and @MINS

@MAX, @MAXS, @MIN and @MINS are used to find the maximum and minimum values of a range. The @MAXS and MINS functions permit skipping of #MISSING and 0 values.
Syntax
@MAX (expList) @MAXS (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList) @MIN (expList) @MINS (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Examples
Qtr1_Max = @MAX(Jan:Mar); Qtr1_MaxS_Both = @MAXS(SKIPBOTH, Qtr1_MaxS_None = @MAXS(SKIPNONE, Qtr1_Min = @MIN(Jan:Mar); Qtr1_MinS_Both = @MINS(SKIPBOTH, Qtr1_MinS_None = @MINS(SKIPNONE, Jan:Mar); Jan:Mar); Jan:Mar); Jan:Mar);
Sales Jan Feb Mar Qtr1_Max Qtr1_MaxS_Both Qtr1_MaxS_None Qtr1_Min Qtr1_MinS_Both Qtr1_MinS_None 500 0 700 700 700 700 0 500 0
COGS #Missing 1500 2300 2300 2300 2300 #Missing 1500 #Missing
Other -500 -350 0 0 -350 0 -500 -500 -500
Hyperion
5-11
Math Functions
@MOD
@MOD function calculates the modulus (the remainder) of a division operation. The modulus is produced by dividing mbrName1 by mbrName2. The modulus is the remainder for an integer quotient.
Syntax
@MOD (mbrName1, mbrName2)
Example
Mod = @MOD(Value, divisor);
This example produces the following results: Value 6.8 6.8 5.3 5.3 -5.3 -5.3 divisor 3 3.2 3 3.2 3 3.2 Mod 0.8 0.4 2.3 2.1 -2.3 -2.1
5-12
Hyperion
Math Functions
@POWER
The @POWER() function returns the value of the specified member or expression raised to power.
Syntax
@POWER (expression, power) power - Single member specification, variable name, function, or other numeric expression.
Examples
@POWER(14, 3) = 2744 @POWER (2, 8) = 256
Notes
If expression is negative, and if power is not an integer, Essbase returns #MISSING. If the value calculated by @POWER is an infinite number, Essbase returns #MISSING.
Hyperion
5-13
Math Functions
@REMAINDER
The @REMAINDER() function returns the value the decimal portion of the expression.
Syntax
@REMAINDER (expression)
Example
Remain = @REMAINDER(Value);
This example produces the following results: Value 6.8 5.3 -0.4 -0.7 -5.3 -6.8 Remain 0.8 0.3 -0.4 -0.7 -0.3 -0.8
5-14
Hyperion
Math Functions
@ROUND
@ROUND rounds expressions as indicated by the numDigits parameter. If numDigits is 0, an expression is rounded to the nearest integer. If numDigits is greater than 0, an expression is rounded to the specified number of decimal places. A negative value for numDigits rounds an expression to a power of 10. In this way, @ROUND also acts as a scaling factor.
Syntax
@ROUND (expression, [numDigits]) numDigits [optional] - Single-member specification, variable name, or other numeric expression that provides an integer value. Its default value is 0.
Example
Round = @ROUND(Value); Round2 = @ROUND(Value, 2);
This yields the following results: Value 6.82145 5.32544 -0.42135 -0.70688 -5.31234 -6.80988 Round 7 5 0 -1 -5 -7 Round2 6.82 5.33 -0.42 -0.71 -5.31 -6.81
Hyperion
5-15
Math Functions
@SUM
The @SUM() function returns the summation of all the values in a list.
Syntax
@SUM (expList)
Example
West = @SUM(California:Nevada);
This example produces the following results: Cola California Oregon Washington Utah Nevada West 678 160 130 130 76 1174 Diet Cola 145 150 #MI 170 #MI 465
5-16
Hyperion
Math Functions
@TRUNCATE
@TRUNCATE returns only the integer portion of an expression.
Syntax
@TRUNCATE (expression)
Example
Trunc = @TRUNCATE(Value);
This yields the following results: Value 6.82145 5.32544 -0.42135 -0.70688 -5.31234 -6.80988 Trunc 6 5 0 0 -5 -6
Hyperion
5-17
Math Functions
@VAR
@VAR presents the difference between the values of two members. This function considers accounts that are tagged in the database outline as Expense and accounts tagged as No Expense and calculates the variance accordingly. The variance (@VAR) is derived by subtracting mbrName2 values from mbrName1, unless an account is tagged as "Expense", in which case mbrName1 values are subtracted from mbrName2.
Syntax
@VAR (member1, member2)
Example
Variance=@VAR(Value1, Value2);
This yields the following results (assuming Value1 and Value2 do not represent Expense Accounts): Value1 6.82145 5.32544 -5.31234 -6.80988 Value2 5.32544 6.82145 -6.80988 -5.31234 Variance 1.49601 -1.49601 1.49754 -1.49754
5-18
Hyperion
Math Functions
@VARPER
The @VARPER function returns the percent difference between the values of two members. This function considers accounts that are tagged in the database outline as Expense and accounts tagged as No Expense and calculates the variance accordingly. The percent variance (@VARPER) is derived by subtracting the percent value of member2 from the percent value member1, unless an account is tagged as Expense in which case the member1 percent value is subtracted from the member2 percent value.
Syntax
@VARPER (member1, member2)
Example
Variance %=@VARPER(Value1, Value2);
This yields the following results (assuming Value1 and Value2 do not represent Expense Accounts): Value1 6.82145 5.32544 -5.31234 -6.80988 Value2 5.32544 6.82145 -6.80988 -5.31234 Variance % 28.09176 -21.931 21.99065 -28.1898
Hyperion
5-19
Math Functions
Exercise 5-1: Using Math Functions

For level-0 market members (cities), the Average Sales member stores the total sales for that city. For level-1 market members (states), the Average Sales member stores the average of the sales for the cities of a state. For example, the Average Sales for Connecticut is the total sales for Connecticut divided by the number of cities in Connecticut. In this exercise, you use the @ROUND and @AVG functions within a calc script to calculate Connecticuts Average Sales. The value is to be rounded to two decimals. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSMath SS_Math.xls
1) 2)
From Essbase Application Manager, clear all data from your HLandS1 database. Create a new calc script to calculate the Average Sales for Connecticut to represent the average amount of sales in the cities in Connecticut. Use the @AVG function, and use the @ROUND function to round the calculated values to two decimal places. Save the new script as CSMath. Open the SS_Math spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS1 database. From the Calc&Retrieve sheet, run the CSMath calc script. Perform a retrieval and note the calculation results. Ensure that the commission is calculated correctly. If not, revise the calc script and rerun the calculation. Close the CSMath spreadsheet.
3) 4) 5) 6)
7) 8)
5-20
Hyperion
Math Functions
Unit Summary
A wide range of mathematical functions is available for the creation of calc scripts. These include simple arithmetic operations, such as: absolute values rounding, truncation variance calculation factorial
Hyperion
H H H H H H H H
There are more complicated arithmetic operations, such as: logarithms and exponentiation modulus arithmetic
There are also math functions that perform operations on lists, such as: summation and averaging selecting maximum or minimum value
To promote consistency throughout an application, use the Essbase functions rather than creating your own formulas.
5-21
5 Math Functions Check Your Understanding

1)
Now that you have completed the chapter, check your understanding by responding to the following questions: For each of the following situations, identify the Math function that you apply.
Calculate the total of a series of values. Compute the average of a collection of values. What is the value of the next lowest integer to number? Determine the minimum value in a list, excluding #MISSING and 0 values. Find the remainder when one number is divided by another to produce an integer quotient.
5-22
Hyperion
Math Functions

1) For each of the following situations, identify the Math function that you apply.
Calculate the total of a series of values. Compute the average of a collection of values. What is the value of the next lowest integer to number? Determine the minimum value in a list, excluding #MISSING and 0 values. Find the remainder when one number is divided by another to produce an integer quotient. @SUM @AVG @INT
@MINS
@MOD
Hyperion
5-23
Math Functions
5-24
Hyperion
6
Boolean Functions
Chapter Objectives
By the end of this chapter, you will be able to: Describe and demonstrate the use of Boolean functions to test values in a Calc Script Practice using boolean functions to a series of incremental exercises
Boolean Functions
Testing for Values Using Boolean Functions

A Boolean function returns a value of TRUE (1) or FALSE (0). Boolean functions are usually used within conditional statements. The determination is based on the characteristics of the current member combination. For example, you may want to test whether current member California is in a list of members so that you can adjust salary to match California's higher cost of living. When a boolean function begins with @ISI, the TRUE test includes the member specified in the parameter list. For example, @ISDESC(EAST) includes New York, Boston, and Chicago, and @ISIDESC(EAST) includes East, New York, Boston, and Chicago. When a boolean function has a related @ISI function, the detailed description section of this chapter presents them together. Not all tests can be performed with a single condition. Essbase provides three logical connectors for compound logical tests: AND, OR, and NOT.
Boolean Function Parameters

There are common parameters associated with the various boolean functions:
mbrName mbrList rangeList Single-member specification Comma-delimited list of members Colon-delimited range of members, member set functions, or range functions Name of the specified dimension
dimName
6-2
Hyperion
Boolean Functions
Summary of Boolean Functions

This table summarizes the Boolean Functions. Each function is also described, in detail, in this chapter.
Function @ISACCTYPE Tests Does current member have the specified accounts tag? Is the current member an ancestor of the specified member? Is the current member a child of the specified member? Is the current member a descendant of the specified member? Is the current member at the specified dimension generation Is the current member an ancestor of the specified member, or the specified member itself? Is the current member a child of the specified member, or the specified member itself? Is the member being calculated a descendant of the specified member, or the specified member itself? Is the current member the parent of the specified member, or the specified member itself? Is the current member a sibling of the specified member, or the specified member itself? Is the current member at the specified dimension level? Is calculation being done for the specified member? Is the current member the parent of the specified member? Is the current member the same generation as the specified member? Is the current member the same level as the specified member?
@ISANCEST
@ISCHILD
@ISDESC
@ISGEN
@ISIANCEST
@ISICHILD
@ISIDESC
@ISIPARENT
@ISISIBLING
@ISLEV
@ISMBR @ISPARENT
@ISSAMEGEN
@ISSAMELEV
Hyperion
6-3
Boolean Functions
Function @ISSIBLING
Tests Is the current member a sibling of the specified member? Does the current member of the specified dimension have the specified user-defined attribute (UDA) at the time of the calculation?
@ISUDA
6-4
Hyperion
Boolean Functions
@ISACCTYPE
The @ISACCTYPE() function returns TRUE if the current member has the specified accounts tag.
Syntax
@ISACCTYPE(tag) tag - Valid account tag defined in the current database. Any of the following tags may be used: First, Last, Average, Expense, and TwoPass.
Example
The following example is based on the Sample Basic database. For members with the Expense accounts tag, the formula uses the @ABS function to calculate Budget as the absolute value of Budget.
IF (@ISACCTYPE(Expense)) Budget = @ABS(Budget); ENDIF;
Hyperion
6-5
Boolean Functions
@ISANCEST, @ISANCEST
The @ISANCEST() function returns TRUE if the current member is an ancestor of the specified member. This function excludes the specified member. The @ISIANCEST() function returns TRUE if the current member is the specified member or an ancestor of the specified member.
Syntax
@ISANCEST(mbrName) @ISIANCEST(mbrName)
Example
In the Sample Basic database:
@ISANCEST(California) returns TRUE for Market, West. @ISANCEST(West) returns FALSE for California, West, East. @ISIANCEST(California) returnsTRUE for California, Market, West. @ISIANCEST(West) returns FALSE for California, East.
6-6
Hyperion
Boolean Functions
@ISCHILD, @ISICHILD
The @ISCHILD() function returns TRUE if the current member is a child of the specified member. This function excludes the specified member. The @ISICHILD() function returns TRUE if the current member is the specified member or a child of the specified member.
Syntax
@ISCHILD(mbrName) @ISICHILD(mbrName)
Example
@ISCHILD(East) returns TRUE for New York, Florida, Connecticut. @ISCHILD(Margin) returns FALSE for Measures, Profit, Margin. @ISICHILD(East) returns TRUE for New York, Florida, Connecticut,
East.
@ISICHILD(Margin) returns FALSE for Measures, Profit.
Hyperion
6-7
Boolean Functions
@ISDESC, @ISIDESC
The @ISDESC function returns TRUE if the member being calculated is a descendant of the referenced member. The @ISDESC function excludes the specified member. @ISIDESC returns TRUE if the member being calculated is a descendant of the referenced member, or the member itself.
Syntax
@ISDESC (mbrName) @ISIDESC (mbrName)
Example
Payroll (IF(@ISDESC(East) OR @ISDESC (West)) Payroll = Sales * .15; ELSEIF (@ISDESC (Central)) Payroll = Sales * .11; ELSE Payroll = Sales * .10; ENDIF)
The example operates as follows: The IF condition uses @ISDESC to determine whether the member of the Market dimension being calculated is a descendant of either East or West. If the member being calculated on the Market dimension is a descendant of East or West, Payroll is calculated by multiplying the value in Sales by 0.15. If the current member is not a descendant of East or West, the ELSEIF condition uses the @ISDESC function to determine whether the current member is a descendant of Central. If the current member on the Market dimension is a descendant of Central, Payroll is calculated by multiplying the value in Sales by 0.11. If the current member is not a descendant of East, West, or Central, Payroll is calculated by multiplying value in Sales by 0.10.
6-8
Hyperion
Boolean Functions
@ISGEN
The @ISGEN() function returns TRUE if the current member of the specified dimension is in the specified generation.
Syntax
@ISGEN(dimName, genName | genNum) genName - Generation name that defines the number of a generation. or genNum - A non-negative number that defines the number of a generation.
Example
@ISGEN(Measures,3)
returns TRUE if the current member is Margin, Total Inventory, or Margin %, because these members are all in generation 3 of the Measures dimension.
@ISGEN(Market,East)
returns TRUE if the current member is East, West, South or Central because these members are not in the same Market dimension generation as East.
Hyperion
6-9
Boolean Functions
@ISLEV
The @ISLEV function returns TRUE if the current member (the member being calculated) of the specified dimension is at the specified level. The @ISLEV function determines position within a hierarchy and is particularly useful when working with asymmetric hierarchies.
Syntax
@ISLEV (dimName, level) level - Member specification, variable name, or numeric expression (The numeric expression provides an integer value equal to or greater than 0, and identifies the level.)
Example
IF (@ISLEV("Market", 0))
returns TRUE if the current member is New York, Florida, California, etc. because these members are all in level 0 of the Market dimension. returns FASLE if the current member is East because East has children and therefore is a Level 1 member.
Notes
Using @ISLEV can significantly reduce calculation time. If a lower-level formula is calculated, all higher levels are aggregated by default. To prevent this, use @ISLEV to isolate the calculation, thus preventing the default aggregation behavior.
6-10
Hyperion
Boolean Functions
@ISMBR
The @ISMBR function returns TRUE if any specified member matches the member being calculated. A single member, a range of members, or a discrete list of members may be specified.
Syntax
@ISMBR (mbrName | rangeList | mbrList)
Example
Commission (IF @ISMBR(Actual) Commission = Sales *.10; ELSEIF (@ISMBR(Budget)) Commission = 100; ENDIF)
The example syntax calculates different values for Commission for Actual and Budget.
Notes
If you examine the contents of a range or list of values, results such as the following are returned (for the Sample Basic database): @ISMBR(New York:New Hampshire) TRUE for Connecticut. @ISMBR(New York,Oregon,Texas) FALSE for Connecticut. If a cross-dimensional (->) member term is included, the term evaluates as TRUE only if all the cross-dimensional member's components match the current member list.
Hyperion
6-11
Boolean Functions
@ISPARENT, @ISIPARENT
The @ISPARENT() function returns TRUE if the current member is the parent of the specified member. This function excludes the specified member. The @ISIPARENT() function returns TRUE if the current member is the specified member or the parent of the specified member.
Syntax
@ISPARENT(mbrName) @ISIPARENT(mbrName)
Example
@ISPARENT("New York") returns TRUE for East. @ISPARENT(Profit) returns FALSE for Margin, Profit. @ISIPARENT("New York") returns TRUE for East, New York. @ISIPARENT(Profit) returns FALSE for Margin.
6-12
Hyperion
Boolean Functions
@ISSAMEGEN
The @ISSAMEGEN() function returns TRUE if the current member is the same generation as the specified member.
Syntax
@ISSAMEGEN(mbrName)
Example
@ISSAMEGEN(West)returns TRUE for East. @ISSAMEGEN(West)returns FALSE for California.
@ISSAMELEV
The @ISSAMELEV() function returns TRUE if the current member is the same level as the specified member.
Syntax
@ISSAMELEV(mbrName)
Example
@ISSAMELEV(Sales)returns FALSE for Total Expenses . @ISSAMELEV(Jan)returns TRUE for Apr, Jul, Oct.
Hyperion
6-13
Boolean Functions
@ISSIBLING, @ISISIBLING
The @ISSIBLING() function returns TRUE if the current member is a sibling of the specified member. This function excludes the specified member. The @ISISIBLING() function returns TRUE if the current member is the specified member or a sibling of the specified member.
Syntax
@ISSIBLING(mbrName) @ISISIBLING(mbrName)
Example
@ISSIBLING("New York")returns TRUE for Florida, New Hampshire. @ISSIBLING(Sales)returns FALSE for Margin, Sales. @ISISIBLING("New York")returns TRUE for Florida, New Hampshire,
New York.
@ISISIBLING(Sales)returns FALSE for Margin.
6-14
Hyperion
Boolean Functions
@ISUDA
The @ISUDA() function returns TRUE if the specified user-defined attribute (UDA) exists for the current member of the specified dimension at the time of the calculation.
Syntax
@ISUDA(dimName,UDAStr) UDAStr - user-defined attribute (UDA) name string.
Example
This example is based on the Sample Basic database. The Market dimension has members that indicate a geographic location. Some members represent major markets. The example below calculates the database and stores a budget amount for the upcoming year based on the actual amount from this year. A different sales growth rate is applied to major markets than to small markets.
FIX (Budget) Sales (IF(@ISUDA(Market,"Major Market")) Sales = Sales->Actual * 1.2; ELSE Sales = Sales->Actual * 1.1; ENDIF;); ENDFIX
This example tests to see if the current member of Market has a UDA called "Major Market". If it does, the Budget->Sales value is set to 120% of Actual->Sales. If it does not, the Budget->Sales value is set to 110% of Actual->Sales.
Hyperion
6-15
Boolean Functions
Using Logical Connectors with Boolean Functions

Although the use of logical connectors is straightforward, you should be careful of compound conditions. Be careful when using NOT and when placing parentheses. Refer to the following table to reinforce your understanding of logical connectors:
Condition1 Condition2 Condition1 Condition1
NOT
(Condition1)
AND
Condition2 True True False False True False True False True False False False
OR
Condition2 True True True False
False False True True
Examples
Note the use of the NOT connector in the first example:
COMMISSION (IF(NOT(@ISUDA(SCENARIO,"MYUDA"))) COMMISSION = 100; ENDIF)
Some conditional Boolean statements can be complex:

"TAX RATE" (IF(NOT(@ISLEV(GEOGRAPHY,0) AND @ISLEV(TIME,0))) "TAX RATE" = ("TAX PROVISION"/"PRE TAX INCOME") * 100; ENDIF)
Usage
When using compound IF statements, as in the second example, placement of parentheses is very important.
6-16
Hyperion
Boolean Functions
Exercise 6-1: Using Boolean Functions

In this exercise, you use the @ISDESC function within a calc script to calculate the budgeted product sales for all cities. The company expects 2000 sales for cities in the South to increase by 15% over actual 1999 sales, 2000 sales for cities in the East and West to increase by 10% over actual 1999 sales, and 2000 sales for cities in the Central region to decrease by 5% from actual 1999 sales. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSBool SS_Bool.xls
1) 2)
From Essbase Application Manager, clear all data from your HLandS1 database. Create a new calc script to calculate the 2000 budgeted product sales for all cities. The company projects 2000 sales for cities in the South to increase by 15% over actual 1999 sales, 2000 sales for cities in the East and West to increase by 10% over actual 1999 sales, and 2000 sales for cities in the Central region to decrease by 5% from actual 1999 sales. Save the new script as CSBool. Open the SS_Bool spreadsheet. Lock and send the 1999 Actual Sales data in the Lock&Send sheet to the HLandS1 database. From the Calc&Retrieve sheet, run the CSBool calc script. Perform a retrieval and compare the calculation results to the Expected Values column. Ensure that the projected sales are calculated correctly. If not, revise the calc script and rerun the calculation. Close the SS_Bool spreadsheet.
3) 4) 5) 6)
7)
8)
Hyperion
6-17
Boolean Functions
Unit Summary
Tests can be performed on data using if-logic of the conditional statements. Many conditional statements use Boolean functions to identify characteristics of the member for which calculations are currently being performed. Compound conditions can also be created by using: logical connectors: AND, OR and NOT parenthesis to control the logical interpretation
6-18
Hyperion
Boolean Functions

Now that you have completed the chapter, check your understanding by responding to the following questions: 1) For each of the following situations, identify the Boolean function that you would use to isolate the required members. Use the Sample Basic outline.
Perform a calculation for New York, only? Perform a calculation for East, and all the cities in the East market. Perform a calculation for all level one members of the Market Dimension. Perform a calculation for New York, East and Market, only. Perform a calculation for all accounts that are identified as Expense.
Hyperion
6-19
6 Boolean Functions Check Your Understanding Solutions

1)
For each of the following situations, identify the Boolean function that you would use to isolate the required members. Use the Sample Basic outline.
Perform a calculation for New York, only? Perform a calculation for East, and all the cities in the East market. Perform a calculation for all level one members of the Market Dimension. Perform a calculation for New York, East and Market, only. Perform a calculation for all accounts that are identified as Expense. @ISMBR @ISICHILD
@ISLEV
@ISIANCEST
@ISACCTYPE
6-20
Hyperion
Boolean Functions
Hyperion
6-21
Boolean Functions
6-22
Hyperion
7
Member Set Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of member set functions to generate member lists Practice using the member set functions in a series of incremental exercises
Generating Lists Using Member set Functions

A member set function generates a list of members based on the criteria provided as arguments. If a generation or level number is required, the current calculation position affects the returned list. The member list is generated dynamically at the time the member set function is executed, thus reducing the need to hard-code member names. Member set functions can be broken into three basic categories: Family member sets generate a list of members based upon a hierarchical relationship. for example, @CHILDREN, @DESCENDANTS, @SIBLING, @RELATIVE Generation and level member sets generate a list of members based upon a generation or level number, for example, @GENMBRS, @LEVMBRS. Other member sets generate lists in a variety of ways, such as performing a search on a wild card pattern, for example, @MATCH, @UDA. A member set function can be used as a parameter of another function, if the parameter of the other function can be list of members. Using a member set function in conjunction with the FIX command fixes on a list of members. Obviously, this can be used to resolve issues of data that may be constantly changing and to avoid hard-coding of member lists. When a member set function begins with an @I, the generated list includes the referenced member and the requested members. For example, if @DESCENDANTS(EAST) includes New York, Boston, and Chicago, and @IDESCENDANTS(EAST) includes East, New York, Boston, and Chicago.
Member Set Function Parameters

There are common parameters associated with the various member set functions:
dimName mbrName, mbrName1, mbrName2 genLevNum An integer value that defines the generation or level number from which the ancestor value is returned. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. Single dimension name specification. Specifies a single member.
7-2
Hyperion
Summary of Member Set Functions

This table summarizes the Member Set Functions. Each function is also described, in detail, in this chapter.
Function @ALLANCESTORS Used to generate a list containing All the ancestors of that member, including ancestors of any occurrences of the specified member as a shared member. The ancestor at the specified generation or level in the specified dimension of the current member being calculated. All ancestors of the specified member or those up to the specified generation or level. All base members that are associated with the specified attribute member. All members in the level immediately below the specified member. The member that is currently being calculated in the specified dimension. All descendants of the specified member, or those down to the specified generation or level. All members with the specified generation number or generation name in the specified dimension. The specified member and all the ancestors of that member, including ancestors of any occurrences of the specified member as a shared member. The specified member and all ancestors of the specified member or those up to the specified generation or level. The specified member and all members in the level immediately below the specified member. The specified member and all descendants of the specified member, or those down to the specified generation or level. The specified member and all members that share the same parent as that member and precede that member in the database outline. The specified member and all members that share the same parent as that member and that follow that member in the database outline.
@ANCEST
@ANCESTORS
@ATTRIBUTE
@CHILDREN
@CURRMBR
@DESCENDANTS
@GENMBRS
@IALLANCESTORS
@IANCESTORS
@ICHILDREN
@IDESCENDANTS
@ILSIBLINGS
@IRSIBLINGS
Hyperion
7-3
Function @IRDESCENDANTS
Used to generate a list containing The specified member and all descendants of the specified member (including descendants of shared members), or those down to the specified generation or level. The specified member and all siblings of that member. All members with the specified level number or level name in the specified dimension. A collection of individual items that are to be passed to functions that require list arguments. All members that share the same parent as the specified member and precede that member in the database outline. All members whose names match a specified pattern. The member with the name that is provided as a character string. The union of two member lists that are to be passed to another function. The parent of the current member being calculated in the specified dimension. A member list that crosses the specified member from one dimension with the specified member range from another dimension. All descendants of the specified member (including descendants of shared members), or those down to the specified generation or level. All members at the specified generation or level that are above or below the specified member in the database outline. A list from which with selected values have been removed. All members that share the same parent as the specified member and that follow that member in the database outline. All siblings of the specified member. Members with a common user-defined attribute (UDA). All base members that are associated with an attribute that satisfies a specified condition.
@ISIBLINGS @LEVMBRS
@LIST
@LSIBLINGS
@MATCH @MEMBER
@MERGE
@PARENT
@RANGE
@RDESCENDANTS
@RELATIVE
@REMOVE
@RSIBLINGS
@SIBLINGS @UDA
@WITHATTR
7-4
Hyperion
Function @XRANGE *
Used to generate a list containing All members in the range specified by the arguments used in the function.
* New in Essbase XTD Release 6.5.1.
Hyperion
7-5
@ALLANCESTORS
The @ALLANCESTORS() function returns all ancestors of the specified member, including ancestors of any occurrences of the specified member as a shared member. This function excludes the specified member.
Syntax
@ALLANCESTORS(mbrName)
Example
The following example is based on the Sample Basic database. Sample Basic has a shared level of diet drinks, which includes 100-20 (Diet Cola). So 100-20 (Diet Cola) is a descendant of 100 (Colas) and is a shared member descendant of Diet.
@ALLANCESTORS("100-20")returns 100, Diet and Product
Notes
Essbase sorts the generated list of members in ascending order of the member number in the outline. However, the order in which shared ancestors are returned is not guaranteed. This order is important to consider when you use the @ALLANCESTORS member set function with certain forecasting and statistical functions.
7-6
Hyperion
@ANCEST
The @ANCEST() function returns the ancestor at the specified generation or level of the current member being calculated in the specified dimension. If you specify the optional mbrName, that ancestor is combined with the specified member.
Syntax
@ANCEST(dimName, genLevNum [, mbrName])
Example
@ANCEST(Product,2,Sales) returns Colas->Sales, if the current member
of Product being calculated is Diet Cola.

@ANCEST(Measures,3,East) returns Total Expenses->East, if the current
member of Measures being calculated is Payroll.
Notes
You cannot use the @ANCEST function in a FIX statement. You can use the @ANCEST function on both the left-hand and right-hand sides of a formula. In some cases, the @ANCEST function is equivalent to the @ANCESTVAL function, except in terms of calculation performance. For example, the following two formulas are equivalent:
Sales = @ANCEST(Product,2); Sales = @ANCESTVAL(Product,2);
In this case, using the latter formula results in better calculation performance. The time required for retrieval and calculation may be significantly longer if this function is in a formula attached to a member tagged as Dynamic Calc or Dynamic Calc and Store.
Hyperion
7-7
@ANCESTORS
The @ANCESTORS() function returns all ancestors of the specified member or those up to a specified generation or level.
Syntax
@ANCESTORS (mbrName [, genLevNum | genLevName])
Example
@ANCESTORS("New York")returns East, Market (in that order). @ANCESTORS(Qtr4)returns Year. @ANCESTORS("100-10",1)returns 100, Product (in that order). @ANCESTORS(Sales,-2) eturns Margin, Profit (in that order).
Notes
Essbase sorts the generated list of members starting with the specified member, followed by nearest ancestor of the member, then the next nearest ancestor of the member, and so on. This order is important to consider when you use the @ANCESTORS member set function with certain forecasting and statistical functions.
7-8
Hyperion
@ATTRIBUTE
The @ATTRIBUTE() function generates a list of all base members that are associated with the specified attribute member.
Syntax
@ATTRIBUTE (attMbrName) attMbrName - Single attribute member name or member combination.
Example
In the Sample Basic database,
@ATTRIBUTE(Can) returns all base members with the Can attribute: Cola,
Diet Cola, and Diet Cream.
Notes
When @ATTRIBUTE is used with a non-level 0 member of an attribute dimension, Essbase returns all base members that are associated with the children of the attribute member. For example, in the Sample Basic database, @ATTRIBUTE(Large) returns all base members that fall into one of the population ranges for the attribute parent Large. If you specify the name of a Boolean attribute dimension (for example, Caffeinated), Essbase returns all base members that are associated with either Caffeinated member (for example, True or False). To return only one, specify the member name (for example, @ATTRIBUTE(Caffeinated_True)). You may have duplicate Boolean, date, and numeric attribute member names in your outline. For example, 12 can be the attribute value for the size (in ounces) of a product as well as the value for the number of packing units for a product. To distinguish duplicate member names, specify the full attribute member name (for example, @ATTRIBUTE(12_Ounces)). Essbase sorts the generated list of members in ascending order from the database outline. This order is important to consider when you use the @ATTRIBUTE member set function with certain forecasting and statistical functions.
Hyperion
7-9
@CHILDREN
The @CHILDREN () function returns all children of the specified member, excluding the specified member.
Syntax
@CHILDREN(mbrName)
Example
@CHILDREN(Market)returns East, West, South, and Central. @CHILDREN(Margin)returns Sales and COGS.
Notes
Essbase sorts the generated list of members in ascending order. Using Sample Basic as an example, if you specify 100 for mbrName, Essbase returns 100-10, 100-20, 100-30 (in that order). This order is important to consider when you use the @CHILDREN member set function with certain forecasting and statistical functions.
7-10
Hyperion
@CURRMBR
The @CURRMBR() function returns the member that is currently being calculated in the specified dimension.
Syntax
@CURRMBR(dimName)
Example
@CURRMBR(Year)returns Jan if the current member of Year being
calculated is Jan. As a more complex example, consider:

@CHILDREN(@CURRMBR(Product)) generates a list of all children for the current member of the Product dimension.
Notes
You cannot use the @CURRMBR function in a FIX statement. You cannot use the @CURRMBR function on the left-hand side of a formula. The time required for retrieval and calculation may be significantly longer if this function is in a formula attached to a member tagged as Dynamic Calc or Dynamic Calc and Store.
Hyperion
7-11
@DESCENDANTS
The @DESCENDANTS function returns all descendants of the specified member, or those down to the specified generation or level. This function excludes the specified member.
Syntax
@DESCENDANTS(mbrName [, genLevNum| genLevName]) Optional genLevNum - An integer value that defines the absolute generation or level number down to which to select the members. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. or genLevName - Level name or generation name down to which to select the members.
Example
@DESCENDANTS(East)returns New York, Massachusetts, Florida,
Connecticut, and New Hampshire.

@DESCENDANTS(Profit)returns Margin, Sales, COGS, Total Expenses,
Marketing, Payroll, and Misc.

@DESCENDANTS(Market,2)returns East, West, South, and Central . @DESCENDANTS(Diet,0)returns 100-20, 200-20, and 300-30.
Notes
Essbase sorts the generated list of members starting with the nearest descendant of the member, followed by the next nearest descendant of the member, and so on. This order is important to consider when you use the @DESCENDANTS member set function with certain forecasting and statistical functions.
7-12
Hyperion
@GENMBRS
The @GENMBRS() function returns all members with the specified generation number or generation name in the specified dimension.
Syntax
@GENMBRS(dimName,genName|genNum) genNum - An positive integer value that defines the absolute generation number. or genName - Generation name from the specified dimension.
Example
@GENMBRS(Year,May) @GENMBRS(Year,3)
both return Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec (in that order).
Notes
If you specify a name for the genName parameter, Essbase looks for a generation with that name in the specified dimension. If you specify a number for the genName parameter, Essbase first looks for a generation with a number string name. If no generation name exists with that numeric name, Essbase checks to see if the parameter is a valid generation number. If you specify a temporary variable for the genName parameter, Essbase does not recognize the value of the variable. It looks in the outline for a generation name with the same name as the temporary variable. Essbase sorts the generated list of members in ascending order. Using Sample Basic as an example, if you specify @GENMBRS(Product,2), Essbase returns 100, 200, 300, 400, Diet (in that order). This order is important to consider when you use the @GENMBRS member set function with certain forecasting and statistical functions.
Hyperion
7-13
@IALLANCESTORS
The @IALLANCESTORS() function returns the specified member and all the ancestors of that member, including ancestors of any occurrences of the specified member as a shared member.
Syntax
@IALLANCESTORS(mbrName)
Example
The following example is based on the Sample Basic database. Sample Basic has a shared level of diet drinks, which includes 100-20 (Diet Cola). So 100-20 (Diet Cola) is a descendant of 100 (Colas) and is a shared member descendant of Diet.
@IALLANCESTORS("100-20") returns 100-20, 100, Diet and
Product
Notes
Essbase sorts the generated list of members in ascending order of the member number in the outline. However, the order in which shared ancestors are returned is not guaranteed. This order is important to consider when you use the @IALLANCESTORS member set function with certain forecasting and statistical functions.
7-14
Hyperion
@IANCESTORS
The @IANCESTORS() function returns the specified member and all ancestors of the specified member or those up to the specified generation or level.
Syntax
@IANCESTORS (mbrName [, genLevNum | genLevName])
Example
@IANCESTORS("New York") returns New York, East, Market (in that
order).
@IANCESTORS(Qtr4) returns Qtr4, Year. @IANCESTORS("100-10",1) returns "100-10", 100, Product (in that order). @IANCESTORS(Sales,-2) returns Sales, Margin, Profit (in that order).
Notes
Essbase sorts the generated list of members starting with the specified member, followed by nearest ancestor of the member, then the next nearest ancestor of the member, and so on. This order is important to consider when you use the @ANCESTORS member set function with certain forecasting and statistical functions.
Hyperion
7-15
@ICHILDREN
The @ICHILDREN() function includes the specified member and all members in the level immediately below the specified member.
Syntax
@ICHILDREN(mbrName)
Example
@ICHILDREN(Market)returns Market, East, West, South, and Central. @ICHILDREN(Margin)returns Margin, Sales and COGS.
Notes
Essbase sorts the generated list of members starting with the specified member, followed by its children in ascending order. This order is important to consider when you use the @ICHILDREN member set function with certain forecasting and statistical functions.
7-16
Hyperion
@IDESCENDANTS
The @IDESCENDANTS function returns the specified member and all descendants of the specified member, or those down to the specified generation or level.
Syntax
@IDESCENDANTS(mbrName [, genLevNum| genLevName]) genLevNum - An integer value that defines the absolute generation or level number down to which to select the members. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. or genLevName - Level name or generation name down to which to select the members.
Example
@IDESCENDANTS(East) returns East, New York, Massachusetts, Florida,
Connecticut, and New Hampshire.

@IDESCENDANTS(Profit)returns Profi, Margin, Sales, COGS, Total Expenses, Marketing, Payroll, and Misc. @IDESCENDANTS(Diet,0)returns Diet, 100-20, 200-20, and 300-30. @IDESCENDANTS(Market,2) returns Market, East, and West.
Notes
Essbase sorts the generated list of members as follows: The specified member The nearest descendant of the member The next nearest descendant of the member, and so on
This order is important to consider when you use the @IDESCENDANTS member set function with certain forecasting and statistical functions.
Hyperion
7-17
@ILSIBLINGS
The @ILSIBLINGS() function returns the specified member and all of the left siblings of the member. Left siblings are children that share the same parent as the member and that precede the member in the database outline.
Syntax
@ILSIBLINGS(mbrName)
Example
@ILSIBLINGS(Florida) returns New York, Massachusetts, and Florida . @ILSIBLINGS(Qtr3) returns Qtr1, Qtr2, and Qtr3.
Notes
Essbase sorts the generated list of members starting with the left siblings of the member (that is, siblings appearing above the member in the database outline) in ascending order. This order is important to consider when you use the @ILSIBLINGS member set function with certain forecasting and statistical functions.
7-18
Hyperion
@IRDESCENDANTS
The @IRDESCENDANTS function returns the specified member and all its descendants, or those down to the specified generation or level. If one or more of the descendants are shared, the result also includes either all descendants of each member being shared or descendants down to the specified generation or level.
Syntax
@IRDESCENDANTS(mbrName [, genLevNum| genLevName]) genLevNum - An integer value that defines the absolute generation or level number down to which to select the members. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. or genLevName - Level name or generation name down to which to select the members.
Example
Consider an outline with the following Product dimension:
Product 100 100-10 100-20 100-30 200 200-10 200-20 200-30 200-40 Diet 100 (Shared Member) 200 (Shared Member)
Diet has two children "100" and "200". The members "100" and "200" are shared members.
@IRDESCENDANTS(Diet) returns the members: Diet, 100, 100-10, 100-20, 100-30, 200, 200-10, 200-20, 200-30, 200-40 (in that order).
Hyperion
7-19
Notes
In the absence of shared members, @IRDESCENDANTS and @IDESCENDANTS return the same result. Essbase generates the list of members in the following sequence: The specified member The nearest descendant of the member The next nearest descendant of the member, and so on. If a shared member is encountered, the above steps are repeated on the member being shared.
The order of members in the result list is important to consider when you use the @IRDESCENDANTS member set function with certain forecasting and statistical functions.
7-20
Hyperion
@IRSIBLINGS
The @IRSIBLINGS() function returns the specified member and all of the right siblings of the specified member. Right siblings are children that share the same parent as the member and that follow the member in the database outline.
Syntax
@IRSIBLINGS (mbrName)
Example
@IRSIBLINGS(Florida) returns Florida, Connecticut, and New
Hampshire. @IRSIBLINGS(Qtr3) returns Qtr3 and Qtr4.
Notes
Essbase sorts the generated list of members starting with the specified member, followed by the right siblings of the member (that is, siblings appearing below the member in the database outline) in ascending order. Using Sample Basic as an example, if you specify 200-20 for mbrName, Essbase returns 200-20, 200-30, 200-40 (in that order). This order is important to consider when you use the @IRSIBLINGS member set function with certain forecasting and statistical functions.
Hyperion
7-21
@ISIBLINGS
The @ISIBLINGS() function returns the specified member and all siblings of that member.
Syntax
@ISIBLINGS (mbrName)
Example
@ISIBLINGS(California) returns California, Oregon, Washington, Utah, and Nevada (in that order). @ISIBLINGS(Qtr2) returns Qtr1, Qtr2, Qtr3, and Qtr4 (in that order), .
Notes
Essbase sorts the generated list of members in ascending order. Using Sample Basic as an example, if you specify 200-30 for mbrName, Essbase returns 200-10, 200-20, 200-30, 200-40 (in that order). This order is important to consider when you use the @ISIBLINGS member set function with certain forecasting and statistical functions.
7-22
Hyperion
@LEVMBRS
The @LEVMBRS() function returns all members with the specified level number or level name in the specified dimension.
Syntax
@LEVMBRS(dimName, levName|levNum) levName - A level name of the specified dimension. or levNum - An integer value that defines the number of a level. The integer value must be 0 or a positive integer.
Example
@LEVMBRS(Measures,"Profit and Loss") @LEVMBRS(Measures,0)
both return Sales, COGS, Marketing, Payroll, Misc, Opening Inventory, Additions, Ending Inventory, Margin %, Profit %, and Profit per Ounce (in that order).
@LEVMBRS(Scenario,0) returns Actual, Budget, Variance, and Variance
%.
Notes
If you specify a name for the levName parameter, Essbase looks for a level with that name in the specified dimension. If you specify a number for the levName parameter (for example, 2), Essbase first looks for a level with a number string name. If no level name exists with that name, Essbase checks to see if the parameter is a valid level number. If you specify a temporary variable for the levName parameter, Essbase does not recognize the value of the variable. It looks in the outline for a level name with the same name as the temporary variable.
Hyperion
7-23
Essbase sorts the generated list of members in ascending order. This order is important to consider when you use the @LEVMBRS member set function with certain forecasting and statistical functions. If you use a negative number for the level number, no syntax error is noted, but the calculation will fail with an error message.
7-24
Hyperion
@LIST
The @LIST() function creates and distinguishes lists that are processed by functions that require list arguments. @LIST can be used to create expLists, member lists, or rangeLists. @LIST treats a collection of parameters as one entity.
Syntax
@LIST(argument1, argument2,..., argumentN) argument1, argument2,..., argumentN - The list of arguments that are collected and treated as one argument so they can be processed by the parent function. Arguments can be member names, member combinations, member set functions, range functions, and numeric expressions.
Example
A company ran special promotional activities for January, June and August. Their Essbase database has an account field to store sales for the promotional periods. One way to populate this field:
FIX (Sales) Special Sales= @SUM(@LIST(Jan,Jun, Aug)); ENDFIX
Notes
@LIST does not check for or eliminate repetitions.
Hyperion
7-25
@LSIBLINGS
The @LSIBLINGS() function returns the left siblings of the specified member. Left siblings are children that share the same parent as the member and that precede the member in the database outline. This function excludes the specified member.
Syntax
@LSIBLINGS (mbrName)
Example
@LSIBLINGS(Qtr4) returns Qtr3, Qtr2, and Qtr1. @LSIBLINGS(Utah) returns Washington, Oregon, and California.
Notes
Essbase sorts the generated list of left siblings in descending order. This order is important to consider when you use the @LSIBLINGS member set function with certain forecasting and statistical functions.
7-26
Hyperion
@MATCH
The @MATCH function performs wildcard member selections.
Syntax
@MATCH (mbrName|genName|levName, "pattern") mbrName - The default or user-defined name of the member on which to base the search. Essbase searches the member names and alias names of the specified member and its descendants. or genName - The default or user-defined name of the generation to search. Essbase searches all member names and member alias names in the generation. or levName -The default or user-defined name of the level to search. Essbase searches all member names and member alias names in the level. "pattern" The character pattern to search for, including a wildcard character (* or ?).
Example
@MATCH(Product,"???-10") returns: 100-10, 200-10, 300-10, and 400-10 @MATCH(Year,"J*") returns: Jan, Jun, Jul @MATCH(Product,"C*") returns: 100 (Colas), 100-10 (Cola), 100-30
(Caffeine Free Cola), 300 (Cream Soda)
Notes
? substitutes one occurrence of any character. You can use ? anywhere in the pattern. * substitutes any number of characters. You can use * only at the end of the pattern. To include spaces in the character pattern, enclose the pattern in double quotation marks ("").
Hyperion
7-27
This function performs a trailing-wildcard member selection. Essbase searches for member names and alias names that match the pattern you specify and returns the member and alias names it finds. If the members names in the database you are searching are case-sensitive, the search is case-sensitive. Otherwise, the search is not case-sensitive. To define database member names as case-sensitive, choose Settings | Case Sensitive Members from the Application Manager Outline Editor menu. If Essbase does not find any members that match the chosen character pattern, it returns no member names and continues with the other calculation commands in the calculation script.
7-28
Hyperion
@MEMBER
The @MEMBER function returns the member with the name that is provided as a character string.
Syntax
@MEMBER (String) String - A string (enclosed in double quotation marks) or a function that returns a string
Example
Typically, the @MEMBER function is used in combination with string functions that are used to manipulate character strings to form the name of a member. In the following example, the member name QTR1 is appended to the character string 2000_ to form the string 2000_QTR1. The @MEMBER function returns the member 2000_QTR1 and QTD is set to the value of this member.
QTD=@MEMBER(@CONCATENATE("2000_", QTR1));
Hyperion
7-29
@MERGE
The @MERGE() function merges two member lists that are processed by another function. Duplicate values from both lists are included only once in the merged list.
Syntax
@MERGE(list1, list2) list1 - The first list of member specifications to be merged. list2 - The second list of member specifications to be merged.
Example
@MERGE(@CHILDREN(Colas),@CHILDREN("Diet Drinks")) returns
Cola, Diet Cola, Caffeine Free Cola, Diet Root Beer, and Diet Cream Soda. Diet Cola appears only once in the merged list, even though it is a child of both Colas and Diet Drinks.
Notes
Duplicate values are included only once in the merged list. @MERGE can merge only two lists at a time. You can nest @MERGE functions to merge more than two lists.
7-30
Hyperion
@PARENT
The @PARENT () function returns the parent of the current member being calculated in the specified dimension. If you specify the optional member, that parent is combined with the specified member.
Syntax
@PARENT(dimName [, member]) member - Any valid single member name or member combination, or a function that returns a single member or member combination, that is combined with the parent returned.
Example
@PARENT(Market,Sales)returns Central->Sales, if the current member of
Market being calculated is Colorado.

@PARENT(Measures)returns Profit, if the current member of Measures
being calculated is Margin.
Notes
You cannot use the @PARENT function in a FIX statement. You can use the @PARENT function on both the left and right sides of a formula. If you use this function on the left side of a formula in a calculation script, associate it with a member. For example:
Sales(@PARENT(Product) = 5;);
In general, use @PARENT as a member rather than as an implied value of a cell. For example:
Sales = @AVG(SKIPMISSING, @ISIBLINGS(@PARENT("100")));
The time required for retrieval and calculation may be significantly longer if this function is in a formula attached to a member tagged as Dynamic Calc or Dynamic Calc and Store.
Hyperion
7-31
@RANGE
The @RANGE() function returns a member list that crosses the specified member from one dimension with the specified member range from another dimension.
Syntax
@RANGE(mbrName [, rangeList]) Optional rangeList - A valid member name, a comma-delimited list of member names, member set functions, and range functions from the same dimension. If rangeList is not specified, Hyperion Essbase uses the level 0 members from the dimension tagged as Time.
Examples
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Prod Count. The @RANGE function is used with the @COUNT function to calculate the count of all products for which a data value exists:
"Prod Count" = @COUNT(SKIPMISSING,@RANGE(Sales,@CHILDREN(Product)));
This example produces the following results:

Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product 678 551 663 587 #MI 2479 Prod Count #MI #MI #MI #MI #MI 4
7-32
Hyperion
@RDESCENDANTS
The @IRDESCENDANTS function returns the specified member and all its descendants, or those down to the specified generation or level. If one or more of the descendants are shared, the result also includes either all descendants of each member being shared or descendants down to the specified generation or level.
Syntax
@RDESCENDANTS(mbrName [, genLevNum| genLevName]) genLevNum - An integer value that defines the absolute generation or level number down to which to select the members. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. or genLevName - Level name or generation name down to which to select the members.
Example
Consider an outline with the following Product dimension:
Product 100 100-10 100-20 100-30 200 200-10 200-20 200-30 200-40 Diet 100 (Shared Member) 200 (Shared Member)
Diet has two children "100" and "200". The members "100" and "200" are shared members.
@RDESCENDANTS(Diet) returns the members: 100, 100-10, 100-20, 100-30,
200, 200-10, 200-20, 200-30, 200-40 (in that order).
Hyperion
7-33
Notes
In the absence of shared members, @RDESCENDANTS and @DESCENDANTS return the same result. The order of members in the result list is important to consider when you use the @RDESCENDANTS and the @IRDESCENDANTS member set function with certain forecasting and statistical functions. Essbase generates the list of members in the following sequence: The nearest descendant of the member The next nearest descendant of the member, and so on. If a shared member is encountered, the above steps are repeated on the member being shared.
7-34
Hyperion
@RELATIVE
The @RELATIVE function returns all members at the specified generation or level that are above or below the specified member in the database outline.
Syntax
@RELATIVE (mbrName, genLevNum | genLevName)
Example
@RELATIVE(Qtr1,3) @RELATIVE(Qtr1,0)
both return the three members that are at generation 3 (or level 0) and that are below Qtr1 in the Sample Basic outline: Jan, Feb, and Mar.
@RELATIVE(Profit,-1)
returns the two members that are at level 1 and that are below Profit: Margin and Total Expenses (in that order).
Notes
Hyperion Essbase sorts the generated list of members in ascending order. This order is important to consider when you use the @RELATIVE member set function with certain forecasting and statistical functions.
Hyperion
7-35
@REMOVE
The @REMOVE() function removes values or members in one list from another list.
Syntax
@REMOVE (list1, list2) list1 - A list of member specifications, from which the members specified in list2 are removed. list2 - A list of member specifications to be removed from list1.
Example
@REMOVE(@CHILDREN(East),@LIST("New York",Connecticut))
returns Massachusetts, Florida, New Hampshire.
7-36
Hyperion
@RSIBLINGS
The @RSIBLINGS() function returns all of the right siblings of the specified member. Right siblings are children that share the same parent as the member and that follow the member in the database outline. This function excludes the specified member.
Syntax
@RSIBLINGS(mbrName)
Example
@RSIBLINGS(Florida) returns Connecticut and New Hampshire. @RSIBLINGS(Sales) returns COGS .
Notes
Essbase sorts the right siblings in ascending order. This order is important to consider when you use the @RSIBLINGS member set function with certain forecasting and statistical functions.
Hyperion
7-37
@SIBLINGS
The @SIBLINGS() function returns all siblings of the specified member. This function excludes the specified member.
Syntax
@SIBLINGS (mbrName)
Example
@SIBLINGS (Washington)returns Oregon, California, Utah, and Nevada
(in that order).

@SIBLINGS(East)returns West, South, and Central (in that order).
Notes
Essbase sorts the generated list of members as follows: left siblings of the member (that is, siblings appearing above the member in the database outline) in descending order, right siblings of the member (that is, siblings appearing below the member in the database outline) in ascending order.
Using Sample Basic as an example, if you specify 200-30 for mbrName, Essbase returns 200-20, 200-10, 200-40 (in that order). This order is important to consider when you use the @SIBLINGS member set function with certain forecasting and statistical functions.
7-38
Hyperion
@UDA
The @UDA function returns members with a common attribute, which have been defined as a user-defined attribute (UDA) on the Hyperion Essbase server.
Syntax
@UDA (dimName, udaStr) udaStr - User-defined attribute string as it is shown in the database outline.
Example
@UDA(MARKET,"Small Market")
This function returns a list of all members whose Market dimension has been assigned the UDA Small Market.
Notes
You must type the UDA string exactly as it is shown in the database outline.
Hyperion
7-39
@WITHATTR
The @WITHATTR() function returns all base members that are associated with an attribute that satisfies a specified condition. You can use operators such as >, <, =, and IN to specify conditions that must be met.
Syntax
@WITHATTR (dimName, "operator", value) operator - Logical operator enclosed in quotation marks (""). value - A value that, in combination with the operator, defines the condition that must be met. The value can be an attribute member specification, a constant, or a date-format function. The following operators are supported:
Operator > >= < <= == <> or != IN Meaning Greater than Greater than or equal to Less than Less than or equal to Equal to Not equal to In The IN operator returns the base members that are associated with a subcategory of attributes in the attribute dimension. For example, in the Sample Basic database, @WITHATTR(Population,"IN",Medium) returns the base members that are associated with all attributes under the Medium parent member in the Population dimension.
7-40
Hyperion
Examples
The following table shows examples, based on the Sample Basic database, for each type of operator:
Condition @WITHATTR(Population,">","18000000") @WITHATTR(Population,">=",10000000) where 10,000,000 is a constant @WITHATTR(Ounces,"<","16") Returns New York, California, Texas New York, Florida, California, Texas, Illinois, Ohio Cola, Diet Cola, Old Fashioned, Sasparilla Diet Cream Cola, Diet Cola, Caffeine Free Cola, Old Fashioned Cola, Diet Cola, Diet Cream Caffeine Free Cola, Sasparilla, Birch Beer, Grape, Orange, Strawberry Massachusetts, Florida, Illinois, Ohio
@WITHATTR("Intro Date","<=", @TODATE("mm-dd-yyyy","04-01-1996")) @WITHATTR("Pkg Type","= =",Can) @WITHATTR(Caffeinated,"<>",True)
@WITHATTR("Population","IN",Medium)
The following two examples show @WITHATTR used in a calc script, based on the Sample Basic database: /* To increase by 10% the price of products that are greater than or equal to 20 ounces */
FIX (@WITHATTR(Ounces,">=","20")) Price = Price * 1.1; ENDFIX
/* To increase by 10% the marketing budget for products brought to market after a certain date */
FIX (@WITHATTR("Intro Date",">", @TODATE("mm-dd-yyyy","06-26-1996"))); Marketing = Marketing * 1.1; ENDFIX
Notes
If you specify a date attribute with the @WITHATTR function, you must use the @TODATE function in the string parameter to convert the date string to a number.
Hyperion
7-41
Date @WITHATTR("Intro Date","<",@TODATE("mm-dd-yyyy","07-261996")) returns all base members with date attributes that are before July 26, 1996. When using Boolean attributes with @WITHATTR, use only the actual Boolean attribute member name, or use 1 (for True or Yes) or 0 (for False or No). You cannot use True/Yes and False/No interchangeably. Boolean @WITHATTR(Caffeinated,"<",True) returns all base members that have Caffeinated set to False (or No). It does not return base members that do not have Caffeinated set to True (or Yes) or do not have a Caffeinated attribute at all. The behavior is similar for a formula like @WITHATTR(Caffeinated,"<>",True), which returns only base members with Caffeinated set to False. An operator may work differently with different attribute types. For example: Text @WITHATTR(Flavors,"<",Orange) returns base members with attributes that precede Orange in the alphabet; for example, Apple, Cranberry, Mango, and Oat, but not Peach or Strawberry.
7-42
Hyperion
@XRANGE
@XRANGE takes as input two members (single or cross-dimensional) and returns a member range. It determines the cross product of all members in the range and then prunes the set to include only the range requested.
Syntax
@XRANGE (mbrName1, mbrName2)
Examples
This function is useful, for example, when you work with the Time and Scenario dimensions.
@XRANGE(1998->Aug, 2001->March)
This example returns the set consisting of:

1998->Aug, 1999->Jan, 2000->Jan, 2001->Jan, 1998->Sep, 1999->Feb, 2000->Feb, 2001->Feb, ... 1998->Dec, ... 1999->Dec, ... 2000->Dec, 2001->Mar
Notes
@XRANGE can appear anywhere in a formula where a range can normally appear. @XRANGE can be used only in these functions: @AVGRANGE, @SUMRANGE, @MINRANGE, @MINSRANGE, @MAXRANGE, @MAXSRANGE, @STDDEVRANGE, @MOVSUM, @MOVAVG, @MOVMIN, @MOVMAX, @MOVMED, @SPLINE The two arguments to @XRANGE must be either single members or crossdimensional members with the same member components. For example, @XRANGE(1998->Jun, 2001) is invalid. The dimension order of members must match for both arguments. For example, @XRANGE(1998->Jun, March->2001) is invalid. The member components of each argument must be from the same level. For example, @XRANGE(1998->Jun, 2001->Qtr1) is invalid. Although the syntax is correct, a function such as @XRANGE (2001, 1998) results in an empty set.
Hyperion
7-43
Exercise 7-1: Applying Member Set Functions

In this exercise, you create a calc script to calculate all members within East, including the East total. The calc script should calculate all Accounts members, all Time members, and all Products members. This calc script should apply only to the Budget. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSMember SS_Member.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS1 database. Create a calc script to calculate Budget values for all members within East, including the East total. The calc script should calculate all Accounts members, all Time members, and all Products members. Save the new script as CSMember. Open the SS_Member spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS1 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. Notice that the values in pink have not been calculated yet. From the Calc&Retrieve sheet, run the CSmember calc script. Perform a retrieval and notice the calculation results within the pink cells. Do the pink cells beneath Connecticut and East contain data after the calculation? Why or why not? If they do not, modify the CSMember calc script and rerun the calculation until all pink cells are populated with data. Close the spreadsheet.
3) 4) 5)
6) 7)
8)
7-44
Hyperion
Unit Summary
To avoid hard-coding lists of members or dimensions, you use member set functions. Member set functions return lists of members and dimensions. Therefore, when the database structure changes by adding members, for example, an associated calc script need not change. The member set functions are often used in conjunction with Fix structures to isolate specific members for which calculations are to be performed.
Hyperion
7-45
7 Member Set Functions Check Your Understanding

1)
Now that you have completed the chapter, check your understanding by responding to the following questions: For each of the following situations, identify the Member Set function that you would use to create a list of the required members. Use the Sample Basic outline.
All states that begin with the letter N. All the states in the East market, and East, itself. All level one members of the Market Dimension. New York and all its ancestors. All states whose population is greater than 6,000,000.
7-46
Hyperion

1) For each of the following situations, identify the Member Set function that you would use to create a list of the required members. Use the Sample Basic outline. (Multiple solutions may be correct for some of these answers.)
@MATCH @ICHILDREN or @IDESCENDANTS @LVLMBRS @IANCESTORS @WITHATTR
All states that begin with the letter N. All the states in the East market, and East, itself.
All level one members of the Market Dimension. New York and all its ancestors. All states whose population is greater than 6,000,000.
Hyperion
7-47
7-48
Hyperion
8
Relationship Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of relationship functions to generate member lists Practice using the relationship functions in a series of incremental exercises
Using Relationship Functions

A relationship function returns a value based on the member combination being calculated and the degree of relationship specified by the function. In this chapter, the Sample Basic outline and a second, simpler outline are used to explain how relationship functions work. The simpler outline includes:
Market East Region - New York State -- Albany -- Buffalo - Connecticut West Region - California -- Los Angeles -- San Francisco Product Family01 - Group 01-1 -- SKU01-1-1 --SKU01-1-2 - Group 01-2 -- SKU01-2-1 -- SKU01-2-2
Relationship Function Parameters

There are common parameters associated with the various relationship functions:
dimName, dimName1,... dimNameX mbrName, Any valid single member name or member combination (or a function that returns a single member or member combination). An integer value that defines the generation or level number from which the ancestor value is returned. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. Single dimension name specification.
genLevNum, genLevNum1, genLevNumX,
8-2
Hyperion
Summary of Relationship Functions

This table summarizes the Relationship Functions. Each function is also described, in detail, in this chapter.
Function @ANCESTVAL Returns The value of a specified ancestor of the current member being calculated. The associated attribute value from the specified boolean attribute dimension. The associated attribute value from the specified string attribute dimension. The associated attribute value from the specified numeric or date attribute dimension. The generation number of the current member combination for the specified dimension. The level number of the current member combination for the specified dimension. The generation number of the specified member. The level number of the specified member. Multi-dimensional ancestor-level value for the current member being calculated. Multi-dimensional parent-level data for the current member being calculated. The parent value along the specified dimension for the member being calculated Ancestor-level data based on the shared ancestor value of the current member being calculated. Parent-level data based on the shared parent value of the current member being calculated. Values incorporated from a different Essbase database.
@ATTRIBUTEBVAL
@ATTRIBUTESVAL
@ATTRIBUTEVAL
@CURGEN
@CURLEV
@GEN @LEV @MDANCESTVAL
@MDPARENTVAL
@PARENTVAL
@SANCESTVAL
@SPARENTVAL
@XREF
Hyperion
8-3
@ANCESTVAL
The @ANCESTVAL() function returns the ancestor values of a specified member combination.
Syntax
@ANCESTVAL (dimName, genLevNum [, mbrName])
Notes
The returned value will be the value for the specified generation (or level) of the dimension and member combination. For example, @ANCESTVAL(Market,2,Sales) refers to the Sales value of generation 2 of the current members Market hierarchy. For the Albany of illustrative outline, this function returns the value of East->Sales.
@ANCESTVAL(Market,-1,Sales) refers to the Sales value of level 1 of the
current members Market hierarchy. For the Albany of illustrative outline, this function returns the value of New York State->Sales.
Example
In this example, SKU Share is derived by taking Sales in each SKU as a percentage of its product family. Families are at generation 2; therefore, each descendant of family is calculated as a percentage its specific generation 2 ancestor. Consolidated results must be calculated for Sales by Product before the SKU Share calculation occurs.
"SKU Share" = Sales % @ANCESTVAL(Product,2,Sales);

Sales SKU01-1-1 SKU01-1-2 - Group01-1 SKU01-2-1 SKU01-2-2 - Group01-2 --- Family01 510 520 1030 430 500 930 1960 SKU Share 26.0 26.5 52.5 21.9 25.5 47.4 100.00
8-4
Hyperion
@ATTRIBUTEBVAL
For the current member being calculated, the @ATTRIBUTEBVAL() function returns the associated attribute value from the specified Boolean attribute dimension.
Syntax
@ATTRIBUTEBVAL(attDimName) attDimName - The name of a Boolean attribute dimension.
Example
The Product dimension is associated with the Caffeinated Boolean attribute dimension, as shown in the following example:
Product {Caffeinated} 100 100-10 {Caffeinated:True} 100-20 {Caffeinated:True} 100-30 {Caffeinated:False} 200 200-10 {Caffeinated:True} 200-20 {Caffeinated:True} 200-30 {Caffeinated:False} 200-40 {Caffeinated:False} Caffeinated Attribute {Type: Boolean} True False
For the current member of the base dimension Product, the function
@ATTRIBUTEBVAL(Caffeinated)
returns the associated attribute value from the Boolean attribute dimension, Caffeinated. The following table shows the value that would be returned:
Current Member 100-10 100-20 100-30 100 Return Value True True False #MISSING
Hyperion
8-5
200-10 200-20 200-30 200-40 200 Product
True True False False #MISSING #MISSING
Notes
The @ATTRIBUTEBVAL function works only with Boolean attribute dimensions. If no attribute is associated with the member being calculated or if the attribute associated with the member is a text, numeric, or date attribute, @ATTRIBUTEBVAL returns #MISSING. Only level 0 members of attribute dimensions can be associated as attributes of members of a base dimension.
8-6
Hyperion
@ATTRIBUTESVAL
For the current member being calculated, the @ATTRIBUTESVAL() function returns the associated attribute value from the specified text attribute dimension.
Syntax
@ATTRIBUTESVAL(attDimName) attDimName - The name of a text attribute dimension.
Example
This example is based on the Sample Basic database. The Product dimension is associated with the Pkg Type text attribute dimension, as shown in the following example:
Product {Pkg Type} 100 100-10 {Pkg 100-20 {Pkg 100-30 {Pkg 200 200-10 {Pkg 200-20 {Pkg 200-30 {Pkg 200-40 {Pkg Pkg Type Attribute Bottle Can
Type:Can} Type:Can} Type:Bottle} Type:Bottle} Type:Bottle} Type:Bottle} Type:Bottle} {Type: Text}
For the current member of the base dimension, Product, the function
@ATTRIBUTESVAL("Pkg Type")
returns the associated attribute value from the text attribute dimension, Pkg Type. The following table shows the value that would be returned:
Current Member 100-10 100-20 100-30 100 Return Value Can Can Bottle (empty string)
Hyperion
8-7
200-10 200-20 200-30 200-40 200 Product
Bottle Bottle Bottle Bottle (empty string) (empty string)
Notes
The @ATTRIBUTESVAL function works only with text attribute dimensions. If no attribute is associated with the member being calculated or if the attribute associated with the member is a numeric, Boolean, or date attribute, @ATTRIBUTESVAL returns an empty string. Only level 0 members of attribute dimensions can be associated as attributes of members of a base dimension.
8-8
Hyperion
@ATTRIBUTEVAL
For the current member being calculated, the @ATTRIBUTEVAL() function returns the associated attribute value from the specified numeric or date attribute dimension.
Syntax
@ATTRIBUTEVAL(attDimName) attDimName - Single dimension specification for a numeric or date attribute dimension.
Example
The following example is based on the Sample Basic database:
"Profit Per Ounce" = Profit/@ATTRIBUTEVAL(Ounces);
In this formula, for the current member being calculated, @ATTRIBUTEVAL returns the associated attribute from the Ounces numeric attribute dimension. For example, if the member being calculated is Cola and if the Ounces attribute value associated with Cola is 12, @ATTRIBUTEVAL returns 12. This example produces the following results:
Profit ======== 4593 Profit Per Ounce ================ 382.75
Cola
Notes
The @ATTRIBUTEVAL function works only with numeric and date attribute dimensions. Only level 0 members of attribute dimensions can be associated as attributes of members of a base dimension. If there is no attribute associated with the member being calculated, or if the attribute associated with the member is a text attribute, @ATTRIBUTEVAL returns #MISSING. When the @ATTRIBUTEVAL function is used with a date attribute dimension, Essbase converts the date string to the number of seconds elapsed since midnight, January 1, 1970.
Hyperion
8-9
@CURGEN
The @CURGEN() function returns the generation number of the current member combination for the specified dimension. This number represents the number of members separating the current member from the top-most member of the dimension.
Syntax
@CURGEN(dimName)
Example
@CURGEN(Year)produces the following results: Current Member Year Qtr2 Oct Value 1 2 3
8-10
Hyperion
@CURLEV
The @CURLEV() function returns the level number of the current member combination for the specified dimension. This number represents the number of members that separates the current member from its bottommost descendant.
Syntax
@CURLEV(dimName)
Example
@CURLEV(Year) produces the following results: Current Member Year Qtr3 Aug Value 2 1 0
Hyperion
8-11
@GEN
The @GEN() function returns the generation number of the specified member.
Syntax
@GEN(mbrName)
Example
@GEN(Year) @GEN(Qtr3) 1 2
8-12
Hyperion
@LEV
The @LEV() function returns the level number of the specified member.
Syntax
@LEV(mbrName)
Example
Function @LEV(Margin) @LEV("New York") Level Returned 1 0
Hyperion
8-13
@MDANCESTVAL
The @MDANCESTVAL() function returns ancestor-level data from multiple dimensions based on the current member being calculated.
Syntax
@MDANCESTVAL(dimCount, dimName1, genLevNum1... dimNameX, genLevNumX [,mbrName]) dimCount - Integer value that defines the number of dimensions from which ancestor values are being returned.
Notes
@MDANCESTVAL(2, Market, 2, Product, 2, Sales) refers to the Sales value found by navigating to generation 2 of the current members Market hierarchy and to generation 2 of the current members Product hierarchy. For the Albany->SKU01-1-2 of illustrative outline, this function returns the value of East Region->Family01->Sales. You must specify a genLevNum for every dimName specified.
Example
Marketing expenses are captured at the Product Family and Region level in a product planning application. The Marketing Expense data must be allocated down to each Product code and city based on Sales. The Marketing Expense value of 400 for East Region and product Family01 is allocated down to each Product code and city with the following formula:
Marketing = (Sales / @MDANCESTVAL(2, Market, 2, Product, 2, Sales)) * @MDANCESTVAL(2, Market, 2, Product, 2, Marketing);
which produces the following (partial) results:

Sales Albany SKU01-1-1 SKU01-1-2 SKU01-2-1 SKU01-2-2 East Region Family01 300 200 400 100 2000 Marketing 60 40 80 20 400
8-14
Hyperion
@MDPARENTVAL
The @MDPARENTVAL() function returns parent-level data from multiple dimensions based on the current member being calculated.
Syntax
@MDPARENTVAL(numDim, dimName1,... dimNameX [,mbrName]) numDim - Integer value that defines the number of dimensions from which parent values are being returned.
Notes
@MDPARENTVAL(2, Market, Product, Sales) refers to the Sales value found by navigating to the current members parent in Market hierarchy and to the parent in Product hierarchy. For the Albany->SKU01-1-2 of illustrative outline, this function returns the value of New York State>Group01-1->Sales.
Example
Marketing expenses are captured at the Product Family and Region level in a product planning application. The Marketing Expense data must be allocated down to each Product Group Code and state based on Sales. The Marketing Expense value of 200 for East Region and product Family01 is allocated down to each Product code and city with the following formula:
Marketing = (Sales / @MDPARENTVAL(2, Market, Product, Sales)) * @MDPARENTVAL(2, Market, Product, Marketing);
which produces the following (partial) results:

Sales New York State Group01-1 Group01-2 Connecticut Group01-1 Group01-2 East Region Family01 300 200 100 400 1000 Marketing 60 40 20 80 200
Hyperion
8-15
@PARENTVAL
The @PARENTVAL() function returns the parent value along the specified dimension for the member being calculated.
Syntax
@PARENTVAL (dimName [, mbrName])
Notes
The returned value will be that of the parent along the specified dimension and member combination. For example, @PARENTVAL(Market,Sales) refers to the Sales value of the parent of the current members Market hierarchy. For Albany of illustrative outline, this function returns the value of New York State->Sales.
Example
The formula calculates Market Share Sales value for each Market member as a percentage of Sales for its Market dimension parent.
"Market Share" = Sales % @PARENTVAL(Market,Sales);
produces the following results:

Sales Albany Buffalo New York State Los Angeles San Francisco California Market 360 240 600 1000 100 300 400 60 40 60 100 Market Share 25 75 40
8-16
Hyperion
@SANCESTVAL
The @SANCESTVAL() function returns ancestor-level data based on the shared ancestor value of the current member being calculated.
Syntax
@SANCESTVAL (rootMbr,genLevNum [, mbrName]) rootMbr - Defines a member that is used to search for the nearest occurrence of an ancestor of a shared member.
Example
Marketing expenses are captured at the Product Category levels in a product planning application. The Product categories are defined as ancestors that contain shared members as children. The Marketing Expense data must be allocated down to each Product code based on Sales contribution. The following Product hierarchy is defined:
Product 100 100-10 100-20 200 200-10 200-20 Diet ~ 100-10 SHARED 200-10 SHARED Caffeine Free ~ 100-20 SHARED 200-20 SHARED
Hyperion
8-17
The Marketing Expense value is allocated down to each Product code with the following formula:
Marketing = (Sales / @SANCESTVAL(Product, 2, Sales)) * @SANCESTVAL(Product, 2, Marketing);
which produces the following result:

Sales 100-10 100-20 100 200-10 200-30 200 100-10 200-10 Diet 100-20 200-30 Caffeine Free 200 400 600 300 100 400 13.3 26.7 40 100 400 900 37.5 12.5 50 300 200 500 12.5 26.7 #Missing Marketing 37.5 13.3 #Missing
Notes
8-18
Hyperion
@SPARENTVAL
The @SPARENTVAL() function returns parent-level data based on the shared parent value of the current member being calculated.
Syntax
@SPARENTVAL(RootMbr [, mbrName]) RootMbr - Defines a member that is used to search for the nearest occurrence of a parent of a shared member.
Example
Marketing expenses are captured at the Product Category (Diet and Caffeine Free) levels in a product planning application. The Product categories are defined as parents that contain shared members as children. The Marketing Expense data must be allocated down to each Product code based on Sales contribution. The following Product hierarchy is defined:
Product 100 100-10 100-20 200 200-10 200-20 Diet ~ 100-10 200-10 Caffeine Free ~ 100-20 200-20 SHARED SHARED SHARED SHARED
The Marketing Expense value is allocated down to each Product code with the following calc script:
FIX (@LVLMBRS(Products,0); Marketing = (Sales / @SPARENTVAL(Product,Sales)) * @SPARENTVAL(Product, Marketing);
ENDFIX;
Hyperion
8-19
Relationship Functions which produces the following result:

Sales 100-10 100-20 100 200-10 200-30 200 100-10 200-10 Diet 100-20 200-30 Caffeine Free 200 400 600 300 100 400 100 400 900 300 200 500
Marketing 37.5 13.3 #Missing 12.5 26.7 #Missing 37.5 12.5 50 13.3 26.7 40
Notes
8-20
Hyperion
@XREF
The @XREF function is a cross-database function that allows a calculation taking place in one Essbase database to incorporate values from a different, possibly remote database.
Syntax
@XREF (locationAlias [, mbrList]) locationAlias - A location alias for the data source. mbrList - A comma-delimited list of member names that qualify the @XREF query.
How @XREF works

The @XREF function retrieves values from a data source to be used in a calculation on a data target. The data source and data target outlines can be different. The following terminology is used to describe the @XREF function: Data target: the database on which the current calculation is running (that is, the database on which the @XREF call originates). Data source: the database that is queried by the @XREF function. This database may be remote (that is, on a different machine than the data target). The data source is described by a location alias. The location alias specifies a server, application, database, username, and password. Location aliases are set by the database administrator at the database level using Essbase Application Manager, ESSCMD, or the API. Point of view: the member combination currently being calculated on the data target (that is, the member combination that identifies the left hand side of a calculation). The members you specify for mbrList are sent to the data source in addition to the members in the current point of view in the data target. The data source then constructs a member combination, using in order of precedence: The members specified in mbrList The members in the current point of view The top member in any unspecified dimensions in the data source
Hyperion
8-21
Example 1
For this example, consider the following two databases: Main Database
Year Qtr1 Qtr2 Measures Sales Units Product 100 100-10 100-20 Market East West Scenario Budget Forecast
Inflation Rates Database (Location Alias: InflatDB)

Year Qtr1 Qtr2 Assumptions Inflation Deflation = Inflation * .5 (Dynamic Calc) Country US Canada Europe
The following formula is associated with the Main Database:

Units = Units * @XREF(InflatDB,Inflation,US);
In this example, Essbase calculates the following member combinations: Units->Qtr1->100-10->East->Budget = Units->Qtr1->100-10->East>Budget * Inflation->Qtr1->US Units->Qtr2->100-10->East->Budget = Units->Qtr2->100-10->East>Budget * Inflation->Qtr2->US and so on.
8-22
Hyperion
Example 2
The following formula modifies the point of view on the data target:
1999->Jan->Inventory = @XREF(sourceDB,Dec);
If the cube on the data source (sourceDB) contains data only from 1998, this formula sets Inventory for Jan in 1999 to the Inventory value for Dec from 1998.
Example 3
The following formula defines a specific point of view on the data target:
Sales->Jan = @XREF(sourceDB,January);
Assume that the data target contains the member Jan, while the data source (sourceDB) contains the member January. This formula simply maps the member in the data target (Jan) with its corresponding member in the data source (January), and pulls Sales->January from sourceDB.
Notes
Essbase returns an error message if the members supplied in mbrList do not exist in the data source. The number of data cells queried on the data source must match the number of data cells expected on the data target. For example, consider the following formula:
West->Inventory = @XREF(SourceDb, California, Oregon);
Hyperion
H H H H
This formula would return two data values, one for Inventory in California and one for Inventory in Oregon. However, since the current point of view calls for only one data cell Inventory->West, Essbase returns an error message. The member list cannot contain functions that return more than one member. For example, the following formula is not valid:
West->Inventory = @XREF(SourceDb, @LEVMBRS(Market,0));
The member list cannot contain ranges. For example, the following formula is not valid:
West->Inventory = @XREF(SourceDb, Jan:Mar);
8-23
mbrList can contain attribute members. For example, if the data source classifies products based on a color attribute, the following formula would calculate the sum of the sales of all red products and would assign the result to member RedThings:
RedThings->Sales = @XREF(SourceDb, Red);
Defining a Location Alias

The @XREF command uses a location alias name to identify the data source. A location alias is set at the database level and specifies the server, application, username and password to be assigned to the alias name. You need database designer privileges to maintain location alias definitions.
8-24
H H H H
1)
mbrList can contain attribute operators. For example, the following formula calculates RedThings as the average sales of all red products:
RedThings->Sales = @XREF(SourceDb, Red, Average);
@XREF can query all types of members supported by the Essbase server. For example, members retrieved from a data source can be Dynamic Calc members as well as attribute members. Keep in mind that all performance considerations that apply to dynamic and attribute calculations also apply to @XREF queries that depend on dynamic and attribute members. Over the course of an @XREF calculation, data in the source database may change. @XREF does not incorporate changes made after the beginning of the calculation.
To define a location alias:

In the server window of the Essbase Application Manager, select the application and database that accesses the source data (that is, the data target).
Hyperion
Select Database / Location Aliases. The Location Aliases dialog displays:
3) 4) 5)
In the Alias text box, type the alias name for the remote database. In the Server text box, type the server name or IP address for the remote database. In the Application text box, type the application name for the remote database. In the Database text box, type the database name for the remote database. Type the User name and Password in the respective text boxes. Click Set. The location alias is added to the alias list:
6) 7) 8)
9)
Click OK. Use the Alias name in the @XREF formula.
Hyperion
8-25
Exercise 8-1: Applying Relationship Function (@ANCESTVAL)

In this exercise, you create a calc script that allocates Corporate Expenses for all individual products. Corporate Expenses are loaded at the product family level (for example, 1000 Product Family, 2000 Product Family). These corporate expenses are to be allocated to each product, based on percentage of individual product sales to total sales. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSAncest SS_Ancest.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS1 database. Create a calc script to allocate Corporate Expenses for all individual products to each product, based on percentage of individual product sales to total sales. Save the new script as CSAncest. Open the SS_Ancest spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS1 database. Switch to the Calc&Retrieve sheet. Retrieve from the Essbase database into this sheet. Notice that the values in the Check your results column are not calculated. From the Calc&Retrieve sheet, run the CSAncest calc script. Retrieve from the Essbase database into this sheet. Are the values in the Check your results column the same as the retrieved results? If not, modify the CSAncest calc script and rerun the calculation until all pink cells are populated with correct results. Close the spreadsheet.
3) 4) 5)
6) 7) 8)
9)
8-26
Hyperion
Exercise 8-2: Applying Relationship Function (@CHILDREN)

In this exercise, you create a calc script that calculates the average inventory for each market. The average inventory for a Market member is calculated by averaging the ending inventory for each child member of that Market member. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSCrmbr SS_Currmbr.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate the average inventory for each market. The average inventory for a Market member is calculated by averaging the ending inventory for each child member of that Market member. Save the new script as CSCrmbr. Open the SS_Currmbr spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS1 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. Notice that the values Average Inventory column are #Missing. From the Calc&Retrieve sheet, run the CSCrmbr calc script. Perform a retrieval. Are the results in the Average Inventory column as expected? If not, modify the CSCmbr calc script and rerun the calculation until these values are correct. Close the spreadsheet.
3) 4) 5)
6) 7)
8)
Hyperion
8-27
Exercise 8-3: Applying Relationship Function (@XREF)

In this exercise, you create a calc script that calculates the Cost of Goods Sold for individual products. The COGS database contains, for each product, the costs of goods sold as percentage of that product's sales. The actual cost of goods is then calculated by multiplying these COGS percentages by the actual sales amounts, which have been loaded at the Product level. For this exercise, you use the following files:
Database CALC:HLandS1 CALC:COGS Calc Script (new) Spreadsheet CSXref SS_Xref.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS1 database. Review the structure of the Calc:COGS database.
Set up Location Alias

3) 4) In the server window, select CALC:HLANDS1. From the main menu, select Database / Location Aliases. The Location Aliases window displays. In the Location Aliases window, type the following:
In Field... Alias Server Application Database User name Password Type... COGS Localhost CALC COGS trnadmin Hyperion
5)
6)
Click OK.
8-28
Hyperion
Create the Calc Script

7) Create a calc script for the HLandS1 database to calculate the Cost of Goods Sold for individual products. The Actual cost of goods is calculated by multiplying the COGS percentages (found in the COGS database) by the Actual Sales amounts, which have been loaded at the Product level. Save the new script as CSXref.
Test the Calc Script

8) 9) Open the SS_Xref spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS1 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. Notice that the values in the COGS column display #Missing. From the Calc&Retrieve sheet, run the CSXref calc script. Perform a retrieval and notice the results in the COGS column. Are the results in the COGS column as expected? If not, modify the CSXref calc script and rerun the calculation until these values are correct. Close the spreadsheet.
10) 11) 12)
13)
Hyperion
8-29
Unit Summary
Relationship functions look up specific values within the database based on current cell location and a series of parameters. You can use these functions to refer to another value in a data series. Relationship functions have an implicit current member argument; that is, these functions are dependent on the current member's position.
8-30
Hyperion

Now that you have completed the chapter, check your understanding by responding to the following questions: 1) For each of the following situations, identify the Relationship function that you would use to retrieve the required value. Use the Sample Basic outline. (Multiple solutions may be correct for some of these answers.)
The value of the Population attribute for the current member. For current member Diet Cola->Massachusetts, the value of 100->East. A value from another database. The level number of the current member. For current member Diet Cola->Massachusetts, the value of 100->Massachusetts.
Hyperion
8-31
8 Relationship Functions Check Your Understanding Solutions

1)
For each of the following situations, identify the Relationship function that you would use to retrieve the required value. Use the Sample Basic outline. (Multiple solutions may be correct for some of these answers.)
@ATTRIBUTEVAL
The value of the Population attribute for the current member. For current member Diet Cola->Massachusetts, the value of 100->East. A value from another database. The level number of the current member. For current member Diet Cola->Massachusetts, the value of 100->Massachusetts.
@MDPARENTVAL
@XREF @CURLEV @PARENTVAL
8-32
Hyperion
9
Range and Financial Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of Range and Financial Functions to generate member lists Practice using the Range and Financial Functions in a series of incremental exercises
Using Range and Financial Functions

Range functions take a range of members as an argument. Rather than return a single value, these functions calculate a series of values internally based on the range specified. Financial functions never return a value; rather, they internally calculate a series of values based on the range specified and write the results to a range of cells. Thus, you cannot apply any operator directly to the function.
Range and Financial Function Parameters

There are common parameters associated with the various Range and Financial Functions:
mbrName rangeList Specifies a single member. Optional comma-delimited list of members, member set functions, or range functions from the same dimension, across which the accumulation occurs. When an optional parameter, if rangeList is not specified, Essbase uses the level 0 members from the dimension set as Time. SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH Used in conjunction with an expList, this parameter indicates how missing and zero values are to be processed. SKIPNONE - Includes in the operation all values specified in expList regardless of their content SKIPMISSING - Ignores all #MISSING values SKIPZERO - Ignores all 0 values SKIPBOTH - Ignores all 0 and #MISSING values dimName, dimName1, DimNameX genLevNum An integer value that defines the generation or level number from which the ancestor value is returned. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. Single dimension name specification.
9-2
Hyperion
Summary of Range and Financial Functions

This table summarizes the Range (and Financial) Functions. Each function is also described, in detail, in this chapter.
Function @ACCUM Returns Accumulated total values across the specified range. The average value of the specified member across the specified range. Amount of compound interest on a series of periodic deposits. The accumulation of principal and interest on a single payment over time. A member list based on the relative position of the current member being calculated. The depreciation amount per period that an asset may be depreciated using the declining balance method. The discounted value at the beginning of the first period for amounts at end each period. A series of values that represent a linear growth of an initial value across the specified range. The amount of simple interest of a value at the specified rate. The Internal Rate of Return on a cash flow. The maximum value of the specified member across the specified range of members. The maximum value of the specified member across the specified range of members allowing for skipping of #MISSING and/or 0 values. A series of data values that are copied from shifted multiple dimension ranges. The minimum value of the specified member across the specified range of members.
@AVGRANGE
@COMPOUND
@COMPOUNDGROWTH
@CURRMBRRANGE
@DECLINE
@DISCOUNT
@GROWTH
@INTEREST
@IRR @MAXRANGE
@MAXSRANGE
@MDSHIFT
@MINRANGE
Hyperion
9-3
Function @MINSRANGE
Returns The minimum value of the specified member across the specified range of members allowing for skipping of #MISSING and/or 0 values. The specified subsequent cell value of the range for the specified member. The specified subsequent cell value of the range for the specified member providing the option to skip #MISSING and/or zero values. The Net Present Value of an investment based on the series of payments and income. The specified previous cell value of the range for the specified member. The specified subsequent cell value of the range for the specified member providing the option to skip #MISSING and/or zero values. The period-to-date values of members in the dimension tagged as Time. The specified subsequent or previous cell value of the range for the specified member. The amount per period that an asset in the current period may be depreciated using a straight-line depreciation method. The summation of all the values of the specified member across the specified range. The amount per period that an asset in the current period may be depreciated using the sum of the years digits method.
@NEXT
@NEXTS
@NPV
@PRIOR
@PRIORS
@PTD
@SHIFT
@SLN
@SUMRANGE
@SYD
9-4
Hyperion
@ACCUM
The @ACCUM() function accumulates the values of mbrName within rangeList, up to the current member in the dimension of which rangeList is a part.
Syntax
@ACCUM (mbrName [, rangeList])
Example
In this example, Accum_Asset is calculated using the following formula: "Accum Asset" = @ACCUM(Asset, FY1992:FY1995); This example produces the following results:
FY1990 FY1991 FY1992 FY1993 FY1994 FY1995
Asset Accum_Asset
9,000 #MI
0 #MI
1,000 1,000
0 1,000
2,500 3,500
1,500 5,000
The results show that the values for Asset are accumulated starting with FY1992 and the accumulated values are placed in Accum_Asset for FY1992 through FY1995:
Notes
@ACCUM accepts the @ATTRIBUTE member set function as a member range. If you use a Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list.
Hyperion
9-5
@AVGRANGE
The @AVGRANGE() function returns the average value of the specified member across the specified range.
Syntax
@AVGRANGE(SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [, rangeList])
Example
The following example is based on the Sample Basic database.
West=@AVGRANGE(SKIPNONE,Sales,@CHILDREN(West));
This example produces the following (partial) results:

Jan California Oregon Washington Utah Nevada West 100 200 300 400 500 300 Feb 100 200 300 400 #Missing 200 Mar 100 200 0 400 500 240
Notes
The @AVGRANGE function accepts the @ATTRIBUTE member set function as a member range.
9-6
Hyperion
@COMPOUND
The @COMPOUND() function compiles the amount of a compound interest based on the balances of the specified member at the specified rate across the specified range.
Syntax
@COMPOUND(balanceMbr, rateMbrConst [, rangeList]) balanceMbr - Single member specification representing the beginning balance across a range of periods. rateMbrConst - Single member specification, variable name, or numeric expression in decimal form that represents the interest rate per time period specified in the rangeList.
Example
The following example determines the compound interest of a series of deposits, based on a credit rate of 0.0525, across a series of fiscal years:
"Compound Interest"= @COMPOUND(Deposit,"Credit Rate",FY1991:FY1995);

FY1991 Credit Rate Deposit Compound Interest 0.0525 0 0 FY1992 0.0525 2,000 105 FY1993 0.0525 0 110.5125 FY1994 0.0525 3,000 273.8144 FY1995 0.0525 0 288.1897
Notes
If balanceMbr is a single value, then Essbase assumes balanceMbr to be a single deposit in the first member of rangeList. This is equivalent to entering the value in the first member in the rangeList followed by zeros. If balanceMbr is a member, or a range, then it is assumed to be a series of deposits. rangeList represents the range over which the interest is compounded.If rangeList is not specified, Essbase uses the level 0 members from the dimension tagged as Time.
Hyperion
9-7
@COMPOUNDGROWTH
The @COMPOUNDGROWTH() function calculates a series of values that represent a compound growth of the first nonzero value in the specified member across the specified range of members.
Syntax
@COMPOUNDGROWTH(principalMbr, rateMbrConst [, rangeList]) principalMbr - Member specification representing the initial value to be compounded. The input line must be a single deposit. rateMbrConst - Single member specification, variable name, or expression which provides a constant value.
Example
The following example determines the compound growth of Principal Amount based on Growth Rate across a series of fiscal years.
"Growth"= @COMPOUNDGROWTH("Principal","Rate",FY1991:FY1996);

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996
Principal Rate Growth
2000 0.0525 2105
0.0525 2215.51
0.0525 2331.83
0.0525 2454.25
0.0525 2583.10
0.0525 2718.71
Notes
You can change the growth rate from period to period by placing a nonzero value in the current period's rateMbrConst cell.
9-8
Hyperion
@CURRMBRRANGE
The @CURRMBRRANGE() function generates a member list that is based on the relative position of the current member being calculated.
Syntax
@CURRMBRRANGE(dimName, {GEN|LEV}, genLevNum, [startOffset], [endOffset]) GEN|LEV - Defines whether the range list to be returned is based on a generation or a level within the dimension. genLevNum - Integer value that defines the absolute generation or level number of the range list to be returned. startOffset Defines the first member in the range to be returned: A null value indicates the first member of the specified genLevNum. An integer value indicates the member relative to the current member being calculated: Negative value for a prior member. 0 for the member currently being calculated. positive value for a subsequent member.
endOffset Defines the last member in the range to be returned. A null value returns the last member of the specified genLevNum. An integer value returns the member name relative to the current member being calculated: Negative value for a prior member. 0 for the member currently being calculated. positive value for a subsequent member.
The first three parameters of this function (dimName,{GEN|LEV},genLevNum) provide a member range list. The startOffset and endOffset parameters create a subset of this list.
Hyperion
9-9
Example 1
The following examples use the Sample Basic database. In this example, the full range list contains the level 0 members of the Year dimension (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec). Consider the following statement:
@CURRMBRRANGE(Year,LEV,0,-1,1) Current Member Jan Feb Mar Returns (Jan, Feb) (Jan, Feb, Mar) (Feb, Mar, Apr)
Consider the following statement:

@CURRMBRRANGE(Year,LEV,0,,0) Current Member Jan Feb Mar Apr Returns (Jan) (Jan, Feb) (Jan, Feb, Mar) (Jan, Feb, Mar, Apr)
9-10
Hyperion
Example 2
Average Inventory is calculated by summing opening inventories from the first month of the year next month, and dividing the result by the number of periods to date plus one period.
"Average Inventory" = @AVGRANGE(SKIPNONE,"Opening Inventory",@CURRMBRRANGE(Year, LEV, 0, , 1));
This example produces the following result:

Jan Opening Inventory Average Inventory 100 Feb 110 Mar 120 Apr 130 . . . Nov 200 Dec 210
105
110
115
120 . . .
155
155
Since a null value is specified for startOffset, the average operations always begin at the first member of the range list, Jan. The endOffset parameter, 1, specifies that the member after the current member being calculated is included in each average operation. The values for Nov and Dec are the same since there is no member after Dec in the range list.
Notes
You cannot use the @CURRMBRRANGE function in a FIX statement. Currently, this function can be used only within range and financial functions, such as @AVGRANGE, @MAXRANGE, @COMPOUND, and @SHIFT.
Hyperion
9-11
@DECLINE
The @DECLINE() function calculates the amount per period that an asset in the current period may be depreciated for the specified period using the declining balance method.
Syntax
@DECLINE (costMbr, salvageMbrConst, lifeMbrConst, factorMbrConst [, rangeList]) costMbr - Single member specification representing the starting value of the asset(s). salvageMbrConst - Single member specification, variable name, or numeric expression that provides a constant value. This value represents the value of the asset at the end of the depreciation. lifeMbrConst - Single member specification, variable name, or numeric expression that provides a constant value. This value represents the number of periods over which the asset is depreciated. factorMbrConst - Single member specification, variable name, or numeric expression that provides a constant value. This value represents the factor by which the asset is depreciated. For example, to calculate a double declining balance, set factorMbrConst to 2.
Example
The following example calculates the depreciation of Asset for the specified series of fiscal years.
"Decline Dep" = @DECLINE(Asset,Residual,Life,2,FY1991:FY1994);

FY1991 Asset Residual Life Decline Dep 9,000 750 5 3,600 FY1992 0 0 0 2,160 FY1993 0 0 0 1,296 FY1994 0 0 0 778
9-12
Hyperion
Notes
More than one asset can be input and depreciated across the specified range. The function calculates each asset separately. Declining Balance Depreciation Method - A rapid depreciation method in which a percentage rate is applied to the undepreciated balance, rather than to the original cost. Double-Declining Balance Depreciation Method - Method of accelerated depreciation, in which double the Declining Balance Depreciation Method amount is taken the first year, and then that same percentage is applied to the undepreciated amount in subsequent years.
Hyperion
9-13
@DISCOUNT
The @DISCOUNT() function calculates the discounted value at the beginning of the first period for amounts at end each period.
Syntax
@DISCOUNT (cashMbr, rateMbrConst [, rangeList]) cashMbr - Member specification representing the value(s) you want to discount from the last period in rangeList to the current period. rateMbrConst - Member specification, variable name, or numeric expression which provides a constant value. The value represents the rate per period which cashMbr is discounted. It is a decimal value, not a percent.
Example
The following example discounts the values in Cash by the rates in Credit Rate and places the results in Discount Amount for each fiscal year.
"Discount" = @DISCOUNT(Cash,"Credit Rate",FY1991:FY1995);

FY1991 Cash Credit Rate Discount 1000.00 0.05 952.38 FY1992 1000.00 0.05 907.03 FY1993 1000.00 0.05 863.84 FY1994 1000.00 0.05 822.70 FY1995 1000.00 0.05 783.53
Notes
More than one value can be discounted simultaneously in this manner.
9-14
Hyperion
@GROWTH
The @GROWTH() function calculates a series of values that represent a linear growth of an initial value across the specified range.
Syntax
@GROWTH(principalMbr, rateMbrConst [, rangeList]) principalMbr - Single member specification that represents the initial value of the value to grow. The first nonzero value encountered is the initial value. Other principalMbr values after the first are ignored. rateMbrConst - Single member specification, variable name, or numeric expression providing a constant value that represents the decimal growth rate to be applied (for example, 10% = .1).
Example
The following example calculates the growth of Principal, using the rate found in Growth Rate for each fiscal year. The results are placed in Growth Amount.
"Amount"=@GROWTH("Principal","Growth Rate",FY1991:FY1996);

FY1991 Principal Amount Growth Rate Growth Amount 1,000 FY1992 0 FY1993 2,000 FY1994 0 FY1995 0 FY1996 0
0.05
0.07
0.08
0.08
0.1
0.1
1,050
1,120
1,200
1,280
1,380
1,480
Hyperion
9-15
@INTEREST
The @INTEREST() function calculates the simple interest of a value at the specified rate. The interest is calculated for each time period in the specified range.
Syntax
@INTEREST(balanceMbr, creditrateMbrConst, borrowrateMbrConst [, rangeList]) balanceMbr - Single member specification representing the balance at the time the interest is calculated. creditrateMbrConst - Single member specification, variable name, or numeric expression providing a constant value. The value must be a decimal number that corresponds to a percentage. borrowrateMbrConst - Single member specification, variable name, or numeric expression providing a constant value. The value must be a decimal number corresponding to a percentage value. If the value specified by balanceMbr is positive, the interest rate applied is the value specified by creditrateMbrConst. If the value specified by balanceMbr is negative, the interest rate applied is the value specified by balanceMbr.
Example
This example calculates the interest for Balance, using Credit Rate for positive balances and using Borrow Rate for negative balances. The results are placed in Amount for each fiscal year.
"Amount" = @INTEREST(Balance,"Credit Rate","Borrow Rate",FY1991:FY1996); FY1991 Balance Credit Rate Borrow Rate Amount 2000 0.065 FY1992 3000 0.065 FY1993 -1000 0.065 FY1994 3000 0.065 FY1995 9000.00 0.065 FY1996 -6000 0.065
0.1125
0.1125
0.1125
0.1125
0.1125
0.1125
130.00
195.00
-112.50
195.00
585.00
-675.00
9-16
Hyperion
@IRR
The @IRR() function calculates the Internal Rate of Return on a cash flow that must contain at least one investment (negative) and one income (positive) value.
Syntax
@IRR(cashflowMbr, discountFlag[, rangeList]) cashflowMbr Single member specification. discountFlag Member specification, variable name, or numeric expression providing a constant value of either 1 or 0. discountFlag indicates whether the function should discount from the first period. 1 means do not discount from the first period.
Example
Example This example calculates the Internal Rate of Return (Return) on a cash flow (Cash).
Return = @IRR(Cash,0,FY1991:FY1996);

FY1991 Cash Return (1,000) 0.41 FY1992 500 0.41 FY1993 500 0.41 FY1994 500 0.41 FY1995 500 0.41 FY1996 500 0.41
Notes
Essbase returns #MISSING from calculator function @IRR if all cash flows are zero.
Hyperion
9-17
@IRR provides an initial guess of 0.07. This cannot be changed, in contrast to similar functions in Excel. Because results depend in part on the initial guess, any difference in the initial guess may result in a different result. Even if both Excel and Essbase start with the same initial guess, results may differ. This is because there may be more than one solution to an equation, and the algorithm stops looking when it finds a valid solution. Which solution is found first may differ based on the algorithm. Although leading or trailing zeros do not matter in a mathematical context, the algorithm may behave differently and find a different root because of the presence of leading or trailing zeros. If you need identical solutions regardless of the presence of leading or trailing zeros, you may wish to create a custom-defined function to handle these issues.
9-18
Hyperion
@MAXRANGE
The @MAXRANGE() function returns the maximum value of the specified member across the specified range of members.
Syntax
@MAXRANGE (mbrName [ ,rangeList])
Example
In the Sample Basic database: Qtr1 = @MAXRANGE(Sales,@CHILDREN(Qtr1)); This example produces the following results:
Jan Sales 678 Feb 645 Mar 675 Qtr1 678
Notes
Depending on the values in the list, @MAXRANGE may return a zero(0) or #MISSING value. For full control over skipping or inclusion of zero(0) and #MISSING values, it is recommended to use the @MAXSRANGE function instead of the @MAXRANGE function.
Hyperion
9-19
@MAXSRANGE
The @MAXSRANGE() function returns the maximum value of the specified member across the specified range of members. @MAXSRANGE enables skipping of #MISSING and 0 values, in contrast with the @MAXRANGE function, which cannot ignore these values.
Syntax
@MAXSRANGE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [ ,rangeList])
Examples
For both examples, assume a database similar to Sample Basic. Example 1
COGS( Qtr1_Max = @MAXSRANGE(SKIPBOTH, COGS, Jan:Mar);) Other_Exp( Qtr1_Min = @MAXSRANGE(SKIPBOTH, Other_Exp, Jan:Mar);)
This example ignores #MISSING and 0 values and produces the following results:
Jan Other_Exp COGS -500 0 Feb #MISSING 1500 Mar -250 2300 Qtr1_Max --500 1500
Example 2
Qtr1_Max = @MAXSRANGE (SKIPNONE, OtherInc_Exp, @CHILDREN(Qtr1));
produces the following results:

Jan Other_Exp COGS -500 0 Feb #MISSING 1500 Mar -250 2300 Qtr1_Max 0 0
9-20
Hyperion
Notes
@MAXSRANGE (SKIPNONE, mbrName, rangeList) is equivalent to @MAXRANGE mbrName, (rangeList). #MISSING values are considered to be greater than negative data values and less than positive data values. If the data being calculated includes only negative and #MISSING values, @MAXSRANGE returns #MISSING. For all members, @MAXSRANGE returns the value calculated for the specified member and range list.
Hyperion
9-21
@MDSHIFT
The @MDSHIFT() function shifts a series of data values across multiple dimension ranges.
Syntax
@MDSHIFT (mbrName, shiftCnt1, dimName1, [range1], . . . shiftCntX, dimNameX, [rangeX]) shiftCnt1...shiftCntX - Integer that defines the number of member positions to shift. range1 . . . rangeX - A valid member name, a comma-delimited list of member names, member set functions, and range functions from the same dimension. If the range list is comma delimited, then the list must be enclosed in parentheses.
Example
The Budget figures for Ending Inventory need to be calculated by taking Prior Year->Opening Inventory results as a starting point:
FIX (Budget) "Ending Inventory" = @MDSHIFT("Opening Inventory", 1, Year, , -1, Scenario,); ENDFIX
In this example, range1 is not specified, so Essbase defaults to the level 0 members of the Year dimension, which was specified as the dimName1 parameter. Since range2 is also not specified, Essbase defaults to the level 0 members of the Scenario dimension, which was specified as the dimName2 parameter. This example produces the following (partial) results:
Jan Prior Year Opening Inventory Ending Inventory 110 Feb 120 Mar 130
Budget
120
130
140
9-22
Hyperion
@MINRANGE
The @MINRANGE() function returns the minimum value of the specified member across the specified range of members.
Syntax
@MINRANGE (mbrName [ ,rangeList])
Example
Qtr1 = @MINRANGE(Sales,Jan:Mar);

Jan Sales 678 Feb 645 Mar 675 Qtr1 645
Notes
Depending on the values in the list, @MINRANGE may return a zero(0) or #MISSING value. For full control over skipping or inclusion of zero(0) and #MISSING values, it is recommended to use the @MINSRANGE function instead of the @MINRANGE function.
Hyperion
9-23
@MINSRANGE
The @MINSRANGE() function returns the minimum value of mbrName across rangeList. @MINSRANGE enables skipping of #MISSING and 0 values, in contrast with the @MINRANGE function, which always includes these values in the calculation.
Syntax
@MINSRANGE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [,rangeList])
Examples
For both examples, assume a database similar to Sample Basic. Example 1
COGS( Qtr1_Min = @MINSRANGE(SKIPBOTH, COGS, Jan:Mar);) Other_Exp( Qtr1_Min = @MINSRANGE(SKIPBOTH, Other_Exp, Jan:Mar);)
This example ignores the 0 value for Mar and produces the following results:
Jan COGS Other_Exp #MISSING 500 Feb 1500 350 Mar 2300 0 Qtr1_Min 1500 350
Example 2
COGS( Qtr1_Min = @MINSRANGE(SKIPNONE, COGS, Jan:Mar);) Other_Exp( Qtr1_Min = @MINSRANGE(SKIPNONE, Other_Exp, Jan:Mar);)
This example does not ignore the 0 value in the calculation. This example produces the following results:
Jan COGS Other_Exp #MISSING 500 Feb 1500 350 Mar 2300 0 Qtr1_Min #Missing 0
9-24
Hyperion
Notes
@MINSRANGE (SKIPNONE, mbrName, rangeList) is equivalent to @MINRANGE (mbrName, rangeList). #MISSING values are considered to be less than positive data values and more than negative data values. Iif the data being calculated includes only positive and #MISSING values, @MINSRANGE returns #MISSING.
Hyperion
9-25
@NEXT
The @NEXT() function returns the nth cell value in the sequence rangeList from mbrName, retaining all other members identical to the current member. @NEXT cannot operate outside the given range.
Syntax
@NEXT (mbrName [, n, rangeList]) n - signed integer.
Example
In this example, Next Cash for each month is derived by taking the Cash value for the following month. Since n is not specified, the default is 1, which provides the next member in the range. Since rangeList is not specified, the level 0 members from the dimension tagged as Time are used (Jan,Feb,Mar, ...).
"Next Cash" = @NEXT(Cash); Two Cash = @NEXT(Cash ,2);

Jan Cash Next Cash Two Cash Feb 100 90 120 Mar 90 120 110 Apr 120 110 150 May 110 150 100 Jun 150 100 #MI 100 #MI #MI
Notes
If you do not specify n, then the default is set to 1, which provides the next member in the range. Using a negative value for n has the same effect as using the matching positive value in the @PRIOR function.
9-26
Hyperion
@NEXTS
The @NEXTS() function returns the nth cell value in the sequence rangeList from the mbrName. @NEXTS provides the option to skip #MISSING, zero, or both #MISSING and zero values. @NEXTS works within a designated range and retains all other members identical to the current member.
Syntax
@NEXTS(SKIPNONE | SKIPMISSING | SKIPZERO | | SKIPBOTH mbrName[,n,rangeList]) n - signed integer.
Example
In this example, Next Cash for each month is derived by taking the Cash value for the following month and ignoring both #MISSING and zero values. Because n is not specified, the default is 1, which provides the next member in the range. Also, because rangeList is not specified, the level 0 members from the dimension set as Time are used (Jan,Feb,Mar,...).
"Next Cash" = @NEXTS(SKIPBOTH, Cash); "Two Cash" = @NEXTS(SKIPBOTH, Cash, 2); Jan Cash Next Cash Two Cash 1100 1000 1000 Feb #MI 1000 1300 Mar 1000 1300 1400 Apr 1300 1400 #MI May 0 1400 #MI Jun 1400 #MI #MI
Notes
Using a negative value for n has the same effect as using the matching positive value in @PRIORS. If you do not specify n, then a default value of 1 is assumed, which returns the next prior member from the lowest level of the dimension set as Time in the database outline.
Hyperion
9-27
@NPV
The @NPV() function calculates the Net Present Value of an investment based on the series of payments (negative values) and income (positive values).
Syntax
@NPV (cashflowMbr, rateMbrConst, discountFlag [, rangeList]) cashflowMbr - Member specification providing a series of numeric values. rateMbrConst - Single member specification, variable name, or numeric expression, providing a constant value. discountFlag - Single member specification, variable name, or numeric expression set to 0 or 1 to indicate whether the function should discount from the first period. 1 means do not discount from the first period.
Example
In this example, Value is calculated with the following formula:
Value = @NPV(Cash, Rate, 0, FY1991:FY1996);
This example produces the following report:

FY1991 Cash Rate Value (1,000) .05 1547.62 1547.62 1547.62 1547.62 1547.62 1547.62 FY1992 500 FY1993 500 FY1994 500 FY1995 500 FY1996 500
9-28
Hyperion
@PRIOR
The @PRIOR() function returns the nth previous cell member from mbrName in rangeList.
Syntax
@PRIOR (mbrName [, n, rangeList]) n - signed integer.
Example
In this example, Prev Inventory for each month is derived by taking the Inventory value from the previous month.
Prev = @PRIOR(Value); Prev2 = @PRIOR(Value, 2);

Jan Value Prev Prev2 1100 #MI #MI Feb 1200 1100 #MI Mar 1300 1200 1100 Apr 1400 1300 1200 May 1500 1400 1300 Jun 1600 1500 1400
Notes
Using a negative value for n has the same effect as using the matching positive value in the @NEXT function. If you do not specify n, then a default value of 1 is assumed, which returns the next prior member from the lowest level of the dimension tagged as Time in the database outline.
Hyperion
9-29
@PRIORS
The @PRIORS() function returns the nth previous cell member from mbrName in the rangeList. @PRIORS provides options to skip #MISSING, zero, or both #MISSING and zero values. All other dimensions assume the same members as the current member. @PRIORS works within the designated range.
Syntax
@PRIORS(SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH mbrName[,n, rangeList]) n - signed integer.
Example
In this example, Prev Inventory for each month is derived by taking the Inventory value from the previous month and ignoring #MISSING and zero values. Because n is not specified, the default is 1, which provides the next prior member in the range. Also, because rangeList is not specified, the level 0 members from the dimension are set as Time used as (Jan,Feb,Mar,...).
"Prev" = @PRIORS(SKIPBOTH,Value); "Prev2" = @PRIORS(SKIPBOTH,Value,2);

Jan Value Prev Prev2 1100 #MI #MI Feb #MI 1100 #MI Mar 1300 1100 #MI Apr 1400 1300 1100 May 0 1400 1300 Jun 1600 1400 1300
Notes
Using a negative value for n has the same effect as using the matching positive value in the @NEXTS function. If you do not specify n, then a default value of 1 is assumed, which returns the next prior member from the lowest level of the dimension set as Time in the database outline.
9-30
Hyperion
@PTD
The @PTD() function calculates the period-to-date values of members in the dimension tagged as Time. By default, data is summed unless Accounts are tagged as "First" or "Last", which returns the periods first and last value, respectively.
Syntax
@PTD (timePeriodList) timePeriodList - Range of members from the dimension tagged as Time.
Example
In this example, assume that the Year dimension in the Sample Basic database outline contains two additional members, YTD and QTD. Opening Inventory is tagged time balance - First. Ending Inventory is tagged time balance - Last.
YTD = @PTD(Jan:May); QTD = @PTD(Apr:May);

Sales Jan Feb Mar Qtr1 Apr May Jun Qtr2 QTD YTD 1000 1000 1000 3000 1000 1000 1000 3000 2000 5000 Opening Inventory 1000 1100 1200 3000 1300 1400 1500 3000 1300 1000 Ending Inventory 1100 1200 1300 3000 1400 1500 1600 3000 1500 1500
Hyperion
9-31
@SHIFT
The @SHIFT() function returns the nth cell value in the sequence rangeList from mbrName, retaining all other members identical to the current member.
Syntax
@SHIFT (mbrName [,n, rangeList]) n - signed integer.
Example
In this example, Prev Asset for each month is derived by taking the Asset value from the previous month because -1 is specified as the n parameter. Next Avl Asset for each month is derived by taking the Asset value from two months following the current month because 2 is specified as the n parameter. Since rangeList is not specified for either formula, the level 0 members from the dimension tagged as Time are used. "Prev" = @SHIFT(Value,-1); "Next" = @SHIFT(Value,1); This example produces the following results:
Jan Value Prev Next 1100 #MI 1200 Feb 1200 1100 1300 Mar 1300 1200 1400 Apr 1400 1300 1500 May 1500 1400 1600 Jun 1600 1500 #MI
Notes
This function gets either the prior or next (nth past or future value in rangeList) value of mbrName, based on n. The direction of shift is wholly based on n, with positive n values producing an effect equivalent to @NEXT and negative values of n producing an equivalent effect to @PRIOR. @SHIFT is provided as a more appropriate, self-documenting name than @NEXT or @PRIOR when the value for n is a variable and may change from positive to negative, depending on the database state when the call occurs (that is, when the usage is likely to be NEXT and/or PRIOR).
9-32
Hyperion
@SLN
The @SLN() function calculates the amount per period that an asset in the current period may be depreciated, calculated across a range of periods. It uses a straight-line depreciation method.
Syntax
@SLN(costMbr, salvageMbrConst, lifeMbrConst [, rangeList]) costMbr - Single member specification representing an input asset for the current period. salvageMbrConst - Single member specification, variable name, or numeric expression, providing a constant numeric value. This value represents the value of the asset in the current period at the end of the useful life of the asset. lifeMbrConst - Single member specification, variable name, or numeric expression representing the useful life of the asset.
Example
In this example, the depreciation for each year is calculated by taking into account the initial asset (Asset), the salvage value of the asset (Residual), and the life of the asset (Life). "SLN Dep" = @SLN(Asset,Residual,Life,FY1991:FY1996); This example produces the following results:
FY1991 Asset Residual Life SLN Dep 9000 750 5 1650 1650 1650 1650 1650 #MI FY1992 FY1993 FY1994 FY1995 FY1996
Notes
More than one asset may be depreciated over the range. Straight line depreciation calculates the depreciation of an asset assuming it will depreciate an equal amount of value each year.
Hyperion
9-33
@SUMRANGE
The @SUMRANGE() function returns the summation of all the values of the specified member across the specified range.
Syntax
@SUMRANGE(mbrName [, rangeList])
Example
The following example is based on the Sample Basic database. Assume that the Year dimension contains an additional member, Partial Year.
"Partial Year"=@SUMRANGE("New York",Feb:May);

Sales Jan Feb Mar Qtr1 Apr May Jun Qtr2 Partial Year 400 100 100 100 300 100 100 100 300
9-34
Hyperion
@SYD
The @SYD() function calculates the amount per period that an asset in the current period may be depreciated, across a range of periods. The depreciation method used is sum of the years digits.
Syntax
@SYD (costMbr, salvageMbrConst, lifeMbrConst [, rangeList]) costMbr - Single member specification representing an input asset for the current period. salvageMbrConst - Single member specification, variable name, or numeric expression, providing a constant numeric value. This value is the value of the asset in the current period after the useful life of the asset. lifeMbrConst - Single member specification, variable name, or numeric expression representing the useful life of the asset.
Example
In this example, the depreciation for each year is calculated by taking into account the initial asset (Asset), the salvage value of the asset (Residual), and the life of the asset (Life).
SYD Dep"=@SYD(Asset,Residual,Life,FY1991:FY1996);

FY1991 Asset Residual Life SYD Dep 9000 750 5 2750 2200 1650 1100 550 #MI FY1992 FY1993 FY1994 FY1995 FY1996
Notes
More than one asset may be depreciated over the range. Sum of years digits calculates depreciation of an asset by assuming higher depreciation charges in the early years of an asset's life.
Hyperion
9-35
Exercise 9-1: Applying Range Functions (@PRIOR)

In this exercise, you create a calc script that calculates opening inventory and inventory additions. The opening inventory value is the ending inventory for the previous month. Additions are the difference between ending and opening inventory for the month. January opening inventory is difference between Januarys ending inventory and additions. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSPrior SS_Prior.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate opening inventory and inventory additions. The opening inventory value is the ending inventory for the previous month. Additions are the difference between ending and opening inventory for the month. January opening inventory is difference between Januarys ending inventory and additions. Save the new script as CSPrior. Open the SS_Prior spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The values in yellow have not been calculated. From the Calc&Retrieve sheet, run the CSPrior calc script. Perform a retrieval and notice the calculation results within the yellow cells. Are the values in the yellow cells as expected? If not, revise the CSPrior calc script and rerun the calculation until the yellow cells contain the expected results. Close the spreadsheet.
3) 4)
5) 6) 7)
8)
9-36
Hyperion
Exercise 9-2: Applying Financial Functions (@IRR)

In this exercise, you create a calc script that calculates the internal rate of return on an investment. In 1997, Hook Line and Sinker invested $38,000 to purchase the capability to produce the "4000 Product Family". The ROI is calculated using this product familys profits for the subsequent years.
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSIrr SS_Irr.xls
1)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate the internal rate of return on an investment. In 1997, Hook Line and Sinker invested $38,000 to purchase the capability to produce the "4000 Product Family". The ROI is calculated using the product line profits for the subsequent years. Save the new script as CSIrr. Open the SS_Irr spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The values in yellow have not been calculated. From the Calc&Retrieve sheet, run the CSIrr calc script. Perform a retrieval and notice the ROI calculation results. Compare the ROI results with the values in the Expected Res sheet. If they are not the same, modify the CSIrr calc script and rerun the calculation until you get the expected results. Close the spreadsheet.
2)
3) 4) 5) 6)
7)
8)
Hyperion
9-37
Unit Summary
Range and Financial functions perform mathematical operations on a range of values. Rather than return a single value, these functions calculate a series of values internally based on the range specified. Financial functions execute specialized financial calculations.
9-38
Hyperion

Now that you have completed the chapter, check your understanding by responding to the following questions: 1) For each of the following situations, identify the Range (Financial) function that you would use to retrieve the required value. Use the Sample Basic outline. (Multiple solutions may be correct for some of these answers.)
What the value of sales for the month in which sales is largest? What is the value of sales three months after the month currently being processed? What is the average amount of monthly sales? What is the amount of compound interest for a series of debt payments? What is the internal rate of return on an investment?
Hyperion
9-39
9 Range and Financial Functions Check Your Understanding Solutions

1)
For each of the following situations, identify the Range (Financial) function that you would use to retrieve the required value. Use the Sample Basic outline. (Multiple solutions may be correct for some of these answers.)
@MAXRANGE
What the value of sales for the month in which sales is largest? What is the value of sales three months after the month currently being processed? What is the average amount of monthly sales? What is the amount of compound interest for a series of debt payments? What is the internal rate of return on an investment?
@NEXT
@AVGRANGE @COMPOUND
@IRR
9-40
Hyperion
10
Allocation Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of Allocation functions to generate member lists Practice using the Allocation functions in a series of incremental exercises
10
Using Allocation Functions

Allocation functions allocate values that are input at the parent level. The
values are allocated across child members in one or more dimensions, based on specified criteria. These functions consolidate the common tasks that are required to perform allocations in Essbase.
Common Parameters
The allocation functions share a common set of parameters. In addition, the @MDALLOCATE function has an extra set of parameters to identify the dimensions that are used to distribute the amount. The parameters that are common to both allocation functions are described here. amount A value, member, or cross-dimensional member that contains the value to be allocated into allocationRange. The value may also be a constant. If amount is a member, the member must be from the dimension to which allocationRange belongs. If amount is a cross-dimensional member, at least one of its members must be from the dimension to which allocationRange belongs. allocationRange A comma-delimited list of members, member set functions, or range functions from the same dimension, into which value(s) from amount are allocated. allocationRange should be from only one level (for example, @CHILDREN(Total Expenses) rather than from multiple levels (for example, @DESCENDANTS(Product)). basisMbr A value, member, or cross-dimensional member that contains the values that provide the basis for the allocation. The method you specify determines how the basis data is used.
roundMbr The member or cross-dimensional member to which rounding errors are added. The member (or at least one member of a cross-dimensional member) must be included in allocationRange.
10-2
Hyperion
Hyperion Essbase Calc Scripts method
10
The expression that determines how values are allocated. One of the following:
Uses basisMbr to calculate a percentage share. The percentage share is calculated by dividing the value in basisMbr for the current member in allocationRange by the sum across the allocationRange for that basis member: amount * (@CURRMBR()->basisMbr/ @SUM(allocationRange-> basisMbr)
share
spread
Spreads amount across allocationRange: amount * (1/@COUNT(SKIP, allocationRange)) SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH: Values to be ignored during calculation of the spread. You must specify a SKIP parameter only for spread. SKIPNONE: Includes all cells. SKIPMISSING: Excludes all #MISSING values in basisMbr, and stores #MISSING for values in allocationRange for which the basisMbr is missing. SKIPZERO: Excludes all zero (0) values in basisMbr, and stores #MISSING for values in allocationRange for which the basisMbr is zero. SKIPBOTH: Excludes all zero (0) values and all #MISSING values, and stores #MISSING for values in allocationRange for which the basisMbr is zero (0) or #MISSING.
percent
Takes a percentage value from basisMbr for each member in allocationRange and applies the percentage value to amount: amount * (@CURRMBR()->basisMbr * .01)
add
Takes the value from basisMbr for each member of allocationRange and adds the value to amount: amount + @CURRMBR()->basisMbr
subtract
Takes the value from basisMbr for each member of allocationRange and subtracts the value from amount: amount - @CURRMBR()->basisMbr
multiply
Takes the value from basisMbr for each member of allocationRange and multiplies the value by amount: amount * @CURRMBR()->basisMbr
divide
Takes the value from basisMbr for each member of allocationRange and divides the value by amount: amount/@CURRMBR()->basisMbr
Hyperion
10-3
10
Allocation Functions round

noRound roundAmt, [numDigits [, roundErr]]
Hyperion Essbase Calc Scripts One of the following:

No rounding. noRound is the default Indicates that you want to round the allocated values. If you specify roundAmt, you also may specify numDigits to indicate the number of decimal places to which to round. You may also specify roundError, which is an expression that specifies where rounding errors should be placed.
numDigits An integer that represents the number of decimal places to round to. You must specify numDigits if you specify roundAmt. If numDigits is 0, the allocated values are rounded to the nearest integer. The default value for numDigits is 0. If numDigits is greater than 0, the allocated values are rounded to the specified number of decimal places. If numDigits is a negative value, the allocated values are rounded to a power of 10. roundErr. An expression that specifies where rounding errors should be placed. If you do not specify roundErr, Essbase discards rounding errors. roundErr may be one of the following:
errorsToHigh Adds rounding errors to the member with the highest allocated value. If allocated values are identical, adds rounding errors to the first value in allocationRange. Adds rounding errors to the member with the lowest allocated value. If allocated values are identical, adds rounding errors to the first value in allocationRange. #MISSING is treated as the lowest value in a list; if multiple values are #MISSING, rounding errors are added to the first #MISSING value in the list. Adds rounding errors to the specified roundMbr, which must be included in allocationRange.
errorsToLow
errorsToMbr
10-4
Hyperion
10
Summary of Allocation Functions

This table summarizes the Allocation Functions. Each function is also described, in detail, in this chapter.
Function @ALLOCATE Used to generate a list containing Allocates values that are input at an upper level to lower-level members. Allocates values that are input at an upper level to lower-level members in multiple dimensions.
@MDALLOCATE
Hyperion
10-5
10
@ALLOCATE
The @ALLOCATE() function allocates values that are input at an upper level to lower-level members. The allocation is based upon a specified share or spread of another variable. For example, you can allocate values loaded to a parent member to all of that member's children. You can specify a rounding parameter for allocated values and account for rounding errors.
Syntax
@ALLOCATE (amount, allocationRange, basisMbr, [roundMbr],method [, methodParams] [, round [, numDigits][, roundErr]])
Example
Consider the following example. The Essbase outline contains a Scenario dimension with two members, PY Actual, for the prior year's actual expenses; and Budget for budget expenses. Data values of 7000 is loaded into Budget->Total Expenses for Jan. You need to allocate values to each expense category (to each child of Total Expenses). The allocation for each of child of Total Expenses is based on the child's share of actual expenses for the prior year (PY Actual):
FIX("Total Expenses") Budget = @ALLOCATE(Budget->"Total Expenses", @CHILDREN("Total Expenses"),"PY Actual",,share); ENDFIX

PY Actual Marketing Payroll Misc Total Expenses 5000 4000 1000 10000 Budget 3500 2800 700 7000
Notes
If no member or cross-dimensional member is from the dimension to which allocationRange belongs, Essbase displays a warning message.
10-6
Hyperion
10
If the amount parameter is a loaded value, it cannot be a Dynamic Calc member. When you use @ALLOCATE in a calculation script, use it within a FIX statement; for example, FIX on the member to which the allocation amount is loaded. Although FIX is not required, using it may improve calculation performance. If you use @ALLOCATE in a member formula, your formula should look like this: Member Name = @ALLOCATE (...) This is because allocation functions never return a value; rather, they calculate a series of values internally based on the range specified.
Hyperion
10-7
10
@MDALLOCATE
The @MDALLOCATE function allocates values that are input at an upper level to lower-level members in multiple dimensions. The allocation is based upon a specified share or spread of another variable. You can specify a rounding parameter for allocated values and account for rounding errors.
Syntax
@MDALLOCATE (amount, Ndim, allocationRange1... allocationRangeN, basisMbr, [roundMbr], method [, methodParams] [, round [, numDigits][, roundErr]])
Additional Parameters
The additional parameters for the @MDALLOCATE function are: Ndim The number of dimensions across which values are allocated.
allocationRange1... allocationRangeN Comma-delimited lists of members, member set functions, or range functions from the multiple dimensions into which values from amount are allocated.
Example
Consider the following example from the Sample Basic database. A data value of 2200 is loaded to Budget->Total Expenses->East for Jan and Colas. You need to allocate this total budgeted amount across each expense category for each child of East. The allocation for each child of East is based on the child's share of Total Expenses->Actual:
FIX("Total Expenses") Budget = @MDALLOCATE(Budget->"Total Expenses"->East,2, @CHILDREN(East),@CHILDREN("Total Expenses"), Actual,, share); ENDFIX
10-8
Hyperion
10
This example produces the following results for Jan, Colas:

Marketing Payroll Misc Total Expenses 400 400 400 400 400
Actual
New York Massachusetts Florida Connecticut New Hampshire East
100 100 100 100 100
200 200 200 200 200
100 100 100 100 100
500 110 110 110 110 110
1000 220 220 220 220 220
500 110 110 110 110 110
2000 #MI #MI #MI #MI #MI
Budget
New York Massachusetts Florida Connecticut New Hampshire East
#MI
#MI
#MI
2200
Notes
If no member or cross-dimensional member is from the dimension to which allocationRange belongs, Essbase displays a warning message. If the amount parameter is a loaded value, it cannot be a Dynamic Calc member. When you use @MDALLOCATE in a calculation script, use it within a FIX statement; for example, FIX on the member to which the allocation amount is loaded. Although FIX is not required, using it may decrease calculation time. If you have very large allocationRange lists, Essbase may return error messages during the calculation. If you receive error messages, you may need to raise the number for CALCLOCKBLOCK DEFAULT or use CALCLOCKBLOCK HIGH in your calculation script.
Hyperion
10-9
10
Exercise 10-1: Applying Allocation Functions

In this exercise, you create a calc script that calculates the budgeted total expenses for Western market for January 2000. The budgeted total expenses are 5% greater than the actual total expenses for January 1999 and are distributed to the individual expense accounts in the same ratios as the actual January 1999 expenses. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSAlloc SS_Alloc.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate the budgeted total expenses for Western market for January 2000. The budgeted total expenses are 5% greater than the actual total expenses for January 1999 and are distributed to the individual expense accounts in the same ratios as the actual January 1999 expenses. Save the new script as CSAlloc. Open the SS_Alloc spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The 1999 Actual-West and 2000 Budget values have not been calculated. From the Calc&Retrieve sheet, run the CSAlloc calc script. Perform a retrieval and compare the Total Expenses results to those in the Expected Results column. Do the Essbase results match those in the Expected Results column? If not, modify the CSAlloc calc script and rerun the calculation until you get the expected results. Close the spreadsheet.
3) 4)
5) 6)
7)
8)
10-10
Hyperion
10
Unit Summary
Allocation functions allocate values that are input at the parent level. The
values are allocated across child members in one or more dimensions, based on specified criteria. There are several allocation methods that may be used.
share Divides the amount among members of the allocation range using basisMbr to calculate a percentage share. Divides the amount evenly across all members of allocationRange. Treats the amount as a percentage value which is applied to basisMbr corresponding to the allocationRange member. Adds the amount to the basisMbr for each member of allocationRange. Subtracts the amount from the basisMbr for each member of allocationRange. Multiplies the amount to the basisMbr for each member of allocationRange. Divides the amount by the basisMbr for each member of allocationRange.
spread
percent
add
subtract
multiply
divide
Hyperion
10-11
10 Allocation Functions Check Your Understanding

1)
Now that you have completed the chapter, check your understanding by responding to the following questions: The value for advertising expense for next year budget is to be allocated to individual products. Which allocation method would be most appropriate in each of the following situations? a. The total budget expense is known for all products and is to be allocated to individual products in the same proportion this years actual advertising expense for each product.
b.
The total budget expense is known for all products and is to be evenly distributed to individual products (each individual product is to receive the same amount of budget).
c.
Next years budget adveristing expense for each individual product is a 10% increase over this year s actual advertising expense.
d.
Each individual products budgeted advertising expense will be increased by $500 over this years actual.
e.
Each individual products budgeted advertising expense will be decreased by $500 over this years actual.
10-12
Hyperion
10

1) The value for advertising expense for next year budget is to be allocated to individual products. Which allocation method would be most appropriate in each of the following situations? a. The total budget expense is known for all products and is to be allocated to individual products in the same proportion this years actual advertising expense for each product. share The total budget expense is known for all products and is to be evenly distributed to individual products (each individual product is to receive the same amount of budget). spread Next years budget adveristing expense for each individual product is a 10% increase over this year s actual advertising expense. percent (or share) Each individual products budgeted advertising expense will be increased by $500 over this years actual. add Each individual products budgeted advertising expense will be decreased by $500 over this years actual. subtract
b.
c.
d.
e.
Hyperion
10-13
10
10-14
Hyperion
11
Forecasting Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of Forecasting functions to generate member lists Practice using the Forecasting functions in a series of incremental exercises
11
Using Forecasting Functions

Forecasting functions manipulate data for the purpose of smoothing, interpolating, or calculating future values. Forecasting functions are often used in planning, analysis, and modeling applications.
Forecasting Function Parameters

There are common parameters associated with the various Forecasting functions
mbrName Any valid single member name or member combination, or a function that returns a single member or member combination. A valid member name, a comma-delimited list of member names, member set functions, and range functions from the same dimension. If rangeList is not specified, Essbase uses the level 0 members from the dimension tagged as Time.
rangelist
11-2
Hyperion
11
Summary of Forecasting Functions

This table summarizes the Forecasting Functions. Each function is also described, in detail, in this chapter.
Function @MOVAVG @MOVMAX @MOVMED @MOVMIN @MOVSUM * @MOVSUMX * Calculates A moving n-term average of an input data set. A moving n-term maximum of an input data set. A moving n-term median of an input data set. A moving n-term minimum of an input data set. A moving n-term sum of an input data set. A moving n-term sum of an input data set and provides several options that control how values are assigned to members that precede the n-term parameter. A smoothing spline to a set of data points. Future values based on curve-fitting to historical values.
@SPLINE @TREND
* New in Essbase XTD Release 6.5.1.
Hyperion
11-3
11
@MOVAVG
The @MOVAVG() function applies a moving n-term average to an input data set. Each term in the set is replaced by a trailing mean of n terms, and the first terms (the n-1 terms) are copies of the input data. @MOVAVG modifies a data set for smoothing purposes.
Syntax
@MOVAVG (mbrName [, n [, rangeList]]) n - A positive integer value that represents the number of values to average. The default is 3.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Mov Avg.
"Mov Avg" = @MOVAVG(Sales,3,Jan:Jun);
In this example, the @MOVAVG function smooths sales data for the first six months of the year (Jan through Jun). This example produces the following results:
Sales Jan Feb Mar Apr May Jun 100 110 120 130 140 150 Mov Avg 100 110 110 120 130 140
In this example, Essbase averages three values at a time for the moving average. The first two values (Jan,Feb) for Mov Avg and the first two values for Sales are the same. The value for Mar represents the trailing average of Jan, Feb, and Mar. The value for Apr represents the trailing average of Feb, Mar, and Apr. The remaining values represent the trailing average for each group of three values.
11-4
Hyperion
11
Notes
The @MOVAVG function calculates a trailing, rather than a centered, average. For example:
Trailing Average 1 2 3 2 Centered Average 1 2 2 3
While calculating the moving average, the @MOVAVG function skips #MISSING values and decreases the denominator accordingly. For example, if one value out of three is #MISSING, Essbase adds the remaining two values and divides the sum by two. If you use a Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. For more information, see the online Technical Reference topic for the member set function you are using. When you use @MOVAVG in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MOVAVG across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
Hyperion
11-5
11
@MOVMAX
The @MOVMAX() function applies a moving n-term maximum (highest number) to an input data set. Each term in the set is replaced by a trailing maximum of n terms, and the first terms (the n-1 terms) are copies of the input data. @MOVMAX modifies a data set for smoothing purposes.
Syntax
@MOVMAX (mbrName [, n [, rangeList]]) n - A positive integer value that represents the number of values that are used to calculate the moving maximum. The default is 3.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Mov Max.
"Mov Max" = @MOVMAX(Sales,3,Jan:Jun);
In this example, the @MOVMAX function smooths sales data for the first six months of the year (Jan through Jun). The results of @MOVMAX can be used with the @TREND function to forecast maximum sales data for a holiday season (for example, October - December). This example produces the following results:
Sales Jan Feb Mar Apr May Jun 551 641 586 630 612 747 Mov Max 551 641 641 641 630 747
In this example, Essbase uses three values at a time to calculate the moving maximum. The first two values (Jan,Feb) for Mov Max and the first two values for Sales are the same. The value for Mar represents the trailing maximum of Jan, Feb, and Mar. The value for Apr represents the trailing maximum of Feb, Mar, and Apr. The remaining values represent the trailing maximum for each group of three values.
11-6
Hyperion
11
Notes
The @MOVMAX function calculates a trailing, rather than a centered, maximum. For example:
Trailing Maximum 1 2 3 3 Centered Maximum 1 2 3 3
While calculating the moving maximum, @MOVMAX skips #MISSING values. For example, if one value out of four is #MISSING, @MOVMAX calculates the maximum of the remaining three values. If you use a Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. When you use @MOVMAX in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MOVMAX across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
Hyperion
11-7
11
@MOVMED
The @MOVMED() function applies a moving n-term median (middle number) to an input data set. Each term in the list is replaced by a trailing median of n terms, and the first terms (the n-1 terms) are copies of the input data. @MOVMED modifies a data set for smoothing purposes.
Syntax
@MOVMED (mbrName [, n [, rangeList]]) n - A positive integer value that represents the number of values that are used to calculate the moving median. The default is 3.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Mov Med.
"Mov Med" = @MOVMED(Sales,3,Jan:Jun);
In this example, the @MOVMED function smooths sales data for the first six months of the year (Jan through Jun). This example produces the following results:
Sales Jan Feb Mar Apr May Jun 551 641 586 630 612 747 Mov Med 551 641 586 630 612 630
In this example, Essbase uses three values at a time to calculate the moving median. The first two values (Jan,Feb) for Mov Med are the same as the first two values for Sales. The value for Mar represents the trailing median of Jan, Feb, and Mar. The value for Apr represents the trailing median of Feb, Mar, and Apr. The remaining values represent the trailing median of each group of three values.
11-8
Hyperion
11
Notes
While calculating the moving median, the @MOVMED function skips #MISSING values. For example, if one value out of four is #MISSING, @MOVMED calculates the median of the remaining three values. The @MOVMED function calculates a trailing, rather than a centered, median. For example:
Trailing Median 1 2 3 2 Centered Median 1 2 2 3
If the group of values being used to calculate the median contains an even number of values, the @MOVMED function averages the two numbers in the middle. If you use a Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. When you use @MOVMED in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MOVMED across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
Hyperion
11-9
11
@MOVMIN
The @MOVMIN() function applies a moving n-term minimum (lowest number) to an input data set. Each term in the list is replaced by a trailing minimum of n terms, and the first terms (the n-1 terms) are copies of the input data. @MOVMIN modifies a data set for smoothing purposes.
Syntax
@MOVMIN (mbrName [, n [, rangeList]]) n - A positive integer value that represents the number of values that are used to calculate the moving minimum. The default is 3.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Mov Min.
"Mov Min" = @MOVMIN(Sales,3,Jan:Jun);
In this example, the @MOVMIN function smooths sales data for the first six months of the year (Jan through Jun). This example produces the following results:
Sales Jan Feb Mar Apr May Jun 551 641 586 630 612 747 Mov Min 551 641 551 586 586 612
In this example, Essbase uses three values at a time to calculate the moving minimum. The first two values (Jan,Feb) for Mov Min and the first two values for Sales are the same. The value for Mar represents the trailing minimum of Jan, Feb, and Mar. The value for Apr represents the trailing minimum of Feb, Mar, and Apr. The remaining values represent the trailing minimum for each group of three values.
11-10
Hyperion
11
Notes
While calculating the moving minimum, the @MOVMIN function skips #MISSING values. For example, if one value out of four is #MISSING, @MOVMIN calculates the minimum of the remaining three values. The @MOVMIN function calculates a trailing, rather than a centered, minimum. For example:
Trailing Minimum 1 2 3 2 Centered Minimum 1 2 2 3
If you use a Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. When you use @MOVMIN in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MOVMIN across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
Hyperion
11-11
11
@MOVSUM
The @MOVSUM function applies a moving n-term sum to an input data set. Each term of the set is replaced by a trailing sum of n terms, and the first terms (the n-1 terms) are copies of the input data. @MOVSUM modifies a data set for smoothing purposes.
Syntax
@MOVSUM (mbrName [, n [, rangeList]]) n - A positive integer value that represents the number of values that are used to calculate the moving minimum. The default is 3.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Mov Sum.
"Mov Sum" = @MOVSUM(Sales,3,Jan:Jun);
In this example, the @MOVSUM function smooths sales data for the first six months of the year (Jan through Jun). This example produces the following results:
Sales Jan Feb Mar Apr May Jun 551 641 586 630 612 747 Mov Sum 551 641 1778 1857 1828 1989
In this example, Essbase uses three values at a time to calculate the moving sum. The first two values (Jan,Feb) for Mov Sum and the first two values for Sales are the same. The value for Mar represents the trailing sum of Jan, Feb, and Mar. The value for Apr represents the trailing sum of Feb, Mar, and Apr. The remaining values represent the trailing minimum for each group of three values.
11-12
Hyperion
11
Notes
The @MOVSUM function calculates a trailing, rather than a centered, sum. For example:
Trailing Sum 1 2 3 6 1 Centered Sum 2 3 3
While calculating the moving sum, @MOVSUM skips #MISSING values. For example, if one value out of three is #MISSING, Essbase adds the remaining two values. If you use an Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. When you use @MOVSUM in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MOVSUM across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
Hyperion
11-13
11
@MOVSUMX
The @MOVSUMX function applies a moving n-term sum to an input data set. Unlike @MOVSUM, @MOVSUMX provides several options that control how values are assigned to members that precede the n-term parameter. @MOVSUMX modifies a data set for smoothing purposes.
Syntax
@MOVSUMX(COPYFORWARD | TRAILMISSING | TRAILSUM, mbrName [,n[,rangelist]] ) COPYFORWARD - Copies the member value into the new member until the n value is reached, then it will begin summing the value. This duplicates the behavior of the @MOVSUM function. TRAILMISSING - Sets the member value to #MISSING until the n value is reached, then it will begin summing the value. TRAILSUM - Sums the trailing values, regardless of whether the n value is reached or not. When the n value is reached, OLAP Server begins summing just those values n - A positive integer value that represents the number of values that are used to calculate the moving minimum. The default is 3.
Example
SumCopy = @MOVSUMX (COPYFORWARD,Sales,3,Jan:Jun); SumMiss = @MOVSUMX (TRAILMISSING,Sales,3,Jan:Jun); SumTrail = @MOVSUMX (TRAILSUM,Sales,3,Jan:Jun);
Produce the following results:

Sales Jan Feb Mar Apr May Jun 551 641 586 630 612 747 SumCopy 551 641 1778 1857 1828 1989 SumMiss #Missing #Missing 1778 1857 1828 1989 SumTrail 551 1192 1778 1857 1828 1989
11-14
Hyperion
11
@SPLINE
The @SPLINE() function applies a smoothing spline to a set of data points. A spline is a mathematical curve that smooths or interpolates data.
Syntax
@SPLINE (YmbrName [, s [, XmbrName [, rangeList]]]) YmbrName A valid single member name that contains the dependent variable values used (when crossed with rangeList) to construct the spline. s - A zero (0) or positive value that determines the smoothness parameter. The default value is 1.0. XmbrName - A valid single member name that contains the independent variable values used (when crossed with rangeList) to construct the spline. The default independent variable values are 0,1,2,3, and so on.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Sales Spline. The formula calculates the spline of Sales values for Jan through Jun, based on a smoothness parameter of 2.
"Sales Spline" = @SPLINE(Sales,2,,Jan:Jun);

Sales Jan Feb Mar Apr May Jun 645 675 712 756 890 912 Sales Spline 632.89 675.82 724.74 784.29 852.44 919.82
Hyperion
11-15
11
Notes
Splines are smooth piecewise polynomials that can be used to represent functions over large intervals, where it would be impractical to use a single approximating polynomial. rangeList must contain at least two values. If rangeList contains gaps in the data (for example: Jan, Feb, Mar, Jun, Jul), be sure to specify XmbrName (for example: 0,1,2,5,6) so that correct results are returned. The @SPLINE function skips #MISSING values in YmbrName and XmbrName; in the result, Essbase replaces the #MISSING values of YmbrName with the spline values. The @SPLINE function calculates a smoothing cubic spline for (n > 0). Setting the smoothness parameter (s) to 0 produces an interpolating spline, that is, a spline that fits the initial data exactly. Increasing s results in a smoother spline but a less exact approximation of the initial data. If you use a Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. When you use @SPLINE in a calculation script, use it within a FIX statement. Although using FIX is not required, it may improve calculation performance. When you use @SPLINE across a large range in a sparse dimension, you may need to increase the size of the calculator cache. View the algorithm for the smoothing spline.
11-16
Hyperion
11
@TREND
The @TREND() function calculates future values based on curve-fitting to historical values. The @TREND procedure considers a number of observations; constructs a mathematical model of the process based on these observations (that is, fits a curve); and predicts values for a future observation. You can use weights to assign credibility coefficients to particular observations, report errors of the curve fitting, choose the forecasting method to be used (for example, linear regression), and specify certain data filters.
Syntax
@TREND (Ylist, [Xlist], [weightList], [errorList], [XforecastList], YforecastList, method[, method parameters] [, Xfilter1 [, parameters]] [,XfilterN [, parameters]][, Yfilter1 [, parameters]] [, YfilterN [,parameters]])
Parameters
Ylist An expression list that contains known observations; for example, sales figures over a period of time. An expression list that contains underlying variable values. For example, for each sales figure in Ylist, Xlist may contain a value for associated time periods. If you do not specify Xlist, the default variable values are 1,2,3, and so on, up to the number of values in Ylist.
Xlist
weightList An expression list that contains weights for the data points in Ylist, for the linear regression method only. If values in weightList are #MISSING, the default is 1. Weights for methods other than linear regression are ignored. Negative weights are replaced with their absolute values. errorList Member list that represents the differences between the data points in Ylist and the data points on the line or curve (as specified for method).
XforecastList Expression list that contains the underlying variable values for which the forecasting is sought. If you do not specify XforecastList, the values are assumed to be as follows: {(last value in Xlist + 1), (last value in Xlist + 2), ...} up to (last value in Xlist + the number of values in YforecastList)
Hyperion
11-17
11
If you forecast consecutively from where Ylist stops, you do not need to specify XforecastList. If you want to move the forecasting period forward, specify the new period with XforecastList. YforecastList A member list into which the forecast values are placed. method A choice among: LR (linear regression) SES (single exponential smoothing) DES (double exponential smoothing) TES (triple exponential smoothing).
Method parameters must be numeric values, not member names. Method parameters vary depending on the method:
LR [,t] standard linear regression with possible weights assigned to each data point and an optional seasonal adjustment period [t], where [t] is the length of the period. In general, the weights are equal to 1 by default. You might want to increase the weight if the corresponding observation is important, or decrease the weight if the corresponding observation is an outlier or is unreliable. single exponential smoothing with parameter c (default c=0.2). This method uses its own weight system, using the single parameter c. Increasing this parameter gives more weight to early observations than to later ones. double exponential smoothing (Holt's method) with optional parameters c1, c2 (default c1=0.2, c2=0.3). This is a two-parameter weight system and a linear subsequent approximation scheme. The first parameter controls weight distribution for the intercept; the second parameter controls weight distribution for the slope of the line fit. triple exponential smoothing (Holt-Winters method) with optional parameters c1, c2, c3, T (default c1=0.2, c2=0.05, c3=0.1, T=1). This is a three-parameter weight system and a linear model with a multiplicative seasonal component.
SES [,c]
DES [[,c1],c2]
TES [[[[,T],c1],c2] ,c3]
11-18
Hyperion
11
Xfilter1... XfilterN Use one or more of the following filter methods to scale Xlist:
XLOG[,c] logarithmic change with shift c (x' = log(x+c)) (default c=1) exponential change with shift c (x' = exp(x+c)) (default c=0) power change with power c (x' = x^c) (default c=2)
XEXP[,c]
XPOW[,c]
Yfilter1... YfilterN Use one or more of the following filter methods to scale Ylist:
YLOG[,c] logarithmic change with shift c (y' = log(y+c)) (default c=1) exponential change with shift c (y' = exp(y+c)) (default c=0) power change with power c (y' = y^c) (default c=2)
YEXP[,c]
YPOW[,c]
Example
The following example is based on the Sample Basic database. It forecasts sales data for May through December, based on the trend of the sales from January through April. The method used is linear regression with no seasonal adjustment.
Sales(@TREND(Jan:Apr,,,,,May:Dec,LR););

Sales Jan Feb Mar Apr May Jun Jul Aug 2339 2298 2313 2332 2319 2318.4 2317.8 2317.2
Hyperion
11-19
11
Sep Oct Nov Dec
2316.6 2316 2315.4 2314.8
Notes
The @TREND function can be used only in calculation scripts, not in outline formulas. In a calculation script, you must associate the @TREND formula with a member. Ylist, Xlist, weightList, and errorList should contain the same number of values. XforecastList and YforecastList should contain the same number of values. The method and filter parameters must be numbers only; functions and member names are not allowed. @TREND ignores #MISSING values during calculation of the trend. When you use the LR method with seasonal adjustments or when you use the TES method, Essbase places strict requirements on the input data. With these methods, input data cannot contain #MISSING values. Also, if you specify Xlist, the data must be equidistant, with the interval (step) being a whole fraction of the period, T (for example, T/5, T/2). The XforecastList parameters should also contain multiples of the interval. If you use a Essbase member set function to generate a member list for this function, (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. For more information, see the online Technical Reference topic for the member set function you are using.
11-20
Hyperion
11
Exercise 11-1: Applying Forecasting Functions

In this exercise, you create a calc script that forecasts the budgeted sales for the four sales regions (East, West, South and Central) for 2000. The budgeted sales are predicted using a linear regression of actual sales for 1997, 1998 and 1999. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSTrend SS_Trend.xls
1) 2)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate the budgeted sales for the four sales regions (East, West, South and Central) for 2000. The budgeted sales are predicted using a linear regression of actual sales for 1997, 1998 and 1999. Save the new script as CSTrend. Open the SS_Trend spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The 2000 Budget values have not been calculated. From the Calc&Retrieve sheet, run the CSTrend calc script. Perform a retrieval and review the results in the 2000 Budget column. Do the Essbase results match your expectations? If not, modify the CSTrend calc script and rerun the calculation until you get the expected results. Close the spreadsheet.
3) 4) 5)
6) 7)
8)
Hyperion
11-21
11
Unit Summary
Forecasting functions manipulate data for the purpose of smoothing, interpolating, or calculating future values. Forecasting functions are often used in planning, analysis, and modeling applications.
11-22
Hyperion
12
Statistical Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of Statistical functions to generate member lists Practice using the Statistical functions in a series of incremental exercises
12
Generating Lists Using Statistical Functions

Statistical functions calculate advanced statistical values, such as correlation or variance. These functions are often used in sales and marketing applications.
Statistical Function Parameters

There are common parameters associated with the various Statistical functions:
dimName mbrName genLevNum Single dimension name specification. Specifies a single member. An integer value that defines the generation or level number from which the ancestor value is returned. A positive integer defines a generation number. A value of 0 or a negative integer defines a level number. Comma-delimited list of members, variable names, functions, and numeric expressions, all of which return numeric values. Used in conjunction with an expList parameter, this parameter indicates how missing and zero values are to be processed. SKIPNONE - Includes in the operation all values specified in expList regardless of their content SKIPMISSING - Ignores all #MISSING values SKIPZERO - Ignores all 0 values SKIPBOTH - Ignores all 0 and #MISSING values
expList, expList1, explist2
SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH
12-2
Hyperion
12
Summary of Statistical Functions

This table summarizes the Statistical Functions. Each function is also described, in detail, in this chapter.
Function @CORRELATION Returns The correlation coefficient between two parallel data sets. The number of data values in the specified data set. The median of the specified data set. The mode of the specified data set. The rank of the specified members or the specified value among the values in the specified data set. The standard deviation of a specified data set that represents a sample of a population. The standard deviation of a specified data set that represents a population. The standard deviation of the specified member across the specified data set that represents a sample of a population. The statistical variance of a specified data set that represents a sample of a population. The statistical variance of a specified data set that represents a population.
@COUNT @MEDIAN @MODE @RANK
@STDEV
@STDEVP
@STDEVRANGE
@VARIANCE
@VARIANCEP
Hyperion
12-3
12
@CORRELATION
The @CORRELATION() function returns the correlation coefficient between two parallel data sets (expList1 and expList2). The correlation coefficient determines the relationship between two data sets.
Syntax
@CORRELATION (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList1, expList2)
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Sales Correl. The calculation script calculates the correlation coefficient for a set of members (Sales for the children of Qtr1 and Qtr2). Because the calculation script fixes on Jun, the results are placed in Sales Correl->Jun. This example uses the @RANGE function to generate expList1 and expList2:
FIX(June) "Sales Correl"=@CORRELATION(SKIPNONE, @RANGE(Sales,@CHILDREN(Qtr1)),@RANGE(Sales,@CHILDREN(Qtr2))) ; ENDFIX

Sales Jan Feb Mar Apr May Jun Sales Correl 678 645 675 712 756 890 #MI #MI #MI #MI #MI 0.200368468
12-4
Hyperion
12
Notes
The expList1 and expList2 parameters must have the same number of data points. If expList1 and expList2 have different numbers of data points, @CORRELATION returns #MISSING. The @CORRELATION function returns #MISSING if expList1 and expList2 (1) are empty, (2) contain only #MISSING values, or (3) have a standard deviation of 0 (all values are constant). The @CORRELATION function treats #MISSING values as zero (0) values, unless SKIPMISSING or SKIPBOTH is specified. If a value in expList1 is #MISSING, and SKIPMISSING is specified, the value's corresponding value in expList2 is treated as #MISSING. (That is, both values are deleted before calculation.) SKIPZERO and SKIPBOTH work similarly. The @CORRELATION function returns values from -1 to 1. If you use a Essbase member set function to generate a member list for this function (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list.
Hyperion
12-5
12
@COUNT
The @COUNT() function returns the number of data values in the specified data set.
Syntax
@COUNT (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
Example The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Prod Count. This example calculates the count of all products for which a data value exists and uses the @RANGE function to generate expList:
FIX(Product) "Prod Count" = @COUNT(SKIPMISSING,@RANGE(Sales,@CHILDREN(Product))); ENDFIX
This example produces the following report. Since SKIPMISSING is specified in the calculation script, the #MI values are skipped during the product count.
Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product Prod Count Product 678 #MI 663 587 #MI 2479 3 Budget 640 530 510 620 #MI 2300 4
Notes
The @COUNT function always returns an integer greater than or equal to 0.
12-6
Hyperion
12
@MEDIAN
The @MEDIAN() function returns the median (the middle number) of the specified data set. Half the numbers in the data set are larger than the median, and half are smaller.
Syntax
@MEDIAN (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Median. This example calculates the median sales values for all products and uses the @RANGE function to generate expList:
FIX (Product) Median = @MEDIAN(SKIPBOTH,@RANGE(Sales,@CHILDREN(Product))); ENDFIX

Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product Median Product 678 #MI 663 587 #MI 2479 663 Budget 640 530 510 620 #MI 2300 575
Because SKIPBOTH is specified in the calculation script, the #MI values are skipped. In the Budget scenario, the remaining four products create an even-numbered data set. to calculate Median->Product->Budget, the two middle numbers in the set (530 and 620) are averaged to create the median (575).
Hyperion
12-7
12
Notes
If the member you are calculating and expList are not in the same dimension, use the @RANGE function to cross the member with the list of members (for example, to cross Sales with the children of 100). @MEDIAN sorts expList in ascending order before calculating the median. When expList contains an even number of values, the @MEDIAN function calculates the average of the two middle numbers. @MEDIAN treats #MISSING values as 0 unless SKIPMISSING or SKIPBOTH is specified. When you use @MEDIAN in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MEDIAN across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
12-8
Hyperion
12
@MODE
The @MODE() function returns the mode (the most frequently occurring value) in the specified data set.
Syntax
@MODE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
The following example calculates the mode of the units sold for the Central region and uses the @RANGE function to generate expList:
FIX (Actual, Central) "Mode" = @MODE(SKIPMISSING,@RANGE(Units,@CHILDREN(Central))); ENDFIX

Actual Units Illinois Ohio Wisconsin Missouri Iowa Colorado Central Mode Central 3 2 3 #MI 0 6 14 3
Notes
When two or more values in expList occur at the same frequency, Essbase sorts the list of values in ascending order and chooses the lowest value that occurs with the most frequency as the mode. For example, if expList contains [2,1,2,2,2,3,3,3,3], Essbase sorts the list as [1,2,2,2,2,3,3,3,3] and chooses the value [2] as the mode.
Hyperion
12-9
12
If expList contains no duplicate values, the @MODE function returns the smallest value in the list as the mode. For example, if expList contains [2,4,7,10,14], @MODE returns 2 as the mode. If #MISSING is the mode of expList, @MODE returns #MISSING unless SKIPMISSING or SKIPBOTH is specified. If you specify SKIPMISSING or SKIPBOTH and all values in expList are #MISSING, @MODE returns #MISSING. If you specify SKIPZERO or SKIPBOTH and all values in expList are 0, @MODE returns #MISSING. When you use @MODE in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance. When you use @MODE across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
12-10
Hyperion
12
@RANK
The @RANK() function returns the rank of the specified members or the specified value among the values in the specified data set. The rank of a value is equivalent to its position (its rank) in the sorted data set.
Syntax
@RANK (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, value, expList) value - either the member or member combination for which the rank is calculated, or a constant value for which the rank is calculated.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, Sales Rank. Essbase ranks the sales values for a set of products:
"Sales Rank" = @RANK(SKIPBOTH,Sales, @RANGE(Sales,@LEVMBRS(Product,1)));
This example produces the following report. Since SKIPBOTH is specified in the formula, the #MI value for Sales->Diet Drinks is not included in the ranked list:
Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks 678 551 663 587 #MI Sales Rank 1 4 2 3 #MI
Notes
After SKIP processing, the @RANK function sorts the data set in descending order (for example, 15341, 9650, 6556, 4255, 1989). The rank of a value identifies its position in the sorted data set (for example, 15341 is ranked 1; 1989 is ranked 5) An input value of #MISSING returns #MISSING. #MISSING is also returned if, after SKIP processing, there are no values to compare. Hyperion 12-11
12
The @RANK function assigns the same rank to duplicate values; however, the presence of duplicate values affects the rank numbers. For example, if a list of values contains [2,2,4,5], Essbase first sorts the list [5,4,2,2] and then ranks: [5] has a rank of 1, [4] has a rank of 2, and [2] has a rank of 3. In this case, no value has a rank of 4. If value is a constant value and that value is not included in expList, Essbase inserts the constant value in the list and then ranks it accordingly. For example, if a list of values contains [2,4,6,13], and you want to rank a value of [3] in this list, Essbase: Sorts the list in descending order [13,6,4,2] Inserts [3] in the list [13,6,4,3,2] Ranks [3] in the list: in this case, [3] has a rank of 4.
When you use @RANK in a calculation script, use it within a FIX statement. Although using FIX is not required, it may improve calculation performance. When you use @RANK across a large range in a sparse dimension, you may need to increase the size of the calculator cache.
12-12
Hyperion
12
@STDEV
The @STDEV() function calculates the standard deviation of the specified data set. The calculation assumes that the data set represents a sample of a population. Standard deviation is a measure of how widely values are dispersed from their mean (average).
Syntax
@STDEV (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, StdDev. This example calculates the standard deviation (based on a sample of a population) of the sales values for all products.
FIX (Product) "StdDev" = @STDEV(SKIPBOTH,@RANGE(Sales,@CHILDREN(Product))); ENDFIX

Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product StdDev Product 678 551 663 587 #MI 2479 60.73 Budget 640 530 510 620 #MI 2300 64.55
Hyperion
12-13
12
Notes
The @STDEV function replaces the @STDDEV function. The only difference between the functions is the SKIP parameter in the new @STDEV function. Although the old @STDDEV function is supported for migration purposes, you can no longer select it in the Calc Script Editor or Formula Editor. @STDEV is the square root of the variance calculated for the same data set using @VARIANCE. @STDEV assumes that expList represents a sample of a population. If you want expList to represent the entire population, use @STDEVP. For large samples, the functions return similar values. @STDEV is calculated using the "nonbiased" or "n-1" method.
12-14
Hyperion
12
@STDEVP
The @STDEVP() function calculates the standard deviation of the specified data set. The calculation assumes that the data set represents the population. Standard deviation is a measure of how widely values are dispersed from their mean (average).
Syntax
@STDEVP (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, StdDevP. This example calculates the standard deviation (based on the entire population) of the sales values for all products.
FIX (Product) "StdDevP" = @STDEVP(SKIPBOTH,@RANGE(Sales,@CHILDREN(Product))); ENDFIX

Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product StdDevP Product 678 551 663 587 #MI 2479 52.59 Budget 640 530 510 620 #MI 2300 55.90
Notes
@STDEVP assumes that expList represents the entire population. If you want expList to represent a sample of a population, use @STDEV. For large samples, the functions return similar values.
Hyperion
12-15
12
@STDEVP is the square root of the variance calculated for the same data set using @VARIANCEP. @STDEVP is calculated using the "biased" or "n" method.
12-16
Hyperion
12
@STDEVRANGE
The @STDEVRANGE() function calculates the standard deviation of all values of the specified member across the specified data set. The calculation assumes that the data set represents a sample of a population. Standard deviation is a measure of how widely values are dispersed from their mean (average).
Syntax
@STDEVRANGE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [, rangeList]) mbrName - Any valid single member name or member combination, or a function that returns a single member or member combination. rangeList - A valid member name, a comma-delimited list of member names, member set functions, and range functions from the same dimension. If rangeList is not specified, Essbase uses the level 0 members from the dimension tagged as Time.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, StdDev. This example calculates the standard deviation (based on a sample of a population) of the sales values for all products.
FIX (Product) "StdDev" = @STDEVRANGE(SKIPBOTH,Sales,@CHILDREN(Product)); ENDFIX

Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product StdDev Product 678 551 663 587 #MI 2479 60.73 Budget 640 530 510 620 #MI 2300 64.55
Hyperion
12-17
12
Notes
The @STDEVRANGE function replaces the @STDDEVRANGE function. The only difference between the functions is the SKIP parameter in the new @STDEVRANGE function. Although the old @STDDEVRANGE function is supported for migration purposes, you can no longer select it in the Calc Script Editor or Formula Editor. The specified mbrName is crossed with rangeList to obtain the sample across which the standard deviation is calculated. @STDEVRANGE is calculated using the "unbiased" or "n-1" method.
12-18
Hyperion
12
@VARIANCE
The @VARIANCE() function calculates the statistical variance of the specified data set. The calculation assumes that the data set represents a sample of a population. Variance is a measure of the dispersion of a set of data points around their mean (average) value.
Syntax
@VARIANCE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, SalesVar. This example uses the @RANGE function to generate expList, and calculates the variance of the sales values for a product family.
FIX (Product) "SalesVar" = @VARIANCE(SKIPBOTH,@RANGE(Sales,@CHILDREN(Product))); ENDFIX

Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product SalesVar Product 678 551 663 587 #MI 2479 3687.58 Budget 640 530 510 620 #MI 2300 4166.67
Notes
@VARIANCE is different from @VAR, which calculates the variance (difference) between two members.
Hyperion
12-19
12
@VARIANCE is the square of the standard deviation calculated for the same data set using @STDEV. @VARIANCE assumes that expList represents a sample of the population. If you want expList to represent the entire population, use @VARIANCEP. @VARIANCE is calculated with the "unbiased" or "n-1" method.
12-20
Hyperion
12
@VARIANCEP
The @VARIANCEP() function calculates the statistical variance of the specified data set. The calculation is based upon the entire population. Variance is a measure of the dispersion of a set of data points around their mean (average) value.
Syntax
@VARIANCEP (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)
Example
Example The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, SalesVar. This example uses the @RANGE function to generate expList and calculates the variance of the sales values for a product family.
FIX (Product) "SalesVar" = @VARIANCEP(SKIPBOTH,@RANGE(Sales,@CHILDREN(Product))); ENDFIX

Actual Sales Colas Root Beer Cream Soda Fruit Soda Diet Drinks Product SalesVar Product 678 551 663 587 #MI 2479 2765.69 Budget 640 530 510 620 #MI 2300 3125.00
Notes
@VARIANCEP is different from @VARPER, which calculates the percent variance (difference) between two members.
Hyperion
12-21
12
@VARIANCEP is the square of the standard deviation calculated for the same data set using @STDEVP. @VARIANCEP assumes that expList represents the entire population. If you want expList to represent a sample of the population, use @VARIANCE. @VARIANCEP is calculated using the "biased" or "n" method.
12-22
Hyperion
12
Exercise 12-1: Applying Statistical Functions

In this exercise, you create a calc script to calculate the rank for the sales of each state. Sales have been entered at the city level. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSRank SS_Rank.xls
1)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate the rank for the sales of each state. Sales have been entered at the city level. Save the new script as CSRank. Open the SS_Rank spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The Sales and Sales Rank for the states values have not been calculated. From the Calc&Retrieve sheet, run the CSRank calc script. Perform a retrieval. Do the Sales Ranks for the states appear correct? If not, modify the CSRank calc script and rerun the calculation until you get the expected results. Sort the data in descending Sales order, and determine if the Sales Ranks match this order. Close the spreadsheet.
2)
3) 4)
5) 6) 7)
8)
Hyperion
12-23
12
Unit Summary
Statistical functions calculate advanced statistical values, such as correlation or variance. These functions are often used in sales and marketing applications.
12-24
Hyperion
13
Date and Time Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of Date and Time functions to generate member lists Practice using the Date and Time functions in a series of incremental exercises
13
Using Date and Time Functions

The date function converts date strings to numbers that can be used in calculation formulas. There is one Date and Time function, @TODATE, which converts date strings to numbers.
13-2
Hyperion
13
@TODATE
The @TODATE() function converts date strings to numbers that can be used in calculation formulas. @TODATE converts date strings into the number of seconds elapsed since midnight, January 1, 1970.
Syntax
@TODATE (formatString, dateString) formatString - The format of the date string, either "mm-dd-yyyy" or "dd-mm-yyyy". dateString - The date string.
Example
The following example is based on the Sample Basic database. Assume that the Measures dimension contains an additional member, New Marketing.
New Marketing (IF (@ATTRIBUTEVAL("Intro Date") > @TODATE("mm-dd-yyyy","06-30-1996")) Marketing * .9; ENDIF;);
This formula searches for members with an Intro Date attribute member that is later than 6-30-96 and, for those members, calculates New Marketing as Marketing reduced by 10 percent. In order to process the formula, Essbase converts the date strings to numbers before it calculates. This example produces the following results:
Marketing New Marketing 9
Intro Date_12-101996
200-30
10
200-40 Intro Date_10-011996 400-10
10 10
9 9
400-20
10
Hyperion
13-3
13
Intro Date_07-261996 Intro Date_06-261996
200-20
10
300-10
10
300-20 300-30 Intro Date_04-011996 100-20
10 10 10
9 9 10
100-30 Intro Date_03-251996 Intro Date_09-271995 100-10
10 10
10 10
200-10
10
10
Notes
If you specify a date string that is earlier than January 1, 1970, @TODATE returns an error. The latest date string supported by @TODATE is January 1, 2038 (01-012038).
13-4
Hyperion
13
Exercise 13-1: Applying the Date & Time Function

In this exercise, you create a calc script that calculates the budgeted marketing expense for New York in December 2000. The budgeted marketing expenses are calculated in comparison to the actual marketing expenses for December 1999. For products introduced on or after January 1, 1997, the budgeted marketing expense will be an increase of 10%. For products introduced prior to July 6, 1996, the budgeted marketing expense will be a decrease of 10%. For all other products, the budgeted marketing expense is equal to the 1999 actual marketing expense. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSTodate SS_ToDate.xls
1)
From Essbase Application Manager, clear all data from the HLandS2 database. Create a calc script to calculate the budgeted marketing expense for New York in December 2000. The budgeted marketing expenses are calculated in comparison to the actual marketing expenses for December 1999. For products introduced on or after January 1, 1997, the budgeted marketing expense will be an increase of 10%. For products introduced prior to July 6, 1996, the budgeted marketing expense will be a decrease of 10%. For all other products, the budgeted marketing expense is equal to the 1999 actual marketing expense. Save the new script as CSTodate. Open the SS_ToDate spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database. Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The Budget 2000 Marketing values are not available. From the Calc&Retrieve sheet, run the CSTodate calc script. Perform a retrieval. Do the 2000 Budget values match expected results? If not, modify the CSTodate calc script and rerun the calculation until you get the expected results. Close the spreadsheet.
2)
3)
4) 5) 6)
7)
Hyperion
13-5
13
13-6
Hyperion
14
Miscellaneous Functions
Chapter Objectives
By the end of this chapter, you will be able to: Explain the purpose and use of Miscellaneous functions to generate member lists Practice using the Miscellaneous functions in a series of incremental exercises
14
Using Miscellaneous Functions

Essbase includes two types of miscellaneous functions. Using @CALCMODE, you can specifies whether Essbase calculates a formula in cell mode or block mode and whether Essbase calculates a formula bottom-up or top-down. @CONCATENATE and @SUBSTRING enable manipulation of character strings.
Summary of Miscellaneous Functions

This table summarizes the Miscellaneous Functions. Each function is also described, in detail, in this chapter.
Function @CALCMODE @CONCATENATE Enables the choice of an execution mode of a formula. Returns a character string that is the result of appending one character string to another character string. Passes the enclosed string or member name as a string to another function. Returns the requested substring of characters from an existing source string.
@NAME
@SUBSTRING
14-2
Hyperion
14
@CALCMODE
The @CALCMODE function enables the choice of an execution mode of a formula.
Syntax
@CALCMODE (CELL|BLOCK|TOPDOWN|BOTTOMUP) CELL - Turns on the cell calculation mode BLOCK - Turns on the block calculation mode TOPDOWN - Turns on the top-down calculation mode BOTTOMUP - Turns on the bottom-up calculation mode
Notes
@CALCMODE can control two types of modes: Whether a formula is calculated in block calculation or cell calculation mode when calculating formulas that contain certain functions (in particular the @ISMBR function) Whether a formula assigned to a sparse member is calculated in bottom-up or top-down mode
Hyperion
H H
Cell and block modes are mutually exclusive. Top-down and bottom-up modes are mutually exclusive. Within one @CALCMODE specification, you can specify only one option. To specify both types of modes, perform the instruction twice; for example:
@CALCMODE (CELL) @CALCMODE (TOPDOWN)
You can also set CALCMODE BLOCK or CALCMODE BOTTOMUP at the server, application, or database level using the configuration setting CALCMODE.
14-3
14
Description Understanding Block Calculation and Cell Calculation Modes

Using block calculation mode, Essbase groups the cells within a block and simultaneously calculates the cells in each group. Block calculation mode is fast, but you must carefully consider data dependencies within the block to ensure that the resulting data is accurate. Using cell calculation mode, Essbase calculates each cell sequentially, following the calculation order, which is based on the order of the dense dimensions in the outline.
Understanding Bottom-Up and Top-Down Calculation Modes

Essbase uses one of two calculation methods to do a full calculation of a database outline: bottom-up calculation (the default) or top-down calculation. If the database outline contains a complex member formula, Essbase performs a top-down calculation for that member. When a formula is compiled, if the formula is to be calculated top-down, Essbase logs a message in the application log file. For a bottom-up calculation, Essbase determines which existing data blocks need to be calculated before it calculates the database. Essbase then calculates only the blocks that need to be calculated during the full database calculation. The calculation begins with the lowest existing block number and works up through each subsequent block until the last existing block is reached. In contrast, a top-down calculation calculates the formula on all potential data blocks with the member. A top-down calculation may be less efficient than a bottom-up calculation because more blocks may be calculated than is necessary. Although a top-down calculation is less efficient than a bottom-up calculation, in some cases top-down calculations are necessary to ensure that calculation results are correct. See Example 4.
Knowing When Essbase uses Cell or Block Mode and Topdown or Bottom-up Mode
When Essbase compiles a formula, it prints a message in the application log file explaining the mode of execution for the formula similar to the following message:
Formula on member Profit % will be executed in CELL and TOPDOWN mode.
14-4
Hyperion
14
When Essbase determines that the formula will be executed in block and bottom-up mode, no message is written in the application log file. By default, for a simple formula such as A = B + C, Essbase does a bottomup calculation. A is calculated only if B or C exists in the database. The dependency of the formula on B and C is known before the calculation is started. For a complex formula such as A = B->D + C->D, Essbase performs a topdown calculation because every possible combination of A must be examined to see whether B->D or C->D exists. By default, Essbase uses cell calculation mode for formulas containing: @ANCEST @CURRMBR @ISMBR on a dense member @MDANCESTVAL @MDPARENTVAL @MDSHIFT @NEXT @PARENT @PARENTVAL @PRIOR @SANCESTVAL @SPARENTVAL @SHIFT
Hyperion
H H H H H H H H H H H H H
For all other formulas, Essbase uses block calculation mode by default. You can also set CALCMODE BLOCK or CALCMODE BOTTOMUP at the server, application, or database level using the configuration setting CALCMODE.
Understanding Data Dependency Issues With Block Calculation Mode

Data dependency occurs if the accurate calculation of one or more members depends on another member or other on members being calculated previously. Most data dependency issues with block calculation mode occur when a formula contains IF ELSE or IF ELSEIF conditions. However, data dependencies can occur in other formulas; for example, when using the @PRIOR function.
14-5
14
Data Dependency Issues With IF ELSE and IF ELSEIF

When Essbase uses block calculation mode to calculate a formula that contains IF ELSE or IF ELSEIF conditions, it separates the members being calculated into two groups. The first group contains the members that satisfy the IF condition. The second group contains the members that satisfy the ELSE or ELSEIF conditions. Essbase simultaneously calculates the members in the first group before simultaneously calculating the members in the second group. See Example 1. If a formula contains data dependencies, ensure that the following conditions are met: Members on which the accurate calculation of other members depends are in the first group. Dependent members are in the second group.
14-6
H H
If an IF condition has multiple ELSEIF conditions, Essbase evaluates each ELSEIF condition, placing the members that satisfy the ELSEIF condition in the first group and the members that satisfy subsequent ELSEIF or ELSE conditions in the second group. See Example 2.
Understanding Other Data Dependency Issues

Data dependencies can occur in formulas that do not contain IF ELSE conditions. See Example 3 for an example of data dependency in a formula containing the @PRIOR function.
Hyperion
14
Examples
Example 1, Example 2, and Example 3 illustrate use of the BLOCK and CELL options of the @CALCMODE function. Example 4 illustrates use of the BOTTOMUP and TOPDOWN options. Example 1 Consider a database with two dense dimensions, Time and Accounts. The following formula is placed on the Budget Sales member of the Accounts dimension. Because this is a formula containing @ISMBR applied to a dense member (Budget Sales), by default Essbase uses cell calculation mode. You can use the @CALCMODE(BLOCK) function to specify block calculation mode for this formula.
"Budget Sales" ( @CALCMODE(BLOCK); IF(@ISMBR(Feb)) "Budget Sales"=100; ELSE "Budget Sales"=Feb+10; ENDIF;)
The following table shows the Budget Sales values before execution and compares the values that would be generated by running the calc script excluding and including the @Calcmode command:
Before Execution Jan Feb Mar 10 20 30 Without @Calcmode 30 100 110 With @Calcmode 110 100 110
Without @Calcmode(Block) - The time blocks are calculated sequentially (i.e., Jan, Feb, Mar). Jan is assigned the pre-existing value for Feb (20) plus ten. Feb is assigned the new value (100). Mar is assigned the new value for Feb (100) plus ten. With @Calcmode(Block) - Essbase calculates the members satisfying the IF condition first. In this example, Feb is the only member that satisfies the IF condition. After calculating Feb, Essbase calculates the members Jan and Mar to have the new value for Feb (100) plus ten.
Hyperion
14-7
14
Miscellaneous Functions Example 2
Now consider the same database as in Example 1, but we place the following formula on the Budget Sales member of the Accounts dimension. As in Example 1, because this is a formula containing @ISMBR applied to a dense dimension member (Budget Sales), by default Essbase uses cell calculation mode. You can use the @CALCMODE(BLOCK) function to specify block calculation mode for this formula.
"Budget Sales" ( @CALCMODE(BLOCK); IF(@ISMBR(Mar)) "Budget Sales"=Feb+20; ELSEIF(@ISMBR(Jan)) "Budget Sales"=Feb+10; ELSE "Budget Sales"=100; ENDIF;)
The following table shows the Budget Sales values before execution and compares the values that would be generated by running the calc script excluding and including the @Calcmode command:
Before Execution Jan Feb Mar 10 20 30 Without @Calcmode 30 100 120 With @Calcmode 30 100 40
Without @Calcmode(Block) - The time blocks are calculated sequentially (i.e., Jan, Feb, Mar). Jan is assigned the pre-existing value for Feb (20) plus ten. Feb is assigned the new value (100). Mar is assigned the new value for Feb (100) plus twenty. With @Calcmode(Block) - Essbase calculates the members satisfying the IF condition first, followed by the members satisfying the ELSEIF condition, followed by the members satisfying the ELSE condition. In this example, Hyperion Essbase calculates the members in the following order: Mar, Jan, Feb.
14-8
Hyperion
Hyperion Essbase Calc Scripts Example 3
14
Consider the following calc script to calculate the members Opening Inventory and Ending Inventory using the @PRIOR function.
Opening Inventory( @CALCMODE(CELL) "Opening Inventory"=@PRIOR("Ending Inventory")+10; "Ending Inventory"="Opening Inventory";)
The following table shows the inventory values before execution and compares the values that would be generated by running the calc script excluding and including the @Calcmode command:
Before Execution Opening Jan Feb Mar #MI #MI #MI Ending #MI #MI #MI Without @Calcmode Opening 10 10 10 Ending 10 10 10 With @Calcmode Opening 10 20 30 Ending 10 20 30
Without @CALCMODE - A block calculation mode is used, Essbase calculates the members simultaneously, taking the previous month's Ending Inventory #MISSING value as 0 for all member combinations and adding 10. With @CALCMODE - Values for Jan is calculated first, then Feb values are calculated using ending value for Jan, and finally Mar is calculated.
Hyperion
14-9
14
Miscellaneous Functions Example 4
Depending on the formula and the structure of the data, calculating a formula top-down versus bottom-up may involve two issues: performance (reflecting the number of calculations that must be made) and accuracy. This example compares calculation results to illustrate both of these issues. The following formula is calculated bottom-up.
@CALCMODE(BOTTOMUP); Budget=Actual*1.10;
This bottom-up calculation calculates two values, based on existing combinations of Budget, with the following results:
Before Execution Actual Jan Feb #MI 200 Budget 50 #MI After Execution Actual #MI 200 Budget #MI #MI #MISSING*1.10 No calculation is performed 400*1.10 Comment
Mar
400
450
400
440
The following formula is calculated top-down.

@CALCMODE(TOPDOWN); Budget=Actual*1.10;
This top-down calculation calculates three values, considering all potential combinations of Budget, with the following results:
Before Execution Actual Jan Feb Mar #MI 200 400 Budget 50 #MI 450 After Execution Actual #MI 200 400 Budget #MI 220 440 #MISSING*1.10 200*1.10 400*1.10 Comment
14-10
Hyperion
14
@CONCATENATE
The @CONCATENATE function returns a character string that is the result of appending one character string to another character string.
Syntax
@CONCATENATE (String1, String2) String1 - A string or member name, or a function that returns a string or single member name String2 - A string or member name, or a function that returns a string or single member name
Examples
The following examples are based on the Sample Basic database: Example 1 The following function statement puts the string Product in front of the name of the member currently being processed in the Measures dimension; for example, if the current member being calculated is 100-10, the result is Product100-10:
@CONCATENATE("Product",@CURRMBR(Product))
Example 2 To concatenate more than two strings, you can nest multiple instances of the @CONCATENATE function. The following function statement returns string values starting with the current member of the Year dimension, followed by an underscore, followed by the current member of the Measures dimension; for example, if the current members being calculated are Qtr1 and Sales, the result is Qtr1_Sales:
@CONCATENATE(@CURRMBR(Year), @CONCATENATE("_",@CURRMBR(Measures)))
Hyperion
14-11
14
@NAME
The @NAME() function passes the enclosed string or member name as a string to another function.
Syntax
@NAME (mbrName) mbrName - Any valid single member name, dimension name, or a string.
Example
The following example is based on the Sample Basic database. A user defined function is used to retrieving the price from the table below. The user defined function (J_GetPrice) takes two string parameters time and product name to return the price for each product.
MonthName Jan Feb Mar Jan Feb Mar ProductId 100-10 100-10 100-10 100-20 100-20 100-20 Price 1.90 1.95 1.98 1.95 2.00 2.05
Price = @J_GetPrice(@NAME(@CURRMBR(Product)),@NAME(@CURRMBR(Year)));
The following report illustrates the above example:

Jan 100-10 100-20 1.90 1.95 Feb 1.95 2.00 Mar 1.98 2.05
Notes
Essbase does not support strings in functions. It treats strings as values or array of values. The @NAME function processes strings.
14-12
Hyperion
14
@SUBSTRING
The @SUBSTRING function returns the requested string of characters from an existing source string. The source string can be a text string or a member name, or it can result from a specified function that returns a text string or a single member name.
Syntax
@SUBSTRING (String, StartPosition [, EndPosition]) String - A string or member name, or a function that returns a string or a single member name StartPosition - Beginning character position within String to include in the substring. An integer greater than or equal to 0, where 0 corresponds to the first character in String, 1 corresponds to the second character, and so on. EndPosition - The first position past the last character to be included in the substring. An integer greater than or equal to 0, where 0 corresponds to the first character in String, 1 corresponds to the second character, and so on. If EndPosition is not specified or is less than StartPosition, Essbase returns all remaining characters from the source string.
Example
The following examples are based on the Sample Basic database:
Statement @SUBSTRING ("100-10",1) @SUBSTRING ("200-21",0,2) @SUBSTRING ("200-21",3,6) @SUBSTRING (@PARENT(Jan),3) Result "00-10" "20" 0-2 1
(The parent of Jan is Qtr1.)
Hyperion
14-13
14
14-14
Hyperion
15
Tips, Tricks and Techniques
Chapter Objectives
By the end of this chapter, you will be able to: Explore calc script options that improve efficiency and ensure accurate calculation results List data management tools used in calc scripts Describe the process of preparing for and creating calc scripts Determine whether IF or FIX is the most efficient way to isolate data in a calc script Illustrate how to use data management commands to prepare budget data Explain how to allocate high-level data to lower levels Demonstrate how to use cross-dimensional operators to perform market-share analysis
15
Calc Script Design Considerations

As you create calc scripts, you find that there are many ways to create similar results, and that some ways are more efficient than others. Keep in mind that order of calculation is determined by the outline unless you override that order.
IF or FIX
As a general rule, use FIX instead of multiple IF statements on sparse blocks. FIX limits the number of blocks brought into memory, and IF tests every block. However, you may wish to experiment with various solutions in your environment to find the combination that works best for you.
Dense calculations before sparse calculations

After a database has been loaded, calculate dense dimensions before sparse dimensions. This minimizes the number of blocks processed on dense calculations, and does not cause the creation of additional sparse blocks. Calculating or aggregating on a sparse dimension exponentially increases the number of blocks.
Two-pass calculations
Use of two-pass calculations ensures correct calculation of higher level blocks. It also, under many circumstances, increases the number of database passes.
Intelligent Calcs
Intelligent Calcs decrease the number of times a block is calculated. If a block has been recently calculated, a flag is set in the index node signifying that the block is clean. As additional calculations are performed, blocks marked clean are not calculated.
Blocks on equations
When you assign a constant to a member on a sparse dimension, Essbase automatically creates a data block for every combination of sparse dimension members containing that member. Because you could inadvertently create thousands of data blocks using this method, use the FIX command to ensure that Essbase creates only the required data blocks. For example:
Fix(Colas,Misc,Actual) California = 120; Endfix
15-2
Hyperion
15
Approaching Calc Scripts Solutions

Although it is tempting to jump into coding a calc script by writing individual calculations, you save yourself time and unexpected results if you use the following method to develop calc scripts.
Business problem
The most important part of a calc script is the part that does not show up in the application: the business problem. Ideally, you receive a written description of the problem to be solved. After you review the descriptionwhich should be clear and specific, review the problem with the analyst who requested the calc script to make sure there are no ambiguities.
Affected data
The two types of affected data are: data that is the subject of the calc script itself and data that is contextually dependent on the subject data. For example, forecast data is dependent on actual sales data. If actual sales increase by 10%, should forecast sales for the same period be restated?
Rollup considerations
At what level in the outline do calculations occur? Is it necessary to roll up changes to higher levels? Is it necessary to push results down to lower levels? In addition to performing the basic calculations called for by the business problem, you may need to perform data management and rollup functions to ensure that the numbers work together.
Individual calculations
As a general rule, calc scripts with fewer calculations run more efficiently. However, you may find it easier to break complex calculations into individual calculations for testing purposes. When you are sure that the individual calculations work correctly, you can combine them and test for similar results.
Communication
As you develop a calc script, you should maintain contact with the analyst who requested it. Often requirements are ambiguous, and you do not discover problems until you are further along in the process. The more contact you have with the analyst, the less likely it is that you be required to redo your work.
Hyperion
15-3
15
IF vs FIX
One consideration for isolating data is the choice between IF and FIX. In many situations, either structure could be used by using a Boolean function in a IF-structure or its corresponding Member Set function in the FIX-structure, for example:
FIX(New York) ... ENDFIX
is often equivalent to:

IF(@ISMBR(New York)) ... ENDIF
Boolean functions and the likely corresponding Member Set functions are:
Boolean Function @ISANCEST @ISCHILD @ISDESC @ISGEN @ISIANCEST @ISICHILD @ISIDESC @ISIPARENT @ISISIBLING @ISLEV @ISPARENT @ISSAMEGEN @ISSAMELEV @ISSIBLING @ISUDA Member Set Function @ANCESTORS @CHILDREN @DESCENDANTS @GENMBRS @IANCESTORS @ICHILDREN @IDESCENDANTS @IALLANCESTORS @ISIBLINGS @LEVMBRS @PARENT @GENMBRS @LEVMBRS @SIBLINGS @UDA
As a general rule, use FIX instead of multiple IF statements on sparse blocks. FIX limits the number of blocks brought into memory, and IF tests every block. However, you may wish to experiment with various solutions in your environment to find the combination that works best for you.
15-4
Hyperion
15
Exercise 15-1: Isolating Data Using IF or FIX

In the scenario, you must perform two calculations for the Eastern region. Although IF and FIX provide the same results, you need to consider density and efficiency when you choose the appropriate command.
Business problem
Make commission adjustments for the Eastern region, increasing all commissions for the 1999 actuals by 25%. You must derive 2000 budget data for commissions. The budgeted amount should reflect the original commissions for the current year, not the increased commissions.
Affected data
All 1999 actual data for commissions in the Eastern region is affected. The 2000 budget is derived from unadjusted commissions for 1999 actuals.
There are no rollup considerations, because data is at the lowest level.
Data for commissions should be copied from 1999 actuals to the 2000 budget. Then actual commissions should be increased for the Eastern region by 25%. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSIf_Fix SS_If_Fix.xls
1) 2) 3)
Open and review the data in spreadsheet SS_If_Fix.xls. From Essbase Application Manager, clear all data from the HLandS2 database. Review the outline for the HLandS2 database. Notice which members are affected and whether the dimensions containing those members are dense or sparse.
Hyperion
15-5
15
Tips, Tricks and Techniques 4)
Create a calc script using the Calc Script Editor. When writing the calc script, consider whether to use IF or FIX on the specific data that you are calculating. Save the calc script as CSIF_Fix. In Microsoft Excel, connect to the Essbase server and select the Calc:HLandS2 database. Lock and send the data in the Lock&Send sheet to the HLandS2 database. From the Calc&Retrieve sheet, run the CSIF_Fix calc script. Perform a retrieval and notice the calculation results. The retrieval may take a few minutes. Ensure that all calculation requirements are met. If all calculation requirements are not met, revise the calc script and rerun the calculation. Close the SS_If_Fix spreadsheet.
5) 6)
7)
8)
9)
15-6
Hyperion
15
Exercise 15-1b: Isolating Data Using IF or FIX

Time permitting, redo the calc script for Exercise 15-1, but replace IF statements with equivalent FIX statements, and the FIX statements with equivalent IF statements. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS2 CSIf_Fix CSIfix2 SS_If_Fix.xls
1) 2) 3)
From Essbase Application Manager, review the event log to determine the length of time required to run the calc script CSIf_Fix. Clear all data from the HLandS2 database. Modify the calc script CSIf_Fix using the Calc Script Editor. Replace IF statements with equivalent FIX statements, and the FIX statements with equivalent IF statements. Save the calc script as CSIfix2. In Microsoft Excel open spreadsheet SS_If_Fix.xls, and connect to the Essbase server and select the Calc:HLandS2 database. Lock and send the data in the Lock&Send sheet to the HLandS2 database. From the Calc&Retrieve sheet, run the CSIfix2 calc script. Perform a retrieval and notice the calculation results. The retrieval may take a few minutes. Ensure that all calculation requirements are met. If all calculation requirements are not met, revise the calc script and rerun the calculation. Close the SS_If_Fix spreadsheet. From Essbase Application Manager, review the event log to determine the length of time required to run the calc script CSIfix2. Which is more efficient for your environment?
4) 5)
6)
7)
8) 9) 10)
Hyperion
15-7
15
Simpler is Usually Better

Use the power of the OLAP structure to help create the simplest solution to your problem. Often the simplest solution is the most efficient. A couple of examples follow.
Allocation vs Cross-Dimensional Operators

When looking at the allocation of values from upper-level members to lower-level members, it is often more efficient to use cross-dimensional operators instead of the @MDALLOCATE function. For example:
FIX ("Total Expenses") "2000 Budget"= @MDALLOCATE (West->"1999 Actual"->"Total Expenses"* 1.05, 2, @CHILDREN (West), @CHILDREN ("Total Expenses"),"1999 Actual",,share); ENDFIX
produces the same results as:

FIX (@CHILDREN (West),@CHILDREN ("Total Expenses")) "2000 Budget"= "1999 Actual"*1.05; ENDFIX
But, in tests with a small database, the second example ran 10% faster.
Looping
The need to use loops is very rare, and should be avoided. They usually consume large amounts of resources. Where possible, solve simultaneous equations algebraically instead of using loops. For example: At present Profit is calculated by consolidation operators within the outline as Margin less various costs. These costs include Freight which is loaded directly into the database at level 0. However Freight is currently only charged as the cost of shipping, and does not account for shipping materials, the department overhead, or record keeping. To cover all the expenses associated with shipping, the new policy is to charge a rate for freight of 1.5% of Profit. Since Profit is calculated by deducting the freight charge from Margin, both Freight and Profit are now unknown values in a simultaneous equation. Therefore, Profit= Sales - COGS - {Other Expenses} - Freight
15-8
Hyperion
Hyperion Essbase Calc Scripts and Freight = .015 * Profit. Algebraic manipulation yields:
15
Profit = (Sales - COGS - {other expenses})/1.015. Two options for creating this calc script are:
VAR Break = 0; LOOP(10, Break) Profit = Sales - COGS - Freight; Freight = Profit * .015; Profit( IF (Profit<>#Missing AND @ABS((.015*(Sales - COGS - Freight))-Freight) < 0.001) Break = 1; ENDIF) ENDLOOP
which produces the same results as:

Profit = (Sales - COGS) / 1.015; Freight = Profit * .015;
But, in tests with a small database, the second example ran over 90% faster.
Hyperion
15-9
15
Exercise 15-2: Allocations

Data can be loaded into high-level members of an Essbase database. For example, total freight can be stored at an ancestor level, rather than at the individual transaction level. To show the true profit on a sale, freight costs must be allocated to each sale. The allocation is based on the ratio of an individual sale to total sales.
Business problem
Calculate a line item for freight for each individual Product-Market combination. Budgeted freight expense is loaded at the highest level, and must be allocated down to the individual Product-Market level. For each Product-Market develop a ratio of actual sales to total sales. Apply each ratio to the total freight costs to provide individual freight costs.
Affected data
Data from total budgeted freight that is loaded is used to provide an individual budgeted freight expense. The Freight data is allocated to each combination of Product and Market.
To obtain accurate data for total Freight expense, Product and Market data must be rolled up to the highest level.
Calculation of lower level freight costs is based on a ratio of actual individual freight to actual total freight. Each Product- Market combination for budgeted freight is calculated based on this ratio.
Solution
Write a calc script to calculate the freight expense for each Product-Market combination. Use cross-dimensional operators to define the formula. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSAlloc2 SS_Alloc2.xls
15-10
Hyperion
15
Review the outline for the HLandS1 database. Note which data is affected and determine whether rollups must be completed before individual calculations. Open and review the data in spreadsheet SS_Alloc2.xls. From Essbase Application Manager, clear all data from the HLandS1 database. Create your calc script using the Calc Script Editor. Save your calc script as CSAlloc2. In Microsoft Excel, connect to the Essbase server and select the CALC:HLandS1 database. Lock and send the data in the Lock&Send sheet to the HLandS1 database. From the Calc&Retrieve sheet, run the CSAlloc2 calc script. Perform a retrieval and notice the calculation results. The retrieval may take a few minutes. Ensure that all calculation requirements are met. If not, revise the calc script and rerun the calculation. Close the SS_Alloc2 spreadsheet. From Essbase Application Manager, review the event log to determine the length of time required to run the calc script CSAlloc2.
2) 3)
4) 5) 6)
7)
8) 9) 10)
Hyperion
15-11
15
Exercise 15-3: Product Share Analysis

Almost every business wants to know what products are its best sellers. Areas of the data must be isolated: sales data for individual products and sales data for total products.
Business problem
Management is concerned with how well Rods & Reels are selling, both on a category level (all Rods & Reels) and on an individual product level. Calculate percentage of Rods & Reels sales to total product sales.
Affected data
Total Products sales and the Rods and Reels member of the Products dimension's are affected or referenced by these calculations. The Sales member of the dimension tagged as accounts in also affected. These are within the Actual scenario.
Because the calculation of the Products share is based upon total Products sales, sales must be rolled up across the entire database for actuals.
Individual calculations consist of calculating a percentage of individual Rods & Reels sales by total Product sales.
Solution
Write a calc script that calculates Product Share. Product Share is equal to a product or sales of a product line as a percentage of total product sales. Use cross-dimensional operators to define the formula. For this exercise, you use the following files:
Database Calc Script (new) Spreadsheet CALC:HLandS1 CSShare SS_Share.xls
1)
Review the data in spreadsheet SS_Share.
15-12
Hyperion
15
Open the outline for the HLandS1 database. Notice which data is affected, and determine whether rollups must be completed before individual calculations. From Essbase Application Manager, clear all data from the HLandS1 database. Create a calc script using the Calc Script Editor. Save the calc script as CSShare. From Essbase Application Manager, clear all data from the HLandS1 database. In Microsoft Excel, open and review the data in spreadsheet SS_Share.xls. Connect to the Essbase server and select the CALC:HLandS1 database. Lock and send the data in the Lock&Send sheet to the HLandS1 database. From the Calc&Retrieve sheet, run the CSShare calc script. Perform a retrieval and compare the retrieved calculation results to the results in the Expected Results column. Do the calculated results match the expected results? If not, revise the calc script and rerun the calculation. Close the SS_Share spreadsheet.
3) 4)
5) 6) 7)
8) 9)
10) 11)
Hyperion
15-13
15
Unit Summary
In previous units, you looked at functions and commands in isolation or in small calc scripts that provided context. In this unit, you had the opportunity to review business problems and develop calc scripts to solve the problems. Careful planning and an understanding of the business problem are key to creating successful calc scripts. The basic steps used to create calc scripts are as follows: Clarify the business problem Identify affected data Satisfy rollups requirements Create individual calculations
15-14
H H H H
You created calc scripts (allocations, budget creation, and market share analysis) to solve common business problems.
Hyperion
A
Suggested Answers
Possible Solutions
Potential solutions to the exercises for the course are presented in this chapter. In some cases, more than one solution is presented. It is left up to you to test these solutions to determine which is the most efficient for your particular environment.
Suggested Answers
Exercise 3-1: Explore Calc Script Editor and Online Help

CALC DIM (Accounts); Variance = @VAR (Actual, Budget);
Exercise 3-2: Running Calc Scripts

SET MSG SUMMARY; CALC DIM (Accounts); Variance = @VAR (Actual, Budget);
Exercise 3-3: Member Calculations and Mathematical Operators

Margin; Total Expenses; Regional Profit; Pre Tax Profit;
Exercise 4-1: Focus Calculations using Fix / EndFix

FIX (Budget, "Albany", "Buffalo", "Jan 1999") Sales = Sales * 1.15; ENDFIX
Exercise 4-2: Focus Calculations using If / Else / Endif

CALC DIM (Accounts); Variance = @VAR(Actual, Budget); Commission ( IF ("Margin Percent" > 15) Commission = Sales * .10; ELSE Commission = Sales * .08; ENDIF )
Exercise 4-3: Focus Calculations using Cross-Dimensional Operators

Sales ( Budget->"Feb 1999"->Sales= Budget->"Jan 1999"->Sales*1.1; )
A-2
Hyperion
Suggested Answers
Exercise 5-1: Use Math Functions

FIX ("Jan 1999", Actual) FIX (Sales) Connecticut= @ROUND(@AVG(SKIPNONE,Bridgeport:Waterbury),2); ENDFIX ENDFIX
Exercise 6-1: Using Boolean Functions

FIX (Products, "2000", Budget) Sales( IF (@ISDESC (East) OR @ISDESC (West) ) Sales = Actual->"1999"*1.1; ELSEIF (@ISDESC (South)) Sales = Actual->"1999"*1.15; ELSE Sales = Actual->"1999"*.95; ENDIF; ENDFIX
Exercise 7-1: Applying Member Set Functions

FIX (Budget) FIX(@IDESCENDANTS (East)) CALC DIM (Time, Accounts, Products); ENDFIX @IDESCENDANTS (East); ENDFIX
Exercise 8-1: Applying Relationship Function (@ANCESTVAL)

FIX (Budget) FIX (Sales) CALC DIM (Time, Markets, Products); ENDFIX "Corporate Expenses"= @ANCESTVAL (Products, 2,"Corporate Expenses") * Sales/@ANCESTVAL (Products, 2, Sales); ENDFIX
Hyperion
A-3
Suggested Answers
Exercise 8-2: Applying Relationship Function (@CHILDREN)

FIX (Jan, "1011-0010", "2000 Actual") CALC DIM(Markets); FIX(@IDESCENDANTS(Markets,-1)) "Average Inventory" = @AVGRANGE (SKIPMISSING, "Ending Inventory", @CHILDREN (@CURRMBR (Markets))); ENDFIX ENDFIX
Exercise 8-3: Applying Relationship Function (@XREF)

FIX (Actual) COGS (IF (@ISLEV (Products, 0)) COGS=Sales*(@XREF (COGS, COGS)); ENDIF) ENDFIX
OR FIX (Actual, @LVLMBRS(Products,0)) COGS COGS=Sales*(@XREF (COGS, COGS)); ENDFIX
Exercise 9-1: Applying Range Functions (@PRIOR)

FIX ("1999 Actual") "Opening Inventory" ( IF (@ISMBR (Jan)) "Opening Inventory"="Ending Inventory" - Additions; ELSE "Opening Inventory" = @PRIOR("Ending Inventory"); Additions="Ending Inventory" - "Opening Inventory"; ENDIF ) ENDFIX
Exercise 9-2: Applying Financial Functions (@IRR)

FIX("Total Year", Markets, "4000 Product Family") Cash( IF (NOT(@ISMBR ("1997 Actual"))) Cash = Profit; ENDIF ) ROI=@IRR (Cash, 1, "1997 Actual","1998 Actual", "1999 Actual","2000 Actual"); ENDFIX
A-4
Hyperion
Suggested Answers
Exercise 10-1: Applying Allocation Functions

FIX ("1999 Actual") CALC DIM (Accounts, Markets); ENDFIX FIX ("Total Expenses") "2000 Budget"= @MDALLOCATE (West->"1999 Actual"->"Total Expenses" * 1.05, 2, @CHILDREN (West), @CHILDREN ("Total Expenses"),"1999 Actual",,share); ENDFIX FIX ("2000 Budget") CALC DIM (Accounts, Markets); ENDFIX
Exercise 11-1: Applying Forecasting Functions

FIX ("1011-0000-1", Markets, "Total Year", @LEVMBRS (Markets, 2)) Sales ( @TREND (@LIST("1997 Actual"->"Total Year"->Sales, "1998 Actual"->"Total Year"->Sales, "1999 Actual"->"Total Year"),,,,, "2000 Budget"->"Total Year"->Sales, LR);) ENDFIX
Exercise 12-1: Applying Statistical Functions

FIX("1999 Actual", Jan,"1011-0000-1") CALC DIM(Markets); "Sales Rank"( FIX (@LEVMBRS (Markets,1)) "Sales Rank"=@RANK (SKIPMISSING, Sales, @RANGE (Sales, @LEVMBRS (Markets,1))); ENDFIX ENDFIX
Hyperion
A-5
Suggested Answers
Exercise 13-1: Applying the Date & Time Function

FIX(Dec, "New York") CALC DIM(Products); FIX("2000 Budget" ) Marketing( IF (@ATTRIBUTEVAL ("IntroDate")>= @TODATE ("mm-dd-yyyy", "01-01-1997")) Marketing = "1999 Actual"->Marketing * 1.1; ELSEIF (@ATTRIBUTEVAL ("IntroDate")<= @TODATE ("mm-dd-yyyy", "07-05-1996")) Marketing = "1999 Actual"->Marketing * .9; ELSE Marketing = "1999 Actual"->Marketing; ENDIF ) ENDFIX ENDFIX
Exercise 15-1 & 15-1b: Isolating Data Using IF or FIX

FIX (@IDESCENDANTS (East)) Commission ( IF (@ISMBR ("2000 Budget")) Commission=Commission->"1999 Actual"; ENDIF) Commission ( IF (@ISMBR ("1999 Actual")) Commission=Commission*1.25; ENDIF) ENDFIX
OR FIX ("2000 Budget") Commission ( IF (@ISIDESC (East)) Commission=Commission->"1999 Actual"; ENDIF) ENDFIX FIX ("1999 Actual") Commission ( IF (@ISIDESC (East)) Commission=Commission*1.25; ENDIF) ENDFIX
A-6
Hyperion
Hyperion Essbase Calc Scripts OR -
Suggested Answers
Commission ( IF (@ISIDESC (East)) "2000 Budget"->Commission=Commission->"1999 Actual"; "1999 Actual"->Commission= Commission->"1999 Actual"*1.25; ENDIF)
OR FIX (@IDESCENDANTS (East)) Commission ( "2000 Budget"->Commission=Commission->"1999 Actual"; "1999 Actual"->Commission= Commission->"1999 Actual"*1.25; ) ENDFIX
Exercise 15-2 : Allocations

FIX (Actual,Sales) CALC DIM (Time, Markets, Products); ENDFIX FIX (Budget) Freight=Sales->Actual / Sales->Actual->Markets->Products * Freight->Products->Markets; ENDFIX
OR FIX (Actual,Sales) CALC DIM (Time, Markets, Products); ENDFIX FIX (Budget, @LEVMBRS(Markets, 0), @LEVMBRS(Products, 0)) Freight=Sales->Actual / Sales->Actual->Markets->Products * Freight->Products->Markets; ENDFIX
Exercise 15-3 : Product Share Analysis

FIX (Actual) FIX (Sales) CALC DIM (Time, Markets, Products); ENDFIX FIX (@IDESCENDANTS("2000 Product Family")) "Product Share"=Sales%Sales->Products; ENDFIX ENDFIX
Hyperion
A-7
Suggested Answers
A-8
Hyperion
B
Essbase Outlines
The outlines used in for examples and exercises are detailed in this section. They include Sample - Basic Calc - HLandS1 Calc - HLandS2 Calc - COGS
Essbase Outlines
Sample - Basic
The Sample - Basic outline is used to illustrate many of the examples in the descriptive material:
Year (Dense) Qtr1 Jan Feb Mar Qtr2 Apr May Jun Qtr3 Jul Aug Sep Qtr4 Oct Nov Dec Measures (Dense) Profit Margin Sales COGS Total Expenses Marketing Payroll Misc Inventory Opening Inventory Additions Ending Inventory Ratios Margin % Profit % Profit per Ounce Product (Sparse) 100 Alias: Colas 100-10 100-20 100-30 Alias: Root Beer 200-10 200-20 200-30 200-40 Alias: Cream Soda 300-10 300-20 300-30 Alias: Fruit Soda 400-10 400-20 400-30 Alias: Diet Drinks 100-20 Shared 200-20 Shared 300-30 Shared
200
300
400
Diet
B-2
Hyperion
Essbase Outlines
Sample - Basic (Continued)

Market (Sparse) East New York Massachusetts Florida Connecticut New Hampshire West California Oregon Washington Utah Nevada South Texas Oklahoma Louisiana New Mexico Central Illinois Ohio Wisconsin Missouri Iowa Colorado Scenario (Dense) Actual Budget Variance Variance %
Hyperion
B-3
Essbase Outlines
Sample - Basic (Attribute Dimensions)

Caffeinated (Attribute of Product) TRUE FALSE Ounces (Attribute of Product) 32 20 16 12 Pkg Type (Attribute of Product) Bottle Can Population (Attribute of Market) Small 3000000 6000000 Medium 9000000 12000000 15000000 18000000 Large 21000000 24000000 27000000 30000000 33000000 Intro Date (Attribute of Product) 3/25/96 4/1/96 9/27/95 7/26/96 12/10/96 6/26/96 10/1/96
B-4
Hyperion
Essbase Outlines
Calc - HLandS1
The HLandS1 database is used for many of the exercises. The major differences from HLandS2 are in the structure of the Time and Scenarios dimensions. The Markets and Products dimensions are identical in each of these outlines.l
Time (Dense) 1997 Qtr1 1997 Jan-97 Feb-97 Mar-97 Qtr2 1997 Apr-97 May-97 Jun-97 Qtr3 1997 Jul-97 Aug-97 Sep-97 Qtr4 1997 Oct-97 Nov-97 Dec-97 1998 Qtr1 1998 Jan-98 Feb-98 Mar-98 Qtr2 1998 Apr-98 May-98 Jun-98 Qtr3 1998 Jul-98 Aug-98 Sep-98 Qtr4 1998 Oct-98 Nov-98 Dec-98 1999 Qtr1 1999 Jan-99 Feb-99 Mar-99 Qtr2 1999 Apr-99 May-99 Jun-99 Qtr3 1999 Jul-99 Aug-99 Sep-99 Qtr4 1999 Oct-99 Nov-99 Dec-99 2000 Qtr1 2000 Jan-00
Hyperion
B-5
Essbase Outlines
Feb-00 Mar-00 Qtr2 2000 Apr-00 May-00 Jun-00 Qtr3 2000 Jul-00 Aug-00 Sep-00 Qtr4 2000 Oct-00 Nov-00 Dec-00
Accounts (Dense) Profit Pre Tax Profit Regional Profit Margin Sales COGS Total Expenses Freight Administration Payroll Marketing Miscellaneous Corporate Expenses Tax Inventory Opening Inventory Additions Ending Inventory Ratios Margin Percent Profit Percent Product Share Statistics Average Sales Commission Days of Sales Available Days Of Sales Adjusted Store Count Average Margin
B-6
Hyperion
Essbase Outlines
CALC - HLandS1 (Continued)

Scenario (Dense) Actual Budget Variance Variance Percent Percent
Markets (Sparse) East Connecticut Bridgeport Hartford Stamford Waterbury Maine Augusta Bangor Millinocket Portland Massachuset ts New Bedford Springfield Worcester New York Albany Buffalo Ithaca White Plains Rhode Island Jamestown Providence Quonochontaug West California Bakersfield Foster City Sacramento Half Moon Bay New Mexico Albuquerque Deming Sante Fe Oregon Condon Eugene Salem Washington Olympia Spokane Tacoma Walla Walla South Alabama Andalusia Birmingham Mobile
Hyperion
B-7
Essbase Outlines
Montgomery Florida Orlando Sarasota Tampa Georgia Athens Macon Valdosta Tennessee Memphis Murfreesboro Nashville Central Illinois Antioch Carbondale Cobden Rockford Wisconsin Green Bay La Crosse Milwaukee Neenah Wausau Texas Amarillo Austin Dallas Waco Missouri
Cape Girardeau Kansas City Lebanon Sikeston St. Louis
B-8
Hyperion
Essbase Outlines

Products 1000 Product Family Crazy Horse 1011 1011-0000 1011-0000-1 1011-0000-2 1011-0000-3 1011-0010 1011-0020 1011-0030 1011-0040 Crazy Horse 1021 1021-0000 1021-0010 1021-0020 1021-0020-1 1021-0020-2 1021-0020-3 Crazy Horse 1031 1031-0000 1031-0020 1031-0030 1031-0040 1031-0050 1031-0050-1 1031-0050-2 1031-0050-3 1031-0070 1031-0070-1 1031-0070-2 1031-0090 Crazy Horse 1041 1041-0000 1041-0020 1041-0040 1041-0060 1041-0070 1041-0090 2000 Product Family Old Faithful 2011 2011-0000 2011-0000-1 2011-0000-2 2011-0000-3 2011-0000-4 2011-0000-5 2011-0000-6 2011-0010 2011-0010-1 2011-0010-2 2011-0010-3 2011-0010-4 2011-0010-5 2011-0010-6 Old Faithful 2021 2021-0000 2021-0010 Old Faithful 2031 2031-0000 2031-0000-1 2031-0000-2
Hyperion
B-9
Essbase Outlines

2031-0000-3 2031-0000-4 2031-0000-5 2031-0000-6 2031-0010 2031-0010-1 2031-0010-2 2031-0010-3 2031-0010-4 2031-0010-5 2031-0010-6
Old Faithful 2041 2041-0000 2041-0020 3000 Product Family Pomona 3011 3011-0000 3011-0010 3011-0020 3011-0030 3011-0040 Pomona 3021 3021-0000 3021-0010 3021-0030 Pomona 3031 3031-0000 3031-0030 3031-0020 3031-0040 Pomona 3041 3041-0000 3041-0020 3041-0040 3041-0060 Pomona 3051 3051-0000 3051-0000-1 3051-0000-2 3051-0000-3 3051-0000-4 3051-0020 3051-0020-1 3051-0020-2 4000 Product Family Shawnee 4011 4011-0000 4011-0010 4011-0020 Shawnee 4021 4021-0000 4021-0000-1 4021-0000-2 4021-0010 4021-0010-1 4021-0010-2 Shawnee 4031 4031-0000 4031-0000-1 4031-0000-2 4031-0010 4031-0010-1 4031-0010-2
B-10
Hyperion
Essbase Outlines
Calc - HLandS2
The HLandS2 database is used for many of the exercises. The major differences from HLandS1 are in the structure of the Time and Scenarios dimensions. The Markets and Products dimensions are identical in each of these outlines.
Total Year Qtr1 Jan Feb Mar Qtr2 Apr May Jun Qtr3 Jul Aug Sep Qtr4 Oct Nov Dec
Accounts Profit Pre Tax Profit Regional Profit Margin Sales COGS Total Expenses Freight Administration Payroll Marketing Miscellaneous Corporate Expenses Tax Inventory Opening Inventory Additions Ending Inventory Average Inventory Ratios Margin Percent Profit Percent Product Share Statistics Average Sales Commission Days of Sales Available Days Of Sales Adjusted Store Count Sales Rank Average Margin Cash ROI
Hyperion
B-11
Essbase Outlines

Scenario 1997 1997 Actual 1998 1998 Actual 1998 Budget 1999 1999 Actual 1999 Budget 2000 2000 Actual 2000 Budget Variances 1998 Actual VS 1999 Actual Percent Variance 1998 Budget VS 1999 Budget 1998 Actual VS 1998 Budget
Markets (Sparse) East Connecticut Bridgeport Hartford Stamford Waterbury Maine Augusta Bangor Millinocket Portland Massachuset ts New Bedford Springfield Worcester New York Albany Buffalo Ithaca White Plains Rhode Island Jamestown Providence Quonochontaug West California Bakersfield Foster City Sacramento Half Moon Bay New Mexico Albuquerque Deming Sante Fe Oregon Condon Eugene Salem Washington Olympia
B-12
Hyperion

Spokane Tacoma Walla Walla South Alabama Andalusia Birmingham Mobile Montgomery Florida Orlando Sarasota Tampa Georgia Athens Macon Valdosta Tennessee Memphis Murfreesboro Nashville Central Illinois Antioch Carbondale Cobden Rockford Wisconsin Green Bay La Crosse Milwaukee Neenah Wausau Texas Amarillo Austin Dallas Waco Missouri Cape Girardeau Kansas City Lebanon Sikeston St. Louis
Essbase Outlines
Hyperion
B-13
Essbase Outlines

B-14
Hyperion
Essbase Outlines
2031-0000-3 2031-0000-4 2031-0000-5 2031-0000-6 2031-0010 2031-0010-1 2031-0010-2 2031-0010-3 2031-0010-4 2031-0010-5 2031-0010-6
Hyperion
B-15
Essbase Outlines
CALC - HLandS2 (Attribute Dimension)

IntroDate 1/1/90 7/5/96 7/6/96 10/13/98
B-16
Hyperion
Essbase Outlines
Calc - COGS
Time (Dense) 1997 1998 1999 2000
Accounts COGS
Hyperion
B-17
Essbase Outlines
Calc - COGS (Continued)

B-18
Hyperion
Essbase Outlines
2031-0000-3 2031-0000-4 2031-0000-5 2031-0000-6 2031-0010 2031-0010-1 2031-0010-2 2031-0010-3 2031-0010-4 2031-0010-5 2031-0010-6
Hyperion
B-19
Essbase Outlines
B-20
Hyperion

Calc Script 651

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Calc Script 651

Uploaded by

Copyright:

Available Formats

Calc Scripts

1 Introduction .......................................................................................... 1-1

2 Calculation Architecture ..................................................................... 2-1

Hyperion Essbase Calc Scripts

3 Calculation Script Environment ......................................................... 3-1

Hyperion Essbase Calc Scripts

4 Calculation Script Commands............................................................ 4-1

Hyperion Essbase Calc Scripts

5 Math Functions .................................................................................... 5-1

6 Boolean Functions............................................................................... 6-1

Hyperion Essbase Calc Scripts

7 Member Set Functions ........................................................................ 7-1

Hyperion Essbase Calc Scripts

8 Relationship Functions ....................................................................... 8-1

9 Range and Financial Functions.......................................................... 9-1

Hyperion Essbase Calc Scripts

10 Allocation Functions ....................................................................... 10-1

11 Forecasting Functions .................................................................... 11-1

Hyperion Essbase Calc Scripts

12 Statistical Functions........................................................................ 12-1

13 Date and Time Functions ................................................................ 13-1

14 Miscellaneous Functions ................................................................ 14-1

Hyperion Essbase Calc Scripts

15 Tips, Tricks and Techniques........................................................... 15-1

A Suggested Answers ............................................................................A-1

B Essbase Outlines ................................................................................B-1

Hyperion Essbase Calc Scripts

What is in the Manual

A list of the manuals components:

Hyperion Essbase Calc Scripts

Setting User Defaults

To set user defaults:

Hyperion Essbase Calc Scripts

Hyperion Essbase Calc Scripts

Hyperion Essbase Calc Scripts

Creativity Optimization Techniques Usage Concepts Syntax

Hyperion Essbase Calc Scripts

Reviewing calculation architecture

Building calc scripts

Using calc scripts

Hyperion Essbase Calc Scripts

Exercise 1-1 Hook, Line and Sinker Company

Building an OLAP system

Hyperion Essbase Calc Scripts

Hyperion Essbase Calc Scripts

Hyperion Essbase Calc Scripts

Hyperion Essbase Calc Scripts

Hyperion Essbase Calc Scripts

To connect to the Essbase Server:

To calculate a database in Essbase Application Manager:

Hyperion Essbase Calc Scripts 4)

To view the default calc settings:

Hyperion Essbase Calc Scripts

To change the default calc settings by typing in a new calc script:

To change the default calc settings by selecting an existing calc script:

Hyperion Essbase Calc Scripts 3) Click OK.

Hyperion Essbase Calc Scripts

Default Calculation Characteristics

Minimizes Physical Passes Through the Database

Hyperion Essbase Calc Scripts

Calc Script Calculations

Contents of calc scripts