81816101-CalcScript651

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, what’s 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 purchaser ’s 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 Corporation1344 Crossman AvenueSunnyvale, CA 94089

Hyperion Essbase XTD Calc Scripts / 6.5.1 / 10.18.02

Table of Contents

Preface ......................................................................................................... iWelcome to Hyperion® Essbase® XTD Calc Script Training! ....................................................... iCourse Structure.................................................................................................................................... i

What is in the Manual .................................................................................................................... iConventions ..........................................................................................................................................ii

1 Introduction .......................................................................................... 1-1Learning Essbase ...............................................................................................................................1-2

Syntax ...........................................................................................................................................1-2Concepts.......................................................................................................................................1-2Usage ............................................................................................................................................1-2Techniques ...................................................................................................................................1-2Optimization ...............................................................................................................................1-2Creativity .....................................................................................................................................1-3

Class Overview..................................................................................................................................1-3Reviewing calculation architecture ..........................................................................................1-3Building calc scripts ...................................................................................................................1-3Using calc scripts ........................................................................................................................1-3

Exercise 1-1 – Hook, Line and Sinker Company ..........................................................................1-4Building an OLAP system .........................................................................................................1-4

Unit Summary ...................................................................................................................................1-5

2 Calculation Architecture ..................................................................... 2-1Types of Calculation .........................................................................................................................2-2

Outline calculations....................................................................................................................2-2Calc scripts...................................................................................................................................2-2

Outline Calculations .........................................................................................................................2-3Default Calculation ...........................................................................................................................2-4Default Calculation Characteristics ................................................................................................2-8

Minimizes Physical Passes Through the Database ................................................................2-8Allows Users with Access to Specific Calc Scripts to Run the Default Calc ......................2-8

Calc Script Calculations....................................................................................................................2-9Contents of calc scripts ..............................................................................................................2-9Reasons for calc scripts ..............................................................................................................2-9Functions and commands that work only in scripts .............................................................2-9

Calculation Order............................................................................................................................2-10Data storage ...............................................................................................................................2-10Dimension types .......................................................................................................................2-10

Dense and Sparse Dimensions ......................................................................................................2-10

Table of Contents Hyperion Essbase Calc ScriptsT
Dense dimensions.....................................................................................................................2-10Sparse dimensions ....................................................................................................................2-10Dimension tags..........................................................................................................................2-10
Block and Index Structure..............................................................................................................2-11Generations and Levels ..................................................................................................................2-12Block Types ......................................................................................................................................2-13

Input blocks ...............................................................................................................................2-13Non-input blocks ......................................................................................................................2-13Level zero blocks.......................................................................................................................2-13Upper-level blocks....................................................................................................................2-13

Calculation Order............................................................................................................................2-14Dense Calculations..........................................................................................................................2-14Sparse Calculations .........................................................................................................................2-15Calculation Order: Dense Dimensions.........................................................................................2-16Calculation Order: Sparse Dimensions ........................................................................................2-17Calculation Order: Dynamic Calc Versus Batch.........................................................................2-18Calculation order exceptions .........................................................................................................2-19Two-Pass Calculation .....................................................................................................................2-21

Calculation passes ....................................................................................................................2-21Exercise 2-1: Review Class Files ....................................................................................................2-22Unit Summary .................................................................................................................................2-24

3 Calculation Script Environment ......................................................... 3-1Introducing Calc Scripts ...................................................................................................................3-2

Components of calc scripts........................................................................................................3-2Calc Script Editor and online Help ..........................................................................................3-2Commands and functions .........................................................................................................3-3

Using Calc Script Editor ...................................................................................................................3-4Calc Script Editor ........................................................................................................................3-5Associating an Essbase Outline ................................................................................................3-5Inserting Functions (Using the Function Button) ..................................................................3-6Checking the Syntax and Saving and Running the Calc Script ...........................................3-7

Using Essbase Documentation ......................................................................................................3-10Inserting Functions (From on-line Help) ..............................................................................3-11

Exercise 3-1: Explore Calc Script Editor and Online Help ........................................................3-12Reviewing Essbase Data Using Spreadsheet Add-in.................................................................3-14

Exercise Procedures..................................................................................................................3-14Exercise 3-2: Running Calc Scripts................................................................................................3-16Calc Script Basics.............................................................................................................................3-18

Member Calculations ...............................................................................................................3-18

2 Hyperion

Hyperion Essbase Calc Scripts Table of Contents T
Arithmetic Operators ...............................................................................................................3-19Adding In-line Documentation ..............................................................................................3-20
Introduction to Calc Script Commands and Functions .............................................................3-21Calc Script Command Categories ..........................................................................................3-21Essbase Functions Categories .................................................................................................3-22

Exercise 3-3: Member Calculations and Mathematical Operators ...........................................3-28Unit Summary .................................................................................................................................3-31

4 Calculation Script Commands............................................................ 4-1Calc Member Blocks..........................................................................................................................4-2Focusing Calculations.......................................................................................................................4-3

Focusing Calculations Using Fix...Endfix ...............................................................................4-3Focusing Calculations Using Conditional Statements ..........................................................4-3Focusing Calculations Using the Cross-Dimensional Operator ..........................................4-3

Calc Script Commands .....................................................................................................................4-4Summary of Calc Script Commands ..............................................................................................4-4Detailed Description of Calc Script Commands ...........................................................................4-6

& ....................................................................................................................................................4-6AGG ..............................................................................................................................................4-7ARRAY .........................................................................................................................................4-8CALC ............................................................................................................................................4-9CALC ALL .................................................................................................................................4-10CALC DIM.................................................................................................................................4-11CALC (others) ...........................................................................................................................4-13CCONV ......................................................................................................................................4-14CLEARBLOCK..........................................................................................................................4-15CLEARDATA ............................................................................................................................4-16DATACOPY ..............................................................................................................................4-17FIX / ENDFIX ...........................................................................................................................4-18IF / ELSE / ELSEIF / ENDIF .................................................................................................4-19LOOP/ENDLOOP....................................................................................................................4-22SET ..............................................................................................................................................4-24SET AGGMISSG........................................................................................................................4-25SET CACHE...............................................................................................................................4-26SET CALCHASHTBL...............................................................................................................4-27SET CALCPARALLEL.............................................................................................................4-28SET CALCTASKDIMS .............................................................................................................4-30SET CLEARUPDATESTATUS................................................................................................4-32SET FRMLBOTTOMUP ...........................................................................................................4-34SET LOCKBLOCK ....................................................................................................................4-35

3 Hyperion

SET MSG ....................................................................................................................................4-36SET NOTICE..............................................................................................................................4-37SET UPDATECALC .................................................................................................................4-39SET UPTOLOCAL ....................................................................................................................4-40VAR.............................................................................................................................................4-41
Exercise 4-1: Focus Calculations using Fix / EndFix .................................................................4-42Exercise 4-2: Focus Calculations using If / Else / Endif ...........................................................4-43Exercise 4-3: Focus Calculations using Cross-Dimensional Operators ...................................4-44

Unit Summary...........................................................................................................................4-45

5 Math Functions .................................................................................... 5-1Transforming Values with Math Functions ..................................................................................5-2Math Function Parameters...............................................................................................................5-3Summary of Math Functions ...........................................................................................................5-3Detailed 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-20Unit Summary .................................................................................................................................5-21............................................................................................................................................................5-24

6 Boolean Functions............................................................................... 6-1Testing for Values Using Boolean Functions ................................................................................6-2Boolean Function Parameters ..........................................................................................................6-2Summary of Boolean Functions ......................................................................................................6-3

@ISACCTYPE ..............................................................................................................................6-5@ISANCEST, @ISANCEST........................................................................................................6-6@ISCHILD, @ISICHILD.............................................................................................................6-7

4 Hyperion

@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-16Exercise 6-1: Using Boolean Functions.........................................................................................6-17Unit Summary .................................................................................................................................6-18............................................................................................................................................................6-21

7 Member Set Functions ........................................................................ 7-1Generating Lists Using Member set Functions .............................................................................7-2Member Set Function Parameters...................................................................................................7-2Summary 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

5 Hyperion

@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-44Unit Summary...........................................................................................................................7-45

8 Relationship Functions ....................................................................... 8-1Using Relationship Functions .........................................................................................................8-2Relationship Function Parameters..................................................................................................8-2Summary 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-21How @XREF works ..................................................................................................................8-21

Defining a Location Alias...............................................................................................................8-24Exercise 8-1: Applying Relationship Function (@ANCESTVAL) ............................................8-26Exercise 8-2: Applying Relationship Function (@CHILDREN)................................................8-27Exercise 8-3: Applying Relationship Function (@XREF) ...........................................................8-28Unit Summary .................................................................................................................................8-30

9 Range and Financial Functions.......................................................... 9-1Using Range and Financial Functions............................................................................................9-2Range and Financial Function Parameters ....................................................................................9-2

6 Hyperion

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-36Exercise 9-2: Applying Financial Functions (@IRR) ...................................................................9-37Unit Summary .................................................................................................................................9-38

10 Allocation Functions ....................................................................... 10-1Using Allocation Functions ...........................................................................................................10-2Common Parameters ......................................................................................................................10-2Summary of Allocation Functions ................................................................................................10-5

@ALLOCATE ............................................................................................................................10-6@MDALLOCATE .....................................................................................................................10-8

Exercise 10-1: Applying Allocation Functions ..........................................................................10-10Unit Summary ...............................................................................................................................10-11

11 Forecasting Functions .................................................................... 11-1Using Forecasting Functions .........................................................................................................11-2

7 Hyperion

Forecasting Function Parameters..................................................................................................11-2Summary 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-21Unit Summary ...............................................................................................................................11-22

12 Statistical Functions........................................................................ 12-1Generating Lists Using Statistical Functions...............................................................................12-2Statistical Function Parameters .....................................................................................................12-2Summary 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-23Unit Summary ...............................................................................................................................12-24

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

@TODATE .................................................................................................................................13-3Exercise 13-1: Applying the Date & Time Function ...................................................................13-5

14 Miscellaneous Functions ................................................................ 14-1Using Miscellaneous Functions.....................................................................................................14-2Summary of Miscellaneous Functions .........................................................................................14-2

@CALCMODE ..........................................................................................................................14-3@CONCATENATE.................................................................................................................14-11@NAME....................................................................................................................................14-12

8 Hyperion

@SUBSTRING..........................................................................................................................14-13
15 Tips, Tricks and Techniques........................................................... 15-1Calc Script Design Considerations ...............................................................................................15-2

IF or FIX......................................................................................................................................15-2Dense calculations before sparse calculations ......................................................................15-2Two-pass calculations ..............................................................................................................15-2Intelligent Calcs.........................................................................................................................15-2Blocks on equations ..................................................................................................................15-2

Approaching Calc Scripts Solutions .............................................................................................15-3Business problem......................................................................................................................15-3Affected data .............................................................................................................................15-3Rollup considerations ..............................................................................................................15-3Individual calculations ............................................................................................................15-3Communication ........................................................................................................................15-3

IF vs FIX ............................................................................................................................................15-4Exercise 15-1: Isolating Data Using IF or FIX..............................................................................15-5Exercise 15-1b: Isolating Data Using IF or FIX............................................................................15-7Simpler is Usually Better................................................................................................................15-8Exercise 15-2: Allocations.............................................................................................................15-10Exercise 15-3: Product Share Analysis .......................................................................................15-12Unit Summary ...............................................................................................................................15-14

A Suggested Answers ............................................................................A-1Possible Solutions .......................................................................................................................... 1

B Essbase Outlines ................................................................................B-1Sample - Basic ................................................................................................................................... B-2Calc - HLandS1 ................................................................................................................................. B-5Calc - HLandS2 ............................................................................................................................... B-11Calc - COGS .................................................................................................................................... B-17

9 Hyperion


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

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.

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

A list of the manual’s 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 Hyperion Essbase Calc ScriptsP
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:

To set user defaults:

� Tables are used to define software components, as in this example:

� 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:

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.

Time Periods Periods represent a specific segment of time for each data category based on that category’s frequency.

✍

ii Hyperion

Hyperion Essbase Calc Scripts Preface P
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:

1) Select Clear Profile.

2) 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:

1) Change to the /home/essbase/app directory.

� 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.

Hyperion iii

Preface Hyperion Essbase Calc ScriptsP

iv Hyperion

1Introduction

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 Hyperion Essbase Calc Scripts1
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.

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.

SyntaxConcepts

Usage

Techniques

OptimizationCreativity

SyntaxConcepts

Usage

Techniques


SyntaxConcepts

Usage

Techniques


1-2 Hyperion

Hyperion Essbase Calc Scripts Introduction 1
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

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 stand-alone 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 allocationThe 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

Hyperion Essbase Calc Scripts Introduction 1
Unit Summary
The process of learning Essbase follows a pattern common to that of learning most systems. As you master each learning level—syntax, 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 built-in 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


1-6 Hyperion

2Calculation Architecture

Chapter Objectives


• 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

Calculation Architecture Hyperion Essbase Calc Scripts2
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

Hyperion Essbase Calc Scripts Calculation Architecture 2
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) Ensure Hyperion Essbase OLAP Server and Hyperion Essbase Application Manager are running.

2) To connect to the server from the Essbase Application Manager main menu, select Server / Connect.

3) In the Essbase System Login window, select the desired Server, and type a valid Username and Password. Click OK.

The server window displays:

To calculate a database in Essbase Application Manager:

1) Connect to the Essbase Server.

2) In the Server window, select the Application from the drop-down list.The databases for the selected application display in the Databases list.

3) In the database list, select the database to be calculated.

2-4 Hyperion

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) Connect to the Essbase Server.

2) In the Server window, select the Application from the drop-down list.The databases for the selected application display in the Databases list.

3) In the database list, select the database to be calculated.

Hyperion 2-5

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) From the Set Default Calc window, select Use String.

2) Type commands into text box associated with the Use String option in the Set Default Calc window.

3) Click OK.

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

1) From the Set Default Calc window, select Use Calc Script Object.

2) From the drop-down list, select the calc script that you wish to use as the default calc script.

2-6 Hyperion

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:

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.

Accounts Time Passes

Dense None 1

Sparse None 2

Dense Dense 1

Dense (and is the only dense dim)

Sparse 1

Dense Sparse 2

Sparse Sparse 2

Sparse Sparse 2

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 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

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 block’s 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.

Hyperion 2-11

Generations and Levels
Essbase vocabulary uses two methods for referencing the position of a member within a hierarchy:

� generation � level.

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.

2-12 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 Traversed Dimension

A Cola 1 East

2 West

3 South

4 Markets

B Root Beer 1 East

2 West

3 South

4 Markets

And so on

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:

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:

If you tag East and Total Units as Dynamic Calc and run a calculation, you will receive different results:

1. New York - Total Units 10*2 = 20

2. Florida - Total Units 10*1 = 10

3. East - Units per Container 10+10 = 20

4. East Containers 2+1 = 3

5. East - Total Units 20+10 = 30

Sparse

Dense

Sparse

Dense

Hyperion 2-19

Since Dynamic Calculation calculates along the sparse dimensions before calculating the order of calculation is:
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.

1. East - Units per Container 10+10 = 20

2. East - Containers 2+1 = 3

3. New York - Total Units 10*2 = 20

4. Florida - Total Units 10*1 = 10

5. East - Total Units 20*3 = 60

✍

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:

The second pass corrects the percentage calculation:

Two-pass calculations work only on the Accounts dimension. Although you can tag members in other dimensions as two-pass, the tag is ignored.

Accounts Jan Feb Mar Qtr1

Profit 100 100 100 300

Sales 1000 1000 1000 3000

Profit% (NOT tagged as two-pass)

10% 10% 10% 30%

Accounts Jan Feb Mar Qtr1

Profit 100 100 100 300

Sales 1000 1000 1000 3000

Profit% (tagged as two-pass)

10% 10% 10% 10%

✍

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:

1) Ensure that the Essbase OLAP server is running.

2) Start Essbase Application Manager.

3) From the Essbase Application Manager main menu, select Server / Connect.

The Essbase System Login dialog displays.

4) 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.

5) In the Application field, select CALC.

6) From the list of available databases, select HLandS1. Click Open.

7) Expand each of the dimensions to obtain an understanding of the structure of the HLandS1 database.

8) Close the HLandS1 outline.

9) From the list of available databases, select HLandS2. Click Open.

10) 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).

11) Close the HLandS2 outline.

Database CALC:HLandS1

CALC:HLandS2

CALC:COGS

Spreadsheet SS_Demo.xls

✍

2-22 Hyperion

12) From the list of available databases, select COGS. Click Open.
13) 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.

14) Close the COGS outline.

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) Launch Microsoft Excel.

16) Open the Excel workbook: SS_Demo found in the <x>:\Hyperion\Essbase\App\Calc directory.

17) select the Lock&Send tab.

After clearing the database, you use Essbase / Lock and Essbase / Send to initialize the database’s content.

18) 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.

19) Close the Excel workbook.

✍

✍

✍

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

� 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)

2) 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.

3) 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-26 Hyperion

3Calculation Script Environment

Chapter Objectives


• 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

Calculation Script Environment Hyperion Essbase Calc Scripts3
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

Hyperion Essbase Calc Scripts Calculation Script Environment 3
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) Click Calc Script .

3) 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.

3) From the Calc Scripts list, select the name of the Calc Script to be opened.

4) Click Open.

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:

� 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

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 outline’s 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 3-5


Associating a Hyperion Essbase Outline:

1) In the Calc Script Editor window, click the Associate button , or from the main menu, select Options / Associate Outline.

The Associate Server Outline Object window displays:

The default selections are to use the application and database that was created with.

2) If necessary, select the Server, Application and Database.

3) Click OK.The outline’s 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.

2) If necessary, expand the dimension’s definition in the Members list to reveal the item that you wish to include.

3) Select the item in the Members list.The selected item is copied to edit area at the current cursor position.

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.

3) In the Templates list, select the desired function or command.The command’s template displays below the Categories list. Depending on the command/function selected, the Insert Arguments check box becomes available.

4) If available, and if you want to include the function’s arguments, select Insert Arguments.

5) Click OK.The function / command is added at the cursor position of the edit area in Calc Script Editor window.

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 Editor’s 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 Editor’s status line. “No more errors” will display on the status line if there are no further syntax errors in the calc script.

3) To view the previous error, select Syntax / Previous Error from the main menu.

The previous error displays on the Calc script Editor’s status line. “No more errors” will display on the status line if there are no prior syntax errors in the calc script.

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) In the Object Name field, type the name that want to which you want to save the calc script.

3) Click OK.

Running a Calc Script (Application Manager):

1) From the server window, click Calc Script .

2) From the Calc Scripts list, select the Calc Script to be executed.

3) Click Run.The Select Database window displays.

4) 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.

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 Editor’s 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.


1) Start Essbase Application Manager, and connect to the CALC application. From the list of available databases, select HLandS1.

2) Create a new calc script.

3) Associate the calc script with the HLandS1 outline.

4) Click the Calc Script Editor function button .

5) From the Categories list box of the Function Template, select Functional.

6) From the Templates list box, select Calc Dim. Click OK.The Calc Dim(dimList) statement is copied to the Calc Editor edit area.

7) 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)

8) Place the cursor at the end this line (and click). Either type a semi-colon, or click the semi-colon button on the toolbar. Press [Enter].

The statement in the edit area reads CALC DIM (Accounts);

9) Switch to HTML Help by selecting Help / Functions, and locate the @VAR function. In HTML Help, copy the syntax of @VAR to the clipboard.

10) In the Calc Script Editor, on a new line, type in Variance =, and then paste the contents from the clipboard.


Calc Script (new) CSDemo

3-12 Hyperion

11) 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.

12) Verify the syntax by selecting Syntax / Check Syntax or by clicking the

Syntax Checker button on the toolbar.

13) If there are errors, review your calc script to ensure the syntax and punctuation is correct (according to step 11). Reverify the syntax.

14) 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 Add-in 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.

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):

1) In the server window of Hyperion Essbase Application Manager, select the application and database.

2) From the main menu, select Database / Clear Data / All.

3) Click Yes to the “Are you sure...?” message.

4) Click OK to the Clear Data confirmation message.

3-14 Hyperion


Connecting to the Essbase Database(Spreadsheet Add-in):

1) In the desired worksheet, select Essbase / Connect.

2) 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.

3) Select the appropriate Application/Database combination from the list. Click OK.

Populating the Database (Spreadsheet Add-in):

1) In the desired worksheet, connect to the appropriate Essbase database.

2) Select Essbase / Lock.

3) Select Essbase / Send.

Running a Calc Script (Spreadsheet Add-in):

1) Select Essbase / Calculation.

2) In the Essbase Calculation dialog, select the Calc Script to be run. select Calculate.

3) Click OK at the message stating “Your calculation is finished”.

Retrieving Essbase Data (Spreadsheet Add-in):

1) In the desired worksheet, connect to the appropriate Essbase database.

2) 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.


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) In Microsoft Excel, open SS_Demo from the <x>:\Hyperion\Essbase\App\Calc directory.

4) Select the Lock&Send tab.

Send the Spreadsheet Data to Essbase

5) Connect to the Essbase server and select the Calc:HLandS1 database.

6) 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.


Calc Script CSDemo

Spreadsheet SS_Demo.xls

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.

10) Click Date and in the drop-down list select today's date. Click OK. The Log Viewer window displays.

11) 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.

12) Close the Event Log Viewer window.

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.

15) View the application log once again, and notice how the SET MSG SUMMARY command affects the log entries for the calculation.

16) In Microsoft Excel, close the SS_Demo spreadsheet.

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

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.

mbrName;

(mbrName1, mbrName2);

mbrName, mbrName1, mbrName2 - Member defined in the database outline whose results are to be calculated.

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

Valid mathematical operators:

Examples

“Sales Tax” = Sales * .06;“Margin” = “Net Income” / “Gross Revenue”;“Sales Pct” = Sales % “Total Sales”;Ave = (“First Value” + “Second Value” + “Third Value”) / 3;

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.

+ 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.

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

The free-form text can be anything that you like.

When Essbase’s 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 Essbase’s 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 asNet Income divided by Gross Revenue */

“Margin” = “Net Income” / “Gross Revenue”;

/* Free form text */

or

// Single-line of free form text

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

A command template can be found by selecting its category:

Command Select Category

AGG Functional

ARRAY Data Declarations

CALC Functional

CCONV Functional

CLEARBLOCK Functional

CLEARDATA Functional

DATACOPY Functional

ELSE Conditionals

ELSEIF Conditionals

ENDFIX Control Flow

Hyperion 3-21


Essbase Functions Categories

The categories that contain Essbase functions are:

� Boolean � Relationship functions� Math � Member Set � Range (Financial)� Allocation� Forecasting� Statistical� Date & Time� Miscellaneous

A function template can be found by selecting its category:

ENDIF Conditionals

ENDLOOP Control Flow

FIX Control Flow

IF Conditionals

LOOP Control Flow

SET Functional

VAR Data Declarations

Command Select Category

Function Select Category

@ABS Math

@ACCUM Range (and Financial)

@ALLANCESTORS Member Set

@ALLOCATE Allocation

@ANCEST Member Set

@ANCESTORS Member Set

@ANCESTVAL Relationship Functions

@ATTRIBUTE Member Set

@ATTRIBUTEBVAL Relationship Functions

3-22 Hyperion


@ATTRIBUTESVAL Relationship Functions

@ATTRIBUTEVAL Relationship Functions

@AVG Math

@AVGRANGE Range (and Financial)

@CALCMODE Miscellaneous

@CHILDREN Member Set

@COMPOUND Range (and Financial)

@COMPOUNDGROWTH Range (and Financial)

@CONCATENATE Miscellaneous

@CORRELATION Statistical

@COUNT Statistical

@CURGEN Relationship Functions

@CURLEV Relationship Functions

@CURRMBR Member Set

@CURRMBRRANGE Range (and Financial)

@DECLINE Range (and Financial)

@DESCENDANTS Member Set

@DISCOUNT Range (and Financial)

@EXP Math

@FACTORIAL Math

@GEN Relationship Functions

@GENMBRS Member Set

@GROWTH Range (and Financial)

@IALLANCESTORS Member Set

@IANCESTORS Member Set

@ICHILDREN Member Set

@IDESCENDANTS Member Set

@ILSIBLINGS Member Set


Hyperion 3-23


@INT Math

@INTEREST Range (and Financial)

@IRDESCENDANTS Member Set

@IRR Range (and Financial)

@IRSIBLINGS Member Set

@ISACCTYPE Boolean

@ISANCEST Boolean

@ISCHILD Boolean

@ISDESC Boolean

@ISGEN Boolean

@ISIANCEST Boolean

@ISIBLINGS Member Set

@ISICHILD Boolean

@ISIDESC Boolean

@ISIPARENT Boolean

@ISISIBLING Boolean

@ISLEV Boolean

@ISMBR Boolean

@ISPARENT Boolean

@ISSAMEGEN Boolean

@ISSAMELEV Boolean

@ISSIBLING Boolean

@ISUDA Boolean

@LEV Relationship Functions

@LEVMBRS Member Set

@LIST Member Set

@LN Math

@LOG Math


3-24 Hyperion


@LOG10 Math

@LSIBLINGS Member Set

@MATCH Member Set

@MAX Math

@MAXRANGE Range (and Financial)

@MAXS Math

@MAXSRANGE Range (and Financial)

@MDALLOCATE Allocation

@MDANCESTVAL Relationship Functions

@MDPARENTVAL Relationship Functions

@MDSHIFT Range (and Financial)

@MEDIAN Statistical

@MEMBER Member Set

@MERGE Member Set

@MIN Math

@MINRANGE Range (and Financial)

@MINS Math

@MINSRANGE Range (and Financial)

@MOD Math

@MODE Statistical

@MOVAVG Forecasting

@MOVMAX Forecasting

@MOVMED Forecasting

@MOVMIN Forecasting

@MOVSUM Forecasting

@MOVSUMX Forecasting

@NAME Miscellaneous

@NEXT Range (and Financial)


Hyperion 3-25


@NEXTS Range (and Financial)

@NPV Range (and Financial)

@PARENT Member Set

@PARENTVAL Relationship Functions

@POWER Math

@PRIOR Range (and Financial)

@PRIORS Range (and Financial)

@PTD Range (and Financial)

@RANGE Member Set

@RANK Statistical

@RDESCENDANTS Member Set

@RELATIVE Member Set

@REMAINDER Math

@REMOVE Member Set

@ROUND Math

@RSIBLINGS Member Set

@SANCESTVAL Relationship Functions

@SHIFT Range (and Financial)

@SIBLINGS Member Set

@SLN Range (and Financial)

@SPARENTVAL Relationship Functions

@SPLINE Forecasting

@STDEV Statistical

@STDEVP Statistical

@STDEVRANGE Statistical

@SUBSTRING Miscellaneous

@SUM Math

@SUMRANGE Range (and Financial)


3-26 Hyperion


@SYD Range (and Financial)

@TODATE Date and Time

@TREND Forecasting

@TRUNCATE Math

@UDA Member Set

@VAR Math

@VARIANCE Statistical

@VARIANCEP Statistical

@VARPER Math

@WITHATTR Member Set

@XRANGE Member Set

@XREF 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.


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.


5) From the Calc&Retrieve1 worksheet, retrieve the data from the Essbase database.

Note that all values for “Pre Tax Profit” are “#Missing”.

Create and Run the Calc Script

6) In Essbase Application Manager, connect to the CALC:HLandS1 database.

7) Create a new calc script, and associate it with the HLandS1 outline.


Calc Script (new) CSSimple

Spreadsheet SS_Simple1.xls

3-28 Hyperion

8) In the new calc script file, add a command to calculate:
“Pre Tax Profit”;

9) Verify the calc script, and save it as CSSimple.

10) In Microsoft Excel, click the Calc&Retrieve1 tab of the SS_Simple1.xls spreadsheet.

11) Run the CSSimple calc script.

12) 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) Verify and save the calc script.



17) 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”.

19) In Essbase Application Manager, add the following to the end of the CSSimple Calc Script:Commission = .1 * Sales;

20) Verify and save the calc script.


Hyperion 3-29

23) Retrieve the data from the Essbase database.The commissions, calculated to be 10% of the sales, display.

24) If the expected results are not retrieved, continue to correct and execute the Calc Script, and retrieve the results until they are as expected.

25) Close the Excel spreadsheet (but leave Excel, open).

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


1) 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

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

2) Describe what each of the following calc scripts statements do:

a. January;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

4Calculation Script Commands

Chapter Objectives


• 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

Calculation Script Commands Hyperion Essbase Calc Scripts4
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.

Occasionally, the formula may be too complicated to present as a simple formula. For example, the method to calculate a member’s value may be conditional depending upon the value of another member.

In these situations, a calc member block structure is used.

Syntax

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.

mbrname (<calculation statement(s)>;);

4-2 Hyperion

Hyperion Essbase Calc Scripts Calculation Script Commands 4
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.

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 cross-dimensional operator is used on the left side of a formula.

Hyperion 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:


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 command’s use. Each command is also described, in detail, in this chapter.

Command Category Use

& - Prefaces a substitution variable in a calculation script.

AGG Functional Calculates database values by simply consolidating the defined parent/child relationships and ignoring all member formulas.

ARRAY Data Declares one-dimensional array variables.

CALC Functional Calculates all or selected subsets of the database.

CCONV Functional Calculates currency conversions (available if the optional Hyperion Essbase Currency Conversion product is installed.)

CLEARBLOCK Functional Clears blocks of data and sets them to #MISSING

CLEARDATA Functional Clears data values from the database and sets them to #MISSING.

DATACOPY Functional Copies a range of data cells to another range within the database.

FIX/ENDFIX Control Isolate a subset of the database for further processing.

4-4 Hyperion


IF/ ELSE/ ELSEIF/ ENDIF

Conditional Perform Boolean (logical) tests before performing a calculation.

LOOP/ENDLOOP

Control Specifies the number of times to repeat a series of calculations.

SET Functional Change the Essbase calculation environment during the execution of the Calc Script.

VAR Data Declares a temporary variable containing a single value.

Command Category Use

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

Example

Usage

&CurQtr;

becomes

Qtr1;

if the substitution variable &CurQtr has the value "Qtr1".

&variableName;

variableName - The name of the substitution variable set on the database.

4-6 Hyperion

AGG
The AGG command consolidates database values. An AGG command ignores all member formulas; it simply consolidates parent/child relationships.

Syntax

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. Calculate any members that are "leaf" members (that is, level 0).

2. Aggregate the dimension, using the AGG command.

3. 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.

AGG (dimList);

dimList - Name of a single dimension or a comma-delimited list of sparse dimensions.

Hyperion 4-7

ARRAY
The ARRAY command declares one-dimensional array variables.

Syntax

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.

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.

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)

The CALC ALL command allows for calculating the entire database.

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.

CALC ALL

Low Level data loaded

CALC ALLCALC ALL

Low Level data loaded

Hyperion 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

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

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.

4-10 Hyperion

CALC DIM
CALC DIM calculates the formulas and consolidations associated with all members of all specified dimensions.

Syntax

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 DIM(Dense1);CALC DIM(Sparse1);CALC DIM(Sparse2);CALC 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 thedense dimensions appear in dimList. The sparse dimensions are thencalculated 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.

CALC DIM (dimList);

dimList - Single dimension or comma-delimited list of dimensions to be calculated.

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

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 databaseoutline as time balance First.

The CALC LAST command calculates all members tagged in the databaseoutline as time balance Last. All other member calculations are ignoredduring this process.

The CALC TWOPASS command calculates all members tagged in thedatabase 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 thesecommands.

CALC AVERAGE;

CALC FIRST;

CALC LAST;

CALC TWOPASS;

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

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.

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.

4-14 Hyperion

CLEARBLOCK
The CLEARBLOCK command clears blocks of data and sets them to #MISSING.

Syntax

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.

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.

Hyperion 4-15

CLEARDATA
The CLEARDATA command clears data values from the database and sets them to #MISSING.

Syntax

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.

CLEARDATA mbrName;

mbrName - Any valid single member name or member combination, or a function that returns a single member or member combination.

4-16 Hyperion

DATACOPY
The DATACOPY command copies a range of data cells to another range within the database.

Syntax

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.

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.

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

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

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

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:

> Is greater than.

>= Is greater than or equal to.

< Is less than.

<= Is less than or equal to.

= = Is equal to.

< > or != Is not equal to.

4-20 Hyperion

Compound and complex logical tests can be created by using AND, OR and 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.

AND Logical AND linking operator for multiple value tests. Result is TRUE if both conditions are TRUE. Otherwise the result is FALSE.

OR Logical OR linking operator for multiple value tests. Result is TRUE if either condition is TRUE. Otherwise the result is FALSE.

NOT Logical NOT operator. Result is TRUE if condition is FALSE. Result is FALSE if condition is TRUE.*

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

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.

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

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

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.

SET AGGMISSG ON | OFF;

Hyperion 4-25

SET CACHE
The SET CACHE command specifies the size of the calculator cache.

Syntax

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.

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.

4-26 Hyperion

SET CALCHASHTBL
The SET CALCHASHTBL command optimizes the calculation of large, flat database outlines.

Syntax

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. .

SET CALCHASHTBL ON|OFF;

Hyperion 4-27

SET CALCPARALLEL
SET CALCPARALLEL enables parallel calculation in place of the default serial calculation.

Syntax

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.

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.

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

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.

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.

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

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.

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.

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

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).

SET FRMLBOTTOMUP ON|OFF;

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

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.

SET LOCKBLOCK HIGH | DEFAULT | LOW;

HIGH, DEFAULT, LOW - Levels defining the number of blocks that Hyperion Essbase can address concurrently.

Hyperion 4-35

SET MSG
The SET MSG command indicates the level of messaging that you wish to receive / review during your calculations.

Syntax

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.

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.

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

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.

SET NOTICE HIGH | DEFAULT | LOW;

HIGH, DEFAULT, LOW - Levels defining the frequency and number of completion notices.

Hyperion 4-37

Example
If the essbase.cfg file contains the following settings:

CALCNOTICEHIGH 50CALCNOTICEDEFAULT 20CALCNOTICELOW 5

then, in the calc script:

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

SET NOTICE DEFAULT;displays 20 completion notices at 5% intervals.

SET NOTICE LOW;displays 5 completion notices at 20% intervals.

4-38 Hyperion

SET UPDATECALC
The SET UPDATECALC command turns intelligent calculation on and off.

Syntax

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.

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.

Hyperion 4-39

SET UPTOLOCAL
The SET UPTOLOCAL command restricts consolidations to those parents with the same defined currency.

Syntax

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.

SET UPTOLOCAL ON | OFF;

4-40 Hyperion

VAR
The VAR command declares a temporary variable that contains a single value.

Syntax

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“, “Break3“and initializes them to #Missing.

VAR varName [= value];

varName - Name of the temporary variable.

value - parameter that declares the data value.

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%.


1) From Essbase Application Manager, clear all data from the HLandS1 database.

2) 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.

3) Open the SS_Fix spreadsheet.


5) 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.

6) 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.

7) From Essbase Application Manager, view the application log. Verify that the database calculated only the sales values for Albany, Buffalo, Budget, and Jan 1999.

8) Close the spreadsheet.


Calc Script (new) CSFix

Spreadsheet SS_Fix.xls

✍

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.



2) Open the CSDemo calc script. Save the calc script as CSIF.

3) Remove the line that does the variance calculation.

4) 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.

5) Open the SS_IF spreadsheet.

6) Lock and send the data in the Lock&Send sheet into the HLandS1 database.

7) From the Calc&Retrieve sheet, run the CSIF calc script. Perform a retrieval and notice the calculation results.

8) Ensure that the commission is being calculated correctly. If not, revise the calc script and rerun the calculation.



Calc Script CSDemo

Calc Script (new) CSIF

Spreadsheet SS_IF.xls

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.



2) 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.

3) Open the SS_X_Dim spreadsheet.

4) Lock and send the data in the Lock&Send sheet into the HLandS1 database.

5) From the Calc&Retrieve sheet, run the CSXDim calc script. Perform a retrieval and notice the calculation results.

6) 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.



Calc Script (new) CSXDim

Spreadsheet SS_X_Dim.xls

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 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 FIX…ENDFIX command can be used to restrict a calculation to a particular member or members, while the LOOP…ENDLOOP 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.

Hyperion 4-45


1) For each of the following commands, identify the type of command (Data Declaration, Control flow, Functional or Conditional)

Command Command Type

VAR

FIX

IF

CALC

SET

4-46 Hyperion

1) For each of the following commands, identify the type of command (Data Declaration, Control flow, Functional or Conditional)

Command Command Type

VAR Data Declaration

FIX Control flow

IF Conditional

CALC Functional

SET Functional

Hyperion 4-47


4-48 Hyperion

5Math Functions

Chapter Objectives


• Describe and demonstrate mathematical functions used in Calc Scripts

• Apply these mathematical functions to a series of incremental exercises

Math Functions Hyperion Essbase Calc Scripts5
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

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.

✍

5-2 Hyperion

Hyperion Essbase Calc Scripts Math Functions 5
Math Function Parameters
There are common parameters associated with the various math functions:

Summary of Math Functions

This table summarizes the Math Functions. Each function is also described, in detail, in this chapter.

expression Member name or mathematical expression that generates a numeric value.

mbrName1, mbrName2

Members from the same dimension whose results are to be calculated.

expList Comma-delimited list of members, variable names, functions, and numeric expressions, all of which return numeric values.

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

Function Used to calculate

@ABS The absolute value of number.

@AVG The average of all values in a list.

@EXP The value of e (the base of natural logarithms) raised to a power.

@FACTORIAL The factorial of number.

@INT The next lowest integer value of number.

@LN The natural logarithm (base e).

@LOG The logarithm calculation to a specified base.

@LOG10 The base-10 logarithm.

@MAX The maximum value all values in a list.

@MAXS The maximum value all values in a list. @MAXS enables skipping of #MISSING and 0 values.

Hyperion 5-3


@MIN The minimum value all values in a list.

@MINS The minimum value all values in a list. @MINS enables skipping of #MISSING and 0 values.

@MOD The modulus of a division operation of mbrName1 divided by mbrName2. The modulus is the remainder for an integer quotient.

@POWER The value of the specified expression raised to power.

@REMAINDER The value of the decimal portion of expression.

@ROUND The value rounded to a specified number of digits.

@SUM The summation of all the values in a list.

@TRUNCATE The integer portion of expression.

@VAR The difference between two values.

@VARPER The percent difference between two values.

Function Used to calculate

5-4 Hyperion

Detailed Description of Math Functions
@ABS

@ABS returns the magnitude of the expression as a positive number.

Syntax

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:

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.

@ABS (expression)

Value Abs

6.8 6.8

5.3 5.3

-0.4 0.4

-0.7 0.7

-5.3 5.3

-6.8 6.8

Hyperion 5-5

@AVG
The @AVG() function calculates and returns the average of all values in a list.

Syntax

Example

West=@AVG(SKIPNONE,California:Nevada);

This example produces the following results:

@AVG (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Cola Diet Cola

California 678 145

Oregon 160 150

Washington 130 #MI

Utah 130 170

Nevada 76 #MI

West 234.8 93

5-6 Hyperion

@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

Example

The following example is based on a variation of Sample Basic:

EXP = @EXP(Value);


Note

If the expression is less than -700 or greater than 700, Essbase returns#MISSING.

@EXP (expression)

Value EXP

10.7 44355.6

3.6 36.59823

1 2.718282

0.5 1.648721

-0.5 0.606531

Hyperion 5-7

@FACTORIAL
The @FACTORIAL() function returns the factorial of expression. The factorial of a number is equal to 1*2*3*...* number.

Syntax

Examples

Fact = @FACTORIAL(Value);


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.

@FACTORIAL(expression)

Value Fact

10.7 362880

3.6 36.59823

1 1

0.5 1

-0.5 #Missing

5-8 Hyperion

@INT
The @INT() function returns the next lowest integer value of expression.

Syntax

Example

Int = @INT(Value);

This yields the following result:

@INT (expression)

Value Int

6.8 6

5.3 5

-0.4 -1

-0.7 -1

-5.3 -6

-6.8 -7

Hyperion 5-9

@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

Example

LN_val = @LN(Value);LOG10_val = @LOG10(Value);LOG_val = @LOG(Value, 2);

This example produces the following result:

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.

@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).

Value LN_val LOG10_val LOG_val

.1 -2.30259 -1 -3.32193

100 4.60517 2 6.643856

1000 6.907755 3 9.965784

0 #Missing #Missing #Missing

-10 #Missing #Missing #Missing

5-10 Hyperion

@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

Examples

Qtr1_Max = @MAX(Jan:Mar);Qtr1_MaxS_Both = @MAXS(SKIPBOTH, Jan:Mar);Qtr1_MaxS_None = @MAXS(SKIPNONE, Jan:Mar);Qtr1_Min = @MIN(Jan:Mar);Qtr1_MinS_Both = @MINS(SKIPBOTH, Jan:Mar);Qtr1_MinS_None = @MINS(SKIPNONE, Jan:Mar);

@MAX (expList)

@MAXS (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

@MIN (expList)

@MINS (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Sales COGS Other

Jan 500 #Missing -500

Feb 0 1500 -350

Mar 700 2300 0

Qtr1_Max 700 2300 0

Qtr1_MaxS_Both 700 2300 -350

Qtr1_MaxS_None 700 2300 0

Qtr1_Min 0 #Missing -500

Qtr1_MinS_Both 500 1500 -500

Qtr1_MinS_None 0 #Missing -500

Hyperion 5-11

@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

Example

Mod = @MOD(Value, divisor);


@MOD (mbrName1, mbrName2)

Value divisor Mod

6.8 3 0.8

6.8 3.2 0.4

5.3 3 2.3

5.3 3.2 2.1

-5.3 3 -2.3

-5.3 3.2 -2.1

5-12 Hyperion

@POWER
The @POWER() function returns the value of the specified member or expression raised to power.

Syntax

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.

@POWER (expression, power)

power - Single member specification, variable name, function, or other numeric expression.

Hyperion 5-13

@REMAINDER
The @REMAINDER() function returns the value the decimal portion of the expression.

Syntax

Example

Remain = @REMAINDER(Value);


@REMAINDER (expression)

Value Remain

6.8 0.8

5.3 0.3

-0.4 -0.4

-0.7 -0.7

-5.3 -0.3

-6.8 -0.8

5-14 Hyperion

@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

Example

Round = @ROUND(Value);Round2 = @ROUND(Value, 2);

This yields the following results:

@ROUND (expression, [numDigits])

numDigits [optional] - Single-member specification, variable name, or other numeric expression that provides an integer value. Its default value is 0.

Value Round Round2

6.82145 7 6.82

5.32544 5 5.33

-0.42135 0 -0.42

-0.70688 -1 -0.71

-5.31234 -5 -5.31

-6.80988 -7 -6.81

Hyperion 5-15

@SUM
The @SUM() function returns the summation of all the values in a list.

Syntax

Example

West = @SUM(California:Nevada);


@SUM (expList)

Cola Diet Cola

California 678 145

Oregon 160 150

Washington 130 #MI

Utah 130 170

Nevada 76 #MI

West 1174 465

5-16 Hyperion

@TRUNCATE
@TRUNCATE returns only the integer portion of an expression.

Syntax

Example

Trunc = @TRUNCATE(Value);

This yields the following results:

@TRUNCATE (expression)

Value Trunc

6.82145 6

5.32544 5

-0.42135 0

-0.70688 0

-5.31234 -5

-6.80988 -6

Hyperion 5-17

@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

Example

Variance=@VAR(Value1, Value2);

This yields the following results (assuming Value1 and Value2 do not represent “Expense Accounts”):

@VAR (member1, member2)

Value1 Value2 Variance

6.82145 5.32544 1.49601

5.32544 6.82145 -1.49601

-5.31234 -6.80988 1.49754

-6.80988 -5.31234 -1.49754

5-18 Hyperion

@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

Example

“Variance %”=@VARPER(Value1, Value2);

This yields the following results (assuming Value1 and Value2 do not represent “Expense Accounts”):

@VARPER (member1, member2)

Value1 Value2 Variance %

6.82145 5.32544 28.09176

5.32544 6.82145 -21.931

-5.31234 -6.80988 21.99065

-6.80988 -5.31234 -28.1898

Hyperion 5-19

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 Connecticut’s “Average Sales”. The value is to be rounded to two decimals.


1) From Essbase Application Manager, clear all data from your HLandS1 database.

2) 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.

3) Save the new script as CSMath.

4) Open the SS_Math spreadsheet.


6) From the Calc&Retrieve sheet, run the CSMath calc script. Perform a retrieval and note the calculation results.

7) Ensure that the commission is calculated correctly. If not, revise the calc script and rerun the calculation.

8) Close the CSMath spreadsheet.


Calc Script (new) CSMath

Spreadsheet SS_Math.xls

5-20 Hyperion

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

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.

Hyperion 5-21


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.

5-22 Hyperion

1) For each of the following situations, identify the Math function that you apply.

Calculate the total of a series of values. @SUM

Compute the average of a collection of values. @AVG

What is the value of the next lowest integer to number?

@INT

Determine the minimum value in a list, excluding #MISSING and 0 values.

@MINS

Find the remainder when one number is divided by another to produce an integer quotient.

@MOD

Hyperion 5-23


5-24 Hyperion

6Boolean Functions

Chapter Objectives


• 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 Hyperion Essbase Calc Scripts6
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 Single-member specification

mbrList Comma-delimited list of members

rangeList Colon-delimited range of members, member set functions, or range functions

dimName Name of the specified dimension

6-2 Hyperion

Hyperion Essbase Calc Scripts Boolean Functions 6
Summary of Boolean Functions
This table summarizes the Boolean Functions. Each function is also described, in detail, in this chapter.

Function Tests

@ISACCTYPE Does current member have the specified accounts tag?

@ISANCEST Is the current member an ancestor of the specified member?

@ISCHILD Is the current member a child of the specified member?

@ISDESC Is the current member a descendant of the specified member?

@ISGEN Is the current member at the specified dimension generation

@ISIANCEST Is the current member an ancestor of the specified member, or the specified member itself?

@ISICHILD Is the current member a child of the specified member, or the specified member itself?

@ISIDESC Is the member being calculated a descendant of the specified member, or the specified member itself?

@ISIPARENT Is the current member the parent of the specified member, or the specified member itself?

@ISISIBLING Is the current member a sibling of the specified member, or the specified member itself?

@ISLEV Is the current member at the specified dimension level?

@ISMBR Is calculation being done for the specified member?

@ISPARENT Is the current member the parent of the specified member?

@ISSAMEGEN Is the current member the same generation as the specified member?

@ISSAMELEV Is the current member the same level as the specified member?

Hyperion 6-3


@ISSIBLING Is the current member a sibling of the specified member?

@ISUDA Does the current member of the specified dimension have the specified user-defined attribute (UDA) at the time of the calculation?

Function Tests

6-4 Hyperion

@ISACCTYPE
The @ISACCTYPE() function returns TRUE if the current member has the specified accounts tag.

Syntax

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;

@ISACCTYPE(tag)

tag - Valid account tag defined in the current database. Any of the following tags may be used: First, Last, Average, Expense, and Two-Pass.

Hyperion 6-5

@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

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.

@ISANCEST(mbrName)

@ISIANCEST(mbrName)

6-6 Hyperion

@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

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.

@ISCHILD(mbrName)

@ISICHILD(mbrName)

Hyperion 6-7

@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

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.

@ISDESC (mbrName)

@ISIDESC (mbrName)

6-8 Hyperion

@ISGEN
The @ISGEN() function returns TRUE if the current member of the specified dimension is in the specified generation.

Syntax

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.

@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.

Hyperion 6-9

@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

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.

@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.)

6-10 Hyperion

@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

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.

@ISMBR (mbrName | rangeList | mbrList)

Hyperion 6-11

@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

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.

@ISPARENT(mbrName)

@ISIPARENT(mbrName)

6-12 Hyperion

@ISSAMEGEN
The @ISSAMEGEN() function returns TRUE if the current member is the same generation as the specified member.

Syntax

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

Example


@ISSAMELEV(Sales)returns FALSE for Total Expenses .

@ISSAMELEV(Jan)returns TRUE for Apr, Jul, Oct.

@ISSAMEGEN(mbrName)

@ISSAMELEV(mbrName)

Hyperion 6-13

@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

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.

@ISSIBLING(mbrName)

@ISISIBLING(mbrName)

6-14 Hyperion

@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

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.

@ISUDA(dimName,UDAStr)

UDAStr - user-defined attribute (UDA) name string.

Hyperion 6-15

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:

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.

Condition1 Condition2 Condition1 AND Condition2

Condition1 OR Condition2

NOT (Condition1)

True True True True False

True False False True False

False True False True True

False False False False True

6-16 Hyperion

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.


1) From Essbase Application Manager, clear all data from your HLandS1 database.

2) 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.

3) Save the new script as CSBool.

4) Open the SS_Bool spreadsheet.

5) Lock and send the 1999 Actual Sales data in the Lock&Send sheet to the HLandS1 database.

6) From the Calc&Retrieve sheet, run the CSBool calc script. Perform a retrieval and compare the calculation results to the Expected Values column.

7) Ensure that the projected sales are calculated correctly. If not, revise the calc script and rerun the calculation.

8) Close the SS_Bool spreadsheet.


Calc Script (new) CSBool

Spreadsheet SS_Bool.xls

Hyperion 6-17

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


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

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? @ISMBR

Perform a calculation for East, and all the cities in the East market.

@ISICHILD

Perform a calculation for all level one members of the Market Dimension.

@ISLEV

Perform a calculation for “New York”, East and Market, only.

@ISIANCEST

Perform a calculation for all accounts that are identified as “Expense”.

@ISACCTYPE

6-20 Hyperion


Hyperion 6-21


6-22 Hyperion

7Member Set Functions

Chapter Objectives


• 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

Member Set Functions Hyperion Essbase Calc Scripts7
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 Single dimension name specification.

mbrName,

mbrName1,

mbrName2

Specifies a single member.

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.

7-2 Hyperion

Hyperion Essbase Calc Scripts Member Set Functions 7
Summary of Member Set Functions
This table summarizes the Member Set Functions. Each function is also described, in detail, in this chapter.

Function Used to generate a list containing

@ALLANCESTORS All the ancestors of that member, including ancestors of any occurrences of the specified member as a shared member.

@ANCEST The ancestor at the specified generation or level in the specified dimension of the current member being calculated.

@ANCESTORS All ancestors of the specified member or those up to the specified generation or level.

@ATTRIBUTE All base members that are associated with the specified attribute member.

@CHILDREN All members in the level immediately below the specified member.

@CURRMBR The member that is currently being calculated in the specified dimension.

@DESCENDANTS All descendants of the specified member, or those down to the specified generation or level.

@GENMBRS All members with the specified generation number or generation name in the specified dimension.

@IALLANCESTORS The specified member and all the ancestors of that member, including ancestors of any occurrences of the specified member as a shared member.

@IANCESTORS The specified member and all ancestors of the specified member or those up to the specified generation or level.

@ICHILDREN The specified member and all members in the level immediately below the specified member.

@IDESCENDANTS The specified member and all descendants of the specified member, or those down to the specified generation or level.

@ILSIBLINGS The specified member and all members that share the same parent as that member and precede that member in the database outline.

@IRSIBLINGS The specified member and all members that share the same parent as that member and that follow that member in the database outline.

Hyperion 7-3


@IRDESCENDANTS The specified member and all descendants of the specified member (including descendants of shared members), or those down to the specified generation or level.

@ISIBLINGS The specified member and all siblings of that member.

@LEVMBRS All members with the specified level number or level name in the specified dimension.

@LIST A collection of individual items that are to be passed to functions that require list arguments.

@LSIBLINGS All members that share the same parent as the specified member and precede that member in the database outline.

@MATCH All members whose names match a specified pattern.

@MEMBER The member with the name that is provided as a character string.

@MERGE The union of two member lists that are to be passed to another function.

@PARENT The parent of the current member being calculated in the specified dimension.

@RANGE A member list that crosses the specified member from one dimension with the specified member range from another dimension.

@RDESCENDANTS All descendants of the specified member (including descendants of shared members), or those down to the specified generation or level.

@RELATIVE All members at the specified generation or level that are above or below the specified member in the database outline.

@REMOVE A list from which with selected values have been removed.

@RSIBLINGS All members that share the same parent as the specified member and that follow that member in the database outline.

@SIBLINGS All siblings of the specified member.

@UDA Members with a common user-defined attribute (UDA).

@WITHATTR All base members that are associated with an attribute that satisfies a specified condition.


7-4 Hyperion


@XRANGE * 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

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.

@ALLANCESTORS(mbrName)

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

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.

@ANCEST(dimName, genLevNum [, mbrName])

Hyperion 7-7

@ANCESTORS
The @ANCESTORS() function returns all ancestors of the specified member or those up to a specified generation or level.

Syntax

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 specifiedmember, 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.

@ANCESTORS (mbrName [, genLevNum | genLevName])

7-8 Hyperion

@ATTRIBUTE
The @ATTRIBUTE() function generates a list of all base members that are associated with the specified attribute member.

Syntax

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.

@ATTRIBUTE (attMbrName)

attMbrName - Single attribute member name or member combination.

Hyperion 7-9

@CHILDREN
The @CHILDREN () function returns all children of the specified member, excluding the specified member.

Syntax

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.

@CHILDREN(mbrName)

7-10 Hyperion

@CURRMBR
The @CURRMBR() function returns the member that is currently being calculated in the specified dimension.

Syntax

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.


@CURRMBR(dimName)

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

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.

@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.

7-12 Hyperion

@GENMBRS
The @GENMBRS() function returns all members with the specified generation number or generation name in the specified dimension.

Syntax

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.

@GENMBRS(dimName,genName|genNum)

genNum - An positive integer value that defines the absolute generation number.

or

genName - Generation name from the specified dimension.

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

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.

@IALLANCESTORS(mbrName)

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

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 specifiedmember, 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.

@IANCESTORS (mbrName [, genLevNum | genLevName])

Hyperion 7-15

@ICHILDREN
The @ICHILDREN() function includes the specified member and all members in the level immediately below the specified member.

Syntax

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.

@ICHILDREN(mbrName)

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

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.

@IDESCENDANTS(mbrName [, genLevNum| genLevName])


or


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

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.

@ILSIBLINGS(mbrName)

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

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).

@IRDESCENDANTS(mbrName [, genLevNum| genLevName])


or


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

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.

@IRSIBLINGS (mbrName)

Hyperion 7-21

@ISIBLINGS
The @ISIBLINGS() function returns the specified member and all siblings of that member.

Syntax

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.

@ISIBLINGS (mbrName)

7-22 Hyperion

@LEVMBRS
The @LEVMBRS() function returns all members with the specified level number or level name in the specified dimension.

Syntax

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.

@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.

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

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.

@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.

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

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.

@LSIBLINGS (mbrName)

7-26 Hyperion

@MATCH
The @MATCH function performs wildcard member selections.

Syntax

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 ("").

@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 ?).

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

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));

@MEMBER (String)

String - A string (enclosed in double quotation marks) or a function that returns a string

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

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.

@MERGE(list1, list2)

list1 - The first list of member specifications to be merged.

list2 - The second list of member specifications to be merged.

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

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")));


@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.

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

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)));


@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.

Sales Prod Count

Colas 678 #MI

Root Beer 551 #MI

Cream Soda 663 #MI

Fruit Soda 587 #MI

Diet Drinks #MI #MI

Product 2479 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

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).

@RDESCENDANTS(mbrName [, genLevNum| genLevName])


or


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

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.

@RELATIVE (mbrName, genLevNum | genLevName)

Hyperion 7-35

@REMOVE
The @REMOVE() function removes values or members in one list from another list.

Syntax

Example


@REMOVE(@CHILDREN(East),@LIST("New York",Connecticut)) returns Massachusetts, Florida, New Hampshire.

@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.

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

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.

@RSIBLINGS(mbrName)

Hyperion 7-37

@SIBLINGS
The @SIBLINGS() function returns all siblings of the specified member. This function excludes the specified member.

Syntax

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.

@SIBLINGS (mbrName)

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

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.

@UDA (dimName, udaStr)

udaStr - User-defined attribute string 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

The following operators are supported:

@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.

Operator Meaning

> Greater than

>= Greater than or equal to

< Less than

<= Less than or equal to

= = Equal to

<> or != Not equal to

IN 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:

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.

Condition Returns

@WITHATTR(Population,">","18000000") New York, California, Texas

@WITHATTR(Population,">=",10000000) where 10,000,000 is a constant

New York, Florida, California, Texas, Illinois, Ohio

@WITHATTR(Ounces,"<","16") Cola, Diet Cola, Old Fashioned, Sasparilla Diet Cream

@WITHATTR("Intro Date","<=", @TODATE("mm-dd-yyyy","04-01-1996"))

Cola, Diet Cola, Caffeine Free Cola, Old Fashioned

@WITHATTR("Pkg Type","= =",Can) Cola, Diet Cola, Diet Cream

@WITHATTR(Caffeinated,"<>",True) Caffeine Free Cola, Sasparilla, Birch Beer, Grape, Orange, Strawberry

@WITHATTR("Population","IN",Medium) Massachusetts, Florida, Illinois, Ohio

Hyperion 7-41

Date @WITHATTR("Intro Date","<",@TODATE("mm-dd-yyyy","07-26-1996")) 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

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, 1998->Sep, ... 1998->Dec, 1999->Jan, 1999->Feb, ... 1999->Dec, 2000->Jan, 2000->Feb, ... 2000->Dec, 2001->Jan, 2001->Feb, 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 cross-dimensional 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.

@XRANGE (mbrName1, mbrName2)

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.



2) 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.

3) Open the SS_Member spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. Notice that the values in pink have not been calculated yet.

6) From the Calc&Retrieve sheet, run the CSmember calc script. Perform a retrieval and notice the calculation results within the pink cells.

7) 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.



Calc Script (new) CSMember

Spreadsheet SS_Member.xls

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


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.

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.)

All states that begin with the letter “N”. @MATCH

All the states in the East market, and East, itself. @ICHILDREN or @IDESCENDANTS

All level one members of the Market Dimension. @LVLMBRS

“New York” and all its ancestors. @IANCESTORS

All states whose population is greater than 6,000,000. @WITHATTR

Hyperion 7-47


7-48 Hyperion

8Relationship Functions

Chapter Objectives


• Explain the purpose and use of relationship functions to generate member lists

• Practice using the relationship functions in a series of incremental exercises

Relationship Functions Hyperion Essbase Calc Scripts8
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:

Relationship Function Parameters

There are common parameters associated with the various relationship functions:

Market Product

East Region Family01

- New York State - Group 01-1

-- Albany -- SKU01-1-1

-- Buffalo --SKU01-1-2

- Connecticut - Group 01-2

West Region -- SKU01-2-1

- California -- SKU01-2-2

-- Los Angeles

-- San Francisco

dimName, dimName1,...

dimNameX

Single dimension name specification.

mbrName, Any valid single member name or member combination (or a function that returns a single member or member combination).

genLevNum, genLevNum1,

genLevNumX,

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.

8-2 Hyperion

Hyperion Essbase Calc Scripts Relationship Functions 8
Summary of Relationship Functions
This table summarizes the Relationship Functions. Each function is also described, in detail, in this chapter.

Function Returns

@ANCESTVAL The value of a specified ancestor of the current member being calculated.

@ATTRIBUTEBVAL The associated attribute value from the specified boolean attribute dimension.

@ATTRIBUTESVAL The associated attribute value from the specified string attribute dimension.

@ATTRIBUTEVAL The associated attribute value from the specified numeric or date attribute dimension.

@CURGEN The generation number of the current member combination for the specified dimension.

@CURLEV The level number of the current member combination for the specified dimension.

@GEN The generation number of the specified member.

@LEV The level number of the specified member.

@MDANCESTVAL Multi-dimensional ancestor-level value for the current member being calculated.

@MDPARENTVAL Multi-dimensional parent-level data for the current member being calculated.

@PARENTVAL The parent value along the specified dimension for the member being calculated

@SANCESTVAL Ancestor-level data based on the shared ancestor value of the current member being calculated.

@SPARENTVAL Parent-level data based on the shared parent value of the current member being calculated.

@XREF Values incorporated from a different Essbase database.

Hyperion 8-3

@ANCESTVAL
The @ANCESTVAL() function returns the ancestor values of a specified member combination.

Syntax

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 member’s 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 member’s 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);


@ANCESTVAL (dimName, genLevNum [, mbrName])

Sales SKU Share

SKU01-1-1 510 26.0

SKU01-1-2 520 26.5

- Group01-1 1030 52.5

SKU01-2-1 430 21.9

SKU01-2-2 500 25.5

- Group01-2 930 47.4

--- Family01 1960 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

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:

@ATTRIBUTEBVAL(attDimName)

attDimName - The name of a Boolean attribute dimension.

Current Member Return Value

100-10 True

100-20 True

100-30 False

100 #MISSING

Hyperion 8-5


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.

200-10 True

200-20 True

200-30 False

200-40 False

200 #MISSING

Product #MISSING

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

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 Type:Can} 100-20 {Pkg Type:Can} 100-30 {Pkg Type:Bottle} 200 200-10 {Pkg Type:Bottle} 200-20 {Pkg Type:Bottle} 200-30 {Pkg Type:Bottle} 200-40 {Pkg Type:Bottle}Pkg Type Attribute {Type: Text} Bottle Can

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:

@ATTRIBUTESVAL(attDimName)

attDimName - The name of a text attribute dimension.

Current Member Return Value

100-10 Can

100-20 Can

100-30 Bottle

100 (empty string)

Hyperion 8-7


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.


200-10 Bottle

200-20 Bottle

200-30 Bottle

200-40 Bottle

200 (empty string)

Product (empty string)

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

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.


Profit Profit Per Ounce ======== ================Cola 4593 382.75

Notes

The @ATTRIBUTEVAL function works only with numeric and date attribute dimensions.


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.

@ATTRIBUTEVAL(attDimName)

attDimName - Single dimension specification for a numeric or date attribute dimension.

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

Example


@CURGEN(Year)produces the following results:

@CURGEN(dimName)

Current Member Value

Year 1

Qtr2 2

Oct 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 bottom-most descendant.

Syntax

Example


@CURLEV(Year) produces the following results:

@CURLEV(dimName)

Current Member Value

Year 2

Qtr3 1

Aug 0

Hyperion 8-11

@GEN
The @GEN() function returns the generation number of the specified member.

Syntax

Example


@GEN(mbrName)

@GEN(Year) 1

@GEN(Qtr3) 2

8-12 Hyperion

@LEV
The @LEV() function returns the level number of the specified member.

Syntax

Example


@LEV(mbrName)

Function Level Returned

@LEV(Margin) 1

@LEV("New York") 0

Hyperion 8-13

@MDANCESTVAL
The @MDANCESTVAL() function returns ancestor-level data from multiple dimensions based on the current member being calculated.

Syntax

Notes

@MDANCESTVAL(2, Market, 2, Product, 2, Sales) refers to the Sales value found by navigating to generation 2 of the current member’s Market hierarchy and to generation 2 of the current member’s 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:

@MDANCESTVAL(dimCount, dimName1, genLevNum1... dimNameX, genLevNumX [,mbrName])

dimCount - Integer value that defines the number of dimensions from which ancestor values are being returned.

Sales Marketing

Albany SKU01-1-1 300 60

SKU01-1-2 200 40

SKU01-2-1 400 80

SKU01-2-2 100 20

East Region Family01 2000 400

8-14 Hyperion

@MDPARENTVAL
The @MDPARENTVAL() function returns parent-level data from multiple dimensions based on the current member being calculated.

Syntax

Notes

@MDPARENTVAL(2, Market, Product, Sales) refers to the Sales value found by navigating to the current member’s 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:

@MDPARENTVAL(numDim, dimName1,... dimNameX [,mbrName])

numDim - Integer value that defines the number of dimensions from which parent values are being returned.

Sales Marketing

New York State Group01-1 300 60

Group01-2 200 40

Connecticut Group01-1 100 20

Group01-2 400 80

East Region Family01 1000 200

Hyperion 8-15

@PARENTVAL
The @PARENTVAL() function returns the parent value along the specified dimension for the member being calculated.

Syntax

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 member’s 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:

@PARENTVAL (dimName [, mbrName])

Sales Market Share

Albany 100 25

Buffalo 300 75

New York State 400 40

Los Angeles 360 60

San Francisco 240 40

California 600 60

Market 1000 100

8-16 Hyperion

@SANCESTVAL
The @SANCESTVAL() function returns ancestor-level data based on the shared ancestor value of the current member being calculated.

Syntax

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

@SANCESTVAL (rootMbr,genLevNum [, mbrName])

rootMbr - Defines a member that is used to search for the nearest occurrence of an ancestor of a shared member.

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:

Notes


Sales Marketing

100-10 300 37.5

100-20 200 13.3

100 500 #Missing

200-10 100 12.5

200-30 400 26.7

200 900 #Missing

100-10 300 37.5

200-10 100 12.5

Diet 400 50

100-20 200 13.3

200-30 400 26.7

Caffeine Free 600 40

8-18 Hyperion

@SPARENTVAL
The @SPARENTVAL() function returns parent-level data based on the shared parent value of the current member being calculated.

Syntax

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 SHARED 200-10 SHARED Caffeine Free ~ 100-20 SHARED 200-20 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;

@SPARENTVAL(RootMbr [, mbrName])

RootMbr - Defines a member that is used to search for the nearest occurrence of a parent of a shared member.

Hyperion 8-19

which produces the following result:
Notes


Sales Marketing

100-10 300 37.5

100-20 200 13.3

100 500 #Missing

200-10 100 12.5

200-30 400 26.7

200 900 #Missing

100-10 300 37.5

200-10 100 12.5

Diet 400 50

100-20 200 13.3

200-30 400 26.7

Caffeine Free 600 40

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

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

@XREF (locationAlias [, mbrList])

locationAlias - A location alias for the data source.

mbrList - A comma-delimited list of member names that qualify the @XREF query.

Hyperion 8-21

Example 1
For this example, consider the following two databases:

Main Database

Year Qtr1 Qtr2Measures Sales Units Product 100 100-10 100-20Market East WestScenario 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);

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);

Hyperion 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);

� 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.

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.

To define a location alias:

1) In the server window of the Essbase Application Manager, select the application and database that accesses the source data (that is, the data target).

8-24 Hyperion

2) Select Database / Location Aliases.
The Location Aliases dialog displays:

3) In the Alias text box, type the alias name for the remote database.

4) In the Server text box, type the server name or IP address for the remote database.

5) In the Application text box, type the application name for the remote database.

6) In the Database text box, type the database name for the remote database.

7) Type the User name and Password in the respective text boxes.

8) Click Set.The location alias is added to the alias list:

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.



2) 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.

3) Open the SS_Ancest spreadsheet.


5) 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.

6) From the Calc&Retrieve sheet, run the CSAncest calc script.

7) Retrieve from the Essbase database into this sheet.

8) 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.



Calc Script (new) CSAncest

Spreadsheet SS_Ancest.xls

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.



2) 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.

3) Open the SS_Currmbr spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. Notice that the values “Average Inventory” column are #Missing.

6) From the Calc&Retrieve sheet, run the CSCrmbr calc script. Perform a retrieval.

7) 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.



Calc Script (new) CSCrmbr

Spreadsheet SS_Currmbr.xls

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.



2) Review the structure of the Calc:COGS database.

Set up Location Alias

3) In the server window, select CALC:HLANDS1.

4) From the main menu, select Database / Location Aliases.The Location Aliases window displays.

5) In the Location Aliases window, type the following:

6) Click OK.


CALC:COGS

Calc Script (new) CSXref

Spreadsheet SS_Xref.xls

In Field... Type...

Alias COGS

Server Localhost

Application CALC

Database COGS

User name trnadmin

Password Hyperion

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) Open the SS_Xref spreadsheet.


10) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. Notice that the values in the COGS column display #Missing.

11) From the Calc&Retrieve sheet, run the CSXref calc script. Perform a retrieval and notice the results in the COGS column.

12) 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.


Hyperion 8-29

Unit Summary
Relationship functions look up specific values within the database based oncurrent cell location and a series of parameters. You can use these functionsto refer to another value in a data series. Relationship functions have animplicit current member argument; that is, these functions are dependenton the current member's position.

8-30 Hyperion


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

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.

@ATTRIBUTEVAL

For current member “Diet Cola”->Massachusetts, the value of 100->East.

@MDPARENTVAL

A value from another database. @XREF

The level number of the current member. @CURLEV

For current member “Diet Cola”->Massachusetts, the value of 100->Massachusetts.

@PARENTVAL

8-32 Hyperion

9Range and Financial Functions

Chapter Objectives


• 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

Range and Financial Functions Hyperion Essbase Calc Scripts9
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 Specifies a single member.

rangeList 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.


Used in conjunction with an expList, this parameter indicates how missing and zero values are to be processed.





dimName,

dimName1,

DimNameX

Single dimension name specification.


9-2 Hyperion

Hyperion Essbase Calc Scripts Range and Financial Functions 9
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 Returns

@ACCUM Accumulated total values across the specified range.

@AVGRANGE The average value of the specified member across the specified range.

@COMPOUND Amount of compound interest on a series of periodic deposits.

@COMPOUNDGROWTH The accumulation of principal and interest on a single payment over time.

@CURRMBRRANGE A member list based on the relative position of the current member being calculated.

@DECLINE The depreciation amount per period that an asset may be depreciated using the declining balance method.

@DISCOUNT The discounted value at the beginning of the first period for amounts at end each period.

@GROWTH A series of values that represent a linear growth of an initial value across the specified range.

@INTEREST The amount of simple interest of a value at the specified rate.

@IRR The Internal Rate of Return on a cash flow.

@MAXRANGE The maximum value of the specified member across the specified range of members.

@MAXSRANGE The maximum value of the specified member across the specified range of members allowing for skipping of #MISSING and/or 0 values.

@MDSHIFT A series of data values that are copied from shifted multiple dimension ranges.

@MINRANGE The minimum value of the specified member across the specified range of members.

Hyperion 9-3


@MINSRANGE The minimum value of the specified member across the specified range of members allowing for skipping of #MISSING and/or 0 values.

@NEXT The specified subsequent cell value of the range for the specified member.

@NEXTS The specified subsequent cell value of the range for the specified member providing the option to skip #MISSING and/or zero values.

@NPV The Net Present Value of an investment based on the series of payments and income.

@PRIOR The specified previous cell value of the range for the specified member.

@PRIORS The specified subsequent cell value of the range for the specified member providing the option to skip #MISSING and/or zero values.

@PTD The period-to-date values of members in the dimension tagged as Time.

@SHIFT The specified subsequent or previous cell value of the range for the specified member.

@SLN The amount per period that an asset in the current period may be depreciated using a straight-line depreciation method.

@SUMRANGE The summation of all the values of the specified member across the specified range.

@SYD The amount per period that an asset in the current period may be depreciated using the sum of the years’ digits method.

Function Returns

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

Example

In this example, Accum_Asset is calculated using the following formula:

"Accum Asset" = @ACCUM(Asset, FY1992:FY1995);


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.

@ACCUM (mbrName [, rangeList])

FY1990 FY1991 FY1992 FY1993 FY1994 FY1995

Asset 9,000 0 1,000 0 2,500 1,500

Accum_Asset #MI #MI 1,000 1,000 3,500 5,000

Hyperion 9-5

@AVGRANGE
The @AVGRANGE() function returns the average value of the specified member across the specified range.

Syntax

Example

The following example is based on the Sample Basic database.

West=@AVGRANGE(SKIPNONE,Sales,@CHILDREN(West));

This example produces the following (partial) results:

Notes

The @AVGRANGE function accepts the @ATTRIBUTE member set function as a member range.

@AVGRANGE(SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [, rangeList])

Jan Feb Mar

California 100 100 100

Oregon 200 200 200

Washington 300 300 0

Utah 400 400 400

Nevada 500 #Missing 500

West 300 200 240

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

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);


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.

@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.

FY1991 FY1992 FY1993 FY1994 FY1995

Credit Rate 0.0525 0.0525 0.0525 0.0525 0.0525

Deposit 0 2,000 0 3,000 0

Compound Interest

0 105 110.5125 273.8144 288.1897

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

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);


Notes

You can change the growth rate from period to period by placing a nonzero value in the current period's rateMbrConst cell.

@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.

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Principal 2000 - - - - -

Rate 0.0525 0.0525 0.0525 0.0525 0.0525 0.0525

Growth 2105 2215.51 2331.83 2454.25 2583.10 2718.71

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

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.

@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.

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)

Consider the following statement:

@CURRMBRRANGE(Year,LEV,0,,0)

Current Member Returns

Jan (Jan, Feb)

Feb (Jan, Feb, Mar)

Mar (Feb, Mar, Apr)

Current Member Returns

Jan (Jan)

Feb (Jan, Feb)

Mar (Jan, Feb, Mar)

Apr (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:

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.

Jan Feb Mar Apr Nov Dec

Opening Inventory

100 110 120 130 . . . 200 210

Average Inventory

105 110 115 120 . . . 155 155

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

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);


@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.

FY1991 FY1992 FY1993 FY1994

Asset 9,000 0 0 0

Residual 750 0 0 0

Life 5 0 0 0

Decline Dep 3,600 2,160 1,296 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

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);


Notes

More than one value can be discounted simultaneously in this manner.

@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.

FY1991 FY1992 FY1993 FY1994 FY1995

Cash 1000.00 1000.00 1000.00 1000.00 1000.00

Credit Rate 0.05 0.05 0.05 0.05 0.05

Discount 952.38 907.03 863.84 822.70 783.53

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

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);


@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).

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Principal Amount

1,000 0 2,000 0 0 0

Growth Rate

0.05 0.07 0.08 0.08 0.1 0.1

Growth Amount

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

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);

@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.

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Balance 2000 3000 -1000 3000 9000.00 -6000

Credit Rate

0.065 0.065 0.065 0.065 0.065 0.065

Borrow Rate

0.1125 0.1125 0.1125 0.1125 0.1125 0.1125

Amount 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

Example

Example

This example calculates the Internal Rate of Return (Return) on a cash flow (Cash).

Return = @IRR(Cash,0,FY1991:FY1996);


Notes

Essbase returns #MISSING from calculator function @IRR if all cash flows are zero.

@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.

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Cash (1,000) 500 500 500 500 500

Return 0.41 0.41 0.41 0.41 0.41 0.41

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

Example


Qtr1 = @MAXRANGE(Sales,@CHILDREN(Qtr1));


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.

@MAXRANGE (mbrName [ ,rangeList])

Jan Feb Mar Qtr1

Sales 678 645 675 678

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

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:

Example 2

Qtr1_Max = @MAXSRANGE (SKIPNONE, OtherInc_Exp, @CHILDREN(Qtr1));

produces the following results:

@MAXSRANGE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [ ,rangeList])

Jan Feb Mar Qtr1_Max

Other_Exp -500 #MISSING -250 --500

COGS 0 1500 2300 1500

Jan Feb Mar Qtr1_Max

Other_Exp -500 #MISSING -250 0

COGS 0 1500 2300 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

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:

@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.

Jan Feb Mar

Prior Year Opening Inventory

110 120 130

Budget Ending Inventory

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

Example


Qtr1 = @MINRANGE(Sales,Jan:Mar);


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.

@MINRANGE (mbrName [ ,rangeList])

Jan Feb Mar Qtr1

Sales 678 645 675 645

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

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:

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:

@MINSRANGE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, mbrName [,rangeList])

Jan Feb Mar Qtr1_Min

COGS #MISSING 1500 2300 1500

Other_Exp 500 350 0 350

Jan Feb Mar Qtr1_Min

COGS #MISSING 1500 2300 #Missing

Other_Exp 500 350 0 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

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);


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.

@NEXT (mbrName [, n, rangeList])

n - signed integer.

Jan Feb Mar Apr May Jun

Cash 100 90 120 110 150 100

Next Cash

90 120 110 150 100 #MI

Two Cash

120 110 150 100 #MI #MI

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

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);

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.

@NEXTS(SKIPNONE | SKIPMISSING | SKIPZERO | | SKIPBOTH mbrName[,n,rangeList])

n - signed integer.


Cash 1100 #MI 1000 1300 0 1400

Next Cash

1000 1000 1300 1400 1400 #MI

Two Cash

1000 1300 1400 #MI #MI #MI

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

Example

In this example, Value is calculated with the following formula:

Value = @NPV(Cash, Rate, 0, FY1991:FY1996);

This example produces the following report:

@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.

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Cash (1,000) 500 500 500 500 500

Rate .05

Value 1547.62 1547.62 1547.62 1547.62 1547.62 1547.62

9-28 Hyperion

@PRIOR
The @PRIOR() function returns the nth previous cell member from mbrName in rangeList.

Syntax

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);


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.

@PRIOR (mbrName [, n, rangeList])

n - signed integer.


Value 1100 1200 1300 1400 1500 1600

Prev #MI 1100 1200 1300 1400 1500

Prev2 #MI #MI 1100 1200 1300 1400

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

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);


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.

@PRIORS(SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH mbrName[,n, rangeList])

n - signed integer.


Value 1100 #MI 1300 1400 0 1600

Prev #MI 1100 1100 1300 1400 1400

Prev2 #MI #MI #MI 1100 1300 1300

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 period’s first and last value, respectively.

Syntax

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);


@PTD (timePeriodList)

timePeriodList - Range of members from the dimension tagged as Time.

Sales Opening Inventory Ending Inventory

Jan 1000 1000 1100

Feb 1000 1100 1200

Mar 1000 1200 1300

Qtr1 3000 3000 3000

Apr 1000 1300 1400

May 1000 1400 1500

Jun 1000 1500 1600

Qtr2 3000 3000 3000

QTD 2000 1300 1500

YTD 5000 1000 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

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);


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).

@SHIFT (mbrName [,n, rangeList])

n - signed integer.


Value 1100 1200 1300 1400 1500 1600

Prev #MI 1100 1200 1300 1400 1500

Next 1200 1300 1400 1500 1600 #MI

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

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);


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.

@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.

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Asset 9000

Residual 750

Life 5

SLN Dep 1650 1650 1650 1650 1650 #MI

Hyperion 9-33

@SUMRANGE
The @SUMRANGE() function returns the summation of all the values of the specified member across the specified range.

Syntax

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);


@SUMRANGE(mbrName [, rangeList])

Sales

Jan 100

Feb 100

Mar 100

Qtr1 300

Apr 100

May 100

Jun 100

Qtr2 300

Partial Year 400

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

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);


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.

@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.

FY1991 FY1992 FY1993 FY1994 FY1995 FY1996

Asset 9000

Residual 750

Life 5

SYD Dep 2750 2200 1650 1100 550 #MI

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 January’s ending inventory and additions.



2) 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 January’s ending inventory and additions. Save the new script as CSPrior.

3) Open the SS_Prior spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The values in yellow have not been calculated.

6) From the Calc&Retrieve sheet, run the CSPrior calc script. Perform a retrieval and notice the calculation results within the yellow cells.

7) 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.



Calc Script (new) CSPrior

Spreadsheet SS_Prior.xls

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 family’s profits for the subsequent years.


2) 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.

3) Open the SS_Irr spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The values in yellow have not been calculated.

6) From the Calc&Retrieve sheet, run the CSIrr calc script. Perform a retrieval and notice the ROI calculation results.

7) 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.



Calc Script (new) CSIrr

Spreadsheet SS_Irr.xls

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 aseries of values internally based on the range specified.

Financial functions execute specialized financial calculations.

9-38 Hyperion


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

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?

@MAXRANGE

What is the value of sales three months after the month currently being processed?

@NEXT

What is the average amount of monthly sales? @AVGRANGE

What is the amount of compound interest for a series of debt payments?

@COMPOUND

What is the internal rate of return on an investment? @IRR

9-40 Hyperion

10Allocation Functions

Chapter Objectives


• Explain the purpose and use of Allocation functions to generate member lists

• Practice using the Allocation functions in a series of incremental exercises

Allocation Functions Hyperion Essbase Calc Scripts10
Using Allocation Functions
Allocation functions allocate values that are input at the parent level. Thevalues are allocated across child members in one or more dimensions,based on specified criteria. These functions consolidate the common tasksthat 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 Allocation Functions 10
method The expression that determines how values are allocated. One
of the following:

share 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)

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

round One of the following:
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:

noRound No rounding. noRound is the default

roundAmt, [numDigits

[, roundErr]]

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.

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.

errorsToLow 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.

errorsToMbr Adds rounding errors to the specified roundMbr, which must be included in allocationRange.

10-4 Hyperion

Summary of Allocation Functions
This table summarizes the Allocation Functions. Each function is also described, in detail, in this chapter.


@ALLOCATE Allocates values that are input at an upper level to lower-level members.

@MDALLOCATE Allocates values that are input at an upper level to lower-level members in multiple dimensions.

Hyperion 10-5

@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

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


Notes

If no member or cross-dimensional member is from the dimension to which allocationRange belongs, Essbase displays a warning message.

@ALLOCATE (amount, allocationRange, basisMbr, [roundMbr],method[, methodParams] [, round [, numDigits][, roundErr]])

PY Actual Budget

Marketing 5000 3500

Payroll 4000 2800

Misc 1000 700

Total Expenses 10000 7000

10-6 Hyperion

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

@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

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

@MDALLOCATE (amount, Ndim, allocationRange1... allocationRangeN, basisMbr, [roundMbr], method [, methodParams] [, round [, numDigits][, roundErr]])

10-8 Hyperion

This example produces the following results for Jan, Colas:
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.

Marketing Payroll Misc Total Expenses

Actual New York 100 200 100 400

Massachusetts 100 200 100 400

Florida 100 200 100 400

Connecticut 100 200 100 400

New Hampshire

100 200 100 400

East 500 1000 500 2000

Budget New York 110 220 110 #MI

Massachusetts 110 220 110 #MI

Florida 110 220 110 #MI

Connecticut 110 220 110 #MI

New Hampshire

110 220 110 #MI

East #MI #MI #MI 2200

Hyperion 10-9

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.



2) 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.

3) Open the SS_Alloc spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The “1999 Actual”-“West” and “2000 Budget” values have not been calculated.

6) 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.

7) 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.



Calc Script (new) CSAlloc

Spreadsheet SS_Alloc.xls

10-10 Hyperion

Unit Summary
Allocation functions allocate values that are input at the parent level. Thevalues are allocated across child members in one or more dimensions,based on specified criteria. There are several allocation methods that maybe used.

share Divides the amount among members of the allocation range using basisMbr to calculate a percentage share.

spread Divides the amount evenly across all members of allocationRange.

percent Treats the amount as a percentage value which is applied to basisMbr corresponding to the allocationRange member.

add Adds the amount to the basisMbr for each member of allocationRange.

subtract Subtracts the amount from the basisMbr for each member of allocationRange.

multiply Multiplies the amount to the basisMbr for each member of allocationRange.

divide Divides the amount by the basisMbr for each member of allocationRange.

Hyperion 10-11


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 year’s 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 year’s budget adveristing expense for each individual product is a 10% increase over this year ’s actual advertising expense.

d. Each individual product’s budgeted advertising expense will be increased by $500 over this year ’s actual.

e. Each individual product’s budgeted advertising expense will be decreased by $500 over this year ’s actual.

10-12 Hyperion

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 year’s actual advertising expense for each product.

• share

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).

• spread

c. Next year’s budget adveristing expense for each individual product is a 10% increase over this year ’s actual advertising expense.

• percent (or share)

d. Each individual product’s budgeted advertising expense will be increased by $500 over this year ’s actual.

• add

e. Each individual product’s budgeted advertising expense will be decreased by $500 over this year ’s actual.

• subtract

Hyperion 10-13


10-14 Hyperion

11Forecasting Functions

Chapter Objectives


• Explain the purpose and use of Forecasting functions to generate member lists

• Practice using the Forecasting functions in a series of incremental exercises

Forecasting Functions Hyperion Essbase Calc Scripts11
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.

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.

11-2 Hyperion

Hyperion Essbase Calc Scripts Forecasting Functions 11
Summary of Forecasting Functions
This table summarizes the Forecasting Functions. Each function is also described, in detail, in this chapter.

Function Calculates

@MOVAVG A moving n-term average of an input data set.

@MOVMAX A moving n-term maximum of an input data set.

@MOVMED A moving n-term median of an input data set.

@MOVMIN A moving n-term minimum of an input data set.

@MOVSUM * A moving n-term sum of an input data set.

@MOVSUMX * 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.

@SPLINE A smoothing spline to a set of data points.

@TREND Future values based on curve-fitting to historical values.

* New in Essbase XTD Release 6.5.1.

Hyperion 11-3

@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

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).


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.

@MOVAVG (mbrName [, n [, rangeList]])

n - A positive integer value that represents the number of values to average. The default is 3.

Sales Mov Avg

Jan 100 100

Feb 110 110

Mar 120 110

Apr 130 120

May 140 130

Jun 150 140

11-4 Hyperion

Notes
The @MOVAVG function calculates a trailing, rather than a centered, average. For example:

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.

Trailing Average Centered Average

1 2 3 1 2 3

2 2

Hyperion 11-5

@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

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).


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.

@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.

Sales Mov Max

Jan 551 551

Feb 641 641

Mar 586 641

Apr 630 641

May 612 630

Jun 747 747

11-6 Hyperion

Notes
The @MOVMAX function calculates a trailing, rather than a centered, maximum. For example:

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.


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.

Trailing Maximum Centered Maximum

1 2 3 1 2 3

3 3

Hyperion 11-7

@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

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).


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.

@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.

Sales Mov Med

Jan 551 551

Feb 641 641

Mar 586 586

Apr 630 630

May 612 612

Jun 747 630

11-8 Hyperion

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:

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.


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.

Trailing Median Centered Median

1 2 3 1 2 3

2 2

Hyperion 11-9

@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

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).


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.

@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.

Sales Mov Min

Jan 551 551

Feb 641 641

Mar 586 551

Apr 630 586

May 612 586

Jun 747 612

11-10 Hyperion

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:


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.

Trailing Minimum Centered Minimum

1 2 3 1 2 3

2 2

Hyperion 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

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).


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.

@MOVSUM (mbrName [, n [, rangeList]])


Sales Mov Sum

Jan 551 551

Feb 641 641

Mar 586 1778

Apr 630 1857

May 612 1828

Jun 747 1989

11-12 Hyperion

Notes
The @MOVSUM function calculates a trailing, rather than a centered, sum. For example:

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.

Trailing Sum Centered Sum

1 2 3 1 2 3

6 3

Hyperion 11-13

@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

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:

@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


Sales SumCopy SumMiss SumTrail

Jan 551 551 #Missing 551

Feb 641 641 #Missing 1192

Mar 586 1778 1778 1778

Apr 630 1857 1857 1857

May 612 1828 1828 1828

Jun 747 1989 1989 1989

11-14 Hyperion

@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

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);


@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.

Sales Sales Spline

Jan 645 632.89

Feb 675 675.82

Mar 712 724.74

Apr 756 784.29

May 890 852.44

Jun 912 919.82

Hyperion 11-15

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.


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

@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

Parameters

Ylist An expression list that contains known observations; for example, sales figures over a period of time.

Xlist 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.

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)

@TREND (Ylist, [Xlist], [weightList], [errorList], [XforecastList], YforecastList, method[, method parameters] [, Xfilter1 [, parameters]] [,XfilterN [, parameters]][, Yfilter1 [, parameters]][, YfilterN [,parameters]])

Hyperion 11-17

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.

SES

[,c]

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.

DES

[[,c1],c2]

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.

TES

[[[[,T],c1],c2],c3]

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.

11-18 Hyperion

Xfilter1... XfilterN Use one or more of the following filter methods to scale
Xlist:

Yfilter1... YfilterN Use one or more of the following filter methods to scale Ylist:

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););


XLOG[,c] logarithmic change with shift c (x' = log(x+c)) (default c=1)

XEXP[,c] exponential change with shift c (x' = exp(x+c)) (default c=0)

XPOW[,c] power change with power c (x' = x^c) (default c=2)

YLOG[,c] logarithmic change with shift c (y' = log(y+c)) (default c=1)

YEXP[,c] exponential change with shift c (y' = exp(y+c)) (default c=0)

YPOW[,c] power change with power c (y' = y^c) (default c=2)

Sales

Jan 2339

Feb 2298

Mar 2313

Apr 2332

May 2319

Jun 2318.4

Jul 2317.8

Aug 2317.2

Hyperion 11-19


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.

Sep 2316.6

Oct 2316

Nov 2315.4

Dec 2314.8

11-20 Hyperion

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.



2) 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.

3) Open the SS_Trend spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The 2000 Budget values have not been calculated.

6) From the Calc&Retrieve sheet, run the CSTrend calc script. Perform a retrieval and review the results in the “2000 Budget” column.

7) Do the Essbase results match your expectations? If not, modify the CSTrend calc script and rerun the calculation until you get the expected results.



Calc Script (new) CSTrend

Spreadsheet SS_Trend.xls

Hyperion 11-21

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

12Statistical Functions

Chapter Objectives


• Explain the purpose and use of Statistical functions to generate member lists

• Practice using the Statistical functions in a series of incremental exercises

Statistical Functions Hyperion Essbase Calc Scripts12
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 Single dimension name specification.

mbrName Specifies a single member.


expList, expList1, explist2

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.





12-2 Hyperion

Hyperion Essbase Calc Scripts Statistical Functions 12
Summary of Statistical Functions
This table summarizes the Statistical Functions. Each function is also described, in detail, in this chapter.

Function Returns

@CORRELATION The correlation coefficient between two parallel data sets.

@COUNT The number of data values in the specified data set.

@MEDIAN The median of the specified data set.

@MODE The mode of the specified data set.

@RANK The rank of the specified members or the specified value among the values in the specified data set.

@STDEV The standard deviation of a specified data set that represents a sample of a population.

@STDEVP The standard deviation of a specified data set that represents a population.

@STDEVRANGE The standard deviation of the specified member across the specified data set that represents a sample of a population.

@VARIANCE The statistical variance of a specified data set that represents a sample of a population.

@VARIANCEP The statistical variance of a specified data set that represents a population.

Hyperion 12-3

@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

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


@CORRELATION (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList1, expList2)

Sales Sales Correl

Jan 678 #MI

Feb 645 #MI

Mar 675 #MI

Apr 712 #MI

May 756 #MI

Jun 890 0.200368468

12-4 Hyperion

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

@COUNT
The @COUNT() function returns the number of data values in the specified data set.

Syntax

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.

Notes

The @COUNT function always returns an integer greater than or equal to 0.

@COUNT (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual Budget

Sales Colas 678 640

Root Beer #MI 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

Prod Count Product 3 4

12-6 Hyperion

@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

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


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).

@MEDIAN (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual Budget

Sales Colas 678 640

Root Beer #MI 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

Median Product 663 575

Hyperion 12-7

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

@MODE
The @MODE() function returns the mode (the most frequently occurring value) in the specified data set.

Syntax

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


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.

@MODE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual

Units Illinois 3

Ohio 2

Wisconsin 3

Missouri #MI

Iowa 0

Colorado 6

Central 14

Mode Central 3

Hyperion 12-9

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

@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

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:

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.

@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.

Sales Sales Rank

Colas 678 1

Root Beer 551 4

Cream Soda 663 2

Fruit Soda 587 3

Diet Drinks #MI #MI

Hyperion 12-11

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

@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

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


@STDEV (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual Budget

Sales Colas 678 640

Root Beer 551 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

StdDev Product 60.73 64.55

Hyperion 12-13

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

@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

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


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.

@STDEVP (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual Budget

Sales Colas 678 640

Root Beer 551 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

StdDevP Product 52.59 55.90

Hyperion 12-15

@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

@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

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


@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.

Actual Budget

Sales Colas 678 640

Root Beer 551 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

StdDev Product 60.73 64.55

Hyperion 12-17

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

@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

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


Notes

@VARIANCE is different from @VAR, which calculates the variance (difference) between two members.

@VARIANCE (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual Budget

Sales Colas 678 640

Root Beer 551 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

SalesVar Product 3687.58 4166.67

Hyperion 12-19

@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

@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

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


Notes

@VARIANCEP is different from @VARPER, which calculates the percent variance (difference) between two members.

@VARIANCEP (SKIPNONE | SKIPMISSING | SKIPZERO | SKIPBOTH, expList)

Actual Budget

Sales Colas 678 640

Root Beer 551 530

Cream Soda 663 510

Fruit Soda 587 620

Diet Drinks #MI #MI

Product 2479 2300

SalesVar Product 2765.69 3125.00

Hyperion 12-21

@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

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.



2) 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.

3) Open the SS_Rank spreadsheet.


5) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The Sales and Sales Rank for the states values have not been calculated.

6) From the Calc&Retrieve sheet, run the CSRank calc script. Perform a retrieval.

7) 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.



Calc Script (new) CSRank

Spreadsheet SS_Rank.xls

✍

Hyperion 12-23

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

13Date and Time Functions

Chapter Objectives


• 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

Date and Time Functions Hyperion Essbase Calc Scripts13
Using Date and Time Functions
The date function converts date strings to numbers that can be used incalculation formulas. There is one Date and Time function, @TODATE,which converts date strings to numbers.

13-2 Hyperion

Hyperion Essbase Calc Scripts Date and Time Functions 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

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.


@TODATE (formatString, dateString)

formatString - The format of the date string, either "mm-dd-yyyy" or "dd-mm-yyyy".

dateString - The date string.

Marketing New Marketing

Intro Date_12-10-1996

200-30 10 9

200-40 10 9


400-10 10 9

400-20 10 9

Hyperion 13-3


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-01-2038).


200-20 10 9


300-10 10 9

300-20 10 9

300-30 10 9


100-20 10 10

100-30 10 10


100-10 10 10


200-10 10 10

13-4 Hyperion

Hyperion Essbase Calc Scripts Date and Time Functions 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.



2) 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.

3) Open the SS_ToDate spreadsheet. Lock and send the data in the Lock&Send sheet to the HLandS2 database.

4) Switch to the Calc&Retrieve sheet. Retrieve into this sheet. The Budget 2000 Marketing values are not available.

5) From the Calc&Retrieve sheet, run the CSTodate calc script. Perform a retrieval.

6) 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.



Calc Script (new) CSTodate

Spreadsheet SS_ToDate.xls

Hyperion 13-5


13-6 Hyperion

14Miscellaneous Functions

Chapter Objectives


• Explain the purpose and use of Miscellaneous functions to generate member lists

• Practice using the Miscellaneous functions in a series of incremental exercises

Miscellaneous Functions Hyperion Essbase Calc Scripts14
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 Enables the choice of an execution mode of a formula.

@CONCATENATE Returns a character string that is the result of appending one character string to another character string.

@NAME Passes the enclosed string or member name as a string to another function.

@SUBSTRING Returns the requested substring of characters from an existing source string.

14-2 Hyperion

Hyperion Essbase Calc Scripts Miscellaneous Functions 14
@CALCMODE
The @CALCMODE function enables the choice of an execution mode of a formula.

Syntax

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

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.

@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

Hyperion 14-3

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 Top-down 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

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 bottom-up 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 top-down 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

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.

Hyperion 14-5

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.

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.

14-6 Hyperion

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:

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.

Before Execution

Without @Calcmode

With @Calcmode

Jan 10 30 110

Feb 20 100 100

Mar 30 110 110

Hyperion 14-7

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:

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.

Before Execution

Without @Calcmode

With @Calcmode

Jan 10 30 30

Feb 20 100 100

Mar 30 120 40

14-8 Hyperion

Example 3
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:

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.

Before Execution Without @Calcmode With @Calcmode

Opening Ending Opening Ending Opening Ending

Jan #MI #MI 10 10 10 10

Feb #MI #MI 10 10 20 20

Mar #MI #MI 10 10 30 30

Hyperion 14-9

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:

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 After Execution Comment

Actual Budget Actual Budget

Jan #MI 50 #MI #MI #MISSING*1.10

Feb 200 #MI 200 #MI No calculation is performed

Mar 400 450 400 440 400*1.10

Before Execution After Execution Comment

Actual Budget Actual Budget

Jan #MI 50 #MI #MI #MISSING*1.10

Feb 200 #MI 200 220 200*1.10

Mar 400 450 400 440 400*1.10

14-10 Hyperion

@CONCATENATE
The @CONCATENATE function returns a character string that is the result of appending one character string to another character string.

Syntax

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)))

@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

Hyperion 14-11

@NAME
The @NAME() function passes the enclosed string or member name as a string to another function.

Syntax

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.

Price = @J_GetPrice(@NAME(@CURRMBR(Product)),@NAME(@CURRMBR(Year)));

The following report illustrates the above example:

Notes

Essbase does not support strings in functions. It treats strings as values or array of values. The @NAME function processes strings.

@NAME (mbrName)

mbrName - Any valid single member name, dimension name, or a string.

MonthName ProductId Price

Jan 100-10 1.90

Feb 100-10 1.95

Mar 100-10 1.98

Jan 100-20 1.95

Feb 100-20 2.00

Mar 100-20 2.05

Jan Feb Mar

100-10 1.90 1.95 1.98

100-20 1.95 2.00 2.05

14-12 Hyperion

@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

Example

The following examples are based on the Sample Basic database:

@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.

Statement Result

@SUBSTRING ("100-10",1) "00-10"

@SUBSTRING ("200-21",0,2) "20"

@SUBSTRING ("200-21",3,6) “0-2”

@SUBSTRING (@PARENT(Jan),3)

(The parent of Jan is Qtr1.) “1”

Hyperion 14-13


14-14 Hyperion

15Tips, Tricks and Techniques

Chapter Objectives


• 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

Tips, Tricks and Techniques Hyperion Essbase Calc Scripts15
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

Hyperion Essbase Calc Scripts Tips, Tricks and Techniques 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 description-which 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

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:

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.

Boolean Function Member Set Function

@ISANCEST @ANCESTORS

@ISCHILD @CHILDREN

@ISDESC @DESCENDANTS

@ISGEN @GENMBRS

@ISIANCEST @IANCESTORS

@ISICHILD @ICHILDREN

@ISIDESC @IDESCENDANTS

@ISIPARENT @IALLANCESTORS

@ISISIBLING @ISIBLINGS

@ISLEV @LEVMBRS

@ISPARENT @PARENT

@ISSAMEGEN @GENMBRS

@ISSAMELEV @LEVMBRS

@ISSIBLING @SIBLINGS

@ISUDA @UDA

15-4 Hyperion

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%.


1) Open and review the data in spreadsheet SS_If_Fix.xls.


3) Review the outline for the HLandS2 database. Notice which members are affected and whether the dimensions containing those members are dense or sparse.


Calc Script (new) CSIf_Fix

Spreadsheet SS_If_Fix.xls

Hyperion 15-5

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.

5) In Microsoft Excel, connect to the Essbase server and select the Calc:HLandS2 database.


7) 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.

8) Ensure that all calculation requirements are met. If all calculation requirements are not met, revise the calc script and rerun the calculation.

9) Close the SS_If_Fix spreadsheet.

15-6 Hyperion

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.


1) From Essbase Application Manager, review the event log to determine the length of time required to run the calc script CSIf_Fix.

2) Clear all data from the HLandS2 database.

3) 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.

4) In Microsoft Excel open spreadsheet SS_If_Fix.xls, and connect to the Essbase server and select the Calc:HLandS2 database.


6) 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.

7) Ensure that all calculation requirements are met. If all calculation requirements are not met, revise the calc script and rerun the calculation.

8) Close the SS_If_Fix spreadsheet.

9) From Essbase Application Manager, review the event log to determine the length of time required to run the calc script CSIfix2.

10) Which is more efficient for your environment?


Calc Script

(new)

CSIf_Fix

CSIfix2

Spreadsheet SS_If_Fix.xls

Hyperion 15-7

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

and Freight = .015 * Profit.
Algebraic manipulation yields:

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

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.



Calc Script (new) CSAlloc2

Spreadsheet SS_Alloc2.xls

15-10 Hyperion

1) Review the outline for the HLandS1 database. Note which data is
affected and determine whether rollups must be completed before individual calculations.

2) Open and review the data in spreadsheet SS_Alloc2.xls.


4) Create your calc script using the Calc Script Editor. Save your calc script as CSAlloc2.

5) In Microsoft Excel, connect to the Essbase server and select the CALC:HLandS1 database.


7) 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.

8) Ensure that all calculation requirements are met. If not, revise the calc script and rerun the calculation.

9) Close the SS_Alloc2 spreadsheet.

10) From Essbase Application Manager, review the event log to determine the length of time required to run the calc script CSAlloc2.

Hyperion 15-11

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:

1) Review the data in spreadsheet SS_Share.


Calc Script (new) CSShare

Spreadsheet SS_Share.xls

15-12 Hyperion

2) Open the outline for the HLandS1 database. Notice which data is
affected, and determine whether rollups must be completed before individual calculations.


4) Create a calc script using the Calc Script Editor. Save the calc script as CSShare.


6) In Microsoft Excel, open and review the data in spreadsheet SS_Share.xls.

7) Connect to the Essbase server and select the CALC:HLandS1 database.


9) 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.

10) Do the calculated results match the expected results? If not, revise the calc script and rerun the calculation.

11) Close the SS_Share spreadsheet.

Hyperion 15-13

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

You created calc scripts (allocations, budget creation, and market share analysis) to solve common business problems.

15-14 Hyperion

ASuggested 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 Hyperion Essbase Calc ScriptsA
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

Hyperion Essbase Calc Scripts Suggested Answers A
Exercise 5-1: Use Math Functions
FIX ("Jan 1999", Actual)FIX (Sales)

Connecticut=@ROUND(@AVG(SKIPNONE,Bridgeport:Waterbury),2);

ENDFIXENDFIX

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

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)));

ENDFIXENDFIX

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

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)));

ENDFIXENDFIX

Hyperion A-5

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) ENDFIXENDFIX

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

OR -
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);

ENDFIXFIX (Budget)

Freight=Sales->Actual / Sales->Actual->Markets->Products * Freight->Products->Markets;

ENDFIXOR -

FIX (Actual,Sales) CALC DIM (Time, Markets, Products);

ENDFIXFIX (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);ENDFIXFIX (@IDESCENDANTS("2000 Product Family"))

"Product Share"=Sales%Sales->Products;ENDFIX

ENDFIX

Hyperion A-7


A-8 Hyperion

BEssbase 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 Hyperion Essbase Calc ScriptsB
Sample - Basic
The Sample - Basic outline is used to illustrate many of the examples in the descriptive material:

Year (Dense)Qtr1

JanFebMar

Qtr2AprMayJun

Qtr3JulAugSep

Qtr4OctNovDec

Measures (Dense)Profit

MarginSalesCOGS

Total ExpensesMarketingPayrollMisc

InventoryOpening InventoryAdditionsEnding Inventory

RatiosMargin %Profit %Profit per Ounce

Product (Sparse)100 Alias: Colas

100-10100-20100-30

200 Alias: Root Beer200-10200-20200-30200-40

300 Alias: Cream Soda300-10300-20300-30

400 Alias: Fruit Soda400-10400-20400-30

Diet Alias: Diet Drinks100-20 Shared200-20 Shared300-30 Shared

B-2 Hyperion

Hyperion Essbase Calc Scripts Essbase Outlines B
Sample - Basic (Continued)
Market (Sparse)East

New YorkMassachusettsFloridaConnecticutNew Hampshire

WestCaliforniaOregonWashingtonUtahNevada

SouthTexasOklahomaLouisianaNew Mexico

CentralIllinoisOhioWisconsinMissouriIowaColorado

Scenario (Dense)ActualBudgetVarianceVariance %

Hyperion B-3

Sample - Basic (Attribute Dimensions)
Caffeinated (Attribute of Product) TRUEFALSE

Ounces (Attribute of Product)32201612

Pkg Type (Attribute of Product)BottleCan

Population (Attribute of Market)Small

30000006000000

Medium9000000120000001500000018000000

Large2100000024000000270000003000000033000000

Intro Date (Attribute of Product)3/25/964/1/969/27/957/26/9612/10/966/26/9610/1/96

B-4 Hyperion

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 1997Jan-97Feb-97Mar-97

Qtr2 1997Apr-97May-97Jun-97

Qtr3 1997Jul-97Aug-97Sep-97

Qtr4 1997Oct-97Nov-97Dec-97

1998Qtr1 1998

Jan-98Feb-98Mar-98




1999Qtr1 1999

Jan-99Feb-99Mar-99




2000Qtr1 2000

Jan-00

Hyperion B-5

Feb-00Mar-00



Accounts (Dense)Profit

Pre Tax ProfitRegional Profit

MarginSalesCOGS

Total ExpensesFreightAdministrationPayrollMarketingMiscellaneous

Corporate ExpensesTax

InventoryOpening InventoryAdditionsEnding Inventory

RatiosMargin PercentProfit PercentProduct Share

StatisticsAverage SalesCommissionDays of SalesAvailable Days Of SalesAdjusted Store CountAverage Margin

B-6 Hyperion

CALC - HLandS1 (Continued)
Scenario (Dense)ActualBudgetVarianceVariance PercentPercent

Markets (Sparse)East

ConnecticutBridgeportHartfordStamfordWaterbury

MaineAugustaBangorMillinocketPortland

Massachusetts

New BedfordSpringfieldWorcester

New YorkAlbanyBuffaloIthacaWhite Plains

Rhode IslandJamestownProvidenceQuonochontaug

WestCalifornia

BakersfieldFoster CitySacramentoHalf Moon Bay

New MexicoAlbuquerqueDemingSante Fe

OregonCondonEugeneSalem

WashingtonOlympiaSpokaneTacomaWalla Walla

SouthAlabama

AndalusiaBirminghamMobile

Hyperion B-7

Montgomery
FloridaOrlandoSarasotaTampa

GeorgiaAthensMaconValdosta

TennesseeMemphisMurfreesboroNashville

CentralIllinois

AntiochCarbondaleCobdenRockford

WisconsinGreen BayLa CrosseMilwaukeeNeenahWausau

TexasAmarilloAustinDallasWaco

MissouriCape GirardeauKansas CityLebanonSikestonSt. Louis

B-8 Hyperion

Products1000 Product Family

Crazy Horse 10111011-0000

1011-0000-11011-0000-21011-0000-3

1011-00101011-00201011-00301011-0040

Crazy Horse 10211021-00001021-00101021-0020

1021-0020-11021-0020-21021-0020-3

Crazy Horse 10311031-00001031-00201031-00301031-00401031-0050

1031-0050-11031-0050-21031-0050-3

1031-00701031-0070-11031-0070-2

1031-0090Crazy Horse 1041

1041-00001041-00201041-00401041-00601041-00701041-0090

2000 Product Family

Old Faithful 20112011-0000

2011-0000-12011-0000-22011-0000-32011-0000-42011-0000-52011-0000-6

2011-00102011-0010-12011-0010-22011-0010-32011-0010-42011-0010-52011-0010-6

Old Faithful 20212021-00002021-0010


2031-0000-12031-0000-2

Hyperion B-9

2031-0000-32031-0000-42031-0000-52031-0000-6
2031-00102031-0010-12031-0010-22031-0010-32031-0010-42031-0010-52031-0010-6

Old Faithful 20412041-00002041-0020

3000 Product FamilyPomona 3011

3011-00003011-00103011-00203011-00303011-0040

Pomona 30213021-00003021-00103021-0030

Pomona 30313031-00003031-00303031-00203031-0040

Pomona 30413041-00003041-00203041-00403041-0060

Pomona 30513051-0000

3051-0000-13051-0000-23051-0000-33051-0000-4

3051-00203051-0020-13051-0020-2

4000 Product FamilyShawnee 4011

4011-00004011-00104011-0020

Shawnee 40214021-0000

4021-0000-14021-0000-2

4021-00104021-0010-14021-0010-2

Shawnee 40314031-0000

4031-0000-14031-0000-2

4031-00104031-0010-14031-0010-2

B-10 Hyperion

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 YearQtr1

JanFebMar

Qtr2AprMayJun

Qtr3JulAugSep

Qtr4OctNovDec

AccountsProfit

Pre Tax ProfitRegional Profit

MarginSalesCOGS

Total ExpensesFreightAdministrationPayrollMarketingMiscellaneous

Corporate ExpensesTax

InventoryOpening InventoryAdditionsEnding InventoryAverage Inventory

RatiosMargin PercentProfit PercentProduct Share

StatisticsAverage SalesCommissionDays of SalesAvailable Days Of SalesAdjusted Store CountSales RankAverage MarginCashROI

Hyperion B-11

Scenario1997

1997 Actual1998

1998 Actual1998 Budget



Variances1998 Actual VS 1999 Actual Percent Variance1998 Budget VS 1999 Budget1998 Actual VS 1998 Budget

Markets (Sparse)East

ConnecticutBridgeportHartfordStamfordWaterbury

MaineAugustaBangorMillinocketPortland

Massachusetts

New BedfordSpringfieldWorcester

New YorkAlbanyBuffaloIthacaWhite Plains

Rhode IslandJamestownProvidenceQuonochontaug

WestCalifornia

BakersfieldFoster CitySacramentoHalf Moon Bay

New MexicoAlbuquerqueDemingSante Fe

OregonCondonEugeneSalem

WashingtonOlympia

B-12 Hyperion

SpokaneTacomaWalla Walla
SouthAlabama

AndalusiaBirminghamMobileMontgomery

FloridaOrlandoSarasotaTampa

GeorgiaAthensMaconValdosta

TennesseeMemphisMurfreesboroNashville

CentralIllinois

AntiochCarbondaleCobdenRockford

WisconsinGreen BayLa CrosseMilwaukeeNeenahWausau

TexasAmarilloAustinDallasWaco

MissouriCape GirardeauKansas CityLebanonSikestonSt. Louis

Hyperion B-13



1011-0000-11011-0000-21011-0000-3

1011-00101011-00201011-00301011-0040

Crazy Horse 10211021-00001021-00101021-0020

1021-0020-11021-0020-21021-0020-3

Crazy Horse 10311031-00001031-00201031-00301031-00401031-0050

1031-0050-11031-0050-21031-0050-3

1031-00701031-0070-11031-0070-2


1041-00001041-00201041-00401041-00601041-00701041-0090

2000 Product Family


2011-0000-12011-0000-22011-0000-32011-0000-42011-0000-52011-0000-6

2011-00102011-0010-12011-0010-22011-0010-32011-0010-42011-0010-52011-0010-6

Old Faithful 20212021-00002021-0010


2031-0000-12031-0000-2

B-14 Hyperion

2031-0000-32031-0000-42031-0000-52031-0000-6
2031-00102031-0010-12031-0010-22031-0010-32031-0010-42031-0010-52031-0010-6

Old Faithful 20412041-00002041-0020


3011-00003011-00103011-00203011-00303011-0040

Pomona 30213021-00003021-00103021-0030

Pomona 30313031-00003031-00303031-00203031-0040

Pomona 30413041-00003041-00203041-00403041-0060

Pomona 30513051-0000

3051-0000-13051-0000-23051-0000-33051-0000-4

3051-00203051-0020-13051-0020-2


4011-00004011-00104011-0020

Shawnee 40214021-0000

4021-0000-14021-0000-2

4021-00104021-0010-14021-0010-2

Shawnee 40314031-0000

4031-0000-14031-0000-2

4031-00104031-0010-14031-0010-2

Hyperion B-15

CALC - HLandS2 (Attribute Dimension)
IntroDate1/1/907/5/967/6/9610/13/98

B-16 Hyperion

Calc - COGS
Time (Dense)1997199819992000

AccountsCOGS

Hyperion B-17

Calc - COGS (Continued)


1011-0000-11011-0000-21011-0000-3

1011-00101011-00201011-00301011-0040

Crazy Horse 10211021-00001021-00101021-0020

1021-0020-11021-0020-21021-0020-3

Crazy Horse 10311031-00001031-00201031-00301031-00401031-0050

1031-0050-11031-0050-21031-0050-3

1031-00701031-0070-11031-0070-2


1041-00001041-00201041-00401041-00601041-00701041-0090

2000 Product Family


2011-0000-12011-0000-22011-0000-32011-0000-42011-0000-52011-0000-6

2011-00102011-0010-12011-0010-22011-0010-32011-0010-42011-0010-52011-0010-6

Old Faithful 20212021-00002021-0010


2031-0000-12031-0000-2

B-18 Hyperion

2031-0000-32031-0000-42031-0000-52031-0000-6
2031-00102031-0010-12031-0010-22031-0010-32031-0010-42031-0010-52031-0010-6

Old Faithful 20412041-00002041-0020


3011-00003011-00103011-00203011-00303011-0040

Pomona 30213021-00003021-00103021-0030

Pomona 30313031-00003031-00303031-00203031-0040

Pomona 30413041-00003041-00203041-00403041-0060

Pomona 30513051-0000

3051-0000-13051-0000-23051-0000-33051-0000-4

3051-00203051-0020-13051-0020-2


4011-00004011-00104011-0020

Shawnee 40214021-0000

4021-0000-14021-0000-2

4021-00104021-0010-14021-0010-2

Shawnee 40314031-0000

4031-0000-14031-0000-2

4031-00104031-0010-14031-0010-2

Hyperion B-19


B-20 Hyperion

Documents

81816101-CalcScript651