Documente Academic
Documente Profesional
Documente Cultură
Contents
Documentation Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Part I. Understanding Essbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 1. Introducing Essbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Essbase Product Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Essbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Sample Essbase Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Administration Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Essbase Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Provider Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Smart View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Application Programming Interface (API) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Developer Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Lifecycle Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Integration with Existing Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Data Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Ease of Server and Database Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Mission Critical Applications in Web-based Environments . . . . . . . . . . . . . . . . . . . . 50
Powerful Querying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Write-Back and Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Ease of Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Chapter 2. Quick Start for Implementing Essbase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Chapter 3. Understanding Multidimensional Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
OLAP and Multidimensional Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Dimensions and Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
iii
Outline Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Dimension and Member Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Standard Dimensions and Attribute Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Sparse and Dense Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Selection of Dense and Sparse Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Data Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Data Blocks and the Index System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Multiple Data Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
The Essbase Solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 4. Case Study: Designing a Single-Server, Multidimensional Database . . . . . . . . . . . . . . . . . . . . . . . 77
Process for Designing a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Case Study: The Beverage Company . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Analyzing and Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Analyzing Source Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Identifying User Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Planning for Security in a Multiple User Environment . . . . . . . . . . . . . . . . . . . . . . . . 81
Creating Database Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Drafting Outlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Dimension and Member Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Dimension Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Member Storage Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Checklist for Dimension and Member Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Designing an Outline to Optimize Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Checking System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Loading Test Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Defining Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Consolidation of Dimensions and Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Tags and Operators on Example Measures Dimension . . . . . . . . . . . . . . . . . . . . . . . . 98
Accounts Dimension Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Formulas and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Dynamic Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Two-Pass Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Checklist for Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Defining Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Verifying the Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Chapter 5. About Administration Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
iv
vi
vii
viii
ix
xi
xii
Optimizing Name Lookup and Insertion During Dimension Build and Outline
Editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Debugging Data Loads and Dimension Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Verifying that Essbase Server Is Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Verifying that the Data Source Is Available . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Checking Error Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Recovering from an Essbase Server Crash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Resolving Problems with Data Loaded Incorrectly . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Creating Rejection Criteria for End of File Markers . . . . . . . . . . . . . . . . . . . . . . . . . 314
Understanding How Essbase Processes a Rules File . . . . . . . . . . . . . . . . . . . . . . . . . 315
Understanding How Essbase Processes Missing or Invalid Fields During a Data
Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Chapter 21. Understanding Advanced Dimension Building Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Understanding Build Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Using Generation References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Using Level References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Using Parent-Child References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
Adding a List of New Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Adding Members Based On String Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
Adding Members as Siblings of the Lowest Level . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Adding Members to a Specified Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Building Attribute Dimensions and Associating Attributes . . . . . . . . . . . . . . . . . . . . . . . 329
Building Attribute Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Associating Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Updating Attribute Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Removing Attribute Associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Working with Multilevel Attribute Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Working with Numeric Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Reviewing the Rules for Building Attribute and Base Dimensions . . . . . . . . . . . . . . . 338
Building Shared Members by Using a Rules File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Sharing Members at the Same Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
Sharing Members at Different Generations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Sharing Non-Level 0 Members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Building Multiple Roll-Ups by Using Level References . . . . . . . . . . . . . . . . . . . . . . . 345
Creating Shared Roll-Ups from Multiple Data Sources . . . . . . . . . . . . . . . . . . . . . . 346
Building Duplicate Member Outlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Uniquely Identifying Members Through the Rules File . . . . . . . . . . . . . . . . . . . . . . 348
Building Qualified Member Names Through the Rules File . . . . . . . . . . . . . . . . . . . 348
xiii
xiv
xv
xvi
xvii
xix
xx
xxi
xxiii
xxv
xxvi
Understanding and Using Dimension Build and Data Load Error Logs . . . . . . . . . . . 751
Chapter 48. Managing Database Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
Understanding the Essbase Server Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755
Understanding Buffered I/O and Direct I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Viewing the I/O Access Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Setting the I/O Access Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Understanding Kernel Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
Index Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757
Allocation Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758
Data Block Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
LRO Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Lock Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759
Transaction Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
Understanding Kernel Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
Understanding the Precedence of Database Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 760
Understanding How Essbase Reads Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
Viewing Most-Recently Entered Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761
Customizing Database Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Specifying and Changing Database Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762
Using alter database in MaxL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Using SETDBSTATEITEM in ESSCMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Chapter 49. Allocating Storage and Compressing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Storage Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Checking Index and Data File Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Specifying Disk Volumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766
Reviewing an Example of Specifying Volumes to Control Storage . . . . . . . . . . . . . . . 769
Data Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770
Bitmap Data Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
RLE Data Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771
zlib Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Index Value Pair Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Deciding Which Compression Type to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Changing Data Compression Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
Checking the Compression Ratio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
Data Block Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
Chapter 50. Ensuring Data Integrity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
Understanding Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777
xxvii
xxviii
xxix
xxx
xxxii
xxxiii
Chapter 64. Performing Custom Calculations and Allocations on Aggregate Storage Databases . . . . . . . . . . 991
Performing Custom Calculations and Allocations on Aggregate Storage Databases . . . . . 991
Custom Calculations on Aggregate Storage Databases . . . . . . . . . . . . . . . . . . . . . . . . . . 992
List of Custom Calculations Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993
Writing Custom Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
Executing Custom Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994
Sample Use Case for Custom Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995
Allocations on Aggregate Storage Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
List of Allocation Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997
Understanding Regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
Specifying Allocation Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Setting the POV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Setting the Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001
Setting the Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1002
Setting the Basis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
Setting the Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
Setting the Allocation Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005
Setting the Rounding Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
Setting the Offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Balancing Allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1009
Understanding Settings for Basis and Target Time Span . . . . . . . . . . . . . . . . . . . . 1009
Examples of Aggregate Storage Allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1016
Sample Use Case for Aggregate Storage Allocations . . . . . . . . . . . . . . . . . . . . . . . . 1018
Avoiding Data Inconsistency When Using Formulas . . . . . . . . . . . . . . . . . . . . . . . 1020
Understanding Data Load Buffers for Custom Calculations and Allocations . . . . . . . . . 1020
Understanding Offset Handling for Custom Calculations and Allocations . . . . . . . . . . 1021
Understanding Credit and Debit Processing for Custom Calculations and
Allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1022
Chapter 65. Managing Aggregate Storage Applications and Databases . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
Aggregate Storage Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023
Managing Storage for Aggregate Storage Applications . . . . . . . . . . . . . . . . . . . . . . . . . 1024
Working with Tablespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1024
Defining Tablespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Managing the Aggregate Storage Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025
Improving Performance When Building Aggregate Views on Aggregate Storage
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026
Aggregate Storage Database Restructuring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1027
Levels of Aggregate Storage Database Restructuring . . . . . . . . . . . . . . . . . . . . . . . . 1028
Outline-Change Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1030
xxxiv
xxxv
xxxvi
xxxvii
xxxviii
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
39
40
Documentation Feedback
41
42
Part I
Understanding Essbase
In Understanding Essbase:
l
l
l
l
l
Introducing Essbase
Quick Start for Implementing Essbase
Understanding Multidimensional Databases
Case Study: Designing a Single-Server, Multidimensional Database
About Administration Services
43
44
Introducing Essbase
1
In This Chapter
Introduction.................................................................................................45
Essbase Product Components ............................................................................45
Key Features................................................................................................49
Introduction
Oracle Essbase products help you deliver critical business information to the right people at the
right time. With Essbase, you can quickly integrate data from multiple data sources, and then
distribute that information to users in a format tailored to their needs. With the ability to interact
with and explore data in real time, along familiar business dimensions, you can perform speedof-thought analytics.
Essbase
Sample Essbase Applications
Administration Services
Essbase Studio
Provider Services
Smart View
Application Programming Interface (API)
Developer Products
Lifecycle Management
Essbase products incorporate powerful architectural features to handle a wide range of analytic
applications across large multiuser environments. Essbase architecture includes three tiers. The
client tier includes Essbase Server clients, such as Oracle Smart View for Office and
Administration Services Console. The middle tier includes services, such as Oracle Hyperion
Provider Services and Oracle Essbase Administration Services. The database tier is made up of
Essbase Servers. Communication between the client and middle tiers, and the middle and
database tiers, is through HTTP. Communication between the client and database tiers is
45
through TCP/IP or HTTP. Communication between data sources and the metadata catalog with
the middle and database tiers is through ODBC and JDBC drivers.
Essbase
Essbasea multi-threaded OLAP database software that takes advantage of symmetric
multiprocessing hardware platformsis based on Web-deployable, thin-client architecture.
The server acts as a shared resource, handling all data storage, caching, calculations, and data
security. The Essbase Server client needs only to retrieve and view data that resides on a server.
All Essbase application components, including database outlines and calculation scripts,
application control, and multidimensional database information, reside on a server. With
Essbase, you can configure server disk storage to span multiple disk drives, enabling you to store
large databases. Essbase requires a server to run a multi-threaded operating system so a server
can efficiently manage simultaneous requests. A server also runs a server agent process that acts
as a traffic coordinator for all user requests to applications.
Aggregate storage databases provide an alternative to block storage databases and enable
dramatic increases in database dimensionality. Using aggregate storage, Essbase serves a wide
range of analytic needsfinancial analysis, planning, budgeting, sales analysis, marketing
analysis, supply-chain analysis, profitability analyticsall from a single analytic infrastructure.
MaxLa multidimensional database access language that is part of Essbase Serverprovides a
flexible way to automate Essbase administration and maintenance tasks.
To install and configure Essbase, see the Oracle Enterprise Performance Management System
Installation and Configuration Guide.
Administration Services
Administration Servicesthe database and system administrators interface to Essbase
provides a single-point-of-access console to multiple Essbase Servers. Using Administration
Services Console, you can design, develop, maintain, and manage multiple Essbase Servers,
applications, and databases. You can preview data from within the console without having to
open a client application, such as Smart View. You can also use custom Java plug-ins to leverage
and extend key functionality.
46
Essbase Studio
Oracle Essbase Studio simplifies cube construction by delivering a single environment for
performing tasks related to data modeling, cube designing, and analytic application
construction. With a wizard-driven user interface, Essbase Studio supports modeling of the
various data source types from which Essbase applications are typically built.
A single common metadata repository, or catalog, captures all metadata related to all Essbase
applications built in the enterprise and allows the reuse of metadata at the lowest level of
granularity. The catalog makes Essbase Studio inherently aware of the common metadata that
is shared across the various applications enterprise wide.
Essbase Studio supports several drill-through options: relational databases, custom SQL, URLs
(including Oracle Business Intelligence Enterprise Edition and Oracle Hyperion Financial Data
Quality Management URLs), and Java methods. Essbase Studio also supports lineage tracking
through a rich graphical view of metadata relationships, allowing users to follow application
lineages to their metadata components and through to the data sources from which they were
sourced.
Provider Services
Provider Services is a middle-tier data-source provider to Essbase for Java API, Smart View, and
XMLA clients. Provider Services supports highly concurrent analytical scenarios and provides
scalability and reliability in a distributed Web-enabled enterprise environment.
Smart View
Smart View provides a common Microsoft Office interface for Essbase, Oracle Hyperion
Financial Management, Oracle Hyperion Planning, and Oracle Hyperion Enterprise
Performance Management Workspace data. Using Smart View, you can view, import,
manipulate, distribute, and share data in Microsoft Excel, Word, and PowerPoint interfaces.
Developer Products
Essbase developer products enable the rapid creation, management, and deployment of tailored
enterprise analytic applications, whether or not users have programming knowledge.
The products (for example, Application Builder and Oracle Hyperion Application Builder
for .NET) provide a comprehensive set of application programming interfaces, drag-and-drop
components, and services.
47
Lifecycle Management
Oracle Hyperion Enterprise Performance Management System Lifecycle Management provides
a consistent way for Oracle Enterprise Performance Management System products to migrate
an application, a repository, or individual artifacts across product environments and operating
systems. Generally, the Lifecycle Management interface in Oracle Hyperion Shared Services
Console is consistent for all EPM System products that support Lifecycle Management. However,
EPM System products display different artifact listings and export and import options in the
Lifecycle Management interface.
Lifecycle Management features:
l
Auditing migrations
Importing and exporting individual artifacts for quick changes on the file system
In addition to providing the Lifecycle Management interface in Shared Services Console, there
is a command-line utility called Lifecycle Management Utility that provides an alternate way to
migrate artifacts from source to destination. The Lifecycle Management Utility can be used with
a third-party scheduling service such as Windows Task Scheduler or Oracle Enterprise Manager.
Lastly, there is a Lifecycle Management Application Programming Interface (API) that enables
users to customize and extend the Lifecycle Management functionality.
For detailed information about Lifecycle Management, see the Oracle Enterprise Performance
Management System Lifecycle Management Guide.
48
Key Features
Subtopics
l
l
l
l
l
l
l
l
Data Integration
Essbase products enable organizations to leverage data in their data warehouses, legacy systems,
online transaction processing (OLTP) systems, enterprise resource planning (ERP) systems, ebusiness systems, customer relationship management (CRM) applications, Web log files and
other external data sources. For database integration, Essbase Studio provides a suite of graphical
tools, data integration services, and a metadata catalog that tie into relational databases or data
warehouse environments.
49
Powerful Querying
Large communities of business users can interact with data in real time to quickly analyze
business performance. Using Essbase products, you can organize and present data along familiar
business dimensions, enabling users to view and explore the data intuitively and turn it into
actionable information.
Calculations
Essbase includes powerful calculation features for demanding analytic requirements. A rich
library of functions makes it easy to define advanced and sophisticated business logic and
relationships. Essbase gives users the flexibility to build, customize, and extend the calculator
through custom-defined macros and functions, as well as the ability to span calculations across
databases. On multiprocessor systems, a DBA can configure a single calculation request to use
multiple threads to accomplish the calculation, providing enhanced calculation speed.
Aggregate storage databases provide an alternative to block storage databases and enable
dramatic improvements in database aggregation time for certain types of applications.
Ease of Development
Essbase offers many key advantages to help users develop effective multidimensional
applications. Users can:
l
50
Design and manage applications using a graphical interface to control most server functions.
Quickly add dimensions, change calculations, and modify hierarchies to reflect new business
developments. In addition, the dynamic dimension builder automatically defines and
dynamically loads large amounts of data, including data from spreadsheets, flat files, and
supported relational database tables directly into a database.
Define key calculations without having to write a program.
Define security for individuals and groups and customize views and retrieval procedures for
each user without writing a program.
51
52
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
Chapter 60, Comparison of Aggregate and Block Storage
The following table provides a process map for implementing Essbase. Each step in the process
is described at a high level, with references to where you can obtain more detailed information.
Table 1
A Process Map
Process Step
Reference
How will you access the data? If you must access relational data, you may
need Oracle Essbase SQL Interface.
Install Essbase.
53
Process Step
Reference
Identify source data and determine the scope of the Essbase database.
Choose whether to leave data in a relational database and access the data
with XOLAP, or to load all data.
Identify any need for currency conversion applications that track data in
different currencies.
Identify any need to monitor data changes in the database. You monitor
data changes using the Essbase triggers feature.
Estimate the size of your database, check disk space, and ensure that the sizes
of the index, data files, and data caches in memory are adequate.
Appendix A, Limits
Build the dimensions. Decide whether your data loads will introduce new
members into the outline. If so, consider dynamically building your dimensions
using a rules file and a data source. If not, set up regular data loads.
Load your data. You can load data in these ways:
l
Free-form
54
Process Step
Reference
Learn about dynamic calculations and how they can improve performance.
View data with Smart View, other Oracle tools, or third-party tools.
Learn about Partitioning. Think about whether your data can benefit from being
decentralized into connected databases.
Link files or cell notes to data cells.
Allocate storage and specify Essbase kernel settings for your database.
l
Cache sizes: You can specify the index, data file, and data cache sizes. To
prevent a slowdown of the operating system, ensure that the sum of index
and data cache sizes for all the active databases on the server is not more
than two-thirds of the systems RAM.
Cache memory locking: You can lock the memory that is used for the index,
data file, and data caches into physical memory.
Disk volumes: You can specify the storage location of Essbase index files
and data files, appropriate disk volume names, and configuration
parameters.
Isolation level: Specify committed or uncommitted access.
55
Process Step
Reference
Generate a report.
Plan the elements of the report, such as page layout, column number,
member identity, data value format, and title content.
Create and test a report script using Administration Services Report Script
Editor or any other text editor.
56
Process Step
Reference
Set the correct size for the index, data file, data, and calculator caches.
Ensure that disk space is adequate to allow the application to grow over
time.
Enable logging for spreadsheet update to ensure that log files are updated
after archiving.
57
58
Understanding
Multidimensional Databases
3
In This Chapter
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Calculation-intensive capabilities
Time intelligence
59
Key to OLAP systems are multidimensional databases, which not only consolidate and calculate
data; but also provide retrieval and calculation of a variety of data subsets. A multidimensional
database supports multiple views of data sets for users who need to analyze the relationships
between data categories. For example, a marketing analyst might ask following questions:
l
How did Product A sell last month? How does this figure compare to sales in the same month
over the last five years? How did the product sell by branch, region, and territory?
Did this product sell better in particular regions? Are there regional trends?
Did customers return Product A last year? Were the returns due to product defects? Did the
company manufacture the products in a specific plant?
Did commissions and pricing affect how salespeople sold the product? Did certain
salespeople sell more?
In multidimensional databases, the number of data views is limited only by the database outline,
the structure that defines all elements of the database. Users can pivot the data to see information
from a different viewpoint, drill down to find more detailed information, or drill up to see an
overview.
Outline Hierarchies
Dimension and Member Relationships
Standard Dimensions and Attribute Dimensions
Sparse and Dense Dimensions
Selection of Dense and Sparse Dimensions
This section introduces the concepts of outlines, dimensions, and members within a
multidimensional database. If you understand dimensions and members, you are well on your
way to understanding the power of a multidimensional database.
A dimension represents the highest consolidation level in the database outline. The database
outline presents dimensions and members in a tree structure to indicate a consolidation
relationship. For example, in Figure 1 on page 61, Year is a dimension (of type Time) and Qtr1
is a member.
Essbase has standard dimensions and attribute dimensions.
Standard dimensions represent the core components of a business plan and often relate to
departmental functions. Typical standard dimensions: Time, Accounts, Product Line, Market,
and Division. Dimensions change less frequently than members.
Attribute dimensions are associated with standard dimensions. Through attribute dimensions,
you group and analyze members of standard dimensions based on the member attributes
(characteristics). For example, you can compare the profitability of noncaffeinated products
that are packaged in glass to the profitability of noncaffeinated products packaged in cans.
60
Members are the individual components of a dimension. For example, Product A, Product B,
and Product C might be members of the Product dimension. Each member has a unique name.
Essbase can store the data associated with a member (referred to as a stored member in this
chapter), or it can dynamically calculate the data when a user retrieves it.
Outline Hierarchies
All Essbase database development begins with creating a database outline, which accomplishes
the following:
l
Essbase uses the concept of members to represent data hierarchies. Each dimension consists of
one or more members. The members, in turn, may consist of other members. When you create
a dimension, you tell Essbase how to consolidate the values of its individual members. Within
the tree structure of the database outline, a consolidation is a group of members in a branch of
the tree.
For example, many businesses summarize their data monthly, rolling up monthly data to obtain
quarterly figures and rolling up quarterly data to obtain annual figures. Businesses may also
summarize data by zip code, city, state, and country. Any dimension can be used to consolidate
data for reporting purposes.
In the Sample.Basic database included with Essbase Server, for example, the Year dimension
comprises five members: Qtr1, Qtr2, Qtr3, and Qtr4, each storing data for an individual quarter,
plus Year, storing summary data for the year. Qtr1 comprises four members: Jan, Feb, and Mar,
each storing data for a month, plus Qtr1, storing summary data for the quarter. Similarly, Qtr2,
Qtr3, and Qtr4 comprise the members that represent the individual months plus the member
that stores the quarterly totals.
The database outline in Figure 1 uses a hierarchical structure to represent the data consolidations
and relationships in Qtr, as described in the previous paragraph.
Figure 1
Hierarchical Structure
Some dimensions consist of relatively few members, while others may have hundreds or even
thousands of members. Essbase does not limit the number of members within a dimension and
enables the addition of new members as needed.
61
A parent is a member that has a branch below it. For example, Margin is a parent member
for Sales and Cost of Goods Sold.
A child is a member that has a parent above it. For example, Sales and Cost of Goods Sold
are children of the parent Margin.
Siblings are child members of the same immediate parent, at the same generation. For
example, Sales and Cost of Goods Sold are siblings (they both have the parent Margin), but
Marketing (at the same branch level) is not a sibling, because its parent is Total Expenses.
62
Descendants are members in branches below a parent. For example, Profit, Inventory, and
Ratios are descendants of Measures. The children of Profit, Inventory, and Ratios are also
descendants of Measures.
Ancestors are members in branches above a member. For example, Margin, Profit, and
Measures are ancestors of Sales.
The root is the top member in a branch. Measures is the root for Profit, Inventory, Ratios,
and the children of Profit, Inventory, and Ratios.
Leaf members have no children. They are also referred to as level 0 members. For example,
Opening Inventory, Additions, and Ending Inventory are leaf members.
Generation refers to a consolidation level within a dimension. A root branch of the tree is
generation 1. Generation numbers increase as you count from the root toward the leaf
member. In Figure 2, Measures is generation 1, Profit is generation 2, and Margin is
generation 3. All siblings of each level belong to the same generation; for example, both
Inventory and Ratios are generation 2.
Figure 3 shows part of the Product dimension with its generations numbered. Product is
generation 1, 100 is generation 2, 100-10 is generation 3, and 100-10-12 and 100-10-16 are
generation 4.
Figure 3
Generations
Level also refers to a branch within a dimension; levels reverse the numerical ordering used
for generations. Levels count up from the leaf member toward the root. The root level
number varies depending on the depth of the branch. In Figure 2, Sales and Cost of Goods
Sold are level 0. All other leaf members are also level 0. Margin is level 1, and Profit is level
2. Notice that the level number of Measures varies depending on the branch. For the Ratios
branch, Measures is level 2. For the Total Expenses branch, Measures is level 3.
Figure 4 shows part of the Product dimension with its levels numbered. 100 is level 2, 100-10
is level 1, and 100-10-12 and 100-10-16 are level 0.
Figure 4
Levels
63
Essbase maximizes performance by dividing the standard dimensions of an application into two
types: dense dimensions and sparse dimensions. This division allows Essbase to cope with data
that is not smoothly distributed, without losing the advantages of matrix-style access to the data.
Essbase speeds data retrieval while minimizing memory and disk requirements.
Most multidimensional databases are inherently sparse; they lack data values for the majority
of member combinations. A sparse dimension is one with a low percentage of available data
positions filled.
For example, the outline of the Sample.Basic database in Figure 5 includes the Year, Product,
Market, Measures, and Scenario dimensions. Product represents the product units, Market
represents the geographical regions in which the products are sold, and Measures represents the
accounts data. Because not every product is sold in every market, Market and Product are chosen
as sparse dimensions.
Most multidimensional databases also contain dense dimensions. A dense dimension has a high
probability that one or more cells is occupied in every combination of dimensions. For example,
in the Sample.Basic database, accounts data exists for almost all products in all markets, so
Measures is chosen as a dense dimension. Year and Scenario are also chosen as dense dimensions.
Year represents time in months, and Scenario represents whether the accounts values are budget
or actual values.
Caffeinated, Intro Date, Ounces, Pkg Type and Population are attribute dimensions. See
Chapter 10, Working with Attributes.
64
Figure 5
You can apply a recommended configuration, or you can turn off automatic configuration and
manually set the sparse or dense property for each dimension. Attribute dimensions are always
sparse dimensions. Keep in mind that you can associate attribute dimensions only with sparse
standard dimensions.
Note: The automatic configuration of dense and sparse dimensions provides only an estimate.
It cannot take into account the nature of the data that you will load into your database or
multiple user considerations.
65
Essbase creates a data block for each unique combination of members in the Product and Market
dimensions (see Data Storage on page 70). Each data block represents data from the dense
dimensions. The data blocks likely will have few empty cells.
For example, consider the sparse member combination Caffeine Free Cola (100-30), New York,
in Figure 6:
l
If accounts data (represented by the Measures dimension) exists for this combination for
January, it probably exists for February and for all members in the Year dimension.
If a data value exists for one member on the Measures dimension, it is likely that other
accounts data values exist for other members in the Measures dimension.
If Actual accounts data values exist, it is likely that Budget accounts data values exist.
Figure 6
66
The following scenarios show how a database is affected when you select different standard
dimensions. Assume that these scenarios are based on typical databases with at least seven
dimensions and several hundred members.
67
Figure 8
68
Figure 10
Essbase creates data blocks for combinations of members in the sparse standard dimensions
(providing that at least one data value exists for the member combination). The sparse
dimensions are Region and Product. The members of the Region dimension are East, West,
South, and Total US. The members in the Product dimension are Product A, Product B, Product
C, and Total Product.
Figure 11 shows 11 data blocks. No data values exist for Product A in the West and South, for
Product B in the East and West, or for Product C in the East. Therefore, Essbase has not created
data blocks for these member combinations. The data blocks that Essbase has created have few
empty cells. This example effectively concentrates all sparseness into the index and concentrates
all data into fully utilized blocks. This configuration provides efficient data storage and retrieval.
Figure 11
Next, consider a reversal of the dense and sparse dimension selections. In the following example,
Region and Product are dense dimensions, and Time and Accounts are sparse dimensions.
In Figure 12, the two-dimensional data blocks represent data values from the dense dimensions:
Region and Product. In the West region, data is not available for Product A and Product B. Data
is also not available for Total Product in US.
Figure 12
69
Essbase creates data blocks for combinations of members in the sparse standard dimensions
(providing that at least one data value exists for the member combination). The sparse standard
dimensions are Time and Accounts.
Figure 13 shows 12 data blocks. Data values exist for all combinations of members in the Time
and Accounts dimensions; therefore, Essbase creates data blocks for all member combinations.
Because data values do not exist for all products in all regions, the data blocks have many empty
cells. Data blocks with many empty cells store data inefficiently.
Figure 13
Data Storage
Subtopics
l
l
l
Data Values
Data Blocks and the Index System
Multiple Data Views
Each data value in a multidimensional database is stored in one cell. A particular data value is
referenced by specifying its coordinates along each standard dimension.
Note: Essbase does not store data for attribute dimensions. Essbase dynamically calculates
The Accounts dimension has four members: Sales, COGS, Margin, and Margin%.
The Time dimension has four quarter members, and Qtr1 has three month members
70
The Scenario dimension has two child members: Budget for budget values and Actual for
actual values.
Figure 14
Data Values
The intersection of one member from one dimension with one member from each of the other
dimensions represents a data value. The example in Figure 15 has three dimensions (Accounts,
Time, and Scenario); therefore, the dimensions and data values in the database can be
represented as a cube.
Figure 15
Three-Dimensional Database
As illustrated in Figure 16, when you specify Sales, you are specifying the slice of the database
that contains eight Sales values, where Sales intersect with Actual and Budget.
Figure 16
Slicing a database amounts to fixing one or more dimensions at a constant value while allowing
the other dimensions to vary.
As illustrated in Figure 17, when you specify Actual Sales, you are specifying the slice of the
database that contains four Sales values, where Actual and Sales intersect.
71
Figure 17
A data value is stored in one cell in the database. To refer to a specific data value in a
multidimensional database, you specify its member on each dimension. In Figure 18, the cell
containing the data value for Sales, Jan, Actual is shaded. The data value can also be expressed
using the cross-dimensional operator (->) as Sales -> Actual -> Jan.
Figure 18
72
Figure 19
If data exists for Caffeine Free Cola in New York, Essbase creates a data block and an index entry
for the sparse member combination of Caffeine Free Cola (100-30) -> New York. If Caffeine
Free Cola is not sold in Florida, Essbase does not create a data block or an index entry for the
sparse member combination: Caffeine Free Cola (100-30) -> Florida.
The data block Caffeine Free Cola (100-30) -> New York represents all the Year, Measures, and
Scenario dimensions for Caffeine Free Cola (100-30) -> New York.
Each unique data value can be considered to exist in a cell in a data block. When Essbase searches
for a data value, it uses the index to locate the appropriate data block. Then, within the data
block, it locates the cell containing the data value. The index entry provides a pointer to the data
block. The index handles sparse data efficiently because it includes only pointers to existing data
blocks.
Figure 20 shows part of a data block for the Sample.Basic database. Each dimension of the block
represents a dense dimension in the Sample.Basic database: Time, Measures, and Scenario. A
data block exists for each unique combination of members of the Product and Market sparse
dimensions (providing that at least one data value exists for the combination).
Figure 20
Each data block is a multidimensional array that contains a fixed, ordered location for each
possible combination of dense dimension members. Accessing a cell in the block does not involve
sequential or index searches. The search is almost instantaneous, resulting in optimal retrieval
and calculation speed.
Essbase orders the cells in a data block according to the order of the members in the dense
dimensions of the database outline.
73
A (Dense)
a1
a2
B (Dense)
b1
b11
b12
b2
b21
b22
C (Dense)
c1
c2
c3
D (Sparse)
d1
d2
d21
d22
E (Sparse)
e1
e2
e3
The block in Figure 21 represents the three dense dimensions from within the combination of
the sparse members d22 and e3, from the preceding database outline. In Essbase, member
combinations are denoted by the cross-dimensional operator. The symbol for the crossdimensional operator is ->, so d22 -> e3 denotes the block for d22 and e3. The intersection of
A, b21, and c3 is written as A -> b21 -> c3.
Figure 21
Essbase creates a data block for every unique combination of the members of the sparse
dimensions D and E (providing that at least one data value exists for the combination).
Data blocks, such as the one in Figure 21, may include cells that do not contain data values. A
data block is created if at least one data value exists in the block. Essbase compresses data blocks
with missing values on disk, expanding each block fully as it brings the block into memory. Data
compression is optional but is enabled by default. See Data Compression on page 770.
By carefully selecting dense and sparse standard dimensions, you can ensure that data blocks do
not contain many empty cells, minimizing disk storage requirements and improving
performance. In Essbase, empty cells are known as #MISSING data.
74
Planning the development of your multidimensional database, see Chapter 4, Case Study:
Designing a Single-Server, Multidimensional Database.
Selecting dense and sparse dimensions, see Selection of Dense and Sparse Dimensions on
page 65.
Loading data, see Chapter 17, Understanding Data Loading and Dimension Building.
Compressing data and optimizing your database, see Data Compression on page 770.
76
4
In This Chapter
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
77
The outline determines the structure of the databasewhat information is stored and how
different pieces of information interrelate. See Drafting Outlines on page 90.
3. Check system requirements.
How you meet system requirements and define system parameters affects the efficiency and
performance of the database. See Checking System Requirements on page 95.
4. Load test data into the database.
After an outline and a security plan are in place, you load the database with test data to enable
the later steps of the process. See Loading Test Data on page 95.
5. Define calculations.
You test outline consolidations and write and test formulas and calculation scripts for
specialized calculations. See Defining Calculations on page 96.
6. Define reports.
Users access data through print and online reports and spreadsheets or on the Web. If you
plan to provide predefined reports to users, you design report layouts and run reports. See
Defining Reports on page 104.
7. Verify with users.
To ensure that the database satisfies your user goals, solicit and carefully consider user
opinions. See Verifying the Design on page 105.
8. Repeat the process.
To fine-tune the design, repeat steps 1 through 7.
Figure 25
78
Essbase database. TBC is a variation of the Sample.Basic application that is included with the
Essbase installation.
TBC manufactures, markets, and distributes soft drink products internationally. Analysts at TBC
prepare budget forecasts and compare performance to budget forecasts monthly. The financial
measures that analysts track are profit and loss and inventory.
TBC uses spreadsheet packages to prepare budget data and perform variance reporting. Because
TBC plans and tracks a variety of products over several markets, the process of deriving and
analyzing data is tedious. Last month, analysts spent most of their time entering and rekeying
data and preparing reports.
TBC has determined that Essbase is the best tool for creating a centralized repository for financial
data. The data repository will reside on a server that is accessible to analysts throughout the
organization. Users can access the server and load data from various sources and retrieve data
as needed. TBC has a variety of users, so TBC expects that different users will have different
security levels for accessing data.
How information flows within the companywho uses which data for what purposes
The types of reporting the company doeswhat types of data must be included in the outline
to serve user reporting needs
Note: Defining only one database per application enables enhanced memory usage and ease
79
Does the data support the desired analysis and reporting goals?
If not, what additional data do you need, and where can you find it?
Do some users require access to information that other users should not see?
80
Who are the users and what permissions should they have?
See Chapter 39, User Management and Security in EPM System Security Mode.
Next, create a model of the database on paper. To build the model, identify the perspectives and
views that are important to your business. These views translate into the dimensions of the
database model.
Most businesses analyze the following areas:
l
Time periods
Accounting measures
Scenarios
Products
Distribution channels
Geographical regions
Business units
Use the following topics to help you gather information and make decisions.
If analyzing by time, which time periods are needed? Should the analysis include only the
current year or multiple years? Should the analysis include quarterly and monthly data?
Should it include data by season?
81
If analyzing by geographical region, how do you define the regions? Do you define regions
by sales territories? Do you define regions by geographical boundaries such as states and
cities?
If analyzing by product line, should you review data for each product? Can you summarize
data into product classes?
Regardless of the business area, you must determine the perspective and detail needed in the
analysis. Each business area that you analyze provides a different view of the data.
After you determine the dimensions of the database model, choose the elements or items within
the perspective of each dimension. These elements become the members of their respective
dimensions. For example, a perspective of time may include the time periods that you want to
analyze, such as quarters, and within quarters, months. Each quarter and month becomes a
member of the dimension that you create for time. Quarters and months represent a two-level
hierarchy of members and their children. Months within a quarter consolidate to a total for each
quarter.
What are sales for a particular month? How does this figure compare to sales in the same
month over the last five years?
82
In other words, the analyst may want to examine information from three perspectivestime,
account, and scenario. The sample database in Figure 26 represents these three perspectives as
three dimensions, with one dimension represented along each of the three axes:
l
A time dimensionwhich comprises Jan, Feb, Mar, and the total for Qtr1is displayed
along the X-axis.
An accounts dimension, which consists of accounting figures such as Sales, COGS, Margin,
and Margin%, is displayed along the Y-axis.
Another dimension, which provides a different point of view, such as Budget for budget
values and Actual for actual values, is displayed along the Z-axis.
Figure 26
The cells within the cube, where the members intersect, contain the data relevant to all three
intersecting members; for example, the actual sales in January.
Dimensions
Members
Child Members
Year
Qtr1
Year
Qtr2
Year
Qtr3
Year
Qtr4
Measures
Profit
Measures
Inventory
83
Dimensions
Members
Child Members
Measures
Ratios
Product
Colas (100)
Product
Old Fashioned (200-10), Diet Root Beer (200-20), Sarsaparilla (200-30), Birch Beer (200-40)
Product
Dark Cream (300-10), Vanilla Cream (300-20), Diet Cream Soda (300-30)
Product
Market
East
Market
West
Market
South
Market
Central
Scenario
Actual
N/A
Scenario
Budget
N/A
Scenario
Variance
N/A
Scenario
Variance %
N/A
In addition, the planner added two attribute dimensions to enable product analysis based on
size and packaging:
Table 3
Dimensions
Members
Child Members
Ounces
Large
64, 32, 20
Small
16, 12
Bottle
N/A
Pkg Type
Can
84
While the initial dimension design is still on paper, you should review the design according to
a set of guidelines. The guidelines help you fine-tune the database and leverage the
multidimensional technology. The guidelines are processes or questions that help you achieve
an efficient design and meet consolidation and calculation goals.
The number of members needed to describe a potential data point should determine the number
of dimensions. If you are not sure whether you should delete a dimension, keep it and apply
more analysis rules until you feel confident about deleting or keeping it.
Use the information in the following topics to analyze and improve your database design.
Cust A
100
N/A
N/A
Cust B
N/A
150
N/A
Cust C
N/A
N/A
30
Cust A is only in New York, Cust B is only in Illinois, and Cust C is only in California. The
company can define the data in one standard dimension:
Market
New York
Cust A
85
Illinois
Cust B
California
Cust C
However, if you look at a larger sampling of data, you may see that many customers can be in
each market. Cust A and Cust E are in New York; Cust B, Cust M, and Cust P are in Illinois;
Cust C and Cust F are in California. In this situation, the company typically defines the large
dimension, Customer, as a standard dimension and the smaller dimension, Market, as an
attribute dimension. The company associates the members of the Market dimension as attributes
of the members of the Customer dimension. The members of the Market dimension describe
locations of the customers.
Customer (Standard dimension)
Cust A (Attribute:New York)
Cust B (Attribute:Illinois)
Cust C (Attribute:California)
Cust E (Attribute:New York)
Cust F (Attribute:California)
Cust M (Attribute:Illinois)
Cust P (Attribute:Illinois)
Market (Attribute dimension)
New York
Illinois
California
Consider another situation. Again, the company sells products to multiple customers over
multiple markets, but the company can ship to a customer that has locations in different markets:
New York
Illinois
California
Cust A
100
N/A
150
Cust B
75
150
N/A
Cust C
N/A
N/A
30
Cust A is in New York and California. Cust B is in New York and Illinois. Cust C is only in
California. Using an attribute dimension does not work in this situation; a customer member
cannot have multiple attribute members. Therefore, the company designs the data in two
standard dimensions:
Customer
Cust A
Cust B
Cust C
Market
New York
Illinois
California
Dimension Combinations
Break each combination of two dimensions into a two-dimensional matrix. For example,
proposed dimensions at TBC (as listed in Table 2 on page 83) include the following
combinations:
l
86
Ounces and Pkg Type, as attribute dimensions associated with the Product dimension, can be
considered with the Product dimension.
To help visualize each dimension, draw a matrix and include a few of the first-generation
members. Figure 27 shows a simplified set of matrixes for three dimensions.
Figure 27
For each combination, the answers to the questions help determine whether the combination is
valid for the database. Ideally, the answer to each question is yes. If not, consider rearranging
the data into more-meaningful dimensions. As you work through this process, discuss
information needs with users.
Repetition in Outlines
The repetition of elements in an outline often indicates a need to split dimensions. The following
examples show you how to avoid repetition.
87
In Figure 28 on page 88, the left column, labeled Repetition, shows Profit, Margin, Sales,
COGS, and Expenses repeated under Budget and Actual in the Accounts dimension. The right
column, labeled No Repetition, separates Budget and Actual into another dimension
(Scenario), leaving just one set of Profit, Margin, Sales, COGS, and Expenses members in the
Accounts dimension. This approach simplifies the outline and provides a simpler view of the
budget and actual figures of the other dimensions in the database.
Figure 28
In Figure 29 on page 88, the left column, labeled Repetition, uses shared members in the
Diet dimension to analyze diet beverages. Members 10020, 20020, and 30020 are repeated:
once under Diet, and once under their respective parents. The right column, labeled No
Repetition, simplifies the outline by creating a Diet attribute dimension of type Boolean (True
or False). All members are shown only once, under their respective parents, and are tagged with
the appropriate attribute (Diet: True or Diet: False).
Figure 29
Attribute dimensions also provide additional analytic capabilities. See Designing Attribute
Dimensions on page 171.
Interdimensional Irrelevance
Interdimensional irrelevance occurs when many members of a dimension are irrelevant across
other dimensions. Essbase defines irrelevant data as data that Essbase stores only at the summary
(dimension) level. In such a situation, you may be able to remove a dimension from the database
and add its members to another dimension or split the model into separate databases.
For example, TBC considered analyzing salaries as a member of the Measures dimension. But
salary information often proves irrelevant in the context of a corporate database. Most salaries
88
are confidential and apply to individuals. The individual and the salary typically represent one
cell, with no reason to intersect with any other dimension.
TBC considered separating employees into a separate dimension. Table 4 shows an example of
how TBC analyzed the proposed Employee dimension for interdimensional irrelevance.
Members of the proposed Employee dimension (represented in the table header row) are
compared with members of the Measures dimension (represented in the left-most column). The
Measures dimension members (such as Revenue) apply to All Employees; only the Salary
measure is relevant to individual employees.
Table 4
Mary Jones
Mike Garcia
All Employees
Revenue
Irrelevance
Irrelevance
Irrelevance
Relevance
Variable Costs
Irrelevance
Irrelevance
Irrelevance
Relevance
COGS
Irrelevance
Irrelevance
Irrelevance
Relevance
Advertising
Irrelevance
Irrelevance
Irrelevance
Relevance
Salaries
Relevance
Relevance
Relevance
Relevance
Fixed Costs
Irrelevance
Irrelevance
Irrelevance
Relevance
Expenses
Irrelevance
Irrelevance
Irrelevance
Relevance
Profit
Irrelevance
Irrelevance
Irrelevance
Relevance
Drafting Outlines
Subtopics
l
l
l
l
l
Now you can create the application and database and build the first draft of the outline in Essbase.
The draft defines all dimensions, members, and consolidations. Use the outline to design
consolidation requirements and identify where you need formulas and calculation scripts.
Note: Before you create a database and build its outline, create an Essbase application in which
90
Year. TBC needs to collect data monthly and summarize the monthly data by quarter and
year. Monthly data, stored in members such as Jan, Feb, and Mar, consolidates to quarters.
Quarterly data, stored in members such as Qtr1 and Qtr2, consolidates to Year.
Measures. Sales, Cost of Goods Sold, Marketing, Payroll, Miscellaneous, Opening Inventory,
Additions, and Ending Inventory are standard measures. Essbase can calculate Margin, Total
Expenses, Profit, Total Inventory, Profit %, Margin %, and Profit per Ounce from these
measures. TBC needs to calculate Measures on a monthly, quarterly, and yearly basis.
Product. The Product codes are 100-10, 100-20, 100-30, 200-10, 200-20, 200-30, 200-40,
300-10, 300-20, 300-30, 400-10, 400-20, and 400-30. Each product consolidates to its
respective family (100, 200, 300, and 400). Each consolidation allows TBC to analyze by size
and package, because each product is associated with members of the Ounces and Pkg Type
attribute dimensions.
Market. Several states make up a region; four regions make up a market. The states are
Connecticut, Florida, Massachusetts, New Hampshire, New York, California, Nevada,
Oregon, Utah, Washington, Louisiana, New Mexico, Oklahoma, Texas, Colorado, Illinois,
Iowa, Missouri, Ohio, and Wisconsin. Each state consolidates into its regionEast, West,
South, or Central. Each region consolidates into Market.
l
Scenario. TBC derives and tracks budget versus actual data. Managers must monitor and
track budgets and actuals, as well as the variance and variance percentage between them.
Pkg Type. TBC wants to see the effect that product packaging has on sales and profit.
Establishing the Pkg Type attribute dimension enables users to analyze product information
based on whether a product is packaged in bottles or cans.
Ounces. TBC sells products in different sizes in ounces in different markets. Establishing
the Ounces attribute dimension helps users monitor which sizes sell better in which markets.
The following topics present a review of the basics of dimension and member properties and a
discussion of how outline design affects performance.
Dimension types and attribute associations. See Dimension Types on page 91.
For a complete list of dimension and member properties, see Chapter 9, Setting Dimension
and Member Properties.
Dimension Types
A dimension type is a property that Essbase provides that adds special functionality to a
dimension. The most commonly used dimension types: time, accounts, and attribute. This topic
uses the following dimensions of the TBC database to illustrate dimension types.
Database:Design
Year (Type: time)
Measures (Type: accounts)
Product
Market
Scenario
Pkg Type (Type: attribute)
Ounces (Type: attribute)
91
Table 5
Dimension Types
Dimension Types
Description
None
Time
Defines the time periods for which you report and update data. You can tag only one dimension as time. The time
dimension enables several accounts dimension functions, such as first and last time balances.
Accounts
Contains items that you want to measure, such as profit and inventory, and makes Essbase built-in accounting
functionality available. Only one dimension can be defined as accounts.
For discussion of two forms of account dimension calculation, see Accounts Dimension Calculations on page
99.
Attribute
Contains members that can be used to classify members of another, associated dimension.
For example, the Pkg Type attribute dimension contains a member for each type of packaging, such as bottle or can,
that applies to members of the Product dimension.
Country
Contains data about where business activities take place. In a country dimension, you can specify the currency used
in each member.
For example, Canada has three marketsVancouver, Toronto, and Montreal, which use the same currency, Canadian
dollars.
Currency
partition
Separates local currency members from the base currency defined in the application. This dimension type is used only
in the main database and is only for currency conversion applications. The base currency for analysis may be U.S.
dollars, and the local currency members may contain values that are based on the currency type of their region.
Data Storage
Properties
Effects on Members
Store data
The member stores data. Store data is the default storage property.
Dynamic Calc
The data associated with the member is not calculated until requested by a user. The calculated data is not stored;
it is discarded after the request is completed.
The data associated with the member is not calculated until it is requested by a user. The calculated data is then
stored.
Shared member
The data associated with the member comes from another member with the same name.
92
Data Storage
Properties
Effects on Members
Never share
The data associated with the member is duplicated with the parent and its child if an implied shared relationship
exists.
Label only
Although a label only member has no data associated with it, a label only member can display a value. The label
only tag groups members and eases navigation and reporting. Typically, label only members are not calculated.
For example, in the Measures dimension, the member Ratios has three children, Margin%, Profit%, and Profit per
Ounce. The member Ratios defines a category of members. When consolidated, Margin%, Profit%, and Profit per
Ounce do not roll up to a meaningful figure for Ratios. Hence, Ratios is tagged as label only.
Does the data include foreign currencies? If so, did you identify a currency partition
dimension?
Can you identify qualities or characteristics of dimensions that should be defined as separate
attribute dimensions?
Which members require special data storage properties?
Position attribute dimensions at the end of the outline. Position dense dimensions before sparse
dimensions.
The position of dimensions in an outline and the storage properties of dimensions can affect
two areas of performancehow quickly calculations are run and how long it takes users to
retrieve information.
Use the following topics to understand performance optimization basics.
If the outline contains attribute dimensions, ensure that the attribute dimensions are the
only sparse Dynamic Calc dimensions in the outline.
In the outline, place the more-queried sparse dimensions before the less-queried sparse
dimensions.
93
Because the outline contains attribute dimensions, the storage property for standard
dimensions and all standard dimensions members is set as store data.
As the most-queried sparse dimension, the Product dimension is the first of the sparse
dimensions. Base dimensions are typically queried more than other dimensions.
Figure 30
The smallest standard dimension that is sparse, Market, is the first of the sparse dimensions
in the outline.
The largest standard dimension that is sparse, Product, is immediately above the first
attribute dimension. If the outline did not contain attribute dimensions, the Product
dimension would be at the end of the outline.
Figure 31
94
on the database. How often do you expect to update and recalculate the database? What is the
nature of user queries? What is the expected volume of user queries?
A possible workaround is initially to position the dimensions in the outline to optimize
calculation. After you run the calculations, you can manually resequence the dimensions to
optimize retrieval. When you save the outline after you reposition its dimensions, choose to
restructure the database by index only. Before you run calculations again, resequence the
dimensions in the outline to optimize calculation.
Chapter 19, Using a Rules File to Perform Operations on Records, Fields, and Data
If you are satisfied with your database design after the preliminary test, test load the complete
set of real data with which you will populate the final database. Use the test rules files if possible.
This final test may reveal source data problems that were not anticipated during earlier design
process phases.
95
Defining Calculations
Subtopics
l
l
l
l
l
l
l
Calculations are essential to derive certain types of data. Data that is derived from a calculation
is called calculated data; basic noncalculated data is called input data.
The following topics use the Product and Measures dimensions of the TBC application to
illustrate several types of common calculations that are found in many Essbase databases.
For information on block storage calculations, see the following chapters:
l
When you define members of standard dimensions, Essbase automatically tags the members
with the + consolidation operator (plus sign representing addition), meaning that during
consolidation members are added. As appropriate, you can change a member consolidation
property to one of the operators shown in Table 7, Consolidation Operators, on page 98.
Consolidation is the most frequently used calculation in Essbase. This topic uses the Product
dimension to illustrate consolidations.
The TBC application has several consolidation paths:
l
Individual products roll up to product families, and product families consolidate into
Product. The TBC outline also requires multiple consolidation paths; some products must
consolidate in multiple categories.
96
Consolidation operators define how Essbase rolls up data for each member in a branch to the
parent. For example, using the default addition (+) operator, Essbase adds 100-10, 100-20, and
100-30 and stores the result in their parent, 100, as shown in Figure 32.
Figure 32
The Product dimension contains mostly addition (+) operators, which indicate that each group
of members is added and rolled up to the parent. Diet has a tilde (~) operator, which indicates
that Essbase does not include the Diet member in the consolidation to the parent, Product. The
Diet member consists entirely of members that are shared. The TBC product management group
wants to be able to isolate Diet drinks in reports, so TBC created a separate Diet member that
does not impact overall consolidation.
97
Table 7
Consolidation Operators
Consolidation Operator
Description
The default operator. Essbase adds the member to the result of previous calculations performed on members
of the branch.
Dash ()
Essbase multiplies the member by -1 and then adds the product to the result of previous calculations performed
on members of the branch.
Asterisk (*)
Essbase multiplies the member by the result of previous calculations performed on members of the branch.
Essbase divides the member into the result of previous calculations performed on members of the branch.
Essbase divides the member into the sum of previous calculations performed on members of the branch. The
result is multiplied by 100.
Tilda (~)
Essbase does not use the value of the member in the consolidation to its parent.
Caret (^)
Essbase does not use the value of the member in any consolidation in any dimension except attribute
dimensions.
Did you tag each member with the proper consolidation operator?
Would shared members be more efficient if designed within an attribute dimension (other
than shared)?
98
The Inventory and Ratios member names assist the user in data navigation. They do not
contain data and therefore receive a label only tag.
The Measures dimension itself has a label only tag. Some members of Measures have a
Dynamic Calc tag. Dynamic calculations are discussed in Dynamic Calculations on page
102.
Some members of Measures have a time balance tag (TB First or TB Last). Time balance
tags are discussed in Setting Time Balance Properties on page 143.
Figure 33
This topic discusses two forms of calculations for a dimension tagged as accounts, time balance
properties and variance reporting.
99
Table 8
Tags
Description
The value for the last child member is carried to the parent. For example, March is carried to Qtr1.
The value for the first child is carried to the parent. For example, Jan is carried to Qtr1.
In Table 9, Qtr1 (second column from the right) and Year (right-most column) show how
consolidation in the time dimension is affected by time balance properties in the accounts
dimension. Data is shown for the first quarter only.
Table 9
Dimensions
Jan
Feb
Mar
Qtr1
Year
Accounts Member1
11
12
13
36
20
25
21
20
20
25
21
30
30
Value of Qtr4
Normally, the calculation of a parent in the time dimension is based on the consolidation and
formulas of children of the parent. However, if a member in an accounts branch is marked as
TB First, any parent in the time dimension matches the member marked as TB First.
For examples, see Setting Time Balance Properties on page 143.
Variance Reporting
One TBC Essbase requirement is the ability to perform variance reporting on actual versus
budget data. The variance reporting calculation requires that any item that represents an expense
to the company must have an expense reporting tag. Inventory members, Total Expense
members, and the COGS member each receive an expense reporting tag for variance reporting.
Essbase provides two variance reporting propertiesexpense and nonexpense. The default is
nonexpense. Variance reporting properties define how Essbase calculates the difference between
actual and budget data in members with the @VAR or @VARPER function in their member
formulas.
When you tag a member as expense, the @VAR function calculates Budget Actual. For example,
if the budgeted amount is $100 and the actual amount is $110, the variance is 10.
Without the expense reporting tag, the @VAR function calculates Actual Budget. For example,
if the budgeted amount is $100 and the actual amount is $110, the variance is 10.
Functions are predefined routines that perform specialized calculations and return sets of
members or sets of data values. Formulas comprise operators and functions, as well as dimension
names, member names, and numeric constants.
Essbase supports the following operators:
l
The Essbase functions include more than 100 predefined routines to extend the calculation
capabilities of Essbase. Essbase supports the following functions:
l
Boolean functions, which provide a conditional test by returning a TRUE or FALSE value
Relationship functions, which look up data values within a database during a calculation
based on the position of the current member
Range functions, which declare a range of members as an argument to another function or
to a command
Financial functions, which perform specialized financial calculations
Member set functions, which are based on a specified member and which generate lists of
members
Allocation functions, which allocate values that are input at a parent level across child
members
Forecasting functions, which manipulate data for the purpose of smoothing data,
interpolating data, or calculating future values
Date and time functions, which use date and time characteristics in calculation formulas
Calculation mode functions, which specify the calculation mode that Essbase uses to
calculate a formula
Essbase uses consolidation operators to calculate the Margin, Total Expenses, and Profit
members. The Margin% formula uses a % operator, which means express Margin as a
101
percentage of Sales. The Profit% formula uses the same % operator. The Profit per Ounce
formula uses a division operator (/) and a function (@ATTRIBUTEVAL) to calculate
profitability by ounce for products sized in ounces.
Note: In the Profit per Ounce formula, the @NAME function is also used to process the string
Dynamic Calculations
When you design the overall database calculation, you may want to define a member as a
Dynamic Calc member. When you tag a member as Dynamic Calc, Essbase calculates the
combinations of that member when you retrieve the data, instead of precalculating the member
combinations during the regular database calculation. Dynamic calculations shorten regular
database calculation time but may increase retrieval time for dynamically calculated data values.
In Figure 34, the TBC Measures dimension contains several members tagged as Dynamic Calc
Profit, Margin, Total Expenses, Margin %, and Profit %.
Figure 34
When an overall database calculation is performed, the Dynamic Calc members and their
corresponding formulas are not calculated. These members are calculated when a user requests
them, for example, from Smart View. Essbase does not store the calculated values; it recalculates
the values for any subsequent retrieval. However, you can choose to store dynamically calculated
values after the first retrieval.
To decide when to calculate data values dynamically, consider your priorities in the following
areas:
l
102
Two-Pass Calculations
In the TBC database, Margin % and Profit % contain the label two-pass. This default label
indicates that some member formulas must be calculated twice to produce the desired value.
The two-pass property works only on members of the dimension tagged as accounts and on
members tagged as Dynamic Calc and Dynamic Calc and Store.
The following example illustrates why Profit % (based on the formula Profit % Sales) has a twopass tag. The tables have five columns (column headers are labeled left to right as Dimension,
Jan, Feb, Mar, and Qtr1) and three rows (labeled as Profit, Sales, and Profit %). Jan, Feb, Mar,
and Qtr1 are members of the Year dimension. Profit, Sales, and Profit % are members of the
Measures (accounts) dimension.
Table 10 on page 103 defines the initial data to load into Essbase. The data values for Profit ->
Jan, Profit -> Feb, and Profit -> Mar are 100. The data value for Sales -> Jan, Sales -> Feb, and
Sales -> Mar are 1000.
Table 10
Dimension
Jan
Feb
Mar
Qtr1
Profit
100
100
100
N/A
Sales
1000
1000
1000
N/A
Profit %
N/A
N/A
N/A
N/A
First, Essbase calculates the Measures dimension. In Table 11 on page 103, the data values for
Profit % -> Jan, Profit % -> Feb, and Profit % -> Mar are 10%.
Table 11
Dimension
Jan
Feb
Mar
Profit
100
100
100
Sales
1000
1000
1000
Profit %
10%
10%
10%
Qtr1
N/A
Next, Essbase calculates the Year dimension. The data rolls up across the dimension. In Table 12
on page 104, the data values for Profit -> Qtr1 (300) and Sales -> Qtr1 (3000) are correct. The
data value for Profit % -> Qtr1 (30%) is incorrect because Profit % is tagged as a two-pass
calculation.
103
Table 12
Dimension
Jan
Feb
Mar
Qtr1
Profit
100
100
100
300
Sales
1000
1000
1000
3000
Profit %
10%
10%
10%
30%
Essbase then recalculates profit percentage at each occurrence of the member Profit %. In
Table 13 on page 104, the data value for Profit % -> Qtr1 (10%) is correct after the second pass.
Table 13
Dimension
Jan
Feb
Mar
Qtr1
Profit
100
100
100
300
Sales
1000
1000
1000
3000
Profit %
10%
10%
10%
10%
Note: The Essbase triggers feature enables efficient monitoring of data changes in a database.
Defining Reports
To ensure that the design meets user information requirements, you must view data as users
view it. Users typically view data through spreadsheets, printed reports, or reports published on
the Web. Oracle and its partners offer many tools for producing the reporting systems that users
use.
Several tools can help you display and format data quickly, and test whether the database design
meets user needs. You can use the Report Script Editor in Administration Services Console to
write report scripts quickly. Those familiar with spreadsheets can use Smart View (which requires
Provider Services).
104
Grouping and sequencing of data. Do the intersections enabled by the design provide the
data that users need?
Levels of totals. What consolidation levels are required by, for example, a Smart View user
who drills down and up through the hierarchy of the outline design?
Attribute reporting. Does the database design facilitate an analysis that is based on the
characteristics or attributes of specific dimensions or members? For example, do you need
to compare sales by specific combinations of size and packaging, such as comparing the sales
of 16-ounce bottled colas with the sales of 32-ounce bottled colas?
Be sure to use the appropriate tool to create and test predesigned use reports against the test
data. The reports that you design should provide information that meets your original objectives.
The reports should be easy to use, providing the right combinations of data and the right amount
of data. Because reports with too many columns and rows are difficult to use, you may need to
create several reports instead of one all-inclusive report.
105
106
5
In This Chapter
Introduction............................................................................................... 107
Administration Services Architecture ................................................................... 107
Deploying Administration Services ..................................................................... 108
Starting Administration Services........................................................................ 108
About Administration Services Users................................................................... 109
Connecting to Administration Services................................................................. 109
Adding Essbase Administration Servers to Enterprise View .......................................... 109
Adding Essbase Servers to Enterprise View ........................................................... 110
About Essbase Server Connections and Ports ........................................................ 110
About Essbase Administration Server .................................................................. 110
Introduction
Administration Services is the cross-platform administration tool for Essbase. Administration
Services consists of a Java middle-tier server, called Essbase Administration Server, and a Java
client console, called Administration Services Console.
Administration Services Console is the graphical user interface (GUI) that enables
administrators to manage the Essbase environment from one navigation tree, called Enterprise
View. The console provides wizards, editors, and other tools to help administrators view,
manage, and maintain a unique set of Essbase Servers. The console includes a data preview grid
that enables you to preview data without having to switch from the console to another program.
107
Figure 35
108
109
In Enterprise View, right-click an Essbase Server node, and select Add Essbase Server.
Select File, then Wizards, then User Setup. Follow the wizard instructions.
You can also create custom views of the Enterprise View tree in separate tabs in the navigation
pane. See About Custom Views in the Oracle Essbase Administration Services Online Help.
110
111
112
Part II
113
114
6
In This Chapter
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
Create an application.
Create a database.
If necessary, set substitution variables at the Essbase Server, application, or database level.
115
Files that are related to databases are called artifacts (or objects). Database artifacts perform
actions against one or more Essbase databases, such as defining calculations or reporting against
data. By default, artifacts are stored in their associated database folder on the Essbase Server, and
can also be saved to a client computer or to other available network directories. You cannot,
however, load data or calculate data on a client computer.
Essbase provides the following common types:
l
Data sources
Rules for loading data and building dimensions dynamically (rules files)
Security definitions
Partition definitions
116
Some of these artifacts are optional, such as calculation scripts and LROs. See Application and
Database File Types on page 706.
In Administration Services Console, database artifacts are displayed under their associated
applications or database in the Enterprise View tree.
See Creating a Database on page 120 and Chapter 7, Creating and Changing
Database Outlines.
Text files
Spreadsheet files
117
Understanding LROs
An LRO is an artifact associated with a specific data cell in an Essbase database. LROs can enhance
data analysis capabilities by providing additional information on a cell.
An LRO can be any of the following:
l
118
Creating an Application
Creating a Database
Annotating a Database
Create an application and then create its databases. You can annotate the databases.
Creating an Application
When you create an application on the Essbase Server, Essbase creates a subdirectory for the
application on the Essbase Server in the ARBORPATH/app directory. The new subdirectory has
the same name as the application; for example, ARBORPATH/app/app1. In Administration
Services Console, applications and databases are displayed in a tree structure in Enterprise View.
Before naming the application, see Naming Conventions for Applications and Databases on
page 1093.
You can also create an application that is a copy of an existing application. See Copying or
Migrating Applications on page 710.
Topic
Location
Administration Services
Creating Applications
MaxL
create application
ESSCMD
CREATEAPP
119
Creating a Database
When you create a database, Essbase creates a subdirectory for the database within the
application directory. The new subdirectory has the same name as the database; for example,
ARBORPATH/app/app1/dbname1. In Administration Services Console, applications and
databases are displayed in a tree structure in Enterprise View.
You can create normal databases or currency databases. Except for databases requiring use of
the Currency Conversion option, creating one database per application is recommended. See
Chapter 14, Designing and Building Currency Conversion Applications.
Before naming the database, see Naming Conventions for Applications and Databases on page
1093.
Topic
Location
Administration Services
Creating Databases
MaxL
create database
ESSCMD
CREATEDB
Annotating a Database
A database note can provide useful information when you need to broadcast messages to users
about the status of a database, deadlines for updates, and so on. Users can view database notes
in Smart View.
To annotate a database:
See Annotating Databases in the Oracle Essbase Administration Services Online Help.
Substitution variables are global placeholders for regularly changing information. Because
changes to a variable value are reflected everywhere the variable is used, manual changes are
reduced.
120
For example, many reports depend on reporting periods; if you generate a report based on the
current month, you must update the report script manually every month. With a substitution
variable, such as CurMnth, set on the server, you can change the assigned value each month to
the appropriate time period. When you use the variable name in a report script, the information
is dynamically updated when you run the final report.
You can use substitution variables with both aggregate storage and block storage applications
(unless otherwise noted) in the following areas:
l
Report scripts
See Chapter 35, Developing Report Scripts.
Data load rules file header definitions and field definitions. You can enter variable names
for dimension and member names.
See these topics, Setting Headers in the Rules File and Mapping Field Names, in the
Oracle Essbase Administration Services Online Help.
Partition definitions
See Substitution Variables in Partition Definitions on page 223.
Data source name (DSN) specifications in rules files for SQL data sources
See Oracle Essbase SQL Interface Guide.
SELECT, FROM, or WHERE clauses in rules files for SQL data sources
See Oracle Essbase SQL Interface Guide.
Security filters
See Filtering Using Substitution Variables on page 645.
MDX statements
See Using Substitution Variables in MDX Queries on page 597.
Smart View
See the Oracle Smart View for Office User's Guide.
You can set substitution variables on the Essbase Server using Administration Services, MaxL,
or ESSCMD. Set the variable at any of the following levels:
l
Essbase Serverproviding access to the variable from all applications and databases on the
Essbase Server
121
Applicationproviding access to the variable from all databases within the application
If a substitution variable value is numeric, different rules apply for how you enter the
variable:
m
122
Topic
Location
Administration Services
MaxL
alter system
alter application
alter database
ESSCMD
CREATEVARIABLE
To ensure that a new substitution variable value is available in formulas, partition definitions,
and security filters, stop and restart the application. All other uses of substitution variables are
dynamically resolved when used.
Topic
See
Administration Services
MaxL
alter system
alter application
alter database
ESSCMD
DELETEVARIABLE
123
Topic
See
Administration Services
MaxL
alter system
alter application
alter database
ESSCMD
UPDATEVARIABLE
A location alias is a descriptor for a data source. A location alias maps an alias name for a database
to the location of that database. A location alias is set at the database level and specifies an alias,
a server, an application, a database, a user name, and a password. Set the location alias on the
database on which the calculation script is run.
After you create a location alias, you can use the alias to refer to that database. If the location of
the database changes, edit the location definition accordingly.
You can use location aliases only with the @XREF and @XWRITE functions. With @XREF, you
can retrieve a data value from another database to include in a calculation on the current
database. In this case, the location alias points to the database from which the value is to be
retrieved. With @XWRITE, you can write values to another Essbase database, or to the same
database. See the Oracle Essbase Technical Reference.
124
The following considerations apply when using location aliases in secure (SSL) mode:
l
To enable Essbase to use SSL connectivity, you must set ENABLESECUREMODE to TRUE.
If the location alias is being set up to a secure port, you must append :secure to the server
name specification. For example, using MaxL,
create location alias EasternDB from Sample.Basic to East.Sales at Easthost:
6423:secure as User1 identified by password1;
Topic
Location
Administration Services
MaxL
ESSCMD
CREATELOCATION
Topic
Location
Administration Services
MaxL
LISTLOCATIONS
DELETELOCATION
125
126
7
In This Chapter
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
To create an outline:
1
127
If necessary, create attribute dimensions and associate them with the appropriate base dimensions.
See Opening and Editing Outlines in the Oracle Essbase Administration Services Online
Help.
l
Copy an existing outline to the current database and change the existing outline.
Caution!
If you open the same outline with two instances of the Administration Services
Console using the same login ID, each save overwrites the changes of the other
instance. Oracle does not recommend this practice, as it can be difficult to keep track
of the changes that are saved or overwritten.
Topic
Location
Administration Services
MaxL
create database
128
Tool
Topic
Location
ESSCMD
CREATEDB
Topic
Location
Administration Services
Copying Outlines
MaxL
create database as
ESSCMD
COPYDB
Topic
Location
Administration Services
MaxL
create database as
ESSCMD
UNLOCKOBJECT
With a data source and rules file, using Data Prep Editor
Before naming dimensions and members, see Naming Conventions for Applications and
Databases on page 1093.
129
To add dimensions and members dynamically (using a rules file) from Outline Editor:
See Updating an Outline Dynamically Using a Rules File in the Oracle Essbase Administration
Services Online Help.
130
Moving dimensions and members can affect the performance of calculations and retrievals.
See Designing an Outline to Optimize Performance on page 93.
Moving members could move a shared member before the actual member in the outline
(which is not recommend).
If you add, delete, or move nonattribute dimensions or members, Essbase restructures the
database, and you must recalculate the data.
Position attribute dimensions at the end of the outline. Otherwise, during outline
verification, Essbase prompts you to move them there.
You cannot sort Boolean attribute dimensions. See Understanding Attribute Types on page
166.
Verifying Outlines
You can verify an outline automatically when you save it, or you can verify the outline manually
anytime. When verifying an outline, Essbase checks the following items:
131
All member and alias names are valid. Members and aliases cannot have the same name as
other members, aliases, generations, or levels.
See Naming Conventions for Applications and Databases on page 1093.
The currency category and currency name are valid for the currency outline.
Dynamic Calc members in sparse dimensions do not have more than 100 children.
If a parent member has one child, and if that child is a Dynamic Calc member, the parent
member must also be Dynamic Calc.
If a parent member has one child, and if that child is a Dynamic Calc, two-pass member,
the parent member must also be Dynamic Calc, two-pass.
The two names of members of Boolean attribute dimensions are the same as the two Boolean
attribute dimension member names defined for the outline.
The level 0 member name of a date attribute dimension must match the date format name
setting (mm-dd-yyyy or dd-mm-yyyy). If the dimension has no members, because the
dimension name is the level 0 member, the dimension name must match the setting.
The level 0 member name of a numeric attribute dimension is a numeric value. If the
dimension has no members, because the dimension name is the level 0 member, the
dimension name must be a numeric value.
Attribute dimensions are located at the end of the outline, following all standard dimensions.
During outline verify, Essbase also performs the following conversions to appropriate numeric
attribute dimension member names and displays them in the outline:
l
It moves minus signs in member names from the front to the end of the name; for example,
1 becomes 1.
It strips out leading or trailing zeroes in member names; for example, 1.0 becomes 1, and
00.1 becomes 0.1.
To verify an outline:
See Verifying Outlines in the Oracle Essbase Administration Services Online Help.
132
Saving Outlines
Subtopics
l
l
l
You can save outlines to the Essbase Server or to a client computer or network. By default, Essbase
saves outlines to the database directory on Essbase Server. If you are saving changes to an outline,
Essbase may restructure the outline. For example, if you change a member name from Market
to Region, Essbase moves data stored in reference to Market to Region. Each time that you save
an outline, Essbase verifies the outline to ensure that it is correct.
To save an outline:
See Saving Outlines in the Oracle Essbase Administration Services Online Help.
Save the database using a different name, and specify the member to keep.
Only one member can be kept when a dimension is deleted. See Saving an Outline with
One or More Deleted Standard Dimensions on page 133.
133
134
In This Chapter
Creating Duplicate Member Names in Outlines ....................................................... 135
Restrictions for Duplicate Member Names and Aliases in Outlines ................................. 136
Syntax for Specifying Duplicate Member Names and Aliases ....................................... 137
Working with Duplicate Member Names ............................................................... 139
The information in this chapter applies to block storage and aggregate storage databases.
Also see:
l
The qualified member names for the example in Figure 37 are [State].[New York] and [City].
[New York]. See Syntax for Specifying Duplicate Member Names and Aliases on page 137.
135
To create an outline that enables duplicate member names, or to convert a unique member
name outline to a duplicate member name outline, use a tool:
Tool
Topic
Location
Administration Services
MaxL
create database
Note: Save outline changes before converting the outline to a duplicate member name outline.
You cannot convert an outline that has unsaved changes. After converting an outline to
a duplicate member outline, save it before proceeding with other outline changes. A
duplicate member outline cannot be converted back to a unique member outline.
Within a duplicate member outline, you can tag particular dimensions, generations, and levels
as unique or duplicate to restrict the use of duplicate member names within a database. Doing
so enables you to specify member name uniqueness at a more granular level in a duplicate
member outline.
When you create a duplicate member outline, by default, all dimensions in the outline are tagged
as duplicate.
When duplicate members are enabled in a dimension, you can tag particular generations or
levels within the dimension as unique. If a member is assigned conflicting properties, the unique
property takes precedence.
that apply to attribute dimensions in unique outlines. For example, in a duplicate member
Boolean attribute dimension, members do not include dimension, parent, grandparent,
or ancestors affixed to the TRUE and FALSE members. See Setting Prefix and Suffix
Formats for Member Names of Attribute Dimensions on page 173.
136
Dimension names
If you are using aliases, this additional restriction applies: an alias table that contains duplicate
alias names is valid only with a duplicate member outline.
Note: Do not use quotation marks (" "), brackets ([ ]), or tabs in member, dimension, or alias
names. For example, you cannot create a member name [New York].[Area 1]. Outline
verification does not display an error for member names that contain the invalid sequence
of characters, and you can save the outline; however, Essbase cannot accurately query the
data.
Note: A qualified name must comprise all alias names or all member names. You cannot mix
For example:
[Market].[East].[State].[New York]
[Market].[East].[City].[New York]
137
For example:
[State].[New York]
[City].[New York]
Scenario
Example
[DimensionMember].[DuplicateMember]
[Year].[Jan]
[DimensionMember]@[DuplicateMember]
[Year]@[Jan]
[ParentMember].[DuplicateMember]
[East].[New York]
[DimensionMember].[ParentMember].
[DuplicateMember]
[Products].[Personal
Electronics].
[Televisions]
[DimensionMember]@[GenLevelName]|
[DuplicateMember]
[2006]@[Gen1]|[Jan]
[DifferentiatingAncestor].[Ancestors...].
[DuplicateMember]
[2006].[Qtr1].[Jan]
138
[Product].[Jan]
Smart View, see the Oracle Smart View for Office User's Guide
To use duplicate member names in MaxL and MDX, see the Oracle Essbase Technical
Reference.
Note: If an alias name and member name are the same but do not represent the same member,
searching by alias name is not supported in clients (for example Administration Services
or the API).
In Administration Services, if you use the member selection tool to insert a duplicate member
name from the outline tree, the qualified member name is inserted automatically.
If you type a duplicate member name directly into an editor, type the qualified member name
and enclose the qualified name in double quotation marks (" "). For example,
"[State].[New York]"
In MDX and MaxL qualified member names are not enclosed in quotation marks. See Inserting
Dimension and Member Names in MDX Scripts in the Oracle Essbase Administration Services
Online Help. The Administration Services Data Preview feature does not support duplicate
member outlines.
139
140
In This Chapter
Setting Dimension Types ................................................................................ 141
Setting Member Consolidation ......................................................................... 146
Calculating Members with Different Operators ........................................................ 147
Determining How Members Store Data Values........................................................ 147
Setting Aliases ........................................................................................... 153
Setting Two-Pass Calculations .......................................................................... 157
Creating Formulas........................................................................................ 158
Naming Generations and Levels........................................................................ 158
Creating UDAs ............................................................................................ 158
Adding Comments ....................................................................................... 159
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
When you tag a dimension as a specific type, the dimension can access built-in functionality
designed for that type. For example, if you define a dimension as accounts, you can specify
accounting measures for members in that dimension. Essbase calculates the two primary
dimension types, time and accounts, before other dimensions in the database. By default, all
dimensions are tagged as none.
141
You can add time members to dimensions that are not tagged as time.
You can create an outline that does not have a time dimension.
You can specify that members of the accounts dimension are calculated on the second pass
through an outline. See Setting Two-Pass Calculations on page 157.
You can create an outline that does not have an accounts dimension.
142
(TB
(TB
(TB
(TB
First),
First),
First),
First),
Cola,
Cola,
Cola,
Cola,
East,
East,
East,
East,
Actual,
Actual,
Actual,
Actual,
Jan(+),
Feb(+),
Mar(+),
Qtr1(+),
50
60
70
50
(TB
(TB
(TB
(TB
Last),
Last),
Last),
Last),
Cola,
Cola,
Cola,
Cola,
East,
East,
East,
East,
Actual,
Actual,
Actual,
Actual,
Jan(+),
Feb(+),
Mar(+),
Qtr1(+),
50
60
70
70
143
(TB
(TB
(TB
(TB
Average),
Average),
Average),
Average),
Cola,
Cola,
Cola,
Cola,
East,
East,
East,
East,
Actual,
Actual,
Actual,
Actual,
Jan(+),
Feb(+),
Mar(+),
Qtr1(+),
60
62
67
63
Skip Properties
Setting
Essbase Action
None
Missing
Zeros
Skips data that equals zero when calculating the parent value.
Skips #MISSING data and data that equals zero when calculating the parent value.
If you mark a member as last with a skip property of missing or missing and zeros, the parent
of that time period matches the last nonmissing child. In the following example,
EndingInventory is based on the value for Feb, because Mar does not have a value.
Cola,
Cola,
Cola,
Cola,
East,
East,
East,
East,
Actual,
Actual,
Actual,
Actual,
60
70
#MI
70
When you are budgeting nonexpense items, such as sales, the actual sales should be more than
the budget. When actual sales are less than budget, the variance is negative. The @VAR function
calculates Actual Budget. For example, if budgeted sales were $100, and you made $110 in
sales, the variance is 10.
By default, members are nonexpense.
145
This dimension type is used for currency conversion applications. See Chapter 14, Designing
and Building Currency Conversion Applications.
Consolidation Operators
Operator
Description
Adds the member to the result of previous calculations performed on other members. + is the default operator.
Multiplies the member by 1 and adds it to the sum of previous calculations performed on other members.
Multiplies the member by the result of previous calculations performed on other members.
Divides the member into the result of previous calculations performed on other members.
Divides the member into the sum of previous calculations performed on other members. The result is multiplied by 100 to
yield a percentage value.
Does not use the member in any consolidation in any dimension except attribute dimensions.
146
(+)
(+)
(-)
(*)
(%)
(/)
(~)
10
20
25
40
50
60
70
Storage
Property
Behavior
See
Store
Dynamic Calc
and Store
Does not calculate the data value until a user requests it, and then stores
the data value.
147
Storage
Property
Behavior
See
Dynamic Calc
Does not calculate the data value until a user requests it, and then discards
the data value.
Never share
Creates members for navigation only; that is, members that contain no data
values.
Shared member
148
Tagging DescendantC as Store Data or Dynamic Calc and Store resolves the issue.
The data values associated with a shared member come from another member with the same
name. The shared member stores a pointer to data contained in the other member, and the data
is stored only once. To define a member as shared, an actual nonshared member of the same
name must exist. For example, in the Sample.Basic database, the 100-20 member under 100
stores the data for that member. The 100-20 member under Diet points to that value.
Shared members typically are used to calculate the same member across multiple parents; for
example, to calculate a Diet Cola member in both the 100 and Diet parents.
Using shared members lets you use members repeatedly throughout a dimension. Essbase stores
the data value only once, but it displays in multiple locations. Storing the data value only once
saves space and improves processing efficiency.
149
Shared members must be in the same dimension. For example, both 100-20 members in the
Sample.Basic database are in the Product dimension.
You can create a shared member for a member with a duplicate member name. Specify the
duplicate member name for which you want to create the shared member. The qualified
name of the duplicate member, on which the shared member is based, is displayed in the
Member Properties dialog box. See Defining Shared Members in the Oracle Essbase
Administration Services Online Help.
Attributes cannot be associated with shared members.
If accounts properties are assigned to shared members, the values for those accounts
properties are taken from the base member, even if the accounts properties on the shared
member are changed.
Avoid complex relationships between actual and shared members that will be part of an
attribute calculation, or a calculation may return unexpected results. See Understanding
Attribute Calculation and Shared Members on page 181.
Note: You cannot create a shared member and the member on which it is based under the same
from their base members, because you can specify for them to be displayed with a qualified
name (for example, [Parent].[Child]). Shared members can be displayed with qualified
names even if you have not set the outline to enable duplicate member names.
Additionally, you can use qualified member names to search for shared members in the
grid or using member selection.
150
Essbase retrieves stored members (not their shared member counterparts) by default.
If the parent of a shared member is a sibling of the stored member counterpart of one of the
shared members, Essbase retrieves the stored member.
If you retrieve only the children of East, all results are from stored members because Essbase
retrieves stored members by default.
If, however, you retrieve data with the children of test above it in the spreadsheet, Essbase
retrieves the shared members:
New York
Massachusetts
Florida
Connecticut
New Hampshire
test
If you move test above its last two children, Essbase retrieves the first three children as shared
members, but the last two as stored members. Similarly, if you insert a member in the middle
of the list above which was not a sibling of the shared members (for example, California inserted
between Florida and Connecticut), Essbase retrieves shared members only between the
nonsibling and the parent (in this case, between California and test).
151
If you create a spreadsheet with shared members in this order, Essbase retrieves all the shared
members, except it retrieves the stored member West, not the shared member west:
West
New York
Massachusetts
Connecticut
New Hampshire
test
Essbase retrieves the members in this order because test is a parent of west and a sibling of wests
stored member counterpart, West.
A parent has only one child. In this situation, the parent and the child contain the same
data. Essbase ignores the consolidation property on the child and stores the data only once
thus the parent has an implied shared relationship with the child. In the following
example, the parent 500 has only one child, 500-10, so the parent shares the value of that
child:
500 (+)
500-10 (+)
152
A parent has only one child that consolidates to the parent. If the parent has four children,
but three are marked as no consolidation, the parent and child that consolidates contain the
same data. Essbase ignores the consolidation property on the child and stores the data only
oncethus the parent has an implied shared relationship with the child. In the following
example, the parent 500 has only one child, 500-10, that rolls up to it. The other children
are marked as No Consolidate(~), so the parent implicitly shares the value of 500-10.
500 (+)
500-10 (+)
500-20 (~)
500-30 (~)
If you do not want a member to be shared implicitly, mark the parent as Never Share so that the
data is duplicated instead. See Understanding Shared Members on page 149 for an explanation
of how shared members work.
Setting Aliases
The information about aliases and alias tables applies to block storage and aggregate storage
databases.
An alias is an alternate name for a member or shared member. For example, members in the
Product dimension in the Sample.Basic database are identified both by product codes, such as
100, and by more descriptive aliases, such as Cola. Aliases, stored in alias tables, can improve the
readability of outlines or reports.
You can set multiple aliases for a member using alias tables. For example, you can use different
aliases for different kinds of reportsusers may be familiar with 100-10 as Cola, but advertisers
and executives may be familiar with it as The Best Cola. This list shows products in the
Sample.Basic database that have two descriptive alias names:
Product
100-10
100-20
100-30
Default
Cola
Diet Cola
Caffeine Free Cola
Long Names
The Best Cola
Diet Cola with Honey
All the Cola, none of the Caffeine
Alias Tables
Aliases are stored in one or more tables as part of a database outline. An alias table maps a specific,
named set of alias names to member names. When you create a database outline, Essbase creates
an empty alias table named Default. If you do not create any other alias tables, the aliases that
you create are stored in the Default alias table.
You can create an alias table for each set of outline members. When you view the outline or
retrieve data, you can use the alias table name to indicate which set of alias names you want to
see. Identifying which alias table contains the names that you want to see while viewing an outline
is called making an alias table the active alias table. See Setting an Alias Table as Active on page
155.
For Unicode-mode applications, setting up a separate alias table for each user language enables
users to view member names in their own language. See Chapter 42, Understanding the Essbase
Unicode Implementation.
153
Creating Aliases
You can provide an alias for any member. Alias names must follow the same rules as member
names. See Naming Conventions for Dimensions, Members, and Aliases on page 1094.
You can use any of the following methods to create aliases in an existing alias table:
l
To manually assign an alias to a member while editing an outline, see Creating Aliases for
Dimensions and Members in the Oracle Essbase Administration Services Online Help.
To use dimension build and a data source to add aliases to an alias table, see Defining a
Rules File for Adding Aliases in the Oracle Essbase Administration Services Online Help.
To import alias values from an alias table source file created in a predefined format, see
Importing and Exporting Alias Tables on page 156.
You can create up to 32 alias tables for a block storage or aggregate storage outline.
The naming conventions for alias table names are the same as those for dimensions.
See Naming Conventions for Dimensions, Members, and Aliases on page 1094.
The name of the system-generated default alias table, which is Default, cannot be changed;
however, the name of alias tables that you create can be changed.
Optional. You can specify multiple language codes for an alias table. When you create an
alias table, a language code is not specified. See Working with Alias Table Language Codes
on page 155.
154
A new alias table is empty. To add aliases to an alias table and assign them to members, see
Creating Aliases on page 154.
To view a list of alias tables in the outline and to set the current alias table, use a tool:
Tool
Topic
Location
Administration Services
MaxL
query database
alter database
ESSCMD
LISTALIASES
SETALIAS
Topic
Location
Administration Services
MaxL
alter object
ESSCMD
COPYOBJECT
Topic
Location
Administration Services
MaxL
alter object
ESSCMD
RENAMEOBJECT
156
The first line in the file starts with $ALT_NAME. Add one or two spaces followed by the
name of the alias table. If the alias table name contains a blank character, enclose the name
in single quotation marks.
The last line of the file must be $END.
Each line between the first and the last lines contains two values separated by one or more
spaces or tabs. The first value must be the name of an existing outline member; the second
value is the alias for the member.
Any member or alias name that contains a blank or underscore must be enclosed in double
quotation marks.
You can also export an alias table from the Essbase outline to a text file. The export file contains
aliases and the corresponding member namesqualified member names for duplicate
members.
Topic
Location
Administration Services
alter database
ESSCMD
LOADALIAS
UNLOADALIAS
Creating Formulas
You can apply formulas to standard dimensions and members. You cannot set formulas for
attribute dimensions and their members. The formula determines how Essbase calculates the
outline data. See Chapter 23, Developing Formulas for Block Storage Databases.
Creating UDAs
You can create user-defined attributes (UDA) for members. For example, you might create a
UDA called Debit. Use UDAs in the following places:
l
158
Calculation scripts. After you define a UDA, you can query a member for its UDA in a
calculation script. For example, you can multiply all members with the UDA Debit by 1 so
that they display as either positive or negative (depending on how the data is currently
stored). See Chapter 29, Developing Calculation Scripts for Block Storage Databases.
Data loading. You can change the sign of the data as it is loaded into the database based on
its UDA. See Flipping Field Signs on page 304.
To perform a calculation, selectively retrieve data based on attribute values, or provide full
crosstab, pivot, and drill-down support in the spreadsheet, create attribute dimensions instead
of UDAs. See Comparing Attributes and UDAs on page 169.
Note: On aggregate storage databases, using UDAs to define member groups greatly decreases
the execution speeds of Essbase functions. To avoid this performance loss, use attribute
dimensions to define member groups.
Rules when creating UDAs:
l
You cannot set the same UDA twice for one member.
A UDA name can be the same as a member, alias, level, or generation name. Follow the same
naming rules as for members. See Naming Conventions for Dimensions, Members, and
Aliases on page 1094.
A UDA applies to the specified member only. Descendants and ancestors of the member do
not automatically receive the same UDA.
Adding Comments
You can add comments to dimensions and members. Comments can contain 255 characters
maximum. Outline Editor displays comments to the right of the dimension or member in the
following format:
/* comment */
159
160
10
In This Chapter
Process for Creating Attributes.......................................................................... 161
Understanding Attributes ................................................................................ 162
Understanding Attribute Dimensions................................................................... 163
Designing Attribute Dimensions ........................................................................ 171
Building Attribute Dimensions .......................................................................... 172
Setting Member Names in Attribute Dimensions ..................................................... 173
Calculating Attribute Data............................................................................... 177
Varying Attributes ........................................................................................ 182
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
2. Tag the dimension as an attribute dimension and set attribute dimension type as text,
numeric, Boolean, or date.
See Creating Attribute Dimensions on page 146.
3. Add members to the attribute dimension.
See Adding Dimensions and Members to an Outline on page 129.
4. Associate a base dimension with the attribute dimension.
See Understanding the Rules for Attribute Dimension Association on page 165.
5. Associate members of the base dimension with members of the attribute dimension.
See Understanding the Rules for Attribute Member Association on page 165.
6. If necessary, set up the attribute calculations.
See Calculating Attribute Data on page 177.
Understanding Attributes
You can use the Essbase attribute feature to retrieve and analyze data not only from the
perspective of dimensions, but also in terms of characteristics, or attributes, of those dimensions.
For example, you can analyze product profitability based on size or packaging, and you can make
more effective conclusions by incorporating market attributes, such as the population of each
market region, into the analysis.
Such an analysis could tell you that decaffeinated drinks sold in cans in small markets
(populations less than 6,000,000) are less profitable than you anticipated. For more details, you
can filter the analysis by specific attribute criteria, including minimum or maximum sales and
profits of different products in similar market segments.
A few ways analysis by attribute provides depth and perspective, supporting better-informed
decisions:
l
162
You can select, aggregate, and report on data based on common features (attributes).
By defining attributes as having a text, numeric, Boolean, or date type, you can filter (select)
data using type-related functions such as AND, OR, and NOT operators and <, >, and =
comparisons.
You can use the numeric attribute type to group statistical values by attribute ranges; for
example, population groupings such as <500,000, 500,0001,000,000, and >1,000,000.
Through the Attribute Calculations dimension automatically created by Essbase, you can
view sums, counts, minimum or maximum values, and average values of attribute data. For
example, when you enter Avg and Bottle into a spreadsheet, Essbase retrieves calculated
values for average sales in bottles for all the column and row intersections on the sheet.
You can perform calculations using numeric attribute values in calculation scripts and
member formulas; for example, to determine profitability by ounce for products sized by
the ounce.
You can create crosstabs of attribute data for the same dimension, and you can pivot and
drill down for detail data in spreadsheets.
An attribute crosstab is a report or spreadsheet showing data consolidations across attributes
of the same dimension. The crosstab example below displays product packaging as columns
and the product size in ounces as rows. At their intersections, you see the profit for each
combination of package type and size.
From this information, you can see which size-packaging combinations were most profitable
in the Florida market.
Product Year Florida Profit Actual
Bottle
Can
Pkg Type
======
=====
========
32
946
N/A
946
20
791
N/A
791
16
714
N/A
714
12
241
2,383
2,624
Ounces 2,692
2,383
5,075
163
A standard dimension is any dimension that is not an attribute dimension. When an attribute
dimension is associated with a standard dimension, the standard dimension is the base
dimension for that attribute dimension. In Figure 40, the Product dimension is the base
dimension for the Caffeinated, Ounces, and Pkg Type attribute dimensions.
Note: Attribute dimensions and members are Dynamic Calc, so Essbase calculates attribute
You cannot associate an attribute with an implied shared member, the child of which is
tagged as shared.
164
== (equal to)
IN
You cannot associate multiple members from the same attribute dimension with the same
base dimension member. For example, the Bottle and Can package types cannot both be
associated with the product 100-30.
You can associate members from different attribute dimensions with the same member of
a base dimension. For example, a decaffeinated cola product (100-30) sold in 16-ounce
bottles has three attributes: Caffeinated:False; Ounces:16; and Pkg Type:Bottle.
After attributes are associated with base dimension members, if you cut or copy and paste
base dimension members to another outline location, the attribute associations are lost.
Essbase does not require that each member of a base dimension be associated with a member
of an attribute dimension.
All base dimension members associated with members of a particular attribute dimension
must be at the same level.
For example, in Figure 41, all Market dimension members that have Population attributes
are at level 0. You cannot associate East, which is a level 1 member, with a Population
165
attribute, because the other members of the Market dimension that have Population
attributes are level 0 members.
Figure 41
Association of Attributes with the Same Level Members of the Market Dimension
The level 0 members of attribute dimensions are the only members that you can associate
with base dimension members.
For example, in the Population attribute dimension, you can associate only level 0 members
such as 3000000, 6000000, and 9000000, with members of the Market dimension. You
cannot associate a level 1 member such as Small.
The name of the level 0 member of an attribute dimension is the attribute value. The only
members of attribute dimensions that have attribute values are level 0 members.
You can use the higher-level members of attribute dimensions to select and group data. For
example, you can use Small, the level 1 member of the Population attribute dimension, to
retrieve sales in both the 3000000 and 6000000 population categories.
The default attribute type is text. Text attributes enable the basic attribute member selection
and attribute comparisons in calculations. When you perform such comparisons, Essbase
compares characters. For example, the package type Bottle is less than the package type Can,
because B precedes C in the alphabet. In Sample.Basic, Pkg Type is an example of a text
attribute dimension.
The names of level 0 members of numeric attribute dimensions are numeric values. You
can include the names (values) of numeric attribute dimension members in calculations.
For example, you can use the number of ounces specified in the Ounces attribute to calculate
profit per ounce for each product.
You can also associate numeric attributes with ranges of base dimension values; for example,
to analyze product sales by market population groupingsstates with 3,000,000 population
or less in one group, states with a population between 3,000,001 and 6,000,000 in another
group, and so on. See Setting Up Member Names Representing Ranges of Values on page
175.
166
All Boolean attribute dimensions in a database contain only two members. The member
names must match the settings for the database; for example, True and False. If multiple
Boolean attribute dimensions exist, specify a prefix or suffix member name format to ensure
unique member names; for example, Caffeinated_True and Caffeinated_False. See Setting
Boolean Attribute Member Names on page 174.
You can use date attributes to specify the date formatmonth-day-year or day-month-year
and to sequence information accordingly. See Changing the Member Names in Date
Attribute Dimensions on page 175. You can use date attributes in calculations. For
example, you can compare dates in a calculation that selects product sales from markets
established since 10-12-1999.
Essbase supports date attributes from January 1, 1970, through January 1, 2038.
Functionality
Attribute Dimensions
Standard Dimensions
Storage
Storage property
Can be Dynamic Calc only. Therefore, not stored in the database. The outline
does not display this property.
Position in outline
Partitions
Cannot be defined along attribute dimensions, but you can use attributes
to define a partition on a base dimension
Cannot be associated
Can be associated
Shared members
Not allowed
Allowed
Two-pass calculation
member property
Not available
Available
167
Functionality
Attribute Dimensions
Standard Dimensions
Two-pass calculation
with runtime formula
Calculation is performed on
standard members with runtime
formulas and tagged two-pass.
Two-pass calculation
with no member formula
Available
Available
For attributes to work on dense members, data blocks for the dense
members must exist. When retrieving data on a dense member that has a
Dynamic Calc formula and no attributes, Essbase dynamically creates the
data block and returns a value. However, if the Dynamic Calc dense member
has an attribute, doing a retrieve on the attribute member results in
#MISSING, because Essbase skips the dynamic calculation on the dense
member and, therefore, the data block is not created.
To identify nonexisting stored blocks, export the database or run a query to
find out whether the block has data.
UDAs on members
Not allowed
Allowed
Consolidations
Consolidation operation
indicated by assigning the
desired consolidation symbol to
each member
Member selection
facilitated by Level 0
member typing
Associations
N/A
Spreadsheet drilldowns
List the base dimension data associated with the selected attribute. For
example, drilling down on the attribute Glass displays sales for each product
packaged in glass, where Product is the base dimension for the Pkg Type
attribute dimension.
168
Essbase skips the calculation because the formula includes the @CURRMBR runtime function,
which is not allowed, and issues the following error message:
Two-pass calc skipped on member [400-30] in attribute calc
If 400-30 does not have a member formula, the same error message is generated because a
member tagged as two-pass must have a formula.
Table 19
Data storage
Attributes
UDAs
Supported
Supported
Not supported
Supported
Table 20
Data Retrieval
Attributes
UDAs
You can group and retrieve consolidated totals by attribute or UDA value. For example,
associate the value High Focus Item to various members of the Product dimension and
use that term to retrieve totals and details for only those members.
Supported
Supported
Simple
More difficult to
implement, requiring
additional calculation
scripts or commands
169
Data Retrieval
Attributes
UDAs
You can categorize attributes in a hierarchy and retrieve consolidated totals by higher levels
in the attribute hierarchy; for example, if each product has a size attribute such as 8, 12,
16, or 32, and the sizes are categorized as small, medium, and large. You can view the
total sales of small products.
Supported
Supported
You can create crosstab views displaying aggregate totals of attributes associated with
the same base dimension.
Supported
Not supported
You can use Boolean operators AND, OR, and NOT with attribute and UDA values to refine
a query. For example, you can select decaffeinated drinks from the 100 product group.
Supported
Supported
Because attributes have a text, Boolean, date, or numeric type, you can use appropriate
operators and functions to work with and display attribute data. For example, you can view
sales totals of all products introduced after a specific date.
Supported
Not supported
You can group numeric attributes into ranges of values and let the dimension building
process automatically associate the base member with the appropriate range. For
example, you can group sales in various regions based on ranges of their populations
less than 3 million, between 3 million and 6 million, and so on.
Supported
Not supported
Through the Attribute Calculations dimension, you can view aggregations of attribute values
as sums, counts, minimums, maximums, and averages.
Supported
Not supported
You can use an attribute in a calculation that defines a member. For example, you can
use the weight of a product in ounces to define the profit per ounce member of the
Measures dimension.
Supported
Not supported
Supported
Supported
Powerful
conditional and
value-based
selections
Table 21
More difficult to
implement
Data Conversion
Attributes
UDAs
Based on the value of a UDA, you can change the sign of the data as it is loaded into the database. For
example, you can reverse the sign of all members with the UDA Debit.
Not supported
Supported
Table 22
Calculation Scripts
Attributes
UDAs
You can perform calculations on a member if its attribute or UDA value matches a specific value. For example,
you can increase the price by 10% of all products with the attribute or UDA of Bottle.
Supported
Supported
You can perform calculations on base members whose attribute value satisfies conditions that you specify.
For example, you can calculate the Profit per Ounce of each base member.
Supported
Not supported
170
Essbase provides multiple ways to design attribute information into a database. Most often,
defining characteristics of the data through attribute dimensions and their members is the best
approach. The following sections discuss when to use attribute dimensions, when to use other
features, and how to optimize performance when using attributes.
UDAs. Although UDAs provide less flexibility than attributes, you can use them to group
and retrieve data based on its characteristics. See Comparing Attributes and UDAs on
page 169.
Shared members. For example, to include a seasonal analysis in the Year dimension, repeat
the months as shared members under the appropriate season; Winter: Jan (shared member),
Feb (shared member), and so on. A major disadvantage of using shared members is that the
outline becomes large if the categories repeat many members.
171
Standard dimensions and members. Additional standard dimensions provide flexibility but
add storage requirements and complexity to a database. For guidelines on evaluating the
impact of additional dimensions, see Analyzing and Planning on page 79.
Table 23 describes situations in which you might consider an alternative approach to managing
attribute data in a database.
Table 23
Situation
Alternative
Ensure that attribute dimensions are the only sparse Dynamic Calc dimensions in the
outline.
Locate sparse dimensions after dense dimensions in the outline. Place the most-queried
dimensions at the beginning of the sparse dimensions and attribute dimensions at the end
of the outline. In most situations, base dimensions are queried most.
To view the dimension, attribute value, and attribute type of a specific attribute member,
use a tool:
Tool
Topic
Location
Administration Services
MaxL
query database
ESSCMD
GETATTRINFO
Setting Prefix and Suffix Formats for Member Names of Attribute Dimensions
Setting Boolean Attribute Member Names
Changing the Member Names in Date Attribute Dimensions
Setting Up Member Names Representing Ranges of Values
Changing the Member Names of the Attribute Calculations Dimension
When you use the attribute feature, Essbase establishes default member names; for example, the
system-defined True and False precludes other member names of True and False. You can change
these system-defined names for the database. Date attributes and numeric attributes also can be
duplicated. To avoid duplicate name confusion, you can establish settings for qualifying member
names in attribute dimensions. The outline does not show the fully qualified attribute names,
but you can see the full attribute names anywhere you select members, such as when you define
partitions or select information to be retrieved.
Define the member name settings before you define or build the attribute dimensions. Changing
the settings after the attribute dimensions and members are defined could result in invalid
member names.
The following sections describe how to work with the names of members of attribute dimensions:
Note: If you partition on outlines containing attribute dimensions, the name format settings of
members described in this section must be identical in the source and target outlines.
Boolean example
173
If you have multiple Boolean attribute dimensions in an outline, the two members of each
of those dimensions have the same names, by default, True and False.
l
Date example
If you have multiple date attribute dimensions, some member names in both dimensions
could be the same. For example, the date on which a store opens in a certain market could
be the same as the date on which a product was introduced.
Numeric example
The attribute value for the size of a product could be 12, and 12 also could be the value for
the number of packing units for a product. This example results in two members with the
name 12.
You can define unique names by attaching a prefix or suffix to member names in Boolean, date,
and numeric attribute dimensions in the outline. You can affix the dimension, parent,
grandparent, or all ancestors to the attribute name. For example, by setting member names of
attribute dimensions to include the dimension name as the suffix, attached by an underscore,
the member value 12 in the Ounces attribute dimension assumes the unique, full attribute
member name 12_Ounces.
By default, Essbase assumes that no prefix or suffix is attached to the names of members of
attribute dimensions.
The convention that you select applies to the level 0 member names of all numeric, Boolean,
and date attribute dimensions in the outline. You can define aliases for these names if you want
to display shorter names in retrievals.
To define the database setting for the names of members of Boolean attribute dimensions:
See Setting Member Names for Boolean Attribute Dimensions in the Oracle Essbase
Administration Services Online Help.
174
If you change the date member name format, the names of existing members of date attribute
dimensions may be invalid. For example, if the 10-18-2007 member exists, and you change the
format to dd-mm-2007, outline verification will find this member invalid. If you change the
date format, you must rebuild the date attribute dimensions.
Single-value example: the member 12 in the Ounces attribute dimension represents the
single numeric value 12; you associate this attribute with all 12-ounce products. The outline
includes a separate member for each size; for example, 16, 20, and 32.
Range of values example: the Population attribute dimension, as shown in Figure 42:
Figure 42
In this outline, the members of the Population attribute dimension represent ranges of
population values in the associated Market dimension. The 3000000 member represents
populations from zero through 3,000,000; the 6000000 member represents populations
from 3,000,001 through 6,000,000; and so on. A setting for the outline establishes that each
numeric member represents the top of its range.
175
You can also define this outline setting so that members of numeric attribute dimensions
are the bottoms of the ranges that they represent. For example, if numeric members are set
to define the bottoms of the ranges, the 3000000 member represents populations from
3,000,000 through 5,999,999, and the 6000000 member represents populations from
6,000,000 through 8,999,999.
When you build the base dimension, Essbase automatically associates members of the base
dimension with the appropriate attribute range. For example, if numeric members represent the
tops of ranges, Essbase automatically associates the Connecticut market, with a population of
3,269,858, with the 6000000 member of the Population attribute dimension.
In the dimension build rules file, specify the size of the range for each member of the numeric
attribute dimension. In the above example, each attribute represents a range of 3,000,000.
than six decimal positions. Otherwise, because of precision adjustments, an outline may
not pass verification.
If the outline is tagged as a duplicate member outline, you can use the default names to name
other base or attribute members.
If the outline is tagged as a unique member outline, you should avoid using Sum, Count,
Min, Max, and Avg as member names. For example, if you use Max in a standard dimension
and then create an attribute dimension, in which Essbase creates the Max member in the
Attribute Calculations dimension, Essbase detects a duplicate name and returns an error
message indicating the name is already in use.
Regardless of the name that you use for a Attribute Calculations dimension member, its function
remains the same. For example, Count, the second member, always counts.
176
Essbase calculates attribute data dynamically at retrieval time, using members from a systemdefined dimension created by Essbase. Using this dimension, you can apply different calculation
functions, such as a sum or an average, to the same attribute. You can also perform specific
calculations on members of attribute dimensions; for example, to determine profitability by
ounce for products sized by the ounce.
The following information assumes that you understand the concepts of attribute dimensions
and Essbase calculations, including dynamic calculations. See the following sections.
System-defined
When you create the first attribute dimension in an application, Essbase creates the Attribute
Calculations dimension and its members (Sum, Count, Min, Max, and Avg). Each member
represents a type of calculation to be performed for attributes.
See Understanding the Default Attribute Calculations Members on page 179.
Label only
177
Like all label only dimensions, the Attribute Calculations dimension shares the value of its
first child, Sum.
See Member Storage Properties on page 92.
l
Dynamic Calc
The data in the Attribute Calculations dimension is calculated when a user requests it and
is then discarded. You cannot store calculated attribute data in a database.
See Chapter 27, Dynamically Calculating Data Values.
There is no consolidation along attribute dimensions. You cannot tag members from attribute
dimensions with consolidation symbols (for example, + or -) or with member formulas in order
to calculate attribute data. As Dynamic Calc members, attribute calculations do not affect the
batch calculation in terms of time or calculation order.
To calculate attribute data at retrieval time, Essbase performs the following tasks:
1. Finds the base-dimension members associated with the attribute-dimension members
present in the current query
2. Dynamically calculates the sum, count, minimum, maximum, or average for the attributemember combination for the current query
3. Displays the results in the spreadsheet or report
4. Discards the calculated valuesthat is, the values are not stored in the database
Note: Essbase excludes #MISSING values when calculating attribute data.
For example, as shown in Figure 43, a spreadsheet user specifies two members of attribute
dimensions (Ounces_16 and Bottle) and an Attribute Calculations member (Avg) in a
spreadsheet report. Upon retrieval, Essbase dynamically calculates the average sales values of all
products associated with these attributes for the current member combination (Actual -> Sales > East -> Qtr1):
Figure 43
See Accessing Attribute Calculations Members Using the Spreadsheet on page 180.
178
You can change these default member names, subject to the same naming conventions as
standard members. See Changing the Member Names of the Attribute Calculations
Dimension on page 176.
Base-Dimension Member
Associated Attributes
Cola
Ounces_12, Can
23205
Diet Cola
Ounces_12, Can
3068
Diet Cream
Ounces_12, Can
1074
Grape
Ounces_32, Bottle
6398
Orange
Ounces_32, Bottle
3183
Strawberry
Ounces_32, Bottle
5664
Figure 44 on page 180 shows how calculated attribute data might look in a spreadsheet report.
You can retrieve multiple Attribute Calculations members for attributes. For example, you can
calculate Sum, Count, Avg, Min, and Max for bottles and cans.
179
Figure 44
The calculation order for attribute calculations is the same as for dynamic calculations. For
an outline, see Calculation Order for Dynamic Calculation on page 435.
Because Essbase calculates attribute data dynamically at retrieval time, attribute calculations
do not affect the performance of the overall (batch) database calculation.
Tagging base-dimension members as Dynamic Calc may increase retrieval time.
When a query includes the Sum member and an attribute-dimension member whose
associated base member is tagged as two-pass, retrieval time may be slow.
To maximize attribute retrieval performance, use any of the following techniques:
m
180
Configure the outline using the tips in Optimizing Outline Performance on page
172.
Drill down to the lowest level of base dimensions before retrieving data. For example,
in Smart View, turn on the Navigate Without Data feature, drill down to the lowest level
of the base dimensions included in the report, and then retrieve data.
When the members of a base dimension are associated with several attribute dimensions,
consider grouping the members of the base dimension according to their attributes. For
example, in the Sample.Basic database, you can group all 8-ounce products.
members. See the rows about two-pass calculations in Table 18 on page 167 and
Understanding Two-Pass Calculations on Attribute Dimensions on page 169.
Table 25 lists functions you can use to perform specific calculations on attributes:
Table 25
Function
Type of Calculation
@ATTRIBUTE
Generate a list of all base members with a specific attribute. For example, generate a list of members that have the
Bottle attribute, and then increase the price for those members.
@ATTRIBUTEVAL
Return the value of the level 0 attribute member that is associated with the base member being calculated.
@ATTRIBUTEBVAL
@ATTRIBUTESVAL
For example, return the numeric value of a size attribute (for example, 12 for the member 12 under Ounces) for the
base member being calculated (for example, Cola).
For an additional example using @ATTRIBUTEVAL in a formula, see Calculating an Attribute Formula on page 390.
@TODATE
Convert a date string to numbers for a calculation. For example, use @TODATE in combination with the @ATTRIBUTEVAL
function to increase overhead costs for stores opened after a certain date.
@WITHATTR
Generate a list of base dimension members associated with attributes or varying attributes that satisfy the conditions
that you specify. For example, generate a list of products that are greater than or equal to 20 ounces, and then increase
the price for those products.
181
Member 2 (shared)
Member B (stored)
Member 1 (shared member whose stored member is Member 1 above)
To avoid unexpected results with attribute calculation, avoid mixing shared and stored members.
For this example, if Member 2 were not shared, or Member 1 did not have a corresponding
shared member elsewhere in the outline, calculation results would be as expected.
Given these differences, the result of aggregating attribute dimension members might differ from
the result of aggregating standard dimension members, if shared members are involved and
there are multiple aggregation paths.
To workaround this issue, remove duplicate shared members under the aggregating attribute
hierarchy or remodel the outline so that there are not multiple aggregation paths.
Varying Attributes
Subtopics
l
l
l
l
A varying attribute enables you to track two values in relation to a third dimension called an
independent dimension. You could, for example, track your product in eight ounces over a year.
In this scenario, Time is the independent dimension. The value of this third factor can vary
(hence the name). For example, you could track your product over a year, a quarter, or a month.
Note: There are two types of independent dimensions: continuous and discrete. The members
in a continuous dimension reflect continuity. For example, week, month, and quarter
reflect the continuity in a time dimension. The members in a discrete dimension do not
imply continuity. For example, California, Texas, and Ohio in a market dimension do
not have a relationship based on continuity.
As another example, consider this scenario: The sales representative for a client changes in
midyear. Table 26 lists the customer sales totals and sales representative assignments over six
months:
Table 26
March
April
May
June
July
August
4000
6000
2000
1000
1000
7000
Jones
Jones
Jones
Smith
Smith
Smith
In this example, Sales Representative is the varying attribute. Data retrievals show that the sales
representative Jones sold the customer a total of $12,000 worth of products from March through
May and the sales representative Smith then sold a total of $9,000 worth of products to the
customer from June through August. Without the use of the varying attribute, the only known
sales representative would be the current representative Smith to whom all sales ($21,000) would
be credited.
Varying attributes offer alternate ways of grouping your members. For example, you can use
color to group SKUs. In this scenario, the attribute dimension Color is associated with SUBSKU:
Product_H
Family
SKU
SUBSKU
Color
SUBSKU
When Color is set as a varying attribute, the retrieval results would be similar to the values in
Table 27:
Table 27
SUBSKU
SKU
Red
100
White
400
White
600
183
SUBSKU
SKU
Black
200
Black
300
Silver
500
You can enable an outline to support varying attributes. You can define attribute dimensions to
function as varying attributes. You can also edit varying attributes to reflect the type of
information you need.
184
Add new varying attribute associations to independent members (for example, add a
new job title for an employee).
<PERSPECTIVE
<WITHATTREX
<ATTRIBUTEVA
The following calculation functions and command work with varying attributes.
l
@WITHATTR
@ISATTRIBUTE
@ISMBRWITHATTR
SET SCAPERSPECTIVE
The following MDX functions are designed to work with varying attributes.
l
AttributeEx
WithAttrEx
Cannot be deleted
Must be level 0
185
Independent members that are newly moved or added cannot be used to denote a range until
the outline is saved.
186
11
In This Chapter
Understanding LROs ..................................................................................... 187
Understanding LRO Types and Data Cells ............................................................. 188
Setting Up Permissions for LROs ....................................................................... 188
Viewing and Deleting LROs.............................................................................. 189
Exporting and Importing LROs .......................................................................... 190
Limiting LRO File Sizes for Storage Conservation ..................................................... 190
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Understanding LROs
You can link various kinds of data with any cell in an Essbase database, using a linked reporting
object (LRO). This ability is similar to attaching a file to e-mail. An LRO provides improved
support for planning and reporting applications and can enhance your data analysis capabilities.
LROs are objects (alternatively called artifacts) that you associate with specific data cells in an
Essbase database. Users create, retrieve, and edit linked objects through Smart View. You can
link an unlimited number of objects to a cell. The objects are stored on the Essbase Server, where
they are available to any user with the appropriate access permissions. For the maximum sizes
of the types of linked objects described in Table 28, see Appendix A, Limits.
Table 28
Object Type
Description
Cell note
A text annotation
File
An external file, such as a Microsoft Word document, an Excel spreadsheet, a scanned image, an audio clip, or an HTML
file (for example, mypage.htm).
URL
For example:
http://www.oracle.com
ftp://ftp.oracle.com
Linked partition
A set of data cells that you can link to in another Essbase database.
187
For example, a sales manager may attach cell notes to recently updated budget items. A finance
manager may link a spreadsheet containing supporting data for this quarters results. A product
manager may link bitmap images of new products. A sales manager may link the URL of a
companys Web site to quickly access the information on the Web site.
If the object is a cell note, the text is stored as part of the object description in the catalog
entry.
If the object is a file, Essbase stores the contents of the file in the database directory on the
Essbase Server, giving it an .lro extension. Essbase imposes no restrictions on the data
formats of linked files and performs no file-type checking. It is up to the users client
computer to render the file after retrieving it from the Essbase Server.
If the object is a URL, Essbase stores it as part of the object description in the catalog entry.
When the user tries to view the URL, Essbase does a preliminary syntax check; then the
default Web browser checks for the existence of the URL.
If the object is a linked partition, it is available through the Essbase Partitioning module.
Essbase uses the database index to locate and retrieve linked objects. If you clear all data
values from a database, the index is deleted, and so are the links to linked objects. If you
restructure a database, the index is preserved, as are the links to linked objects.
Shared members share data values but not LROs, because LROs are linked to specific
member combinations, and shared members do not have identical member combinations.
To link an object to shared members, link it to each shared member individually.
You cannot change the member combination associated with any linked object. To move
an object to another member combination, delete it, and then use Smart View to re-link the
object to the desired member combination.
188
Table 29
Task
Permission
Read-write
Read
Read-write
Read-write
Read
Read-write
To prevent users from linking files to data cells without changing user access to other data in a
database, you can set the maximum file size for linked files to 1. Users can then create cell notes,
link to a URL, or view linked partitions but can attach only files smaller than 1 KB.
Topic
Location
Administration Services
Managing LROs
MaxL
query database
ESSCMD
LISTLINKEDOBJECTS
Topic
Location
Administration Services
Managing LROs
MaxL
alter database
189
Tool
Topic
Location
ESSCMD
PURGELINKEDOBJECTS
Topic
Location
Administration Services
Exporting LROs
Importing LROs
export lro
MaxL
import lro
URLs. The lengths of the cell note, URL string, and LRO descriptions are fixed. For the
maximum sizes of these objects, see Appendix A, Limits.
Topic
Location
Administration Services
MaxL
alter application
ESSCMD
SETAPPSTATE
190
12
In This Chapter
About Typed Measures .................................................................................. 191
Working with Text Measures............................................................................. 192
Working with Date Measures............................................................................ 193
Performing Database Operations on Text and Date Measures....................................... 195
Working with Format Strings ............................................................................ 198
191
3. Create a text measure in the outline (in the Accounts dimension), and in the member
properties:
a. Define it as type Text.
b. Associate it with the text list object.
See Performing Database Operations on Text and Date Measures on page 195.
192
Table 30
Name
ID
Missing
#MISSING
N/A
#OUTOFRANGE
High
Medium
Low
Each text value must map to a unique numeric value. Any text value that does not map to an
integer in the text list object is considered by Essbase to be invalid.
The first two IDs, #MISSING and #OUTOFRANGE, are for handling cases where the textual
data is invalid or empty. For example, if a user attempted to load an unmapped value such as
Average to a text measure, the cell value would not be updated, and would display as
#MISSING in a subsequent query. If a user loads a numerical cell value which is unmapped, the
subsequent query would return N/A.
Aside from #MISSING and #OUTOFRANGE , all of the other IDs must be integers.
193
DateDiff
DatePart
DateRoll
FormatDate
GetFirstDate
GetLastDate
ToDate
ToDateEx
Today
The following calculation functions are useful for calculations based on date measures.
l
@DATEDIFF
@DATEPART
@DATEROLL
@FORMATDATE
@TODATEEX
@TODAY
194
This section explains how to perform common database operations when using text and date
measures.
grammar of the import data statement. In Administration Services Console, use the
overwrite existing values option in the Data Load dialog box. In the Essbase API, use
the ulCommitType field of EssLoadBufferTerm.
l
Use a single load buffer to load all values associated with date/text measures.
195
Caution!
Aggregate_use_last is set when creating the load buffer. In MaxL, see the PROPS terminal
that is part of the initialize load_buffer grammar in the alter database statement. In
Administration Services Console, select the aggregate use last check box in the Data Load
dialog box. In the Essbase API, use the ulDuplicateAggregationMethod field of
EssLoadBufferInit.
l
Avoid loading #MISSING values to text/date measures in incremental data load mode. When
a #MISSING value is loaded to a cell with a non-Missing value in incremental load, it is
replaced with a zero value. The zero value may not have the same meaning as the #MISSING
value for date/text measures. Use full data load if you need to load #MISSING values to date/
text measures.
If mixed (numeric and text or date) data are being loaded, either ensure that Replace mode is
sufficient for your numeric data, or create a separate data load process for the numeric data.
You can load text or date values with or without rules files. When a rules file is not used, you
must distinguish text or date values from member names by enclosing the text values in double
quotation marks and prefixing them with the string #Txt:.
Here is an example of a line of data in a free-form data load file:
"100-10" "New York" "Cust Index" #Txt:"Highly Satisfied"
The text value "Highly Satisfied" is pre-fixed with #Txt:to differentiate it from member names
such as "New York".
The "#Txt" prefix is also required for date measures when a rules file is not used for data load.
You can clear, lock and send, and export text or date values just as you perform those operations
on numeric values.
0. You can consolidate values to parent levels by taking an average of values at child levels. For
example, the value of CustomerSatisfaction at [Qtr1] is the average of values at [Jan], [Feb],
[Mar].
RESTRICT
TOP
BOTTOM
SORT* commands
CALCULATE COLUMN
CALCULATE ROW
The MDX function EnumValue and the calculation function @ENUMVALUE are designed
specifically for getting the text value of text measures. These functions can be useful in MDX
scripts, calc scripts, or formulas, when you need to do operations based on the text value of a
member rather than its internally stored numeric value. See the Oracle Essbase Technical Reference
197
198
where string_value_expression is a valid MDX string value expression as described in the MDX
specification documented in the Oracle Essbase Technical Reference.
Most MDX expressions can be used to specify format strings; however, format strings cannot
contain references to values of data cells other than the current cell value being formatted. The
current cell value can be referenced using the MDX CellValue function.
Essbase treats members with invalid format strings as if there is no format string defined. Outlines
can be saved with invalid format strings. Essbase generates a warning if a query consists of a
member with an invalid format string.
If a member is not associated with a format string, default format rules are applied. The default
format rules format a cell based on whether the measure is numeric, text, or date type. For
numeric measures, the default formatted value is the text version of that number. For text
measures, the default formatted value is the text value based on the associated text list object.
For date values, the default format is a date string formatted according the date format string
defined in the outline properties.
EnumText, returns the text list label associated with the internal numeric value.
EnumValue, returns the internal numeric value for a text list label.
The @ENUMVALUE calculation function can be useful when writing calculation scripts for a
block storage database that has text measures or format strings. This function returns the text
list label associated with the internal numeric value.
The MaxL alter session set dml_output statement has a clause set formatted_value on | off. By
default, formatted values are displayed in queries, but this statement can be used to turn off the
display of formatted values.
The OUTFORMATTEDVALUES Report Writer command returns formatted cell values in a
report.
For information about these functions, commands, and statements, see the Oracle Essbase
Technical Reference.
199
200
13
In This Chapter
Overview of Drill-through to Oracle Applications ...................................................... 201
Understanding Drill-through URLs ...................................................................... 202
Creating and Managing Drill-through URLs ............................................................ 203
201
drill-through definitions and host the Web pages that they wish to use as targets of drillthrough URLs.
See the following topics, which describe the components of drill-through URLs:
l
202
create drillthrough
alter drillthrough
display drillthrough
drop drillthrough
Use the following Essbase API structures and functions to manage the drill-through URLs on
the Essbase database:
l
EssCreateDrillThruURL
EssDeleteDrillThruURL
EssGetDrillThruURL
EssGetCellDrillThruReports
EssListDrillThruURLs
EssMDXIsCellGLDrillable
EssUpdateDrillThruURL
EsbCreateDrillThruURL
EsbUpdateDrillThruURL
EsbDeleteDrillThruURL
EsbListDrillThruURLs
203
EsbGetDrillThruURL
EsbGetCellDrillThruReports
To manage drill-through URLs in Administration Services, see these topics in the Oracle Essbase
Administration Services Online Help:
l
204
14
In This Chapter
About Currency Conversion ............................................................................. 205
About the Sample Currency Application ............................................................... 206
Structure of Currency Applications ..................................................................... 206
Conversion Methods ..................................................................................... 210
Building Currency Conversion Applications and Performing Conversions........................... 211
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
205
In addition, TBC adds a new member, U.S., a consolidation of data from the U.S. regions: East,
West, South, and Central.
Data for each TBC market location is captured in local currency. U.S. dollar values are derived
by applying exchange rates to local values.
TBC must analyze actual data in two ways:
l
Actuals are converted at budget exchange rates to analyze variances due to exchange rates.
After all actuals are processed, budget data is converted with budget exchange rates.
The TBC currency application consists of the main database (Interntl) and the currency database
(Xchgrate). On Essbase Server, the databases are in the Sample application. If you do not have
access to the databases, contact your Essbase administrator.
206
Figure 45
Main Database
To enable Essbase to generate the currency database outline automatically, you modify
dimensions and members in the main database outline. In the Sample currency application, the
main database is Interntl.
The main database outline can contain from 3 to n dimensions. At minimum, the main database
must contain the following dimensions:
l
207
dimension and its four regional members all use the same currency. The same is true of the
Canada member and its three city members. When the children of a given member share a
currency, you must define a currency name for only the parent member.
Table 31
Currency Name
Market - Country
U.S.
East
West
South
Central
Canada
Toronto
Vancouver
Montreal
Europe
UK
EUR (Euro)
Germany
Switzerland
Sweden
When preparing a main database outline for currency conversion, you can create an optional
currency partition to tell Essbase which slice of the database holds local currency data and which
holds data to be converted. The dimension that you tag as currency partition contains members
for both local currency values and converted values. Local currency data is converted to common
currency data using currency conversion calculation scripts. In the Sample.Interntl database,
the Scenario dimension is the currency partition dimension.
For instructions on how to use currency partition dimensions, see Keeping Local and Converted
Values on page 213.
Note: A currency conversion partition applies only to the Currency Conversion option. It is not
related to the Partitioning option that enables data to be shared between databases by
using a replicated, linked, or transparent partition.
Report scripts enable the creation of reports that convert data when the report is displayed, as
discussed under Converting Currencies in Report Scripts on page 215.
Note: For a list of methods used to create the main database outline, see Creating Main
Currency Database
By assigning currency tags to members in the main database outline, you enable Essbase to
generate the currency database automatically. In the Sample currency application, the currency
database is Xchgrate.
Note: In the currency database, all level 0 members must be stored, non-dynamic-calc members.
This means that the database the currency database is generated from must also have all
level 0 members as stored, non-dynamic-calc members.
A currency database always consists of the following three dimensions, with an optional fourth
dimension:
l
A dimension tagged as time, which is typically the same as the dimension tagged as time in
the main database. This allows the currency database to track currency fluctuations over
time and to accurately convert various time slices of the main database. In the
Sample.Xchgrate database, the dimension tagged as time is Year.
Each member of the time dimension in the main database must be defined in the currency
database. Values by time period in the main database usually are converted to the exchange
rates of their respective time period from the currency database (although you can convert
data values against the exchange rate of any period).
A dimension tagged as country, which contains the names of currencies relevant to the
markets (or countries) defined in the main database. Each currency name defined in the
main database must also exist in the currency database. The currency names define the
country-to-exchange rate mapping when conversion occurs.
In the Sample.Xchgrate database, the country dimension is CurName. Table 32 lists the
currency names in the CurName dimension:
Table 32
Alias Name
CurName - Country
U.S. dollar
USD
Canadian dollar
CND
British pound
GBP
Euro
EUR
Swiss franc
CHF
Swedish krona
SEK
l
A dimension tagged as accounts, which enables the application of various rates to members
of the dimension tagged as accounts in the main database. The categories defined for the
accounts dimension in the main database are used to form the members in the accounts
dimension of the currency database. For example, it may be necessary to convert Gross Profit
and Net Profit using one category of rates, while other accounts use a different set of rates.
209
In the Sample.Xchgrate database, the dimension tagged as accounts is CurCategory, and the
account categories included are P&L (Profit & Loss) and B/S (Balance Sheet).
l
A currency database, which typically includes an optional currency type dimension, which
enables different scenarios for currency conversion. Typically, an application has different
exchange rates for different scenarios, such as actual, budget, and forecast. To convert data
between scenarios, select which type of rate to use.
The currency type dimension is created when you generate the currency outline and is not
directly mapped to the main database. Therefore, member names in this dimension need
not match member names of the main database.
In the Sample.Xchgrate database, the currency type dimension is CurType. CurType
includes actual and budget scenarios.
Note: For information about creating the currency database outline, see Building Currency
Conversion Methods
Different currency applications have different conversion requirements. Essbase supports two
conversion methods:
l
Either of these methods may require a currency conversion at report time. Report time
conversion enables analysis of various exchange rate scenarios without actually storing data in
the database. The Currency Conversion module enables performance of ad hoc conversions.
You perform ad hoc conversions by using a report script, as discussed in Converting Currencies
in Report Scripts on page 215.
210
Topic
Location
Administration Services
MaxL
create database
ESSCMD
CREATEDB
211
simultaneously being updated by other user activities (for example, a calculation, data
load, or currency conversion against the same currency partition). Concurrent activity
on the data being converted may produce incorrect results. Essbase does not display a
warning message in this situation.
212
Note: When you convert currencies using the CCONV command, the resulting data blocks are
marked as dirty for the purposes of Intelligent Calculation. Thus, Essbase recalculates all
converted blocks when you recalculate the database.
To see sample currency conversion calculation scripts, see the Oracle Essbase Technical
Reference.
If required, you can specify a currency name that contains the required exchange rate. The
following calculation script converts the values in the database to USD, using the exchange rate
for Jan as defined in the currency database:
CCONV Jan->USD;
CALC ALL;
The CALC ALL command is required in the examples shown because the CCONV command
converts only currencies. It does not consolidate or calculate members in the database.
The following calculation script uses the Act xchg rate to convert the converted values back
to their original local currency values:
CCONV TOLOCALRATE "Act xchg";
CALC ALL;
Note: You cannot use the FIX command unless you are using a currency partition dimension
and the CCTRACK configuration setting is TRUE in the essbase.cfg file.
To create a calculation script that copies local data to a converted partition and calculates
the data:
Use the DATACOPY command to copy data from the local to the converted partition.
Use the FIX command to calculate only the converted partition and use the CCONV command to convert
the data.
213
Note: When using a currency partition dimension, you must FIX on a member of the
The following example is based on the Sample.Interntl database and the corresponding
Sample.Xchgrate currency database. Figure 46 shows the currency partition from the
Sample.Interntl database.
Figure 46
The following calculation script performs three currency conversions for Actual, Budget, and
Actual @ Bud Xchg data values:
/* Copy data from the local partition to the master partition (for converted values) */
DATACOPY Act TO Actual;
DATACOPY Bud TO Budget;
/* Convert the Actual data values using the "Act xchg" rate */
FIX(Actual)
CCONV "Act xchg"->US$;
ENDFIX
* Convert the Budget data values using the "Bud xchg" rate */
FIX(Budget)
CCONV "Bud xchg"->US$;
ENDFIX
/* Convert the "Actual @ Bud XChg" data values using the "Bud xchg" rate */
FIX("Actual @ Bud XChg")
CCONV "Bud xchg"->US$;
ENDFIX
/* Recalculate the database */
CALC ALL;
CALC TWOPASS;
The following calculation script converts the Actual and Budget values back to their original
local currency values:
FIX(Actual)
CCONV TOLOCALRATE "Act xchg";
ENDFIX
FIX(Budget)
214
Note: When you convert currencies using the CCONV command, the resulting data blocks are
marked as dirty for the purposes of Intelligent Calculation. Thus, Essbase recalculates all
converted blocks when you recalculate the database.
Calculating Databases
If you execute a CALC ALL command to consolidate the database after running a conversion,
meaningful total-level data is generated in the converted base rate partition, but the local rate
partition contains a meaningless consolidation of local currency values. To prevent meaningless
consolidation, use the calculation command SET UPTOLOCAL, which restricts consolidations
to parents with the same defined currency. For example, all cities in the U.S. use dollars as the
unit of currency. Therefore, all children of U.S. consolidate to U.S. Consolidation stops at the
country level, however, because North America contains countries that use other currencies.
If two transparent partition databases are calculated using different conversions, you
cannot perform currency conversions in reports.
The following Sample report contains first-quarter Budget Sales for colas, using the January
exchange rate for the Peseta currency.
Illinois Sales Budget
Jan
Feb
======== ========
100-10
3
3
100-20
2
2
100-30
#MISSING #MISSING
100
5
5
Mar
========
3
2
#MISSING
5
Mar
========
3
2
#MISSING
5
215
Use the following script to create the Sample currency conversion report:
<Page (Market, Measures, Scenario)
{SupCurHeading}
Illinois Sales Budget
<Column (Year)
<children Qtr1
<Currency "Jan->Peseta->Act xchg"
<Ichildren Colas
!
{CurHeading}
Illinois Sales Budget
<Column (Year)
<children Qtr1
!
By default, CCTRACK is turned on. Essbase tracks which currency partitions have been
converted and which have not. The tracking is done at the currency partition level: a database
with two partitions has two flags, each of which can be converted or unconverted. Essbase
does not store a flag for member combinations within a partition.
When using a currency partition, and when CCTRACK is set to TRUE (the default) in
essbase.cfg, you must FIX on a single currency partition member. You cannot FIX on
multiple members, because CCTRACK works at the currency partition member level and marks
as converted or unconverted all data associated with the currency partition member. For
example, in the Sample.Basic database, the following example is valid:
FIX(Actual)
CCONV "Act xchg"->US$;
ENDFIX
In the Sample.Basic database, if you were able to use a FIX command to convert the actual values
for only the members Jan and Feb, the database would have converted and unconverted data in
the same currency partition, causing a data consistency issue.
216
partition, use the DATACOPY command to copy the entire currency partition that contains the
updated data, and then run the conversion on the currency partition.
Note: Always do a partial data load to the local partition and use the DATACOPY command to
copy the entire currency partition to the converted partition before running the currency
conversion. Updating data directly into the converted partition causes incorrect results.
Use the SET CCTRACKCALC ON|OFF command in a calculation script to turn off
CCTRACK temporarily. You can use this command at calculation time to increase flexibility
and efficiency during currency conversion.
Use the CLEARCCTRACK calculation command to clear the internal exchange rate tables
created by CCTRACK. You can use the command inside a FIX statement to clear the
exchange rates for a currency partition. Use the command after a data load to reset the
exchange rate tables so that they are ready for future currency conversion calculations.
Set CCTRACK to FALSE in the essbase.cfg file. Setting CCTRACK to FALSE turns off
the tracking system and has the following results:
m
The CCONV command assumes that data is unconverted (is in local currency). If you
accidentally run the CCONV command multiple times on the same data, the resulting
data is inaccurate.
Similarly, the currency report options assume that the data is unconverted (is in local
currency). If the data already has been converted in the database, it is reconverted at
report time, resulting in inaccurate data.
The restrictions on using the FIX and DATACOPY commands in currency conversions
do not apply.
Note: When running a currency conversion, ensure that the data being converted is not
simultaneously being updated by other user activities (for example, a calculation, data
load, or currency conversion against the same currency partition). Concurrent activity
on the data being converted may produce incorrect results. Essbase does not display a
warning message in this situation.
217
218
15
Designing Partitioned
Applications
In This Chapter
Understanding Essbase Partitioning ................................................................... 219
Partition Design Requirements ......................................................................... 224
Replicated Partitions..................................................................................... 228
Transparent Partitions ................................................................................... 232
Linked Partitions ......................................................................................... 238
Case Studies for Designing Partitioned Databases ................................................... 240
Partition Types
Table 33 lists the types of partitions that are supported in Essbase:
Table 33
Partition Types
Partition Type
Description
Applies To
Replicated
A copy of a portion of the data source that is stored in the data target.
Aggregate storage
databases
Allows users to access data from the data source as though it were stored in the data target.
The data is, however, stored at the data source, which can be in another application or
Essbase database, or on another Essbase Server.
Transparent
Aggregate storage
databases
Sends users from a cell in one database to a cell in another database. Linked partitions
give users a different perspective on the data.
See Linked Partitions on page 238.
Use the information in Table 34 to help you choose which type of partition to use:
219
Table 34
Feature
Replicated
Up-to-the-minute data
Reduced network traffic
Linked
Transparent
x
x
Smaller databases
Improved query speed
x
x
x
x
x
x
Partitions contain the following parts, as illustrated in Figure 47 and described in Table 35 on
page 221.
220
Parts of a Partition
x
x
Parts of a Partition
Figure 47
Table 35
Parts of a Partition
Part
Description
Type of partition
Data source
information
Data target
information
The login and password information for the data source and the data target. This information is used for internal
requests between the two databases to execute administrative and end-user operations.
Shared areas
A definition of one or more areas, or regions, shared between the data source and the data target. To share
multiple noncontiguous portions of a database, define multiple areas in a single partition. This information
determines which parts of the data source and data target are shared so that Essbase can put the proper data
into the data target and keep the outlines for the shared areas synchronized.
Member mapping
information
A description of how the members in the data source map to members in the data target. Essbase uses this
information to determine how to put data into the data target if the data target and the data source use different
names for some members and dimensions.
Information about whether the partition is up-to-date and when the partition was last updated.
An Essbase database can contain many partitions, as well as data that is not shared with any
other Essbase database. You can define partitions between the following databases:
l
Different databases in different applications, as long as each database uses the same language
and the same Unicode-related mode.
The applications can be on the same computer or different computers.
You can define only one partition of each type between the same two databases. For example,
you can create only one replicated partition between the Sampeast.East and Samppart.Company
databases. The East or Company databases can, however, contain many replicated partitions
that connect to other databases.
One database can serve as the data source or data target for multiple partitions. To share data
among many databases, create multiple partitions, each with the same data source and a different
data target, as shown in Figure 49:
Figure 49
Table 36 lists the combinations of block storage and aggregate storage databases as data target
and data source that are supported by each partition type:
Table 36
Source
Target
Replicated
Transparent
Linked
Block storage
Block storage
Yes
Yes
Yes
Aggregate storage
Block storage
No
Yes
Yes
Aggregate storage
Aggregate storage
No
Yes
Yes
Block storage
Aggregate storage
Yes
Yes
Yes
Overlapping Partitions
An overlapping partition occurs when similar data from multiple databases is the data source
for one data target in a partition.
For example, IDESC East, Sales from database 1 and Boston, Sales from database 2 are mapped
to IDESC East, Sales and Boston, Sales in database 3. Because Boston is a member of the East
dimension, the data for Boston mapped to database 3 from database 1 and database 2 overlap.
This data overlap results in an overlapping partition, as shown in Figure 50:
222
Figure 50
Overlapping Partitions
in the partition definition until after the application is restarted. For example, if the value
of &Curmonth is Jan and you change the value to Feb, the value in the partition definition
stays at Jan until you restart the application.
Attributes in Partitions
For block storage databases, you can use attribute functions for partitioning on attribute values,
but you cannot partition an attribute dimension. Use attribute values to partition a database to
access members of a dimension according to their characteristics.
For example, in the Sample.Basic database, you cannot partition the Pkg Type attribute
dimension, but you can create a partition that contains all the members of the Product dimension
223
that are associated with either or both members (Bottle and Can) of the Pkg Type dimension.
If you create a partition that contains members associated with Can, you can access data only
on Product members that are packaged in cans; namely, 100-10, 100-20, and 300-30.
Note: Retrieving data on attribute members of block storage databases may result in missing
data. See the entry for Dense Dynamic Calc members in nonexisting stored blocks in
Table 18, Differences Between Attribute and Standard Dimensions, on page 167.
You can use the @ATTRIBUTE command and the @WITHATTR command to define partitions.
For example, to extract data on all members of the Product dimension that are associated with
the Caffeinated attribute dimension, you can create a partition such as @ATTRIBUTE
(Caffeinated). But you cannot partition the Caffeinated attribute dimension.
Based on the previous example, this partition is correct:
Source
@ATTRIBUTE(Caffeinated)
Target
@ATTRIBUTE(Caffeinated)
Target
Caffeinated
For more information about these commands, see the Oracle Essbase Technical Reference.
Also see Chapter 10, Working with Attributes.
Replicated
Transparent
Linked
Encoding: The application modeUnicode mode or non-Unicode modeof both ends of the
partition must be the same for these partition types:
l
Replicated
Transparent
224
Benefits of Partitioning
Partitioning can provide the following benefits:
l
Partitioning Strategies
Based on user requirements, select a partitioning strategy:
l
Partition databases according to attribute values associated with base dimensions (a standard
dimension associated with one or more attribute dimensions).
Use this strategy to extract data based on the characteristics of a dimension, such as flavor
or size.
Note: You cannot partition attribute dimensions. See Attributes in Partitions on page
223.
The data should be closer to the people who are using it.
225
It takes too long to perform calculations after new data is loaded, and you want to
improve performance by spreading calculations across multiple processors or
computers.
Users want to see the data in different application contexts, and you want to control
how users navigate between databases.
You need to synchronize information from different sources.
You plan to add new organizational units that would benefit from having their own
databases.
You want to save disk space by giving users access to data stored in a remote location.
You have disk space, network bandwidth, and administrative resource concerns.
You perform complex allocations where unit level values are derived from total values.
Which database should be the data source and which the data target? The database that
owns the data, where the data is updated and where most of the detail data is stored, should
be the data source.
Are some parts of the database accessed more frequently than others?
What are the available resources: disk space, CPUs, and network resources?
226
How much data must be transferred over the network? How long does it take?
Is there information in separate databases that should be accessed from a central location?
How closely are groups of data related?
When creating replicated partitions using the create replicated partition MaxL
statement, if you do not specify the update allow grammar, replicated partitions cannot
be updated by default. See the Oracle Essbase Technical Reference.
When creating replicated partitions using Administration Services Console, by default,
replicated partitions can be updated. See the Oracle Essbase Administration Services
Online Help.
4. If you are creating a linked partition, create accounts for users at the data source. Users
accessing linked databases may need to connect to multiple databases.
See Drill Across and Linked Partitions on page 240.
227
You can create filters on the administrative account and on the end users. Filters on the
administrative account can ensure that no one at the data target can view or update inappropriate
data. For example, the administrator at the corporate database can restrict write access on certain
cells to avoid relying on administrators in the regions to set up security correctly for each end
user.
Create the required administrative users with the correct filters.
1. Create an administrative account at the data source and data target.
See Setting the User Name and Password on page 247.
Essbase uses this account to log onto the data source to retrieve data and to perform outline
synchronization operations.
2. Create read and write filters to determine which data administrators can view and update.
See Chapter 39, User Management and Security in EPM System Security Mode.
l
For replicated partitions, set up read filters at the data source to determine which data
Essbase reads when replicating, and set up write filters at the data target to determine
which data Essbase writes to when replicating.
For transparent partitions, set up read filters at the data source to determine which data
Essbase retrieves for end users, and set up write filters at the data source to determine
which data Essbase updates for end users.
Replicated Partitions
A replicated partition is a copy of a portion of the data source that is stored in the data target.
Some users can then access the data in the data source while others access it in the data target.
For example, in the Samppart and Sampeast sample applications, the DBA at The Beverage
Company (TBC) created a replicated partition between the East database and the Company
database containing Actual, Budget, Variance, and Variance%. Users in the eastern region now
store their budget data locally. Because they do not have to retrieve this data live from corporate
headquarters, response times are faster, and they have more control over the downtimes and
administration of local data. See Case Study 1: Partitioning an Existing Database on page
241.
Changes to the data in a replicated partition flow from the data source to the data target. Changes
made to replicated data in the data target do not flow back to the data source. If users change
the data at the data target, Essbase overwrites their changes when the DBA updates the replicated
partition.
228
When a replicated partition is defined, the DBA can select a setting to prevent the data in the
replicated portion of the data target from being updated. The update setting (which allows or
disallows updates) takes precedence over access provided by security filters and is also honored
by batch operations, such as data load and calculation. The default behavior of the update setting
depends on whether you create the replicated partition using MaxL or Administration Services
Console. See Setting up End-User Security on page 227.
Use a replicated partition to achieve any of the following goals:
l
You must be able to map the shared replicated areas of the data source and data target
outlines, although the shared areas need not be identical. You must tell Essbase how each
dimension and member in the data source maps to each dimension and member in the data
target.
The data source and data target outlines for the non-shared areas do not have to be mappable.
Because none of the areas that you use as a replicated partition target can come from a
transparent partition source, you cannot create a replicated partition on top of a transparent
partition, as shown in Figure 51:
Figure 51
The cells in the data target of a replicated partition cannot come from two data sources; the
cells in one partition must come from one database. To replicate cells from multiple
databases, create a different partition for each data source.
The cells in a data target can be the data source for a different replicated partition. For
example, if the Samppart.Company database contains a replicated partition from the
Sampeast.East database, you can replicate the cells in Sampeast.East into a third database,
such as Sampwest.West.
You cannot use attribute members to define a replicated partition. For example, associated
with the Market dimension, the Market Type attribute dimension members are Urban,
Suburban, and Rural. You cannot define a partition on Urban, Suburban, or Rural, because
229
a replicated partition contains dynamic data, not stored data. Therefore, an attempt to map
attributes in replicated partitions results in an error message. However, you can use the
WITHATTR command to replicate attribute data.
Because data is stored closer to end users, in the data target, replicated partitions can decrease
network activity, resulting in improved retrieval times for users.
The data is more easily accessible to all users. Some users access the data at the data source,
others at the data target.
Failures are not as catastrophic. Because the data is in multiple places, if one database fails,
only the users connected to that database are unable to access the information. Data is still
available at and can be retrieved from the other sites.
Local DBAs can control the downtime of their local databases. For example, because users
in the eastern region are accessing their own replicated data instead of the Company
database, DBAs can bring down the Company database without affecting users in the eastern
region.
Because only the relevant data is kept at each site, databases can be smaller. For example,
users in the eastern region can replicate only the eastern budget information, instead of
accessing a larger company database containing budget information for all regions.
You need more disk space because data is stored in multiple locations.
Because the DBA must manually refresh data regularly, users may not see the latest version
of the data.
Do not replicate members that are dynamically calculated in the data source, because Essbase
must probe the outline to find dynamically calculated members and their children to
determine how to perform the calculation.
Do not replicate derived data from the data source. Instead, replicate the lowest practical
level of each dimension and perform the calculations on the data target after you complete
the replication.
For example, to replicate the database along the Market dimension:
m
230
Define the shared area as the lowest-level members of the Market dimension that you
care about, for example, East, West, South, and Central and the level 0 members of the
other dimensions.
After you complete the replication, calculate the values for Market and the upper-level
values in the other dimensions at the data target.
Sometimes you cannot calculate derived data at the data target. In that case, replicate it
from the data source. For example, you cannot calculate derived data at the data source
if the data meets any of the following criteria:
o
To optimize the replication of an aggregate storage database when the aggregate storage
database is the target and a block storage database is the source and the two outlines are
identical, use one of these methods:
m
When updating the essbase.cfg file, you must stop and then restart Essbase Server
for the changes to take effect.
m
When using the alter database statement, you do not need to stop and restart the
aggregate storage application.
Both optimization methods affect only the target aggregate storage application; the source
block storage application is not affected. The methods do not apply to block storage
replication.
l
Partitioning along a dense dimension takes longer than partitioning along a sparse
dimension. When Essbase replicates data partitioned along a dense dimension, it must access
every block in the data source and then create each block in the data target during the
replication operation.
You cannot replicate data into a member that is dynamically calculated at the data target.
Essbase does not load or replicate into Dynamic Calc and Dynamic Calc and Store members,
because these members do not contain data until a user requests it at runtime. Essbase avoids
sending replicated data for both dynamic dense and dynamic sparse members on the
replication target, because this data is not stored on the data target.
To replicate only the data values that have changed instead of the entire partition, see
Populating or Updating Replicated Partitions on page 258.
231
a problem.
Transparent Partitions
A transparent partition allows users to manipulate data that is stored remotely as if it were part
of the local database. The remote data is retrieved from the data source each time that users at
the data target request it. Users do not need to know where the data is stored, because they see
it as part of their local database.
Figure 52
Transparent Partitions
Because data is retrieved directly from the data source, users see the latest version. When they
update the data, their updates are written back to the data source. This process means that other
users at the data source and the data target have immediate access to those updates.
With a transparent partition, users at the data source and at the data target may notice slower
performance as more users access the source data.
For example, the DBA at TBC can use a transparent partition to calculate each member of the
Scenario dimension on a separate computer. This process reduces the elapsed time for the
calculation while providing users with the same view of the data. See Case Study 1: Partitioning
an Existing Database on page 241.
Use a transparent partition to achieve the following goals:
l
232
The shared transparent areas of the data source and data target outlines need not be identical,
but you must be able to map the dimensions in them. You must tell Essbase how each
dimension and member in the data source maps to each dimension and member in the data
target.
The data source and data target outlines for the nonshared areas need not be mappable, but
attribute associations must be identical. Otherwise, users can get incorrect results for some
retrievals. For example, if product 100-10-1010 is associated with the Grape Flavor attribute
on the source, but product 100-10-1010 is not associated with Grape on the target, the total
of sales for all Grape flavors in New York is incorrect.
The partition definition must contain only stored members. You cannot use attribute
dimensions or members to define a transparent partition. For example, the Market Type
attribute dimension, which is associated with the Market dimension, has members Urban,
Suburban, and Rural. You cannot define a partition on Urban, Suburban, or Rural.
If a cell is mapped from the data source to an aggregate storage database as the target, all the
cell's dependents must also be mapped to the same partition definition.
You can create a transparent partition on top of a replicated partition. In other words, you
can create a transparent partition target using a replicated partition source, as shown in
Figure 53
Figure 53
As illustrated in Figure 54, you cannot create a transparent partition on top of multiple other
partitions. In other words, you cannot create a transparent partition target from multiple
sources because each cell in a database must be retrieved from only one locationeither the
local disk or a remote disk.
233
Figure 54
Carefully consider any formulas you assign to members in the data source and data target.
You need less disk space, because you are storing the data in one database.
The data accessed from the data target is always the latest version.
When the user updates the data at the data source, Essbase makes those changes at the data
target.
The distribution of the data is invisible to the end user and the end users tools.
You can load the data from either the data source or data target.
You can enable write-back functionality for aggregate storage databases by creating a
transparent partition between an aggregate storage database as the source and a block storage
database as the target.
See Using a Transparent Partition for Write-Back to Aggregate Storage Databases on page
931.
234
Transparent partitions increase network activity, because Essbase transfers the data at the
data source across the network to the data target. Increased network activity results in slower
retrieval times for users.
Because more users are accessing the data source, retrieval time may be slower.
If the data source fails, users at both the data source and the data target are affected.
Therefore, the network and data source must be available whenever users at the data source
or data target need them.
You can perform some administrative operations only on local data. For example, if you
archive the data target, Essbase archives only the data target and not the data source. The
following administrative operations work only on local data in block storage databases:
m
EXPORT command
VALIDATE command
When you perform a calculation on a transparent partition, Essbase performs the calculation
using the current values of the local data and transparent dependents. Essbase does not
recalculate the values of transparent dependents, because the outlines for the data source
and the data target may be so different that such a calculation is inaccurate. To calculate all
partitions, issue a CALC ALL command for each individual partition, and then perform a
CALC ALL command at the top level using the new values for each partition.
Consider this example:
m
The data target outline contains a Market dimension with East, West, South, and Central
members
The data source outline contains an East dimension with New York and New Jersey
members
If you tried to calculate the data target outline, you would assume that East was a level 0
member. In the data source, however, East is derived by adding New York and New Jersey.
Any calculations at the data target, however, would not know this information and could
not reflect changes made to New York and New Jersey in the data source. To perform an
accurate calculation, therefore, calculate East in the data source and then calculate the data
target.
l
Formulas assigned to members in the data source may produce calculated results that are
inconsistent with formulas or consolidations defined in the data target, and vice versa.
235
To improve performance, consider including one or more sparse dimensions in the area
definition so that the number of blocks required is limited to combinations with the sparse
members.
l
Basing transparent partitions on the attribute values of a dimension can increase retrieval
time, because attributes are associated with sparse dimensions. In such cases, partitioning
at a level higher than the level that is associated with attributes improves retrieval time. For
example, in the Product dimension of the Sample.Basic database, if children 100-10, 200-10,
and 300-10 (level 0) are associated with attributes, then partition their parents 100, 200, and
300 (level 1) for better retrieval performance.
Loading data into the data source from the data target can greatly slow performance. If
possible, load data into the data source locally.
Retrieval time is slower because users access the data over the network.
When a transparent partition is the target, consider using these configuration settings:
m
For requests sent from a data source to a transparent partition target (whether a block
storage or aggregate storage database), you can log transaction response times using the
ENABLE_DIAG_TRANSPARENT_PARTITION configuration setting in the
essbase.cfg file. Logging these messages is helpful when troubleshooting response
times that are too slow.
When the transparent partition target is an aggregate storage database, you can specify
the maximum size of the request grid and the response grid, using the
MAX_REQUEST_GRID_SIZE and MAX_RESPONSE_GRID_SIZE configuration
settings.
236
If you are absolutely sure that a target partition calculation script does not involve access to
remote data, you can use the SET REMOTECALC OFF calculation command in the
calculation script to stop retrieval efforts from the source partition. See the Oracle Essbase
Technical Reference.
Dynamic Calc or Dynamic Calc and Store members as parents of the transparent data so
that the data is calculated on the fly when it is retrieved. This process reduces the batch
processing time. Essbase performs the calculation only when users request it.
A replicated layer between the low-level transparent data and high-level local data.
Keep the partition fully within the calculator cache area (see Sizing the Calculator Cache
on page 828), which means that any sparse members in the partition definition must be
contained within the calculator cache. For example, in the Sample.Basic database, if a
partition definition includes @IDESC(East), all descendants of East must be within the
calculator cache.
Enable the calculator cache, and assign a sufficient amount of memory to it.
Do not use complex formulas on any members that define the partition. For example, in
Sample.Basic, assigning a complex formula to New York or New Jersey (both children of
East) forces Essbase to use the top-down calculation method. See Bottom-Up and TopDown Calculation on page 872.
237
formulas are calculated, affecting the calculated value of Market on the data target. These results
may be different from how the Market member are calculated from the North and South
members on the data target, where these formulas may not exist.
Ensure that any formulas you assign to members in the data source and data target produce the
results you want.
Linked Partitions
A linked partition connects two databases with a data cell. When you click the linked cell in the
data target, you drill across to a second databasethe data sourceand view the data there. For
example, if you are using Smart View, a new spreadsheet that displays the dimensions from the
linked database opens when you launch a linked partition. From there, you can drill down into
the dimensions of the linked database.
Unlike replicated or transparent partitions, linked partitions do not restrict you to viewing data
in the same dimensionality as the target database. The database that you link to can contain
different dimensions than the database from which you connected. With linked partitions, data
is not physically transferred from the source to the target. Instead, a data cell or range of cells
on the target provides a link point to a cell or range of cells on the source.
Figure 55
Linked Partition
To prevent users from seeing privileged data, establish security filters on the data source and the
data target. See Security for Partitioned Databases on page 227.
238
There are no performance considerations for linked partitions, beyond optimizing the
performance of each linked database.
For example, if TBC grew into a large company, it might have several business units. Some data,
such as profit and sales, exists in each business unit. TBC can store profit and sales in a centralized
database so that the profit and sales for the entire company are available at a glance. The DBA
can link business unit databases to the corporate database. See Case Study 3: Linking Two
Databases on page 244.
A user in such a scenario can perform these tasks:
l
View the general profit and sales at the corporate level in a spreadsheet at the data target.
Drill across to individual business units, such as East (this action opens a new spreadsheet).
Figure 56
For linked partitions, the spreadsheet that the user first views is connected to the data target,
and the spreadsheet that opens when the user drills across is connected to the data source. This
setup is the opposite of replicated and transparent databases, in which users move from the data
target to the data source.
Use a linked partition to connect databases with different dimensionality.
You can view data in a different context; that is, you can navigate between databases
containing many dimensions.
You need not keep the data source and data target outlines closely synchronized, because
less of the outline is shared.
A single data cell can allow the user to navigate to multiple databases. For example, the Total
Profit cell in the Accounting database can link to the Profit cells in the databases of each
business unit.
Performance may improve, because Essbase accesses the database directly, not through a
data target.
239
Create accounts for each user on each database. For example, if Mary accesses data in a
Company database and an East database, create an account with the same login and password
for Mary on the Company and East databases.
Create a default account that users can use when accessing target databases. For example, if
users access data through a data source named Company and a data target named East, create
a guest account for the East database with the appropriate permissions. Use the guest account
login and password as the default login when creating the linked partition.
When a user drills across on data to a data target, Essbase logs the user into the data target using
the following steps:
1. Checks whether the user has an account on the data target with the same name and password.
If so, Essbase logs in the user using that account.
2. Checks whether you specified a default account on the data target when you created the
partition. If you did, Essbase logs the user in using that account.
3. Opens a login window prompting the user to enter a new login and password. After the user
enters a valid login and password, Essbase logs the user in using that account.
240
Partition the database along the East member of the Market dimension to give the
eastern region more control over the contents of its database.
Partition the database along the Actual and Corp_Budget members of the Scenario
dimension.
241
For Eastern Region and Actual, East is the source and Company is the target, because
the eastern region needs to update its market and actual information.
For Corp_Budget, use Company as source and East as Target, because the company
owns the corporate budgetit is the source.
For East, use transparent because the data target (Company) needs up-to-the-minute
data.
For Corp_Budget, use transparent because the data target (East) needs up-to-theminute data.
For East Actual, use replication because the data target (Company) does not need upto-the-minute data.
After the corporate database is partitioned, users and DBAs see the following benefits:
l
Faster response times, because they are competing with fewer users for the data and they are
accessing the data locally
Easier maintenance, because DBAs can control the downtime of their local databases
Access to more data, because users can connect to both the eastern and corporate budgets
Higher-quality data, because the corporate budget and eastern budget are now synchronized
they use the same data.
No one has control over his own data, because it is centrally managed.
242
Connect the Payroll, Marketing, and Sales databases. Perform steps step 1 through step 3 for each
database.
Edit existing data sources, rules files, calculation scripts, report scripts, and outlines
Now that the Sample.Basic database is partitioned, users and DBAs see the following benefits:
l
Easier maintenance, because DBAs can control the downtime of local databases.
Higher-quality data, because the databases are now synchronized (they use the same data).
243
The DBA for Sample.Basic notices that more users are requesting that she add channel
information to Sample.Basic. But, because she does not own the data for channel information,
she is reluctant to do so. Instead, she decides to allow her users to link to the TBC.Demo database,
which already contains this information.
Note: This example is not shipped with Essbase.
The DBA decides to link the Product dimension of Sample.Basic to the Product dimension
of TBC.Demo.
Users can then drill across to TBC.Demo and view the Channel and Package information.
Because users start at the Sample.Basic database, it is considered the data target. Because
users move to TBC.Demo, it is considered the data source.
Note: This setup is the opposite of replicated and transparent databases, in which users
Establish a link from the Product member of Sample.Basic to the Product dimension of
TBC.Demo. Remember to map the extra dimensions from TBC.DemoChannel and
Productto void in Sample.Basic.
See Mapping Data Cubes with Extra Dimensions on page 248.
Set up a guest account on TBC.Demo that gives the users who connect from
Sample.Basic permissions to access the Channel and Package dimensions.
To assign accounts to linked partitions, see Choosing a Partition Type on page 245.
After the databases are linked, users and DBAs see the following benefits:
l
244
16
In This Chapter
Process for Creating Partitions.......................................................................... 245
Choosing a Partition Type ............................................................................... 245
Setting up the Data Source and the Data Target ..................................................... 246
Setting the User Name and Password ................................................................. 247
Defining a Partition Area ................................................................................ 247
Mapping Members ....................................................................................... 247
Validating Partitions ..................................................................................... 253
Saving Partitions ......................................................................................... 254
Process for Maintaining Partitions...................................................................... 254
Populating or Updating Replicated Partitions ......................................................... 258
Editing and Deleting Partitions.......................................................................... 260
Viewing Partition Information ........................................................................... 260
Partitioning and SSL ..................................................................................... 260
Troubleshooting Partitions............................................................................... 261
Replicated
Transparent
Linked
245
Specify the names of the application and database for the data source and data target.
See Specifying Connection Information for Partitions in the Oracle Essbase Administration
Services Online Help.
Specify the locations of the Essbase Servers on which the data source and data target reside.
See Specifying Connection Information for Partitions in the Oracle Essbase Administration
Services Online Help.
If you want to use network aliases for the data source or data target names, ensure that the
aliases are propagated to all computers on your system. Otherwise, use the full server name.
To propagate an alias to all the computers on your system, edit the hosts file (you need
root or administrative privileges) for the operating system you are using:
l
Windows: %WINDIR%/system32/drivers/etc/hosts
UNIX: /etc/hosts
Note: Do not use localhost as an alias to specify source and target server names.
See Specifying Connection Information for Partitions in the Oracle Essbase Administration
Services Online Help.
By default, all changes made on the data source outline overwrite the data target outline
when you synchronize the outlines. You can, however, specify that changes made to the data
target outline overwrite the data source outline when you synchronize the outlines.
246
Transfer data between the data source and the data target for replicated and transparent
partitions. Local security filters apply to prevent end users from seeing privileged data.
Synchronize database outlines for all partition types.
To set the user name and password for the data source and the data target:
See Specifying Connection Information for Partitions in the Oracle Essbase Administration
Services Online Help.
Mapping Members
To create a partition, Essbase must be able to map all shared data source members to data target
members. Oracle recommends that data source member names and data target member names
247
are the same to reduce maintenance requirements for the partition, especially when the partition
is based on member attributes.
If the data source and data target contain the same number of members and use the same member
names, Essbase automatically maps the members. You need only validate, save, and test the
partitions. If Essbase cannot map automatically, you must map manually.
Map data source members to data target members in any of the following ways:
l
Enter or select member names manually. (When you type a duplicate member name, type
the qualified member name and enclose it in double quotation marks; for example,
[State].[New York]
Note: You can use substitution variables for member names in mapping specifications. See
Target
Product
Cola
Year
1998
Market
East_Region
Because you know that East in the data source corresponds to East_Region in the data target,
map East to East_Region. Then, all references to East_Region in the data target point to East in
the data source. For example, if the data value for Cola, 1998, East is 15 in the data source, the
data value for Cola, 1998, East_Region is 15 in the data target.
248
Target
Product
Cola
Market
East
Year
1999
1998
1997
Cola
Market
East
You can map member 1997 of the Year dimension to Void in the data target. First, define the
areas of the data source to share with the data target:
Source
@DESCENDANTS(Market), 1997
Target
@DESCENDANTS(Market)
Then, map the data source member to Void in the data target:
Source
1997
Target
Void
for the mapped member. In the above example, the Year dimension contains three
members: 1999, 1998, and 1997. If you map member 1997 from the data source to the
data target, the partition results reflect Product and Market data only for 1997. Product
and Market data for 1998 and 1999 will not be extracted.
The following example illustrates a case where the data target includes more dimensions than
the data source:
Source
Product
Cola
Year
1997
Target
Product
Cola
Market
East
Year
1997
In such cases, first define the shared areas of the data source and the data target:
Source
@IDESCENDANTS(Product)
Target
@IDESCENDANTS(Product), East
You can then map member East from the Market dimension of the data target to Void in the
data source:
Source
Void
Target
East
If member East from the Market dimension in the data target is not included in the target areas
definition, you will receive an error message when you attempt to validate the partition.
249
Data source members column (left)lists the member names in the data source. Member
names containing spaces must be in quotation marks.
Data target members column (center)lists the member names in the data target. Member
names containing spaces must be in quotes.
Non-member column (left)missing members. Use it to map an extra member in the data
source to Void in the data target or to map an extra member in the data target to Void in
the data source.
Separators (between the columns)tabs or spaces to separate columns.
Extra column (right)the file can contain extra columns that do not contain member
names.
250
Note: You cannot map members of attributes dimension in replicated partitions (see Rules for
Replicated Partitions on page 229). You can, however, map attributes in transparent and
linked partitions (see Attributes in Partitions on page 223).
In the following example, the outline for the data source contains a Product dimension with a
member 100 (Cola). Children 100-10 and 100-20 are associated with member TRUE of the
Caffeinated attribute dimension, and child 100-30 is associated with member FALSE of the
Caffeinated attribute dimension.
The data target outline has a Product dimension with a member 200 (Cola). Children 200-10
and 200-20 are associated with member Yes of the With_Caffeine attribute dimension, and child
200-30 is associated with No of the With_Caffeine attribute dimension.
First define the areas to be shared from the data source to the data target:
Source
@DESCENDANTS(100)
@DESCENDANTS(East)
Target
@DESCENDANTS(200)
@DESCENDANTS(East)
Target
20010
20020
20030
With Caffeine
With_Caffeine_True
With_Caffeine_False
Target
Create the Caffeinated attribute dimension and its members in the outline of the data target
and associate them with the Product dimension. You can then map the attributes from the
data source to the data target.
Map the Caffeinated attribute dimension in the data source to Void in the data target.
For a comprehensive discussion of attributes, see Chapter 10, Working with Attributes. For a
general discussion of attributes in partitions, see Attributes in Partitions on page 223.
251
Map multiple members in the data source to a single member in the data target.
Because Essbase cannot determine how to map multiple members in the data source to a single
member in the data target, you must logically determine how to divide your data until you can
apply one mapping rule to that subset of the data. Then use that rule in the context of areaspecific mapping to map the members.
Target
Product
Cola
Market
East
Year
1998
1999
Scenario
Actual
Budget
The data source does not have a Scenario dimension. Instead, it assumes that past data is actual
data and future data is forecast, or budget, data.
You know that 1998 in the data source should correspond to 1998, Actual in the data target and
1999 in the data source should correspond to 1999, Budget in the data target. So, for example,
if the data value for Cola, East, 1998 in the data source is 15, the data value for Cola, East, 1998,
Actual in the data target should be 15.
Because mapping works on members, not member combinations, you cannot simply map 1998
to 1998, Actual. Define the area (1998 and 1998, Actual) and then create area-specific mapping
rules for that area.
Because the data source does not have Actual and Budget members, you also must map these
members to Void in the data target.
252
Target
Customer_Planning
NY_Actual
NY_Budget
CA_Actual
CA_Budget
Scenario
Actual
Budget
You know that NY and Actual in the data source should correspond to NY_Actual in the data
target and NY and Budget in the data source should correspond to NY_Budget in the data target.
So, for example, if the data value for NY, Budget in the data source is 28, the data value for
NY_Budget in the data target should be 28.
Because mapping works on members, not member combinations, you cannot simply map NY,
Actual to NY_Actual. Define the area (NY and Actual, and NY_Actual) and then create areaspecific mapping rules for that area.
Because the data target does not have NY and CA members, you must also map these members
to Void in the data target so that the dimensionality is complete when going from the data source
to the data target.
Validating Partitions
When you create a partition, validate it to ensure its accuracy before you use it. Database Manager
permissions or higher are required. After you validate, save the partition definition. If necessary,
you can edit an existing partition.
When Essbase validates a partition definition, it checks on the Essbase Server for the data source
and the data target to ensure that:
l
The specified data source members are valid and map to valid members in the data target.
All connection information is correct; that is, the server names, database names, application
names, user names, and password information.
For linked partitions, the default user name and password that you provide are correct.
For replicated and transparent partitions, a replication target does not overlap with a
replication target; a replication target does not overlap with a transparent target; and a
transparent target does not overlap with a transparent target.
For replicated and transparent partitions, the cell count for the partition is the same on the
data source and the data target.
253
For replicated and transparent partitions, the area dimensionality matches the data source
and the data target.
You must validate a transparent partition that is based on attribute values to ensure that the
results are complete. Essbase does not display an error message when results are incomplete.
After you validate, save the partition; the partition definition is saved to two .ddb files, on the
data source server and the data target server.
Topic
Location
Administration Services
Validating Partitions
ESSCMD
VALIDATEPARTITIONDEFFILE
MaxL
create partition
Saving Partitions
After you validate the partition definition, you can save the partition definition to any of the
following locations:
l
To both the data source server and the data target server. The partition definition is stored
in two .ddb files.
To a client machine. The partition definition is stored in a .ddb file.
Note: Although you can save a partition with mapping errors, operations using that partition
Testing Partitions
Synchronizing Outlines
254
Testing Partitions
To test a partition:
l
View data targets using Smart View or another tool to ensure that the user sees the correct
data.
When testing a linked partition, ensure that Essbase links you to the expected database and
that the default user name and password work correctly.
Synchronizing Outlines
Subtopics
l
l
l
l
When you partition a database, Essbase must be able to map each dimension and member in
the data source outline to the appropriate dimension and member in the data target outline.
After you map the two outlines to each other, Essbase can make the data in the data source
available from the data target, as long as the outlines are synchronized and the partition
definitions are up-to-date.
If you make changes to one outline, the two outlines are no longer synchronized. Although
Essbase makes whatever changes it can to replicated and transparent partitions when the outlines
are not synchronized, Essbase may not be able to make the data in the data source available in
the data target.
Essbase tracks changes that you make to block storage outlines and provides tools to keep your
block storage outlines synchronized.
Note: Essbase does not enable automatic synchronization of aggregate storage outlines. You
must manually make the same changes to the source and target outlines.
The source outline is the outline from which outline changes are taken.
The target outline is the outline to which outline changes are applied.
By default, the source outline is from the same database as the data source; that is, outline and
data changes flow in the same direction. For example, if the East database is the data source and
the Company database is the data target, the default source outline is East.
255
You can also use the data target outline as the source outline. Consider this method if the
structure of the outline (its dimensions, members, and properties) is maintained centrally at a
corporate level, while the data values in the outline are maintained at the regional level (for
example, East). Administrators can make changes in the Company outline and apply those
changes to each regional outline when the outline is synchronized.
If you make changes to the shared area in the source outline, you can propagate them to the
target outline when you synchronize the outlines.
If you make changes to the target outline, those changes cannot be propagated back to the
source outline when you synchronize the outlines. To move these changes up to the source
outline, make those changes in Outline Editor. See Chapter 7, Creating and Changing
Database Outlines.
Essbase updates as many changes as possible to the target outline. If Essbase cannot apply all
changes, a warning message prompts you to see the application log for details. Messages that
pertain to outline synchronization are prefixed with OUTLINE SYNC. See Viewing the Essbase
Server and Application Logs on page 739.
To set the source outline, see Setting up the Data Source and the Data Target on page 246.
Topic
Location
Administration Services
Synchronizing Outlines
MaxL
refresh outline
ESSCMD
GETPARTITIONOTLCHANGES
APPLYOTLCHANGEFILE
RESETOTLCHANGETIME
PURGEOTLCHANGEFILE
Note: For synchronizing non-Unicode-mode outlines with multibyte characters, you can use
only non-Unicode clients such as ESSCMD or MaxL statements executed through the
MaxL Shell.
Outline synchronization cannot be performed on an outline containing a Dynamic Calc
member that has many (approximately 100 or more) children.
Tracking Changes
This topic describes the process for changing the source outline and synchronizing the target
outline with the source outline.
l
256
When you make changes to the source outline, Essbase takes the following actions:
1. Records the changes in a change log named essxxxx.chg, where xxxxx is the number
of the partition. If you have multiple partitions on a source outline, Essbase creates a
change log for each partition.
2. Creates or updates the outline change timestamp for that partition in the partition
definition (.ddb) file. Each partition defined against the source outline has a separate
timestamp in the .ddb file.
l
When you pull changes from the outline source, Essbase takes the following actions:
1. Compares the last updated timestamp in the target outline .ddb file to the last updated
timestamp in the source outline backup (.dbb) file. Essbase updates the target
timestamp when it finishes synchronizing the outlines using the last updated time on
the source outline, even if the two outlines are on servers in different time zones.
2. If the source outline has changed since the last synchronization, Essbase retrieves those
changes from the source outline change log and places them in the target outline change
log. The change logs may have different names on the source outline and the target
outline.
When you select the changes to apply to the target outline, Essbase takes the following
actions:
1. Applies the changes to the target outline.
2. Updates the timestamp in the target outlines .ddb file, using the time from the source
outline.
Caution!
If you choose not to apply some changes, you cannot apply those changes later.
257
If you make a change to an actual member in the undefined partition area, such as adding an
alias to the 100-10 actual member, that change is propagated to the target outline because it is
associated with a shared member in the defined partition area.
The reverse is also true. If a shared member is not in the partition area and its actual member
is, a change to the shared member in the undefined area is propagated to the target outline.
Any change made to a member that does not have at least one actual member (or shared member)
in the defined partition area is not propagated to the target outline. For example, in Figure 59,
a change to the parent 100 is not propagated to the target outline because it is in the undefined
partition area and does not have an associated shared member in the defined partition area.
If a shared member is included in the partition area, it is recommended to include its parent. In
the above example, the parent Diet is included in the outline because its children are shared
members and in the defined partition area.
Implied shared members are treated the same as shared members during outline
synchronization. Actual members and their implied shared members in the source outline are
propagated to the target outline if at least one actual or implied shared member is defined in the
partition definition.
Using the partition definition as @CHILD(A) in the example in Figure 60, A1 and A2 are in
the defined partition area, and A11, A21, and A22 are in the undefined partition area. Although
A11 (implied shared member) is in the undefined partition area, a change to A11 is propagated
to the target outline because its parent, A1, is in the defined partition area. The change to the
children A21 and A22 is not propagated to the target outline because these members are not
defined in the partition area and are not associated with a member that is in the defined partition
area.
The reverse is true again. If A1 is not defined in the partition area and its implied shared member
is, any change to A1 is propagated to the target outline.
Figure 60
258
FasterOnly the cells that have changed since the last replication
SlowerAll cells
The slower update is useful under certain conditions; for example, updating all cells to
recover lost data at the target.
Unless you update all cells, replication does not update target data when the source data has
not changed since the last replication.
By default, Essbase replicates #MISSING cells. If you do not want to replicate #MISSING
cells, you can use the DISABLEREPLMISSINGDATA configuration setting in the
essbase.cfg file. See the Oracle Essbase Technical Reference.
If you deleted data blocks on the data source, Essbase updates all data cells at the data target,
even if you choose to update only changed cells. You can delete data blocks at the data source
using any of these methods:
m
Topic
Location
Administration Services
Replicating Data
MaxL
259
Tool
Topic
Location
ESSCMD
GETUPDATEDREPLCELLS
GETALLREPLCELLS
PUTUPDATEDREPLCELLS
PUTALLREPLCELLS
Topic
Location
Administration Services
MaxL
display partition
ESSCMD
PRINTPARTITIONDEFFILE
The partition source and target must have the same security protocol; for example, both or
neither use SSL.
To enable Essbase to use SSL connectivity, you must set ENABLESECUREMODE to TRUE.
260
Troubleshooting Partitions
The following table lists common problems that you may encounter when using partitions.
Table 37
Symptom
Possible Cause
Solution
The data source and the data target outlines are no longer
mappable.
Your host names may not match. Did you use the hosts
file to provide aliases to your local machine?
Data is confusing.
261
262
Part III
263
264
17
In This Chapter
Introduction............................................................................................... 265
Process for Data Loading and Dimension Building ................................................... 266
Data Sources ............................................................................................. 266
Rules Files ................................................................................................ 271
Situations that Do and Do Not Need a Rules File .................................................... 272
Data Sources that Do Not Need a Rules File.......................................................... 273
Security and Multiple-User Considerations ............................................................ 276
The information in this chapter applies to block storage databases and aggregate storage
database. As some rules file options and data source requirements vary for aggregate storage
databases, also see Preparing Aggregate Storage Databases on page 949.
Introduction
An Essbase database contains dimensions, members, and data values.
l
Loading data is the process of adding data values to an Essbase database from a data source,
such as a Microsoft Excel spreadsheet or SQL database. If the data source is not perfectly
formatted, you need a rules file to load the data values.
Building dimensions is the process of loading dimensions and members to an Essbase
database outline by using a data source and a rules file. You can also use Outline Editor to
add dimensions and members manually.
If you use the Essbase API, XML outline editing enables you to use an XML file to make
basic changes to the database outline without needing to use a rules file nor invoke the
Outline API. To perform XML outline editing, you reference a provided .xsd file, create
an .xml file, and call the C Main API function EssBuildDimXML (or the Java API method
buildDimensionXml). For more information, see EssBuildDimXML in the Oracle Essbase
API Reference.
To use the XML outline editing feature, aggregate storage outlines that were created in an
earlier release of Essbase must first be migrated to the current release. Once an aggregate
storage outline is migrated, it cannot be edited in an earlier release client. Block storage
outlines created in an earlier release of Essbase can use XML outline editing without needing
to migrate the outline.
265
In the remainder of this chapter, all content pertains to non-API methods of data loading and
dimension building.
Data Sources
Data sources contain the information that you want to load into the Essbase database. A data
source can contain:
l
Data values
Information about members, such as member names, member aliases, formulas, and
consolidation properties
Attributes
UDAs
The following sections describe the components of any kind of data source.
Essbase export files (export files do not need a rules file to load)
266
Note: When using spreadsheet files to load data or build an outline in Essbase, the spreadsheet
files must reside on a Windows computer, regardless of the tool you use. Spreadsheet files
that reside on a UNIX computer or are transferred via FTP to a UNIX computer are not
supported. If Essbase Administration Server is installed on a UNIX computer, data loads
and dimension builds from client-side spreadsheet files are not supported.
To avoid rules file, data load, and dimension build errors, remove formatting in Microsoft Excel
data source files; for example, in Excel, set color to Automatic and No Fill, and remove font
settings such as bold and italic.
A delimiter indicates that a field is complete and that the next character in the record starts
another field.
Essbase reads data sources starting at the top and proceeding from left to right.
Figure 61
As illustrated in Figure 62, data sources can contain dimension fields, member fields, member
combination fields, and data fields.
Figure 62
Kinds of Fields
Dimension fields identify the dimensions of the database, such as Market. Use dimension
fields to tell Essbase the order of the dimensions in the data source. In Figure 62, for example,
the dimension fields are Market, Product, Year, Measures, and Scenario. Fields in the Market
267
column, such as Texas, are members of the Market dimension, and fields in the Product
column, such as 100-10, are members of the Product dimension. Although you can set
dimension fields in the data source, usually you define dimension fields in the rules file.
l
Member fields identify the members or member combinations of the specified dimensions.
Use member fields to tell Essbase to which members to map new data values, or which
members to add to the outline. In Figure 62, for example, Texas, 100-10, Jan, Sales, and
Actual are member fields.
Data fields contain the numeric data values that are loaded into the intersections of the
members of the database. Each data value must map to a dimension intersection. In
Figure 62, for example, 42 is the data value that corresponds to the intersection of Texas,
100-10, Jan, Sales, and Actual.
You can specify information in the header and in an individual record. In the following
example, 100 is the data value that corresponds to the intersection of Jan, Actual, Cola, East,
Sales, and 200 is the data value that corresponds to the intersection of Jan, Actual, Cola,
West, Sales.
Jan, Actual
Cola East Sales 100
Cola West Sales 200
Cola South Sales 300
Data fields are used only for data loading; dimension builds ignore data fields.
The following sections describe each item in a data source.
268
The member field must contain or inherit a valid member name or member property. See
Using the Data Source to Work with Member Properties on page 283. If you are not
performing a dimension build, the member must already exist in the outline. If you are
performing a dimension build, the member can be new.
Either the data source or the rules file must specify which dimension each member field
maps to.
A member field can map to a single member name, such as Jan (which is a member of the
Year dimension), or to a member combination, such as Jan, Actual (which are members of
the Year and Scenario dimensions).
Member names that contain the same character as the file delimiter must be surrounded by
double quotation marks. For example, if the data source is delimited by spaces, ensure that
a member containing spaces, such as New York, is enclosed by double quotation marks.
If you are performing a data load without a rules file, member names containing some other
characters also must be enclosed by quotation marks. See Data Sources that Do Not Need
a Rules File on page 273.
When a rules file is not used, blank dimension and member fields are valid. When Essbase
encounters a blank dimension or member field while loading data without a rules file, it uses
the last dimension or member name encountered for that dimension or member column.
Note: While it processes each record in a data source for a data load, Essbase does not check to
ensure that a member specified in a member field belongs to the dimension specified for
the dimension field. Essbase loads the data value to the data cell identified by the member
combination in the record. In Figure 62 on page 267, for example, if the second record
reversed Jan and Sales (Texas, 100-10, Sales, Jan, Actual, 42), Essbase would load 42 to
the correct data cell. The exception is for fields in the rules file set as dimension reference
method.
Valid Modifiers
Examples
Currency symbols:
Dollar $
Euro
Yen
269
Valid Modifiers
Examples
(12)
Minus sign before numbers. Minus signs after numbers are not valid.
-12
Decimal point
12.3
If the data source contains a member field for every dimension and one field that contains data
values, you must define the field that contains data values as a data field in the rules file. To read
the following data source into the Sample.Basic database, for example, define the last field as a
data field.
Jan
Feb
Cola
Cola
East
East
Sales
Sales
Actual
Actual
100
200
Valid Delimiters
You must separate fields from each other with delimiters. If you are loading data without a rules
file, you must use spaces to delimit fields.
If you are using a rules file, delimiters can be any of the following:
l
Tabs (default)
Spaces
New lines
Carriage returns
Commas
270
Cola
Cola
Cola
Actual
Actual
Actual
Jan
Feb
Mar
Sales
Sales
Sales
10
21
30
To resolve the problem, delete the extra delimiter from the data source.
Formatting Character
Description
==
--
_ _
Multiple underscores
==
_ _
Jan
Feb
Actual
Sales
=====
10
21
"100-10"
Marketing
=========
8
16
Rules Files
Rules define operations that Essbase performs on data values or on dimensions and members
when it processes a data source. Use rules to map data values to an Essbase database or to map
dimensions and members to an Essbase outline.
271
Figure 63
Rules are stored in rules files. A rules file defines which build method to use, whether data values
or members are sorted or are in random order, and how to transform data values or members
before loading them. It is best to create a separate rules file for each dimension.
Essbase reads the data values or members in the data source, changes them based on the rules
in the rules file, and loads the changed data values into the database and the changed members
into the outline. Essbase does not change the data source. You can reuse a rules file with any
data source that requires the same set of rules.
After you create a dimension build rules file, you may want to automate the process of updating
dimensions. See Appendix E, Using ESSCMD.
Building dimensions
Mapping the data in the data source to the database by changing strings
Changing the data values in the data source by scaling data values or by adding data
values to existing data values in the data source
You do not need a rules file if you are performing a data load and the data source maps perfectly
to the database. See Data Sources that Do Not Need a Rules File on page 273.
272
Note: If you are using a rules file, the number of fields in each record in the rules file must match.
One or more valid members from each dimension. A member name must be enclosed in
quotation marks if it contains any of the following:
m
Spaces
Plus signs
Ampersands (&)
If you are performing a data load without a rules file, when Essbase encounters an invalid
member field, it stops the data load even if the Abort on Error flag is not set to true.
Essbase loads all fields read before the invalid field into the database, resulting in a partial
load of the data values. See Loading Dimension Build and Data Load Error Logs on
page 753.
One or more valid data values. See Valid Data Fields on page 269.
If the data source contains blank fields for data values, replace the blank fields with #MI or
#MISSING. Otherwise, the data values may not load correctly.
The fields in the data source must be formatted in an order that Essbase understands. The
simplest way to format a record is to include a member from each dimension and a data field,
as illustrated below:
Sales "100-10" Ohio Jan Actual 25
Sales "100-20" Ohio Jan Actual 25
Sales "100-30" Ohio Jan Actual 25
An incorrectly formatted data source will not load. You can edit the data source using a text
editor and fix the problem. If you must perform many edits (such as moving several fields and
records), consider using a rules file to load the data source. See Rules Files on page 271.
The following sections describe more complicated ways to format free-form data sources.
273
Texas
Jan
"100-10"
98
"100-20"
87
Sales
COGS
Feb
Jan
Feb
89
26
19
78
23
32
Notice that Sales is defined for the first two columns and COGS for the last two columns.
The following sections describe additional types of ranges.
Sales
100-10"
100-20
Jan
98
87
Feb
89
78
Mar
58
115
274
Actual
East
Jan
Feb
100
120
10
30
34
32
For information on restarting the load, see Loading Dimension Build and Data Load Error
Logs on page 753.
Jan
Feb
East
Actual
Sales
108
102
Budget
Actual
Budget
Sales
COGS
COGS
110
49
50
120
57
60
For Actual, the first member of the first range, Essbase maps data values to each member of the
second range (Sales and COGS). Essbase then proceeds to the next value of the first range, Budget,
similarly mapping values to each member of the second range. As a result, Essbase interprets the
file as shown below:
Cola
Jan
Feb
East
Actual
Sales
108
102
COGS
110
120
Budget
Sales
49
57
COGS
50
60
Formatting Columns
If you are performing a dimension build, skip this section.
Files can contain columns of fields. Essbase supports loading data from symmetric columns or
asymmetric columns.
275
Symmetric Columns
If you are performing a dimension build, skip this section. Dimension builds require a rules file.
Symmetric columns have the same number of members under them. In the following example,
each dimension column has one column of members under it. For example, Product has one
column under it (100-10 and 100-10) and Market has one column under it (Texas and Ohio).
Product
"100-10"
"100-10"
Measures
Sales
Sales
Market
Texas
Ohio
Year
Jan
Jan
Scenario
Actual
Actual
112
145
The columns in the following file are also symmetric, because Jan and Feb have the same number
of members under them:
"100-10"
"100-10"
Sales
Sales
Texas
Ohio
Jan
Actual
Budget
112
110
145
120
Feb
Actual
Budget
243
215
81
102
Asymmetric Columns
If you are performing a dimension build, skip this section.
Asymmetric columns have different numbers of members under them. In the following example,
the Jan and Feb columns are asymmetric because Jan has two columns under it (Actual and
Budget) and Feb has one column under it (Budget):
"100-10"
"100-10"
Sales
Sales
Texas
Ohio
Jan
Actual
112
145
Jan
Budget
110
120
Feb
Budget
243
81
If a file contains asymmetric columns, label each column with the appropriate member name.
The example above is valid because the Jan label is now over Actual and Budget. It is clear to
Essbase that both columns map to Jan.
The following example is not valid because the column labels are incomplete. The Jan label must
appear over the Actual and Budget columns.
"100-10"
"100-10"
Sales
Sales
Texas
Ohio
Jan
Actual
112
145
Budget
110
120
Feb
Budget
243
81
276
Security Issues
The security system prevents unauthorized users from changing the database. Only users
with write access to a database can load data values or add dimensions and members to the
database. Write access can be provided globally or by using filters.
l
Locks the block it is loading into so that no one can write to the block.
See Chapter 50, Ensuring Data Integrity for information on Essbase transaction
settings, such as identifying whether other users get read-only access to the locked block
or noting how long Essbase waits for a locked block to be released.
277
278
18
In This Chapter
Process for Creating Data Load Rules Files ........................................................... 279
Process for Creating Dimension Build Rules Files .................................................... 280
Combining Data Load and Dimension Build Rules Files ............................................. 280
Creating Rules Files...................................................................................... 281
Setting File Delimiters ................................................................................... 282
Naming New Dimensions................................................................................ 282
Selecting a Build Method ............................................................................... 282
Setting and Changing Member and Dimension Properties........................................... 283
Setting Field Type Information .......................................................................... 285
Setting Dimension Build Operational Instructions .................................................... 288
Defining Data Load Field Properties.................................................................... 288
Performing Operations on Records, Fields, and Data ................................................ 289
Validating, Saving, and Printing ........................................................................ 289
Also see:
l
279
5. If necessary, set record, field, and data operations to change the data in the data source during
loading.
See Chapter 19, Using a Rules File to Perform Operations on Records, Fields, and Data.
6. Validate and save the rules file.
See Setting Dimension Build Operational Instructions on page 288.
280
Use the same rules file for both data load and dimension build if you plan to load the data source
and build new dimensions simultaneously.
Use separate rules files for data load and dimension build under any of the following
circumstances:
l
To perform different field operations during the data load and dimension build
If you are creating the rules file on the Essbase Server, connect to the server.
Connecting to the server is not necessary if you are creating the rules file on the client.
See Creating Rules Files or Opening Rules Files in the Oracle Essbase Administration
Services Online Help.
You can open Data Prep Editor with a new or existing rules file. After you open Data Prep
Editor, put the editor in the correct mode. See About Data Prep Editor in the Oracle Essbase
Administration Services Online Help.
In Data Prep Editor, you can open data sources such as text files, spreadsheet files, and SQL
data sources. Data Prep Editor displays the data source, enabling you to see what needs to
be changed.
l
To open text files and spreadsheet files, see Opening Data Files in the Oracle Essbase
Administration Services Online Help.
To open SQL data sources, see Opening SQL Databases in the Oracle Essbase
Administration Services Online Help.
To open an SQL data source, use SQL Interface. The Oracle Essbase SQL Interface
Guide provides information on supported environments, installation, and connection
to supported data sources. Contact your Essbase administrator for more information.
You can define a substitution variable for the data source name (DSN). When you open
a SQL data source, you can select the substitution variable for the value you want to use
as the DSN. For example, you can create a substitution variable named Payroll_detail
281
and create a rules file that specifies Payroll_detail as the substitution variable for the data
source name. Before performing the data load or dimension build, you must set the
value for Payroll_detail to the data source name you want to use; for example, an Oracle
or IBM DB2 database. When a data load or dimension build is performed, the
substitution variable value that Essbase Server finds at that time is used. See Using
Substitution Variables on page 120.
Note: When you open an SQL data source, the rules fields default to the SQL data source
column names. If the names are not the same as the Essbase dimension names,
map the fields to the dimensions. See Changing Field Names on page 300.
282
If you are building a new dimension or adding members to an existing dimension, you must
specify a build method for each dimension that you are creating or modifying. For information
about each build method, see Understanding Build Methods on page 319.
283
In Administration Services Console, the following dimension build options control whether the
value in the data source property field is applied to the associated member:
l
In the data source, put the properties in the field directly following the field containing the
members that the properties modify. For example, to specify that the Margin% member not roll
up into its parent and not be shared:
1. Position the ~ property (which indicates that the member should not roll up into its parent)
and the N property (which indicates that the member should not be shared) after the Margin
% field. For example:
Margin%
Margin%
~ N Sales
Table 40 lists all member codes used in the data source to assign properties to block storage
outline members. (For a list of properties that can be assigned to aggregate storage outline
members, see Rules File Differences for Aggregate Storage Dimension Builds on page 950.)
Table 40
Code
Description
284
Code
Description
Exclude data values of zero or #MISSING in the time balance (applies to accounts dimensions only)
Exclude data values of #MISSING from the time balance (applies to accounts dimensions only)
Set member as stored member (non-Dynamic Calc and not label only)
Exclude data values of zero from the time balance (applies to accounts dimensions only)
Member names
Member properties
Attribute associations
For Essbase to process this information, you must specify the following information when setting
field types:
l
Field type
The type of field to expect in that column, such as a generation field or an alias field. The
field type depends on the data source and the build method (see Understanding Build
Methods on page 319).
Dimension
285
Field Type1
Alias
An alias
Note: The alias value will not be assigned to the new member if Member update
dimension build is set to Remove unspecified and the data source for a new
member contains the alias value of a removed member.
Property
A member property.
See Table 40, Member Property Codes, on page 284.
Formula
A formula
Currency name
Currency category
UDA
A UDA
Attribute parent
In an attribute dimension, the name of the parent member of the attribute member
in the following field
Generation
Duplicate generation
Duplicate generation
alias
Level
Duplicate level
286
Generation references
Level references
Field Type1
Parent
Parent-child reference
Child
1Field
types whose names begin with duplicate (such as duplicate generation and duplicate level alias), are not related to duplicate member
names described in Chapter 8, Creating and Working With Duplicate Member Outlines.
Build
Method
Generation
If GEN numbers do not start at 2, the first member of the specified generation must exist in the outline.
GEN numbers must form a contiguous range. For example, if GEN 3 and GEN 5 exist, you must also define GEN 4.
GEN3,PRODUCT
GEN4,PRODUCT
Put attribute association fields after the base field with which they are associated, and specify the generation number
of the associated base dimension member. For example:
GEN2,PRODUCT
GEN3,PRODUCT
OUNCES3,PRODUCT
The generation number must correspond to the generation of the member in the outline for which the field provides
values. For example, the 3 in GEN3,PRODUCT shows that the values in the field are third-generation members of the
Product dimension. The 2 in ALIAS2,POPULATION shows that the values in the field are associated with the secondgeneration member of the Population dimension.
Note: When using the generation build method to create a duplicate member dimension, the maximum number of
generations is 20.
Level
Each record must contain a level 0 member. If a level 0 member is repeated on a new record with a different parent,
Essbase rejects the record unless you select the Allow Moves member property. See Setting and Modifying Member
Properties in the Oracle Essbase Administration Services Online Help.
Put attribute association fields after the base field with which they are associated, and specify the level number of the
associated base dimension member. For example:
LEVEL3,PRODUCT
OUNCES3,PRODUCT
LEVEL2,PRODUCT
The level number must correspond to the level of the member in the outline for which the field provides values. For
example, the 3 in LEVEL3,PRODUCT shows that the values in the field are level 3 members of the Product dimension.
The 2 in ALIAS2,POPULATION shows that the values in the field are associated with the second level of the Population
dimension.
287
Build
Method
Parent-child
If field type is parent or child, enter 0 (zero) in the Number text box.
Attribute
dimension
name
The generation or level number must correspond to the generation or level of the associated base member in the outline.
For example, the 3 in OUNCES3,PRODUCT shows that the values in the field are the members of the Ounces attribute
dimension that are associated with the third-generation member of the Product dimension in the same source data record.
If necessary, move the fields to the required locations. See Moving Fields on page 298.
To move fields:
See Moving Fields in the Oracle Essbase Administration Services Online Help.
Whether to sort members after Essbase has processed and added all members from the data
source
Whether to add the members to the existing outline or to remove unspecified members from
the outline
Removing unspecified members is available only with the generation reference, level
reference, and parent-child reference build methods.
Note: Outlines are invalid if removing members results in level 0 Dynamic Calc members
without formulas.
Level and generation references: The data source contains multiple fields within the
duplicate member dimension to uniquely identify duplicate members.
m
Use the level reference method when fields within a dimension are organized bottomup in the data source.
Use the generation reference method when fields within a dimension are organized topdown in the data source. For example:
gen2,Market, gen3,Market, Product, Year, Measures, Scenario, *data*
State,"New York","100-10",Jan,Sales,Actual,42
288
Rules files are validated to ensure that the members and dimensions in the rules file map to the
outline. Validation cannot ensure that the data source loads properly.
Data load: Requirements for Valid Data Load Rules Files on page 290
Dimension build: Requirements for Valid Dimension Build Rules Files` on page 290
289
Does each record in the data source contain only one member from each dimension?
See Items in a Data Source on page 267.
Are all members surrounded by quotation marks if they contain numbers or file delimiters?
See Valid Member Fields on page 268.
Is the member that each data field maps to spelled correctly in the rules file?
See Changing Field Names on page 300.
Is the dimension name used in only one field (for example, not in a field name and the
header)?
You can map a single data value to only one set of members.
Does each record contain only one member from each dimension?
See Items in a Data Source on page 267.
Are all members enclosed in quotation marks if they contain numbers or file delimiters?
290
Are any dimensions specified in both the header record in the rules file and the header record
in the data source?
Dimensions can be specified in either the header in the rules file or the header in the data
source, but not in both. See Defining Header Records on page 295.
Topic
Location
Administration Services
MaxL
alter object
ESSCMD
COPYOBJECT
292
19
In This Chapter
Performing Operations on Records ..................................................................... 293
Performing Operations on Fields........................................................................ 297
Performing Operations on Data......................................................................... 302
Also see:
l
Selecting Records
Rejecting Records
Combining Multiple Select and Reject Criteria
Setting the Records Displayed
Defining Header Records
You can perform operations at the record level. For example, you can reject certain records
before they are loaded into the database. See the following sections.
Selecting Records
You can specify which records Essbase loads into the database or uses to build dimensions by
setting selection criteria. Selection criteria are string and number conditions that must be met by
one or more fields within a record for Essbase to load the record. If a field or fields in the record
do not meet the selection criteria, Essbase does not load the record. You can define one or more
selection criteria. For example, to load only 2003 Budget data from a data source, create a
selection criterion to load only records in which the first field is Budget and the second field is
2003. If you define selection criteria on multiple fields, you can specify how Essbase combines
the criteria. See Combining Multiple Select and Reject Criteria on page 294.
293
To select a record:
See Selecting Records in the Oracle Essbase Administration Services Online Help.
Rejecting Records
You can specify which records Essbase ignores by setting rejection criteria. Rejection criteria are
string and number conditions that, when met by one or more fields within a record, cause Essbase
to reject the record. You can define one or more rejection criteria. If no field in the record meets
the rejection criteria, Essbase loads the record. For example, to reject Actual data from a data
source and load only Budget data, create a rejection criterion to reject records in which the first
field is Actual.
To reject a record:
See Rejecting Records in the Oracle Essbase Administration Services Online Help.
294
Rules files contain records that translate the data of the data source to map it to the database.
As part of that information, rules files can also contain header records. For example, the
Sample.Basic database has a dimension for Year. If several data sources arrive with monthly
numbers from different regions, the month itself might not be specified in the data sources. You
must set header information to specify the month.
You can create a header record using one of the following methods:
l
Define header information in the data source and, in the rules file, point to the header
records.
Placing header information in the data source makes it possible to use the same rules file for
multiple data sources with different formats, because the data source format is specified in
the data source header (not in the rules file).
When you add one or more headers to the data source, you must also specify in the rules
files the location of the headers in the data source. The rules file tells Essbase to read the
header information as a header record (not as a data record). You can also specify the type
of header information in each header record.
Header information defined in the data source takes precedence over header information
defined in the rules file.
295
The header record lists field definitions for each field. The field definition includes the field type,
the field number, and the dimension name into which to load the fields. Figure 64 illustrates the
format of a header record:
Figure 64
If the file delimiter is a comma, enclose each field definition in quotation marks (" ").
After you set the header information in the data source, you must specify the location of the
header information in the rules file. If a rules file refers to header information in a data source,
Essbase uses the information in the data sourcerather than the information in the rules file
to determine field types and dimensions.
PARENT, CHILD
PROPERTY
ALIAS
FORMULA
CURNAME
CURCAT
UDA
ATTRPARENT
Each field type that you set requires a field number. When the field type is the name of an attribute
dimension, the field number cannot be greater than 9. See Setting Field Type Information on
page 285.
296
Ignoring Fields
Ignoring Strings
Arranging Fields
Mapping Fields
Changing Field Names
You can perform operations at the field level. For example, you can move a field to a new position
in the record. See the following sections.
Ignoring Fields
You can ignore all fields of a specified column of the data source. The fields still exist in the data
source, but they are not loaded into the Essbase database. For example, the Sample.Basic database
has five standard dimensions: Year, Product, Market, Measures, and Scenario. If the data source
has an extra field that is not a member of any dimension, such as Salesperson, you can tell Essbase
to ignore the Salesperson field.
Ignoring Strings
You can ignore any field in the data source that matches a string, called a token. When you ignore
fields based on string values, the fields are ignored everywhere they appear in the data source,
not just in a particular column. For example, in a data source that is a computer-generated report
in text format, special ASCII characters might be used to create horizontal lines between pages
or boxes around headings. These special characters can be defined as tokens to be ignored.
Arranging Fields
You can set the order of the fields in the rules file to be different from the order of the fields in
the data source. The data source is unchanged. See the following sections.
297
Moving Fields
You can move fields to a different location using a rules file. For example, you can specify the
first field in the data source to be the third field during the data load or dimension build.
In some instances, moved fields may appear to merge. If you move a field that contains empty
cells, and the moved field becomes the last field in the record, as shown below, the field may
merge with the field to its left.
1<tab>2<tab>3
1<tab>2<tab>(null)
To move fields:
See Moving Fields in the Oracle Essbase Administration Services Online Help.
Joining Fields
You can join multiple fields into one field. The new field is given the name of the first field in
the join. For example, if a data source has separate fields for product number (100) and product
family (-10), you must join the fields (100-10) before loading them into the Sample.Basic
database.
Before you join fields, move the fields to join into the order in which you want them joined. See
Moving Fields in the Oracle Essbase Administration Services Online Help.
To join fields:
See Joining Fields in the Oracle Essbase Administration Services Online Help.
298
Copying Fields
You can create a copy of a field while leaving the original field intact. For example, if, during a
single dimension build, you want to define a multilevel attribute dimension and associate
attributes with members of a base dimension, you must copy some of the fields. See Working
with Multilevel Attribute Dimensions on page 332.
To copy a field, select one field and then create a field using a join:
See Creating Fields Using Joins in the Oracle Essbase Administration Services Online Help.
Splitting Fields
You can split a field into two fields. For example, if a data source for the Sample.Basic database
has a field containing UPC100-10-1, you can split UPC out of the field and ignore it. Then,
only 100-10-1, the product number, is loaded.
To split a field:
See Splitting Fields in the Oracle Essbase Administration Services Online Help.
Mapping Fields
This section applies to data load only. If you are performing a dimension build, skip this section.
299
You use a rules file to map data source fields to Essbase member names during a data load. You
can map fields in a data source directly to fields in the Essbase database during a data load by
specifying which field in the data source maps to which member or member combination in the
Essbase database. The data source is not changed.
Note: When you open a SQL data source, the fields default to the SQL data source column
names. If the SQL column names and the Essbase dimension names are the same, you
need not map the column names.
To map fields:
See Mapping Field Names in the Oracle Essbase Administration Services Online Help.
Maps member fields of the data source to dimensions and members of the database
Maps data fields of the data source to member names or member combinations (such as
Jan, Actual) of the database
300
301
This section applies to data load only. If you are performing a dimension build, skip this section.
You can perform operations on the data in a field; for example, moving a field to a new position
in the record. See the following sections.
Product,
100-10
100-20
100-10
Year,
Jan
Jan
Jan
Measures,
Sales
Sales
Sales
Scenario
Actual
Actual
Actual
42
82
37
302
For block storage databases, set the Commit Row database transaction option to 0 to prevent
difficult recoveries. This setting causes Essbase to view the entire load as a single transaction and
to commit the data only when the load is complete. See Understanding Isolation Levels on
page 777.
Using Administration Services Console, you can add to and substract from existing values in
block storage and aggregate storage databases. Using MaxL, you can only add to and substract
from existing values in aggregate storage databases only.
Topic
Location
Administration Services
When you load Week 1 Sales, clear the database value for January Monthly Sales. If there is an
existing value, Essbase performs the following calculation:
January Sales = Existing Value + Week 1 Sales + Week 2 Sales + Week 3 Sales + Week 4
Sales
You can also clear data from fields that are not part of the data load. For example, if a data source
contains data for January, February, and March, and you want to load only the March data, you
can clear January and February data.
304
20
In This Chapter
Prerequisites for Data Loads and Dimension Builds.................................................. 305
Performing Data Loads or Dimension Builds .......................................................... 305
Stopping Data Loads or Dimension Builds ............................................................ 306
Tips for Loading Data and Building Dimensions ...................................................... 307
Debugging Data Loads and Dimension Builds ........................................................ 311
Also see:
l
An Essbase database
If you are not using a rules file, a data source correctly formatted for free-form data loading
See Data Sources that Do Not Need a Rules File on page 273.
305
or build. You can then check the status of the background process to see when the load or build
has completed. See Loading Data and Building Dimensions in the Oracle Essbase
Administration Services Online Help.
If you are using multiple data sources in a dimension build, to reduce total processing time you
can perform a deferred-restructure dimension build. See Performing Deferred-Restructure
Dimension Builds on page 307.
Note: If you are loading data into a transparent partition, follow the same steps as for loading
Topic
Location
Administration Services
MaxL
database, use the Committed Isolation Level setting, if possible. If the data load is
terminated, this setting rolls the data load back to its previous state. See Understanding
Isolation Levels on page 777. If you stop a data load that is adding to or subtracting from
data values, see Recovering from an Essbase Server Crash on page 312.
Topic
Location
Administration Services
306
Tool
Topic
Location
MaxL
This section contains topics to help you load data and build dimensions.
For block storage outlines, see Optimizing Database Restructuring on page 839.
For aggregate storage outlines, see Aggregate Storage Database Restructuring on page
1027.
Administration Services enables you to list all data sources in a single dialog box.
When the files listed are all dimension builds, a deferred-restructure dimension build option
is available. Selecting this option delays restructuring until all sources have been processed.
The outline is validated after each dimension build is processed. See Loading Data and
Building Dimensions in the Oracle Essbase Administration Services Online Help.
MaxL enables you to include all of the data sources within one import database statement.
307
You can control whether outline validation is performed for each file. You must enable
outline validation for the last file. See import database and import dimension in the
MaxL section of the Oracle Essbase Technical Reference.
ESSCMD requires several commands:
In all cases, the data sources are processed in the order in which they are listed.
Note: MaxL and ESSCMD enable you to enforce or suppress outline verification for each file.
To ensure a valid outline, ensure that the last build verifies the outline. Deferredrestructure dimension builds in Administration Services verify the outline after each data
source is processed.
If you must load data into a parent member, ensure that Essbase knows not to consolidate
#MISSING values from the children of the parent into the parent.
Topic
Location
Administration Services
Calculation Script
SET AGGMISSG
MaxL
alter database
ESSCMD
SETDBSTATEITEM
The methods in this table work only if the child values are empty (#MISSING). If the children
have data values, the data values overwrite the data values of the parent. See Consolidating
#MISSING Values on page 884.
308
Note: You cannot load data into Dynamic Calc, Dynamic Calc and Store, or attribute members.
For example, if Year is a Dynamic Calc member, you cannot load data into it. Instead,
load data into Qtr1, Qtr2, Qtr3, and Qtr4, which are not Dynamic Calc members.
To fix the file, insert #MISSING or #MI into the missing field:
Actual Ohio Sales Cola
Jan
Feb
Mar
Apr
10
15
20
#MI
previously for that dimension or member field. See Missing Dimension or Member
Fields on page 316.
If a rules file has extra blank fields, join the empty fields with the field next to them. See Joining
Fields on page 298.
In aggregate storage databases, values can be loaded only to level 0 cells. Specifying #MISSING
or #MI as a value in the data source removes the associated cell if it is present in the database.
For information about data load differences for aggregate storage databases, see Preparing
Aggregate Storage Databases on page 949.
Set the rules file to ignore the column containing the record number.
Define a rejection criterion that rejects all records except those that you want to load.
For example, reject all records for which the ignored column is fewer than 250 or greater
than 500. See Rejecting Records on page 294.
309
Note: You cannot reject more records than the error log can hold. By default, the limit is
310
If a data source does not correctly load into Essbase Server, ensure that you are connected to the
appropriate application and database and that you are loading the correct data source.
If you still encounter problems, see the following topics. After you correct the problems, you
can reload the records that did not load by reloading the error log. See Loading Dimension
Build and Data Load Error Logs on page 753.
The data source is open (for example, is someone editing the data source?).
Essbase can load only data sources that are not locked by another user or application.
The data source name and the path name are correct.
311
The connection information (such as the user name, password, and database name) is
correct.
You can connect to the SQL data source without using Essbase.
If the error log exists but is empty, Essbase does not think that an error occurred during loading.
Check whether the following conditions exist:
l
The rules file contains selection or rejection criteria that rejected every record in the data
source.
See Selecting Records on page 293 and Rejecting Records on page 294.
If you are overwriting the values of the data source, reload the data source when the server
is running again.
If you are adding to or subtracting from existing values in the data source and the Isolation
Level setting is:
m
Committed, reload the data source when the server is running again.
Uncommitted, determine how much data Essbase loaded before the crash:
1. Compare the values of the data source with the values of the database.
2. If the values that you are adding to or subtracting from have not changed, reload
the data source.
3. If the values that you are adding to or subtracting from have changed, clear the
values that loaded and reload the previous data sources. If, for example, you derive
monthly sales figures by adding the sales figures for each week as they are loaded,
clear the sales figures from the database and reload the sales figures for each week
up to the current week.
Texas Sales
51.7
102.5
335.0
96.7
276.0
113.1
167.0
313
There are any implicitly shared members (when a parent and child share the same data value)
of which you were unaware.
This situation occurs if a parent has only one child or only one child rolls up into the parent.
See Understanding Implied Sharing on page 152.
You added incoming data to existing data instead of replacing incoming data with existing
data.
See Adding to and Subtracting from Existing Values on page 302.
You selected or rejected any records that you did not intend to select or reject.
See Selecting Records on page 293 and Rejecting Records on page 294.
The sign is reversed (for example, a minus sign instead of a plus sign) and whether you
performed sign flips on any UDAs.
See Flipping Field Signs on page 304.
You cleared data combinations that you did not intend to clear.
See Clearing Existing Data Values on page 303.
All member and alias names are fewer than 79 characters long.
Note: You can check data by exporting it, by running a report on it, or by using a spreadsheet.
If exporting or running reports, see Chapter 35, Developing Report Scripts and
Appendix E, Using ESSCMD. If using a spreadsheet, see Oracle Smart View for Office
User's Guide.
Determine how to search for the end of file marker using the Essbase search command.
This task may be difficult, because the end of file marker may be composed of one or more
special characters.
See Ignoring Fields By Specifying Tokens in the Oracle Essbase Administration Services
Online Help.
See Rejecting Records in the Oracle Essbase Administration Services Online Help.
314
Performs all replaces in the order in which they are defined in the rules file
j.
315
6. Essbase performs selection or rejection criteria in the order in which the criteria are defined
in the rules file. Essbase loads or rejects individual records of the data source based on the
specified criteria.
Sales
Actual
Ohio
Cola
"Root Beer"
"Diet Cola"
25
50
19
Essbase stops the data load if no prior record contains a value for the missing member field. For
example, if you try to load the following file into the Sample.Basic database, the data load stops,
because the Market dimension (Ohio, in the previous example) is not specified.
Jan
Sales
Actual
Cola
"Root Beer"
"Diet Cola"
25
50
19
For information on restarting the load, see Loading Dimension Build and Data Load Error
Logs on page 753.
316
2
12
15
11
Note: If you are performing a dimension build, you can add the new member to the database.
Cola
Actual
Jan
$10
Feb
$21
Mar
$15-
Apr
$16
For information on continuing the load, see Loading Dimension Build and Data Load Error
Logs on page 753.
317
318
21
Understanding Advanced
Dimension Building Concepts
In This Chapter
Understanding Build Methods .......................................................................... 319
Using Generation References ........................................................................... 320
Using Level References .................................................................................. 322
Using Parent-Child References ......................................................................... 324
Adding a List of New Members ......................................................................... 326
Building Attribute Dimensions and Associating Attributes ........................................... 329
Building Shared Members by Using a Rules File...................................................... 339
Building Duplicate Member Outlines................................................................... 347
Examples
Desired Operation
Build Method1
Top-down data
Year, Quarter,
Month
Generation
references
The generation
number for each
field.
Level references
Month,
Quarter, Year
319
Examples
Desired Operation
Cola, Diet
Cola
Build Method1
Parent-child
references
Field Type
Information
Whether a field is
parent or child. The
field number is 0.
Share non-level 0
members
Modify properties of
existing dimensions and
members
Jan, Feb,
Mar, April
800-10,
800-20
Add as sibling at
the lowest level
800-10,
800-20
Add as sibling to a
member with a
matching string
Cola 16oz
Can, Root
Beer 14oz
Bottle
Generation, level,
or parent-child
references,
depending on the
organization of the
source data
1Using
a level references build, you cannot create an alias that has the same name as its member. This restriction does not apply if you use
other build methods, including the generation references build method.
320
Figure 65
Generations
The top half of Figure 66 shows a top-down data source (GENREF.TXT). The data source is used
to build the Product dimension. The bottom half shows the rules file for the data source
(GENREF.RUL). The rules file specifies the generation number for each field in the data source.
See Setting Field Type Information on page 285.
Figure 66
Figure 67 shows the tree that Essbase builds from the GENREF.TXT data source and
GENREF.RUL rules file:
Figure 67
Generation References
Missing field: If the null occurs where Essbase expects a GENERATION field, Essbase
promotes the next GENERATION field to replace the missing field.
321
GEN3,Products
GEN4,Products
100-10a
When Essbase reads the record, it promotes the GEN4 field (100-10a) to GEN3, as if the
data source looked like the following example:
GEN2,Products
100
l
GEN3,Products
100-10a
GEN4,Products
Missing field before secondary field: If a null occurs directly before a secondary field, Essbase
ignores the secondary field. (Secondary field types are alias, property, formula, duplicate
generation, duplicate generation alias, currency name, currency category, attribute parent,
UDA, and name of an attribute dimension.)
In the following example, there is no field in the GEN2, Products or the ALIAS2,Products
column:
GEN2,Products
ALIAS2,Products
Cola
GEN3,Products
100-10
GEN4,Products
100-10a
When Essbase reads the record, it ignores the ALIAS2 field and promotes the GEN3 field
(100-10) to GEN2 and the GEN4 field (100-10a) to GEN3, as if the data source looked like
the following example:
GEN2,Products
100-10
l
ALIAS2,Products
Cola
GEN3,Products
100-10a
GEN4,Products
Missing secondary field: If the null occurs where Essbase expects a secondary field, Essbase
ignores the secondary null field and continues loading.
In the following example, there is no field in the ALIAS2, Products column:
GEN2,Products
100
ALIAS2,Products
GEN3,Products
100-10
GEN4,Products
100-10a
When Essbase reads the record, it ignores the ALIAS2 field and loads the other fields.
322
Figure 68
To build the outline in Figure 68, you can use the following bottom-up data source:
100-10-12
100-20-12
100-10
100-20
100
100
In a level reference build, the lowest-level members are sequenced left to right. Level 0 members
are in the first field, level 1 members are in the second field, and so on. This organization is the
opposite of how data is presented for generation references (top-down).
In the following example, the rules file uses the level reference build method to add members to
the Product dimension. The rules file specifies the level number and the field type for each field
of the data source (see Setting Field Type Information on page 285). The first column of the
data source contains new members (600-10-11, 600-20-10, and 600-20-18). The second column
contains the parents of the new members (600-10 and 600-20), and the third column contains
parents of the parents (600).
Figure 69
For example, to build the tree in Figure 70, use Figure 69 to set up the data source
(LEVEL.TXT) and the rules file (LEVEL.RUL).
Figure 70
Levels
323
Missing field: If a null occurs where Essbase expects a LEVEL field, Essbase promotes the
next LEVEL field to replace the missing field.
In the following example, there is no field in the LEVEL0, Products column:
LEVEL0,Products
LEVEL1,Products
100-10
LEVEL2,Products
100
When Essbase reads the record, it promotes the LEVEL1 field (100-10) to LEVEL0 and the
LEVEL2 field (100) to LEVEL1, as if the data source looked like the following example:
LEVEL0,Products
100-10
l
LEVEL1,Products
100
LEVEL2,Products
Missing field before a secondary field: If a null occurs directly before a secondary field,
Essbase ignores the secondary field. (Secondary field options are alias, property, formula,
duplicate level, duplicate level alias, currency name, currency category, attribute parent,
UDA, and a name of an attribute dimension.)
In the following example, there is no field in the LEVEL0, Products column:
LEVEL0,Products
ALIAS0,Products
Cola
LEVEL1,Products
100-10
LEVEL2,Products
100
When Essbase reads the record, it ignores the ALIAS0 field and promotes the LEVEL1 field
(100-10) to LEVEL0 and the LEVEL2 field (100) to LEVEL1, as if the data source looked
like the following example:
LEVEL0,Products
100-10
l
ALIAS0,Products
Cola
LEVEL1,Products
100
LEVEL2,Products
Missing secondary field: If a null occurs where Essbase expects a secondary field, Essbase
ignores the secondary null field and continues loading.
In the following example, there is no field in the ALIAS0, Products column:
LEVEL0,Products
100-10a
ALIAS0,Products
100-10
LEVEL1,Products
100
LEVEL2,Products
When Essbase reads the record, it ignores the ALIAS0 field and loads the other fields.
324
Members in a database exist in a parent-child relationship. Figure 71 shows part of the Product
dimension with its parent and children relationships identified. Product is the parent of 100.
100 is the child of Product and the parent of 100-10, 100-10-12, and 100-10-16. 100-10,
100-10-12, and 100-10-16 are the children of 100.
Figure 71
A parent-child data source must contain at least two columns: a parent column and a child
column, in that order. The data source can include columns with other information (for
example, the alias, the attributes, or the properties of the new member). A record within a parentchild data source cannot specify multiple parents or multiple children, and cannot reverse the
order of the parent and child columns.
In a parent-child build, the rules file specifies which column is the parent and which column is
the child. For example, the top half of Figure 72 shows a data source (PARCHIL.TXT), in which
each record specifies the name of a parent and the name of its child, in that order. The bottom
half of the figure shows the rules file (PARCHIL.RUL) that specifies which column is the parent
and which column is the child. Additionally, this example associates aliases with the child field.
Figure 72
Figure 73 shows the tree that Essbase builds from this data source and rules file.
Figure 73
Note: For duplicate member situations, the parent field must contain the qualified member
name. See Building Qualified Member Names Through the Rules File on page 348.
325
Field
Value
Field 1 (Product)
See
Setting Field Type Information on page
285
Fields 2 through 6
Product dimension
326
Figure 74
Rules File Fields Set to Add Members as Siblings with String Matches
Figure 75 shows the tree that Essbase builds from this data source and rules file. 100-11 is added
as a sibling of 100 and 200-22 is added as a sibling of 200.
Figure 75
Rules File Fields Set to Add Members as Siblings of the Lowest Level
To add the example members dynamically to the database, set the values shown in Table 45 in
the rules file:
327
Table 45
Field
Value
Field 3 (Measures)
See
Setting Field Type Information on
page 285
Fields 1, 2, 4, 5, and 6
Measures dimension
Figure 77 shows the tree that Essbase builds from this data source and rules file. A10020 and
A10099 are added as siblings of Margin.
Figure 77
To add the example members to the database under the NewProducts member, set the values
shown in Table 46 in the rules file:
328
Table 46
Field
Value
Field 1 (Product)
See
Setting Field Type Information on page 285
Fields 2 through 6
Product dimension
Figure 79 shows the tree that Essbase builds from this data source and rules file. 600-54 and
780-22 are added as siblings of NewProducts.
Figure 79
If the base dimension does not exist, you must build it.
You must associate members of the base dimension with members of the attribute
dimension.
You can use any of the following approaches to perform these operations:
l
Build the base and attribute dimensions and perform the associations all simultaneously.
Doing so, you use a single rules file to build the base dimension and one or more attribute
dimensions to associate each attribute with the appropriate member of the base dimension.
329
Because this approach uses a single rules file, it can be the most convenient. Use this approach
if the base dimension does not exist and each source data record contains all attribute
information for each member of the base dimension.
l
Build the attribute dimension and perform the associations in one rules file. Assuming that
the base dimension is built in a separate step or that the base dimension already exists, you
can build an attribute dimension and associate the attributes with the members of the base
dimension in one step. You need only to define the attribute associations in the rules file.
See Associating Attributes on page 330.
Build the attribute dimension and then perform the associations using separate rules files.
Assuming that the base dimension is built in a separate step or that the base dimension
already exists, you can build an attribute dimension and associate the attributes with the
members of the base dimension in separate steps. Build the attribute dimension, and then
associate the attribute members with members of the base dimension. Use this approach
when you build numeric attribute dimensions that are multilevel or that have members that
represent different-sized ranges.
Essbase does not support concurrent attribute association with the Add as build methods.
When you define the rules file for building attribute dimensions, specify the base dimension and
the name of the attribute dimension file.
Associating Attributes
Whether you build the attribute dimension and associate the attribute members with the
members of the base dimension in one step or in separate steps, define the fields as described in
this section.
Note: If you are working with a multilevel attribute dimension or with an attribute dimension
of the type numeric, Boolean, or date, the rules file requires an additional field. See
Working with Multilevel Attribute Dimensions on page 332.
330
Every record of the source data must include at least two columns: one for the member of the
base dimension and one for the attribute value of the base dimension member. In the same
source data record you can include additional columns for other attributes that you want to
associate with the member of the base dimension. You must position the field for the member
of the base dimension before any of the fields for the members of the attribute dimension.
Define the field type for the attribute dimension member as the name of the attribute dimension,
use the generation or level number of the associated member of the base dimension, and specify
the base dimension name. For example, as shown in the ATTRPROD.RUL file in Figure 80, the
field definition Ounces3,Product specifies that the field contains members of the Ounces
attribute dimension. Each member of this field is associated with the data field that is defined
as the generation 3 member of the base dimension Product. Based on this field definition, Essbase
associates the attribute 64 with the 500-10 member.
Figure 80
You can have Essbase use the attribute columns to build the members of the attribute
dimensions. In Data Prep Editor, in the Dimension Build Settings tab of the Dimension Build
Settings dialog box, clear the Do not create members option for the base dimension. See Setting
Member Properties in the Oracle Essbase Administration Services Online Help.
When you are working with numeric ranges, you may need to build attribute dimensions and
perform associations in separate steps. See Working with Numeric Ranges on page 334.
The Caffeinated3,Product field in Figure 80 shows how to associate attributes from additional
single-level attribute dimensions. Because the base dimension is already specified, you need only
to define an additional field for each attribute that you want to associate with the member of
the base dimension.
The file in Figure 80 associates attributes as shown in the outline in Figure 81. Member 64 is a
new member of the Ounces attribute dimension. Members 500, 500-10, and 500-20 are new
members of the base dimension, Product, and are associated with member 64.
Figure 81
Associating Attributes
331
contain the qualified member name. See Building Qualified Member Names Through
the Rules File on page 348.
In the Dimension Build Properties tab of the Field Properties dialog box, select Delete when
the field is empty for the attribute field. (This option is ignored if Allow association
changes is not selected.)
Leave the field empty or NULL in the data source.
332
Place the copied attribute dimension field or fields that define the association immediately
to the right of the field for the members of the base dimension.
For a multilevel attribute dimension, place the attribute parent field immediately to the left
of the field that is the child of the attribute parent.
The following steps describe how to define the fields in the rules file to build a multilevel attribute
dimension and associate its members with members of its base dimension. This example uses
the level references build method.
1. In the rules file, in field 1 and field 2, define the attribute dimension fields in the same way
in which you define standard dimensions; specify type (level or generation), number, and
dimension name.
Essbase uses field1 and field2 to build the attribute dimension.
2. Define the fields for building the base dimension.
In the following example, you are defining the level 0 and level 1 fields for the Product
dimension. Figure 82 shows the fields of the rules file at this stage.
Figure 82
3. To define the association, make a copy of the field that contains the level 0 attribute.
In the current example, make a copy of field 1.
a. Use the attribute dimension name as the field type and specify the generation or level
number of the member of the base dimension with which Essbase associates the
attribute; for example, Size0.
b. Specify the base dimension; for example, Product.
c. Move the new field immediately to the right of the field for the base dimension with
which Essbase associates the attribute.
In the current example, move the new field to the right of the field Level0, Product.
4. Make a copy of the field containing the parent of the attribute field.
In the current example, make a copy of field 2.
a. Set the field type of the new field as Attribute Parent and specify the generation or level
number of the base member with which you want Essbase to associate the attribute; for
example, ATTRPARENT0.
b. Specify the attribute dimension; for example, Size.
c. Move the ATTRPARENT field immediately to the left of the attribute association field
that you created in step 3.
As shown in Figure 83, the rules file now contains the field definitions to build the attribute
dimension Size and to associate the members of Size with the appropriate members of the base
dimension Product.
333
Figure 83
Source Data and Rules File for Building a Multilevel Attribute Dimension
When you run a dimension build with the data shown in Figure 83, Essbase builds the Size
attribute dimension and associates its members with the appropriate members of the base
dimension. Figure 84 shows the updated outline.
Figure 84
Figure 85
You must use one rules file to build the Population dimension and another rules file to associate
the Population dimension members as attributes of members of the base dimension.
The name of the attribute dimension and its associated base dimension.
The source data must be in attribute sequence, in ascending order. If ranges have different sizes,
the source data must include a record for every attribute range.
Note: In later builds, you cannot insert attribute members between existing members.
To use the generation method to build the outline in Figure 85, you must sequence the source
data in ascending sequence, based on the numeric attribute value. Define the fields in a rules file
as shown in Figure 86. Additionally, Figure 86 shows how to associate aliases with attributes.
Figure 86
335
When you define the association field (for example, Population3, Market), place the attribute
members within a range. In Data Prep Editor, on the Dimension Build Properties tab of the Field
Properties dialog box, select Place attribute members within a numeric range.
Note: Figure 87 includes a city, Boston, whose population of 3,227,707 is outside the ranges of
the attribute dimension in Figure 85 on page 335, where the ranges extend only to
3,000,000. To allow for values in the source data that are outside the ranges in the attribute
dimension, enter a range size, such as 1000000. Essbase uses the range size to add members
to the attribute dimension above the existing highest member or below the existing lowest
member, as needed.
Caution!
336
After you associate members of the base dimension with members of the attribute
dimension, if you manually insert new members into the attribute dimension or
rename members of the attribute dimension, you may invalidate existing attribute
associations. Consider an example where numeric range attributes are defined as
Tops of ranges and an attribute dimension contains members 100, 200, 500, and
1000. A base dimension member with the value 556 is associated with the attribute
1000. If you rename a attribute dimension member from 500 to 600, the base
dimension member with the value 556 now has an invalid association. This base
member is still associated with the attribute 1000 when it should be associated with
the attribute 600. If you manually insert new members or rename existing members,
to ensure that associations are correct, rerun the dimension build procedure and
associate the base members with the changed attribute dimensions. For example,
rerunning the attribute association procedure correctly associates the member of the
base dimension with the value 556 with the new attribute 600.
Adding or Changing Members of the Attribute Dimension: After you associate members
of a base dimension with their numeric attribute ranges, if you manually insert new members
or rename existing members in the attribute dimension, ensure that associations between
attributes and base members are correct by performing one of the following tasks:
m
Rerun the dimension build procedure that associates the base members with the changed
attribute dimension.
Use Outline Editor to manually review and fix, as needed, the associations of all base
dimensions.
Deleting Members from the Attribute Dimension: You can delete all members of an
attribute dimension so that you can rebuild the dimension with new data. In Data Prep
Editor, on the Dimension Building Properties tab on the Field Properties dialog box, click
the Ranges button and select Delete all members of this attribute dimension. Essbase uses the
start value and range size value to rebuild the attribute dimension. To ensure proper attribute
association, on the Dimension Build Settings tab of the Dimension Build Settings dialog
box, you must select the Allow association changes option for the base dimension.
Adding Members to the Base Dimension: You can use the same rules file to add new
members to the base dimension and to associate the new members with their numeric range
attributes simultaneously. Provide a value for the range size. In Data Prep Editor, on the
Dimension Build Properties tab in the Field Properties dialog box, click the Ranges button
and specify the range size for the attribute dimension.
If Essbase encounters a base dimension value that is greater than the highest attribute
member by more than the range size or is lower than the lowest attribute member by more
than the range size, it creates members in the attribute dimension to accommodate the outof-range values.
For example, in Figure 88, the numeric range attributes are defined as Tops of ranges. The
highest value member of the Population attribute dimension is 3000000. If the source data
includes a record with the population 4,420,000, and the range size is 1000000, Essbase adds
two members to the attribute dimension, 4000000 and 5000000, and associates the base
member with the value of 4,420,000 with the 5000000 attribute.
Figure 88
337
When you add range members and base dimension members simultaneously, Essbase does not
create aliases for the new members of the attribute dimension. If you want aliases that describe
the range values for the new members of the attribute dimension, you must add the aliases in a
separate operation.
Before running a dimension build, you must define the attribute member name formats for
the outline.
See Setting Member Names in Attribute Dimensions on page 173.
Defining new attribute dimensions in a rules file is different from defining new standard
dimensions in a rules file.
For single-level attribute dimensions, define the field that contains the attribute values as
the field to be associated with the members of the base dimension. A dimension build uses
the defined field to add new members to the attribute dimension.
See Associating Attributes on page 330.
For multilevel attribute dimensions, Essbase requires fields that define each generation or
level in the attribute dimension and fields that define the associations. Use the new field
type, Attribute Parent, to identify fields that are parent members for the attribute members
being associated.
See Working with Multilevel Attribute Dimensions on page 332.
338
In Data Prep Editor, in the Dimension Build Settings tab of the Dimension Build Settings
dialog box, select the Allow association changes option for the attribute dimension.
See Setting Member Properties in the Oracle Essbase Administration Services Online Help.
l
Enabling automatic association of base members with attributes that represent ranges of
values
In Data Prep Editor, on the Dimension Building Properties tab of the Field Properties dialog
box, click the Ranges button and define the size of the range.
See Setting Field Type Information on page 285.
Note: Because attributes are defined only in the outline, the data load process does not affect
them.
You can share members among as many parents as you want. Diet Cola has two parents (100
and Diet), but you can define it to roll up into more parents.
You can share members at multiple generations in the outline. In Figure 89, Diet Cola is shared
by two members at generation 2 in the outline, but it can be shared by a member at generation
3 and a member at generation 4, as shown in Figure 94 on page 342.
Creating shared members at different generations in the outline is easy in Outline Editor; creating
shared members using dimension build is more difficult. You must pick the build method and
format the data source carefully.
339
The following sections describe how to build shared members in the outline by using a data
source and a rules file.
l
Note: You should not create an outline in which a shared member is located before the actual
member with which it is associated. If you do this, you will encounter an error while
validating the outline. However, during a dimension build, you can select an option in
the Dimension Build SettingsDimension Build Settings Tab to have Essbase fix the error
by making the top-most shared member the primary member and the former primary
member a shared member. See the Oracle Essbase Administration Services Online Help.
Sharing members at the same generation is the simplest way to share members, and can be
accomplished using generation, level, or parent-child references. See:
l
Using Generation References to Create Same Generation Shared Members on page 341
Using Level References to Create Same Generation Shared Members on page 341
Sample data source and rules files are provided for each build method. The result for each build
method is shown in Figure 90.
340
Sample Rules File: Members Shared at the Same Generation Using Generation References
Sample Rules File: Members Shared at the Same Generation Using Level References
341
Sample Rules File: Members Shared at the Same Generation Using Parent-Child References
342
Using Level References to Create Different Generation Shared Members on page 343
Using Parent-Child References to Create Different Generation Shared Members on page
343
Sample data source and rules files are provided for each build method. The result for each build
method is shown in Figure 94.
Sample Rules File: Members Shared at Different Generations Using Level References
Sample Rules File: Members Shared at Different Generations Using Parent-Child References
343
Sharing non-level 0 members can be accomplished using level or parent-child references. See:
l
Sample data source and rules files are provided for each build method. The result for each build
method is shown in Figure 97.
344
Figure 98
Sample Rules File: Non-Level 0 Members Shared at Different Generations Using Level References
Sample Rules File: Non-Level 0 Members Shared at the Same Generation Using Parent-Child References
345
Figure 100
Sample Rules File: Multiple Roll-Ups at Different Levels Using Level References
Because the record is so long, this second graphic shows the rules file scrolled to the right to
show the extra members:
Figure 101
(Continuation) Sample Rules File: Multiple Roll-Ups at Different Levels Using Level References
When you run the dimension build using the data in Figure 101, Essbase builds the outline
shown in Figure 102:
Figure 102
This example enables analysis not only by package type (Cans), but also by packaging material
(comparing sales of aluminum cans and steel cans).
Because Product is a sparse dimension, you can use an alternative outline design to enable
retrieval of the same information. For example, consider creating a multilevel attribute
dimension for package type with Steel and Aluminum as level 0 members under Can. For outline
design guidelines, see Analyzing Database Design on page 85.
"Soft Drinks"
"Soft Drinks"
Cola
"Root Beer"
Cola
"Root Beer"
TBC
Grandmas
Then load the second data source below to relate the products to the vendors using the parentchild build method. Ensure that Essbase is set up to allow sharing.
Vendor
Vendor
TBC
Grandmas
347
Parent-child dimension builds: The parent-child build method requires two fields, one for
parent and one for child. For duplicate member situations the parent field must contain the
qualified member name. Parent-child dimension builds on duplicate member outlines do
not support attribute association. To ensure that attributes are associated with the correct
members, perform the associations in a separate pass, using a generation-reference or levelreference rules file.
Association of attributes to existing members in the outline: For duplicate member
situations, the field to which the attribute is associated must contain the qualified member
name.
"Kansas City"
"Kansas City"
"New York"
Kansas
Missouri
"New York"
706010
1070052
8104079
Editing this source through the rules file to build qualified names and sequence the field columns
properly involves the following edits:
l
348
Using Create using text operations, create one field each for the following text elements:
m
].[
].[
2
Central
3
].[
4
Kansas
5
].[
6
Kansas City
7
]
8
706010
Using Join operations, join together fields 1 2 3 4 5 6 7 to create the single field to which the
attributes are to be associated: [Central].[Kansas].[Kansas City]. The rules file now shows
two fields:
1
2
[Central].[Kansas].[Kansas City] 706010
349
350
Part IV
Calculating Data
In Calculating Data:
l
l
l
l
l
l
l
l
l
l
l
l
351
352
22
In This Chapter
About Database Calculation ............................................................................ 353
About Multidimensional Calculation Concepts........................................................ 355
Setting the Default Calculation ......................................................................... 358
Calculating Databases................................................................................... 358
Canceling Calculations .................................................................................. 359
Parallel and Serial Calculation.......................................................................... 359
Security Considerations ................................................................................. 359
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
For example:
l
You enter regional sales figures for a variety of products. You calculate the total sales for
each.
You enter the budget and actual values for the cost of goods sold for several products in
several regions. You calculate the variance between budget and actual values for each product
in each region.
The database contains regional sales figures and prices for all products. You calculate what
happens to total profit if you increase the price of one product in one region by 5%.
Small differences in the precision of cell values may occur between calculations run on different
platforms, due to operating system math library differences.
353
Note: Most computers represent numbers in binary, and therefore can only approximately
represent real numbers. Because binary computers cannot hold an infinite number of bits
after a decimal point, numeric fractions such as one-third (0.3333...) cannot be expressed
as a decimal with a terminating point. Fractions with a denominator of the power of two
(for example, 0.50) or ten (0.10) are the only real numbers that can be represented exactly.
See IEEE Standard 754 for Floating-Point Representation (IEEE, 1985).
Essbase offers two methods for calculating a database:
l
Outline calculation
The method that you choose depends on the type of calculation that you want to perform.
Outline Calculation
Outline calculation is the simplest calculation method. Essbase bases the calculation of the
database on the relationships between members in the database outline and on any formulas
that are associated with members in the outline.
For example, Figure 105 shows the relationships between the members of the Market dimension
in the Sample.Basic database. The values for New York, Massachusetts, Florida, Connecticut,
and New Hampshire are added to calculate the value for East. The values for East, West, South,
and Central are added to calculate the total value for Market.
Figure 105
Figure 106 shows the Scenario dimension from the Sample.Basic database. The Variance and
Variance % members are calculated by using the formulas attached to them.
Figure 106
It may be more efficient to calculate some member combinations when you retrieve the data
instead of calculating the member combinations during the regular database calculation. You
354
can use dynamic calculations to calculate data at retrieval time. See Chapter 27, Dynamically
Calculating Data Values.
See Chapter 29, Developing Calculation Scripts for Block Storage Databases.
The Time dimension has four quarters. The example displays only the members in Qtr1Jan,
Feb, and Mar.
The Scenario dimension has two child membersBudget for budget values and Actual for actual
values.
355
An intersection of members (one member on each dimension) represents a data value; a data
value is stored in one cell in the database. To refer to a specific data value in a multidimensional
database, you must specify each member on each dimension. In Essbase, member combinations
are denoted by a cross-dimensional operator (->). Create the cross-dimensional operator using
a hyphen (-) and a greater-than symbol (>). Do not include a space between the crossdimensional operator and members.
The single cell containing the data value for Sales, Jan, Actual, as shown in Figure 109, is written
as Sales -> Jan -> Actual.
Figure 109
When you refer to Sales, you are referring to a slice of the database containing eight values, as
shown in Figure 110, which are:
l
356
Figure 110
When you refer to Actual Sales, you are referring to four values, as shown in Figure 111, which
are:
l
Figure 111
When Essbase calculates the formula Margin% = Margin % Sales, it takes each Margin value
and calculates it as a percentage of its corresponding Sales value.
Essbase cycles through the database and calculates Margin% as follows:
1. Margin -> Jan -> Actual as a percentage of Sales -> Jan -> Actual.
The result is placed in Margin% -> Jan -> Actual.
2. Margin -> Feb -> Actual as a percentage of Sales -> Feb -> Actual.
The result is placed in Margin% -> Feb -> Actual.
3. Margin -> Mar -> Actual as a percentage of Sales -> Mar -> Actual.
The result is placed in Margin% -> Mar -> Actual.
4. Margin -> Qtr1 -> Actual as a percentage of Sales -> Qtr1 -> Actual.
The result is placed in Margin% -> Qtr1 -> Actual.
5. Margin -> Jan -> Budget as a percentage of Sales -> Jan -> Budget.
The result is placed in Margin% -> Jan -> Budget.
357
6. Essbase continues cycling through the database until it has calculated Margin% for every
combination of members in the database.
See Chapter 25, Defining Calculation Order.
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDEFAULTCALCFILE
Calculating Databases
If you have Calculation permissions, you can calculate a database.
When you use Administration Services to calculate a database, you can execute the calculation
in the background so that you can continue working as the calculation processes. You can then
check the status of the background process to see when the calculation is complete.
Topic
Location
Administration Services
MaxL
execute calculation
ESSCMD
Smart View
Calculating a Database
358
Canceling Calculations
To stop a calculation before Essbase completes it, click the Cancel button while the calculation
is running.
When you cancel a calculation, Essbase performs one of the following operations:
l
How Essbase handles the cancellation depends on the Essbase Kernel Isolation Level settings.
See Understanding Isolation Levels on page 777.
Serial calculation (default): All steps in a calculation run on a single thread. Each task is
completed before the next is started.
Parallel calculation: The Essbase calculator can analyze a calculation, and, if appropriate,
assign tasks to multiple CPUs (up to four).
Security Considerations
To calculate a database, you must have Calculate permissions for the database outline. With
calculate permissions, you can calculate any value in the database, and you can calculate a value
even if a security filter denies you read and update permissions. Carefully consider providing
users with calculate permissions.
See Chapter 39, User Management and Security in EPM System Security Mode.
359
360
23
In This Chapter
Using Formulas and Formula Calculations ............................................................ 361
Process for Creating Formulas .......................................................................... 362
Understanding Formula Syntax ......................................................................... 363
Using Functions in Formulas ............................................................................ 367
Using Substitution and Environment Variables in Formulas ......................................... 384
Using Formulas on Partitions ........................................................................... 385
Displaying Formulas ..................................................................................... 386
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
All of the examples in this chapter are based on the Sample.Basic database.
For more information about the functions referenced in this chapter, see the Oracle Essbase
Technical Reference.
Apply formulas to members in the database outline. Use this method if you do not need to
control database calculations carefully for accuracy or performance. This method limits
formula size to less than 64 KB.
See Using Functions in Formulas on page 367.
Place formulas in a calculation script. Use this method if you need to control database
calculations carefully.
361
For formulas applied to members in a database outline, Essbase calculates formulas when you
perform the following actions:
l
For a formula in a calculation script, Essbase calculates the formula when it occurs in the
calculation script.
If a formula is associated with a dynamically calculated member, Essbase calculates the formula
when the user requests the data values. In a calculation script, you cannot calculate a dynamically
calculated member or make a dynamically calculated member the target of a formula calculation.
See Chapter 27, Dynamically Calculating Data Values.
Using dynamically calculated members in a formula on a database outline or in a calculation
script can significantly affect calculation performance. Performance is affected because Essbase
interrupts the regular calculation to perform the dynamic calculation.
You cannot use substitution variables in formulas that you apply to the database outline. See
Using Substitution Variables in Formulas on page 385.
To create a formula:
1
See Creating and Editing Formulas in Outlines in the Oracle Essbase Administration
Services Online Help.
362
See Using Functions in Formulas on page 367 and Creating and Editing Formulas in
Outlines in the Oracle Essbase Administration Services Online Help.
See Creating and Editing Formulas in Outlines in the Oracle Essbase Administration
Services Online Help.
See Saving Outlines in the Oracle Essbase Administration Services Online Help.
End each statement in the formula with a semicolon (;). For example:
Margin % Sales;
Use only saved outline member names. If a substitution variable is used for a member name,
the substitution variable value must be a saved outline member name.
Enclose a member name in double quotation marks () if the member name meets any of
the following conditions:
m
Includes any nonalphanumeric character. For example, hyphens (-), asterisks (*), and
slashes (/).
Is all numeric or starts with one or more numerals. For example, "100" or "10Prod"
For a full list of member names that must be enclosed in quotation marks, see Naming
Conventions in Calculation Scripts, Report Scripts, Formulas, Filters, and Substitution and
Environment Variable Values on page 1098.
l
363
If you are using an IF statement nested within another IF statement, end each IF with an
ENDIF. For example:
"Opening Inventory"
(IF (@ISMBR(Budget))
IF (@ISMBR(Jan))
"Opening Inventory" = Jan;
ELSE
"Opening Inventory" = @PRIOR("Ending Inventory");
ENDIF;
ENDIF;)
You do not need to end ELSE or ELSEIF statements with ENDIFs. For example:
IF (@ISMBR(@DESCENDANTS(West)) OR @ISMBR(@DESCENDANTS(East)
Marketing = Marketing * 1.5;
ELSEIF(@ISMBR(@DESCENDANTS(South)))
Marketing = Marketing * .9;
ELSE Marketing = Marketing * 1.1;
ENDIF;
Note: If you use ELSE IF (with a space) rather than ELSEIF (one word) in a formula, you
When writing formulas, you can check the syntax using the Formula Editor syntax checker. See
Checking Formula Syntax on page 367.
See:
l
Operators
Table 47 lists the types of operators you can use in formulas:
Table 47
Operator Type
Description
Mathematical
364
Operator Type
Description
Conditional
Control the flow of formula executions based on the results of conditional tests.
For example, you can use an IF statement to test for a specified condition.
See Conditional Tests on page 369.
Cross-dimensional
For information about using operators with #MISSING, zero, and other values, see the Essbase
Functions section in the Oracle Essbase Technical Reference.
Scenario
100-10
Feb
Constant Values
You can assign a constant value to a member. For example:
California = 120;
In this formula, California is a member in a sparse dimension and 120 is a constant value. Essbase
automatically creates all possible data blocks for California and assigns the value 120 to all data
cells. Many thousands of data blocks may be created.
To assign constants in a sparse dimension to only those intersections that require a value, use a
FIX statement. See Constant Values Assigned to Members in a Sparse Dimension on page
869.
Nonconstant Values
If you assign anything other than a constant to a member in a sparse dimension, and no data
block exists for that member, new blocks may not be created unless Essbase is enabled to create
blocks on equations. By default, Create Blocks on Equations is disabled.
For example, to create blocks for West that did not exist before running the calculation, you
must enable Create Blocks on Equations for this formula:
West = California + 120;
365
Note: If Create Blocks on Equations is disabled for a database and data blocks exist for members
on either the left- or right-side of the equation, the formula produces results.
You can enable Create Blocks on Equations at the database level, whereby blocks are always
created, or you can control block creation within calculation scripts using the SET
CREATEBLOCKONEQ ON | OFF calculation command.
To enable the Create Blocks on Equations feature for all calculation scripts for a specific
database, use a tool:
Tool
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATE
Because unnecessary blocks can be created when Create Blocks on Equations is enabled at the
application or database level, calculation performance can be affected. To control block creation
within a calculation script, use the SET CREATEBLOCKONEQ ON | OFF calculation command.
See Nonconstant Values Assigned to Members in a Sparse Dimension on page 869.
Basic Equations
You can apply a mathematical operation to a formula to create a basic equation. The equation
can be in the database outline or in a calculation script.
The syntax for an equation:
member = mathematical_operation;
member is a member name from the database outline and mathematical_operation is any
The following example shows how to use an equation in the database outline and in a calculation
script. In the outline, apply the following formula to a Markup member:
(Retail - Cost) % Retail;
Essbase cycles through the database, subtracting the values in Cost from the values in Retail,
calculating the resulting values as a percentage of the values in Retail, and placing the result in
Markup.
366
If a formula passes validation in Formula Editor or Outline Editor, but Essbase Server detects
semantic errors when the outline is saved, check the following:
l
The incorrect formula is saved as part of the outline, even though it contains errors.
Essbase Server writes a message in the application log that indicates what the error is and
displays the incorrect formula.
Essbase Server writes an error message to the comment field of the member associated with
the incorrect formula. The message indicates that the incorrect formula was not loaded. You
can view this comment in Outline Editor by closing and reopening the outline.
If you do not correct the member formula, and a calculation that includes that member is
run, the formula is ignored during the calculation.
After you have corrected the formula and saved the outline, the message in the member comment
is deleted. You can view the updated comment when you reopen the outline.
367
Table 48
Function Type
Description
Boolean
Mathematical
Relationship
Range
Financial
Specifying member
lists and ranges
Generating member
lists
Character string
manipulation
Member
combinations across
dimensions
Point to data values of specific member combinations by using the cross-dimensional operator (->).
Interdependent
values
For formulas that require values from members of the same dimension, but for which the required values have not
yet been calculated.
368
Function Type
Description
Variances and
variance
percentages
Allocation
Allocate values that are input at a parent level across child members. You can allocate values within the same
dimension or across multiple dimensions.
See Calculating Variances or Percentage Variances Between Actual and Budget Values on page 381.
For example, you can use the @ALLOCATE function to allocate sales values that are input at a parent level to the
children of the parent; the allocation of each child is determined by its share of the sales of the previous year.
See Allocating Values on page 382.
Forecasting
Manipulate data for the purposes of smoothing or interpolating data, or calculating future values.
For example, you can use the @TREND function to calculate future values that are based on curve-fitting to historical
values.
See Forecasting Functions on page 383.
Statistical
Calculate advanced statistics. For example, you can use the @RANK function to calculate the rank of a specified
member or a specified value in a data set.
See Statistical Functions on page 383.
Calculation mode
Specify calculation modes that Essbase is to use to calculate a formulacell, block, bottom-up, and top-down.
See Calculation Mode Function on page 384.
Custom-defined
This type enables you to perform functions that you develop for calculation operations. These custom-developed
functions are written in the Java programming language and are called by the Essbase calculator framework as
external functions.
See Custom-Defined Functions on page 384.
Note: Abbreviations of functions are not supported. Some commands may work in an
abbreviated form, but if another function has a similar name, Essbase may use the wrong
function. Use the complete function name to ensure correct results.
Conditional Tests
You can define formulas that use a conditional test or a series of conditional tests to control the
flow of calculation.
The IF and ENDIF commands define a conditional block. The formulas between the IF and the
ENDIF commands are executed only if the test returns TRUE (1). If the test returns FALSE (0),
you can use the ELSE and ELSEIF commands to specify alternative actions. The formulas
following each ELSE command are executed only if the previous test returns FALSE (0).
Conditions following each ELSEIF command are tested only if the previous IF command returns
FALSE (0). See Understanding Formula Syntax on page 363.
369
When you use a conditional formula in a calculation script, enclose it in parentheses and associate
it with a member in the database outline, as shown in the examples in this section.
In conjunction with an IF command, you can use functions that return TRUE or FALSE (1 or
0, respectively) based on the result of a conditional test. These functions are known as Boolean
functions.
Use Boolean functions to determine which formula to use. The decision is based on the
characteristics of the current member combination. For example, to restrict a certain calculation
to the members in the Product dimension that contain input data, preface the calculation with
an IF test based on @ISLEV(Product,0).
If one of the function parameters is a cross-dimensional member, such as @ISMBR(Sales > Budget), all of the parts of the cross-dimensional member must match the properties of the
current cell to return a value of TRUE (1).
Table 49 lists Boolean functions that specify conditions:
Table 49
Function
Condition
@ISACCTYPE
Current member has a specified accounts tag (for example, an Expense tag)
@ISANCEST
@ISIANCEST
Current member is an ancestor of the specified member, or the specified member itself
@ISCHILD
@ISICHILD
Current member is a child of the specified member, or the specified member itself
@ISDESC
@ISIDESC
Current member is a descendant of the specified member, or the specified member itself
@ISGEN
@ISLEV
@ISMBR
@ISPARENT
@ISIPARENT
Current member is the parent of the specified member, or the specified member itself
@ISSAMEGEN
Current member (of the same dimension as the specified member) is in the same generation as the specified member
@ISSAMELEV
Current member (of the same dimension as the specified member) is in the same level as the specified member
@ISSIBLING
@ISISIBLING
Current member is a sibling of the specified member, or the specified member itself
@ISUDA
A specified UDA exists for the current member of the specified dimension
370
When you place formulas on the database outline, you can use only the IF, ELSE, ELSEIF, and
ENDIF commands and Boolean functions to control the flow of the calculations. You can use
additional control commands in a calculation script.
For information about how to develop calculation scripts and how to use them to control how
Essbase calculates a database, see Chapter 29, Developing Calculation Scripts for Block Storage
Databases. For information on individual Essbase functions and calculation commands, see
the Oracle Essbase Technical Reference.
If you place the formula in a calculation script, you must associate the formula with the
Commission member as shown:
Commission (IF(Sales > 500000)
Commission = Sales * .01;
ENDIF;)
If you place the formula in a calculation script, you must associate the formula with the Payroll
member as shown:
Payroll(IF(@ISIDESC(East) OR @ISIDESC(West))
Payroll = Sales * .15;
ELSEIF(@ISIDESC(Central))
Payroll = Sales * .11;
ELSE
Payroll = Sales * .10;
ENDIF;)
371
Mathematical Operations
Table 50 lists mathematical functions, which allow you to perform many mathematical
operations in formulas:
Table 50
Function
Operation
@ABS
@AVG
Return the average value of the values in the specified member list
@EXP
Return the value of e (the base of natural logarithms) raised to power of the specified expression
@FACTORIAL
@INT
@LN
@LOG
@LOG10
@MAX
Return the maximum value among the expressions in the specified member list
@MAXS
Return the maximum value among the expressions in the specified member list, with the ability to skip zero and #MISSING
values
@MIN
Return the minimum value among the expressions in the specified member list
@MINS
Return the minimum value among the expressions in the specified member list, with the ability to skip zero and #MISSING
values
@MOD
372
Function
Operation
@POWER
Return the value of the specified member raised to the specified power
@REMAINDER
@ROUND
Return the member or expression rounded to the specified number of decimal places
@SUM
@TRUNCATE
@VAR
@VARPER
Function
Look-up Value
@ANCESTVAL
@ATTRIBUTEVAL
Numeric value of the attribute from the specified numeric or date attribute dimension associated with the current
member
@ATTRIBUTESVAL
Text value of the attribute from the specified text attribute dimension associated with the current member
@ATTRIBUTEBVAL
Value (TRUE or FALSE) of the attribute from the specified Boolean attribute dimension associated with the current
member
@CURGEN
Generation number of the current member combination for the specified dimension
@CURLEV
Level number of the current member combination for the specified dimension
@GEN
@LEV
@MDANCESTVAL
@SANCESTVAL
@PARENTVAL
@MDPARENTVAL
@SPARENTVAL
373
Function
Look-up Value
@XREF
Data value from another database to be used for calculation of a value from the current database
@XWRITE
For information about specific Essbase functions, see the Oracle Essbase Technical Reference.
Range Functions
Table 52 lists range functions, which allow you to execute a function for a range of members:
Table 52
Function
Calculation
@AVGRANGE
@CURRMBRRANGE
A range of members that is based on the relative position of the member combination Essbase is currently
calculating
@MAXRANGE
@MAXSRANGE
The maximum value of a member across a range of members, with the ability to skip zero and #MISSING
values
@MDSHIFT
The next or nth member in a range of members, retaining all other members identical to the current member
across multiple dimensions
@MINRANGE
@MINSRANGE
The minimum value of a member across a range of members, with the ability to skip zero and #MISSING
values
@NEXT
@NEXT
The next or nth member in a range of members, with the option to skip #MISSING, zero, or both values
@PRIOR
@PRIORS
The previous or nth previous member in a range of members, with the option to skip #MISSING, zero, or
both values
@SHIFT
The next or nth member in a range of members, retaining all other members identical to the current member
and in the specified dimension
Financial Functions
Table 53 on page 375 lists financial functions, which allow you to include financial calculations
in formulas:
374
Table 53
Function
Calculation
@ACCUM
@COMPOUND
@COMPOUNDGROWTH
A series of values that represent the compound growth of the specified member across a range of members
@DECLINE
Depreciation for a specific period, calculated using the declining balance method
@DISCOUNT
A value discounted by the specified rate, from the first period of the range to the period in which the amount to
discount is found
@GROWTH
A series of values that represents the linear growth of the specified value
@INTEREST
@IRR
The Internal Rate of Return on a cash flow that is calculated across the time dimension or a specified range of
members and must contain at least one investment (negative) and one income (positive). Includes an initial
guess of 0.07 (the initial guess cannot be configured).
@IRREX
The Internal Rate of Return on a cash flow that is calculated across the time dimension or a specified range of
members and must contain at least one investment (negative) and one income (positive). Includes functionality
to configure the initial guess and the number of iterations the algorithm can make.
@NPV
The Net Present Value of an investment (based on a series of payments and incomes)
@PTD
@SLN
The amount per period that an asset in the current period may be depreciated (calculated across a range of
periods).
The depreciation method used is straight-line depreciation.
@SYD
The amount per period that an asset in the current period may be depreciated (calculated across a range of
periods).
The depreciation method used is sum of the year's digits.
Note: One member formula cannot contain multiple financial functions (for example, @NPV
and @SLN, or multiple instances of @NPV). A member formula that requires multiple
financial functions must be broken into separate formulas so that each formula contains
only one financial function (for example,
MemberName(@NPV(...));Membername(@NPV(...))).
Member-Related Functions
This section discusses creating formulas that refer to members.
l
375
Syntax
One member
A list of members
The two defining member names separated by a colon (:). For example:
Jan2000:Dec2000
For example:
Q1_2000::Q4_2000
For a list of member list contents and corresponding functions, see Generating Member
Lists on page 376.
If you do not specify a list of members or a range of members in a function that requires either,
Essbase uses the level 0 members of the dimension tagged as time. If no dimension is tagged as
time, Essbase displays an error message.
376
Table 55
Function
@ALLANCESTORS
All ancestors of the specified member, including ancestors of the specified member as a shared member. This function
does not include the specified member.
@IALLANCESTORS
All ancestors of the specified member, including ancestors of the specified member as a shared member. This function
includes the specified member.
@ANCEST
@ANCESTORS
All ancestors of the specified member (optionally, up to the specified generation or level), but not the specified
member
@IANCESTORS
All ancestors of the specified member (optionally, up to the specified generation or level), including the specified
member
@LANCESTORS
All ancestors of the specified list of members (optionally, up to the specified generation or level), but not including
the specified members
@ILANCESTORS
All ancestors of the specified list of members (optionally, up to the specified generation or level), including the
specified members
@ATTRIBUTE
All base-dimension members that are associated with the specified attribute-dimension member
@WITHATTR
All base members that are associated with attributes that satisfy the specified conditions
@BETWEEN
All members whose name string value fall between, and are inclusive of, two specified string tokens
@CHILDREN
All children of the specified member, but not including the specified member
@ICHILDREN
@CURRMBR
@DESCENDANTS
All descendants of the specified member (optionally, up to the specified generation or level), but not the specified
member nor descendants of shared members
@IDESCENDANTS
All descendants of the specified member (optionally, up to the specified generation or level), including the specified
member, but not descendants of shared members
@LDESCENDANTS
All descendants of the specified list of members (optionally, down to the specified generation or level), but not
including the specified members
@ILDESCENDANTS
All descendants of the specified list of members (optionally, down to the specified generation or level), including the
specified members
@RDESCENDANTS
All descendants of the specified member (optionally, up to the specified generation or level), including descendants
of shared members, but not the specified member
@IRDESCENDANTS
All descendants of the specified member (optionally, up to the specified generation or level), including the specified
member and descendants of shared members
@EQUAL
@NOTEQUAL
@EXPAND
Expands a member search by calling a member set function for each member in a member list
377
Function
@GENMBRS
@LEVMBRS
@LIKE
@LIST
Separate lists of members to be processed by functions that require multiple list arguments
@MATCH
@MBRCOMPARE
@MBRPARENT
@MEMBER
@MERGE
@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
@REMOVE
@RELATIVE
All members of the specified generation or level that are above or below the specified member
@SHARE
A member list that identifies all shared members among the specified members
@SIBLINGS
All siblings of the specified member, but not the specified member
@ISIBLINGS
@LSIBLINGS
All siblings that precede the specified member in the database outline, but not the specified member
@RSIBLINGS
All siblings that follow the specified member in the database outline, but not the specified member
@ILSIBLINGS
All siblings that precede the specified member in the database outline, including the specified member
@IRSIBLINGS
All siblings that follow the specified member in the database outline, including the specified member
@SHIFTSIBLING
@NEXTSIBLING
@PREVSIBLING
@UDA
@XRANGE
A member list that identifies the range of members between (and inclusive of) two specified single or crossdimensional members at the same level
378
Function
@CONCATENATE
Create a character string that is the result of appending a member name or specified character string to another member
name or character string
@NAME
@SUBSTRING
Return a substring of characters from another character string or from a member name
The following example, which allocates miscellaneous expenses to each product in each market,
illustrates how to use the cross-dimensional operator. The value of Misc_Expenses for all
products in all markets is known. The formula allocates a percentage of the total Misc_Expenses
value to each Product -> Market combination. The allocation is based on the value of Sales for
each product in each market.
Misc_Expenses = Misc_Expenses -> Market -> Product *
(Sales / ( Sales -> Market -> Product));
2. Multiplies the value calculated in step 1 by the Misc_Expenses value for all markets and all
products (Misc_Expenses -> Market -> Product).
3. Allocates the result to Misc_Expenses for the current member combination.
Using the cross-dimensional operator can have significant performance implications. For
optimization guidelines, see Using Cross-Dimensional Operators on page 870.
Value-Related Functions
This section discusses formulas related to values.
Using Interdependent Values on page 380
Calculating Variances or Percentage Variances Between Actual and Budget Values on page
381
Feb
Mar
Opening Inventory
100
120
110
Sales
50
70
100
Addition
70
60
150
Ending Inventory
120
110
160
Assuming that the Opening Inventory value for January is loaded into the database, the following
calculations are required to get the results in Table 57:
1.
2.
3.
4.
5.
January Ending
February Opening
February Ending
March Opening
March Ending
=
=
=
=
=
You can calculate the required results by applying interdependent, multiple equations to one
member in the database outline.
380
The following formula, applied to the Opening Inventory member in the database outline,
calculates the correct values:
IF(NOT @ISMBR (Jan))
"Opening Inventory" = @PRIOR("Ending Inventory");
ENDIF;
"Ending Inventory" = "Opening Inventory" - Sales + Additions;
If you place the formula in a calculation script, you must associate the formula with the Opening
Inventory member as shown:
"Opening Inventory"
(IF(NOT @ISMBR (Jan))
"Opening Inventory" = @PRIOR("Ending Inventory");
ENDIF;)
"Ending Inventory" = "Opening Inventory" - Sales + Additions;
Opening Inventory. If you place the formulas for Opening Inventory and Ending
Inventory on their separate members, Essbase calculates Opening Inventory for all
months and then Ending Inventory for all months. This organization means that the value
of the Ending Inventory of the previous month is not available when Opening Inventory
is calculated.
Expense items. You want Essbase to show a positive variance if the actual values are less than
the budget values (for example, if actual costs are less than budgeted costs).
Nonexpense items. You want Essbase to show a negative variance if the actual values are less
than the budget values (for example, if actual sales are less than budgeted sales).
By default, Essbase assumes that members are nonexpense items and calculates the variance
accordingly.
381
See Creating and Editing Formulas in Outlines in the Oracle Essbase Administration
Services Online Help.
Variance Example
Allocating Values
Allocation functions allow you to allocate values that are input at the parent level across child
members in the same dimension or in different dimensions. The allocation is based on a variety
of specified criteria.
Table 58
Function
Allocated Values
@ALLOCATE
Values from a member, cross-dimensional member, or value across a member list within the same dimension.
@MDALLOCATE
For examples of calculation scripts using @ALLOCATE, see Allocating Costs Across Products
on page 491; using @MDALLOCATE, see Allocating Values Across Multiple Dimensions on
page 494.
382
Forecasting Functions
Forecasting functions allow you to manipulate data for the purposes of interpolating data or
calculating future values. Table 59 lists the functions that forecast values:
Table 59
Function
Data Manipulation
@MOVAVG
Apply a moving average to a data set and replace each term in the list with a trailing average.
This function modifies the data set for smoothing purposes.
@MOVMAX
Apply a moving maximum to a data set and replace each term in the list with a trailing maximum.
This function modifies the data set for smoothing purposes.
@MOVMED
Apply a moving median to a data set and replace each term in the list with a trailing median.
This function modifies the data set for smoothing purposes.
@MOVMIN
Apply a moving minimum to a data set and replace each term in the list with a trailing minimum.
This function modifies the data set for smoothing purposes.
@MOVSUM
Apply a moving sum to a data set and replace each term with a trailing sum.
This function modifies the data set for smoothing purposes.
@MOVSUMX
Apply a moving sum to a data set and replace each term with a trailing sum. Specify how to assign values to members
before you reach the number to sum.
This function modifies the data set for smoothing purposes.
@SPLINE
@TREND
Calculate future values and base the calculation on curve-fitting to historical values.
For information about specific Essbase functions, see the Oracle Essbase Technical Reference.
Statistical Functions
Statistical functions allow you to calculate advanced statistics in Essbase.
Table 60
Function
Calculated Value
@CORRELATION
@COUNT
@MEDIAN
@MODE
The mode, or the most frequently occurring value, in the specified data set
@RANK
The rank of the specified member or value in the specified data set
383
Function
Calculated Value
@STDEV
@STDEVP
The standard deviation, based upon the entire population, of the specified members
@STDEVRANGE
The standard deviation, crossed with a range of members, of the specified members
@VARIANCE
@VARIANCEP
The variance, based upon the entire population, of the specified data set
BLOCK or BOTTOMUP at the database, application, or server level. See the Oracle Essbase
Technical Reference.
Custom-Defined Functions
You can create custom-defined functions, to be used in formulas and calculation scripts, to
perform calculations not otherwise supported by the Essbase calculation scripting language.
Custom-developed functions must be written in the Java programming language and registered
on the Essbase Server. The Essbase calculator framework calls them as external functions.
Custom-defined functions are displayed in the functions tree in Calculation Script Editor, where
you can select them to insert into a formula.
See Chapter 33, Developing Custom-Defined Calculation Functions.
384
At the time Essbase calculates the outline, it replaces the substitution variable, as shown:
@ISMBR(Jan:Jun)
Note: Substitution variables used in formulas for new outline members do not pass verification
385
You can use formulas in partitioning, just as you use formulas on your local database. If, however,
a formula you use in one database references a value from another database, Essbase must retrieve
the data from the other database when calculating the formula; therefore, ensure that the
referenced values are up-to-date and carefully consider the performance impact on the overall
database calculation. See Writing Calculation Scripts for Partitions on page 482.
With transparent partitions, carefully consider how you use formulas on the data target. See
Transparent Partitions and Member Formulas on page 237 and Performance Considerations
for Transparent Partitions on page 235.
See Chapter 15, Designing Partitioned Applications and Chapter 16, Creating and
Maintaining Partitions.
Displaying Formulas
To display a formula, use a tool:
Tool
Topic
Location
Administration Services
ESSCMD
GETMBRCALC
MaxL
query database
386
24
Reviewing Examples of
Formulas for Block Storage
Databases
In This Chapter
Calculating Period-to-Date Values...................................................................... 387
Calculating Rolling Values............................................................................... 388
Calculating Monthly Asset Movements................................................................. 389
Testing for #MISSING Values ........................................................................... 390
Calculating an Attribute Formula ....................................................................... 390
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
Chapter 30, Reviewing Examples of Calculation Scripts for Block Storage Databases
To calculate period-to-date values for the year and for the current quarter, add two members to
the Year dimension: QTD for quarter-to-date and YTD for year-to-date. For example:
QTD (~) @PTD(Apr:May)
YTD (~) @PTD(Jan:May);
Assuming that the current month is May, add this formula to the QTD member:
@PTD(Apr:May);
387
Essbase sums the values for the range of months, as appropriate. Opening Inventory, however,
has a time balance tag, First, and Ending Inventory has a time balance tag, Last. Essbase takes
these values and treats them accordingly. See Calculating First, Last, and Average Values on
page 445.
Table 61 provides an example of the calculation results for the members in the Inventory branch
and for the Sales member:
Table 61
Measures->Time
Jan
Feb
Mar
Apr
May
QTD
YTD
Opening Inventory
100
110
120
110
140
110
100
Additions
110
120
100
160
180
340
670
Sales
100
110
110
130
190
320
640
Ending Inventory
110
120
110
140
130
130
130
Essbase calculates the average Sales values across the months in the dimension tagged as time.
The SKIPNONE parameter means that all values are included, even #MISSING values. Essbase
places the results in AVG_Sales. See Consolidating #MISSING Values on page 884.
388
Table 62 shows the results when Essbase calculates the cumulative Sales values and places the
results in YTD_Sales:
Table 62
Jan
Feb
Mar
Qtr1
Sales
100
200
300
600
AVG_Sales
100
150
200
#MISSING
YTD_Sales
100
300
600
#MISSING
The values for AVG_Sales are averages of the months-to-date. For example, AVG_Sales -> Mar
is an average of Sales for Jan, Feb, and Mar.
The values for YTD_Sales are the cumulative values up to the current month. So YTD_Sales ->
Feb is the sum of Sales -> Jan and Sales -> Feb.
For Jan, the Asset_MVNT value is calculated by subtracting the Opening_Balance value from
the Jan value.
You would add this formula on the Asset_MVNT member:
IF(@ISMBR(Jan)) Asset_MVNT = Assets - Opening_Balance;
ELSE Asset_MVNT = Assets - @PRIOR(Assets);
ENDIF;
Table 63 shows the results when Essbase calculates the difference between the values of assets in
successive months:
Table 63
Opening_Balance
Jan
Feb
Mar
Assets
1200
1400
1300
1800
200
-100
500
Asset_MVNT
1. The IF statement and @ISMBR function check whether the current member on the Year
dimension is Jan. This check is necessary because the Asset_MVNT value for Jan cannot be
calculated by subtracting the previous months value.
2. If the current member on the Year dimension is Jan, Essbase subtracts the Opening_Balance
from the Jan -> Assets value and places the result in Jan -> Asset_MVNT.
3. If the current member on the Year dimension is not Jan, the @PRIOR function obtains the
value for the previous months assets. Essbase subtracts the previous months assets from
the current months assets. It places the result in the current months Asset_MVNT value.
If you place the formula in a calculation script, you must associate it with the Commission
member as shown:
Commission(IF(Sales <> #MISSING) Commission = Sales * .1;
ELSE Commission = #MISSING;
ENDIF;);
390
Essbase cycles through the Products dimension, performing the following calculations:
1. For each base member that is associated with a member from the Ounces attribute
dimension, the @ATTRIBUTEVAL function returns the numeric attribute value (for
example, 12 for the member 12 under Ounces).
Note: The @NAME function is required to process the string Ounces before passing it to
391
392
25
In This Chapter
Data Storage in Data Blocks............................................................................ 393
Member Calculation Order .............................................................................. 395
Block Calculation Order ................................................................................. 400
Data Block Renumbering................................................................................ 402
Cell Calculation Order ................................................................................... 402
Calculation Passes....................................................................................... 408
Calculation of Shared Members ........................................................................ 410
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
393
Figure 115
Note: Sample.Basic also contains five attribute dimensions. These dimensions are sparse,
Dynamic Calc, meaning that attribute data is not stored in the database. See Chapter 10,
Working with Attributes.
Essbase creates a data block for each unique combination of members in the Product and Market
dimensions (providing that at least one data value exists for the combination). For example, it
creates one data block for the combination of 100-10, New York. This data block contains all
the Year, Measures, and Scenario values for 100-10, New York. Figure 116 shows an outline of
the Product and Market dimensions in the Sample.Basic database:
Figure 116
In Essbase, member combinations are denoted by the cross-dimensional operator. The symbol
for the cross-dimensional operator is -> (a hyphen followed by a greater-than symbol). So
100-10, New York is written as 100-10 -> New York.
You can categorize data blocks in the following ways:
l
Input
These blocks are created by loading data to cells in a block. Input blocks can be created for
(1) sparse, level 0 member combinations or (2) sparse, upper-level member combinations,
when at least one of the sparse members is a parent-level member. Input blocks can be level
0 or upper-level blocks.
Noninput
These blocks are created through calculations. For example, in Sample.Basic, the East ->
Cola block is created during a sparse calculation process (that is, the block did not exist
before calculation).
Level 0
These blocks are created for sparse member combinations when all of the sparse members
are level 0 members. For example, in Sample.Basic, New York -> Cola is a level 0 block
because New York and Cola are level 0 members of their respective sparse dimensions. Level
394
0 blocks can be input or noninput blocks; for example, a level 0 noninput block is created
during an allocation process, where data is loaded at a parent level and then allocated down
to level 0.
l
Upper level
These blocks are created for sparse member combinations when at least one of the sparse
members is a parent-level member. Upper-level blocks can be input or noninput blocks.
See Generations and Levels on page 63 and Data Blocks and the Index System on page 72.
If both a dimension tagged as accounts and a dimension tagged as time exist, and if formulas
are applied to members on the accounts dimension, Essbase calculates in this order:
1. Dimension tagged as accounts
2. Dimension tagged as time
3. Other dense dimensions (in the order in which they are displayed in the database
outline)
4. Other sparse dimensions (in the order in which they are displayed in the database
outline)
Note: Attribute dimensions, which are not included in the database consolidation, do not affect
395
Jan is the first member in the first branch. Jan has no formula, so it is not calculated. The same
applies to Feb and Mar, the other two members in the branch.
Essbase calculates Qtr1 by consolidating Jan, Feb, and Mar. In this example, these members are
added.
Essbase then calculates the Qtr2 through Qtr4 branches in the same way.
Finally, Essbase calculates the Year member by consolidating the values of Qtr1 through Qtr4.
These members are added.
Note: If you use dynamic calculations, Essbase may use a different calculation order. See
Use calculation operators to divide (/), multiply (*), or calculate percentages (%) for
members in the database outline.
Place formulas on members in the database outline.
You need not consider calculation order if you use only calculation operators to add (+) and
subtract () members in the database outline and you do not use formulas in the outline.
397
Figure 118
To calculate the correct result, make Child 1 the last member in the branch.
You can apply a formula to a member on the database outline to achieve the same result.
However, it is far more efficient to use these calculation operators on members as shown in
Figure 118.
In Outline Editor, when you verify the outline, Essbase identifies shared members with forward
calculation references. Verifying the outline does not identify nonshared members that have
forward calculation references. You can save and use an outline containing forward calculation
references.
398
Consider the five members under Diet. The members P100-20, P300-20, and P500-20 have
forward calculation references:
l
P100-20 (+) (Shared Member): Essbase calculates the shared member P100-20 before it
calculates the actual member P100-20. Because the actual member P100-20 has children,
Essbase must calculate the actual member by adding its children before it can accurately
calculate the shared member P100-20.
P300-20 (+) (Shared Member): Essbase calculates the shared member P300-20 before it
calculates the actual member P300-20. Because the actual member P300-20 has a formula,
Essbase must calculate the actual member before it can accurately calculate the shared
member P300-20.
P500-20 (+) (P200-20 + P300-20): The formula applied to P500-20 references members
that Essbase has not yet calculated. One referenced member, P300-20, has its own formula,
and Essbase must calculate P300-20 before it can accurately calculate P500-20. The members
P200-20 and P400-20 calculate correctly, because they do not have forward calculation
references.
P200-20 (+) (Shared Member): P200-20 is not a forward calculation reference, although
Essbase calculates the shared member P200-20 before it calculates the actual member
P200-20. The actual member P200-20 has no calculation dependencies (no children and no
formula). Therefore, Essbase does not need to calculate the actual member before the shared
member. Essbase simply takes the value of the actual member.
P400-20 (+) (P200-10 * 2): P400-20 is not a forward calculation reference, although the
formula that is applied to P400-20 references a member that Essbase has not yet calculated.
The member referenced in the formula does not itself have calculation dependencies.
P200-10 is the only member in the formula, and P200-10 does not itself have children or a
formula. Essbase accurately calculates P400-20.
To get accurate calculation results for P100-20, P300-20, and P500-20, change the order of
members in the outline. By placing the Diet shared members after the Regular members, as
shown in Figure 120, you ensure that Essbase calculates the members in the required order.
Figure 120
399
The actual member P100-20 before it calculates the shared member P100-20. So, P100-20
no longer has a forward calculation reference.
The actual member P300-20 before the shared member P300-20. So, P300-20 no longer has
a forward calculation reference.
The referenced member with a formula, P300-20, before the member P500-20. So, P500-20
no longer has a forward calculation reference.
Note: The attribute dimensions in the Sample.Basic outline (not shown in the figure above),
are not included in the database consolidation and do not affect block calculation order.
See Chapter 10, Working with Attributes..
As shown in Figure 122, Product has 19 members (excluding the shared members, for which
Essbase does not create data blocks). Therefore, the first 19 data blocks in the database are
numbered according to the calculation order of members in the Product dimension.
400
Figure 122
The other sparse dimension is Market. The first 19 data blocks contain the first member to be
calculated in the Market dimension, which is New York. Table 64 shows the sparse member
combinations of each Product member and New York, for the first five of these 19 data blocks:
Table 64
Block Number
Product Member
Market Member
Cola (100-10)
New York
New York
New York
Colas (100)
New York
New York
The next member in the Market dimension is Massachusetts. Essbase creates the next 19 data
blocks for sparse combinations of each Product member and Massachusetts. Table 65 shows the
sparse member combinations for the block numbers 19 through 23:
Table 65
Block Number
Product Member
Market Member
19
Cola (100-10)
Massachusetts
20
Massachusetts
21
Massachusetts
22
Colas (100)
Massachusetts
23
Massachusetts
401
Essbase continues until blocks have been created for all combinations of sparse dimension
members for which at least one data value exists.
Essbase creates a data block only if at least one value exists for the block. For example, if no data
values exist for Old Fashioned Root Beer (200-10) in Massachusetts, then Essbase does not create
a data block for 200-10 -> Massachusetts. However, Essbase does reserve the appropriate block
number for 200-10 -> Massachusetts in case data is loaded for that member combination in the
future.
When you run a default calculation (CALC ALL) on a database, each block is processed in order,
according to its block number. If you have Intelligent Calculation turned on, and if the block
does not need to be calculated, then Essbase skips the block and moves to the next block. For
information about how intelligent calculation is used to optimize performance, see Chapter 26,
Understanding Intelligent Calculation.
402
Essbase calculates dense dimensions in the order in which they are defined in the database
outline. Assume that the Year dimension is positioned in the database outline before the
Market dimension and is calculated first.
Table 66 shows a subset of the cells in a data block:
Table 66
Year-Market
New York
Massachusetts
East
Jan
112345
68754
Feb
135788
75643
Mar
112234
93456
Qtr1
Data values have been loaded into the following input cells:
l
Essbase calculates the following cells. In Table 66, the calculation order for these cells is
represented by the numbers 1 through 6 that appear in the cells:
1. Qtr1 -> New York
2. Qtr1 -> Massachusetts
3. Jan -> East
4. Feb -> East
5. Mar -> East
6. Qtr1 -> East
Qtr1 -> East has multiple consolidation paths; it can be consolidated on Market or on Year.
When consolidated on Market, it is a consolidation of Qtr1 -> New York and Qtr1 ->
Massachusetts. When consolidated on Year, it is a consolidation of Jan -> East, Feb -> East, and
Mar -> East.
Essbase knows that Qtr1 -> East has multiple consolidation paths. Therefore, it calculates Qtr1
-> East only once by consolidating the values for Qtr1 and uses the consolidation path of the
dimension calculated last (in this example, the Market dimension), as shown in Table 67.
403
Table 67
Year-Market
New York
Massachusetts
East
Jan
112345
68754
181099
Feb
135788
75643
211431
Mar
112234
93456
205690
Qtr1
360367
237853
598220
Based on the calculation order, if you place a member formula on Qtr1 in the database outline,
Essbase ignores it when calculating Qtr1 -> East. If you place a member formula on East in the
database outline, the formula is calculated when Essbase consolidates Qtr1 -> East on the Market
consolidation path.
If required, you can use a calculation script to calculate the dimensions in the order you choose.
See Chapter 29, Developing Calculation Scripts for Block Storage Databases.
The setting for consolidating #MISSING values is turned off (the default).
Year-Market
New York
Massachusetts
East
Jan
112345
68754
Feb
135788
75643
Mar
112234
93456
Qtr1
3/7
Data values have been loaded into the following input cells:
l
404
Essbase calculates the Qtr1 cells for New York, Massachusetts, and East and the East cells for
Jan, Feb, and March. In Table 68, the calculation order for these cells is represented by the
numbers 1 through 7 that appear in the cells:
1. Qtr1 -> New York
2. Qtr1 -> Massachusetts
3. Qtr1 -> East
4. Jan -> East
5. Feb -> East
6. Mar -> East
7. Qtr1 -> East
Qtr1 -> East is calculated on both the Year and Market consolidation paths. First, Qtr1 -> East
is calculated as a consolidation of Qtr1 -> New York and Qtr1 -> Massachusetts. Second, Qtr1
-> East is calculated as a consolidation of Jan -> East, Feb -> East, and Mar -> East.
The results, as shown in Table 69, are identical to the results for example 1 (see Table 67 on page
404). However, Qtr1 -> East has been calculated twice. This fact is significant when you need to
load data at parent levels (see Cell Calculation Order: Example 3 on page 405).
Table 69
Year-Market
New York
Massachusetts
East
Jan
112345
68754
181099
Feb
135788
75643
211431
Mar
112234
93456
205690
Qtr1
360367
237853
598220
Based on the calculation order, if you place a member formula on Qtr1 in the database outline,
its result is overwritten when Essbase consolidates Qtr1 -> East on the Market consolidation
path. If you place a member formula on East in the database outline, the result is retained, because
the Market consolidation path is calculated last.
The setting for consolidating #MISSING values is turned off (the default).
405
Year-Market
New York
Massachusetts
East
Jan
#MISSING
#MISSING
181099
Feb
#MISSING
#MISSING
211431
Mar
#MISSING
#MISSING
205690
Qtr1
#MISSING
#MISSING
The cells are calculated in the same order as in Cell Calculation Order: Example 2 on page
404. Qtr1 -> East is calculated on both the Year and Market consolidation paths.
Because the setting for consolidating #MISSING values is turned off, Essbase does not
consolidate the #MISSING values. Thus, the data that is loaded at parent levels is not overwritten
by the #MISSING values below it.
However, if any of the child data values are not #MISSING, these values are consolidated and
overwrite the parent values. For example, if Jan -> New York contains 50000.00, this value
overwrites the values loaded at parent levels.
The results, as shown in Table 71, show that Essbase first correctly calculates the Qtr1 -> East
cell by consolidating Jan -> East, Feb -> East, and Mar -> East, and then calculates on the Market
consolidation path. However, it does not consolidate the #MISSING values in Qtr1 -> New York
and Qtr1 -> Massachusetts; therefore, the value in Qtr1 -> East is not overwritten.
Table 71
Year-Market
New York
Massachusetts
East
Jan
#MISSING
#MISSING
181099
Feb
#MISSING
#MISSING
211431
Mar
#MISSING
#MISSING
205690
Qtr1
#MISSING
#MISSING
598220
Essbase must calculate the Qtr1 -> East cell twice to ensure that a value is calculated for the cell.
If Qtr1 -> East is calculated according to only the last consolidation path, the result is #MISSING,
which is not the required result.
406
The setting for consolidating #MISSING values is turned off (the default).
The Marketing, Payroll, and Misc Expenses values have been loaded at the Qtr1, parent level.
Figure 123 shows the Profit branch of the Measures dimension in the Sample.Basic database.
This example assumes that Total Expenses is not a Dynamic Calc member.
Figure 123
Calculation Order Example 4: Input Cells, #MISSING Values, and Calculated Cells
Measures/Year
Jan
Feb
Mar
Qtr1
Sales
31538
32069
32213
13
COGS
14160
14307
14410
14
Margin
10/15
Marketing
#MISSING
#MISSING
#MISSING
15839
Payroll
#MISSING
#MISSING
#MISSING
12168
Misc
#MISSING
#MISSING
#MISSING
233
Total Expenses
11/16
Profit
12/17
Because the setting for consolidating #MISSING values is turned off, Essbase does not
consolidate the #MISSING values. Thus, any data that is loaded at parent levels is not overwritten
by the #MISSING values and Essbase calculates the cells with multiple consolidation paths twice.
The results are shown in Table 73:
Table 73
Measures/Year
Jan
Feb
Mar
Qtr1
Sales
31538
32069
32213
95820
COGS
14160
14307
14410
42877
Margin
17378
17762
17803
52943
Marketing
#MISSING
#MISSING
#MISSING
15839
Payroll
#MISSING
#MISSING
#MISSING
12168
Misc
#MISSING
#MISSING
#MISSING
233
28240
Total Expenses
Profit
17378
17762
17803
Based on the calculation order, if you place a member formula on, for example, Margin in the
database outline, its result is overwritten by the consolidation on Qtr1.
Calculation Passes
Whenever possible, Essbase calculates a database in one calculation pass through the database.
Thus, it reads each of the required data blocks into memory only once, performing all relevant
calculations on the data block and saving it. However, in some situations, Essbase must perform
multiple calculation passes through a database. On subsequent calculation passes, Essbase brings
data blocks back into memory, performs further calculations on them, and saves them again.
408
12/17
When you perform a default, full calculation of a database (CALC ALL), Essbase attempts to
calculate the database in one calculation pass. If you have dimensions that are tagged as accounts
or time, Essbase may have to do multiple calculation passes through the database.
Table 74 shows the number of calculation passes Essbase performs if you have dimensions that
are tagged as time or accounts, and you have at least one formula on the accounts dimension:
Table 74
Dimension Tagged As
Accounts
Dimension Tagged
As Time
Calculation Passes
Dense or Sparse
None
All dimensions
Dense
Dense
All dimensions
Dense
Sparse
Sparse
Sparse
Sparse
Dense
If you are using formulas that are tagged as Two-Pass, Essbase may need to do an extra calculation
pass to calculate these formulas. See Using Two-Pass Calculation on page 876.
When you use a calculation script to calculate a database, the number of calculation passes
Essbase needs to perform depends upon the calculation script. See Calculation Passes on page
408 and Understanding Multiple-Pass Calculations on page 422. Also see Grouping
Formulas and Calculations on page 467.
If the isolation level is set for committed access, and multiple passes are required, Essbase writes
data values at the end of each pass. Data retrievals that occur between passes can pick up
intermediate values.
When you calculate a database, Essbase automatically displays the calculation order of the
dimensions for each pass through the database and tells you how many times Essbase has cycled
through the database during the calculation. Essbase displays this information in the ESSCMD
window and in the application log.
To display the application log, see Viewing the Essbase Server and Application Logs on page
739.
For each data block, Essbase decides whether to do a dense or a sparse calculation. The type of
calculation it chooses depends on the type of values within the data block. When you run a
default calculation (CALC ALL) on a database, each block is processed in order, according to its
block number.
Essbase calculates the blocks using this procedure:
409
If you have Intelligent Calculation turned on, and if the block does not need to be calculated
(if it is marked as clean), Essbase skips the block and moves to the next block. See Chapter 26,
Understanding Intelligent Calculation.
If the block needs recalculating, Essbase checks to see if the block is a level 0, an input, or an
upper-level block. See Data Storage in Data Blocks on page 393.
If the block is a level 0 block or an input block, Essbase performs a dense calculation on the
block. Each cell in the block is calculated. See Cell Calculation Order on page 402.
If the block is an upper-level block, Essbase either consolidates the values or performs a
sparse calculation on the data block.
The sparse member combination of each upper-level block contains at least one parent
member. Essbase consolidates or calculates the block based on the parent members
dimension. For example, if the upper-level block is for Product -> Florida from the
Sample.Basic database, then Essbase chooses the Product dimension.
If the sparse member combination for the block has multiple parent members, Essbase
chooses the last dimension in the calculation order that includes a parent member. For
example, if the block is for Product -> East, and you perform a default calculation on the
Sample.Basic database, Essbase chooses the Market dimension, which contains East. The
Market dimension is last in the default calculation order because it is placed after the Product
dimension in the database outline. See Member Calculation Order on page 395.
Based on the chosen sparse dimension, Essbase either consolidates the values or performs
a sparse calculation on the data block:
m
If a formula is applied to the data block member on the chosen sparse dimension, Essbase
performs a formula calculation on the sparse dimension. Essbase evaluates each cell in
the data block. The formula affects only the member on the sparse dimension, so overall
calculation performance is not significantly affected.
If the chosen sparse dimension is a default consolidation, Essbase consolidates the
values, taking the values of the previously calculated child data blocks.
410
Figure 124
A calculation on a shared member is a calculation on the actual member. If you use the FIX
command to calculate a subset of a database and the subset includes a shared member, Essbase
calculates the actual member.
411
412
26
Understanding Intelligent
Calculation
In This Chapter
Introducing Intelligent Calculation...................................................................... 413
Using Intelligent Calculation ............................................................................ 416
Using the SET CLEARUPDATESTATUS Command...................................................... 417
Calculating Data Blocks ................................................................................. 420
Understanding the Effects of Intelligent Calculation .................................................. 425
A calculation script that calculates all members in one CALC DIM statement.
For database calculations that cannot use Intelligent Calculation for the full calculation, you
may be able to use Intelligent Calculation for part of the calculation.
413
For example, to significantly improve calculation performance for a case in which you
calculate a database by doing a default consolidation and then an allocation of data, enable
Intelligent Calculation for the default consolidation and then disable Intelligent Calculation
for the allocation.
Assuming that Intelligent Calculation is turned on (the default), create a calculation script
to perform these steps for a partial Intelligent Calculation:
m
Allocate data
A calculation script that calculates all the dimensions in one CALC DIM statement.
For example, the following calculation script calculates all members in the Sample.Basic
database:
CALC DIM(Measures, Product, Market, Year, Scenario);
Compare this calculation script to a calculation script that calculates all the members with
two CALC DIM statements:
CALC DIM(Measures, Product);
CALC DIM(Market, Year, Scenario);
Using two CALC DIM statements causes Essbase to do at least two calculation passes through
the database. In this calculation, Essbase does not, by default, mark the data blocks as clean.
Because Intelligent Calculation depends on accurate clean and dirty status, you must manage
these markers carefully. See Maintaining Clean and Dirty Status on page 415.
Essbase marks calculated data blocks as clean only in the situations described above, unless you
use the SET CLEARUPDATESTATUS command in a calculation script. See Using the SET
CLEARUPDATESTATUS Command on page 417.
414
Calculating the data block for a partial calculation of the database only if SET
CLEARUPDATESTATUS AFTER is not part of the partial calculation statement in the
calculation script
Intelligent Calculation works on a data block level and not on a cell level. For example, if
you load a data value into one cell of a data block, the whole data block is marked as dirty.
A CALC ALL that requires two passes through the database may calculate incorrectly. The
problem occurs because blocks that are marked clean during the first pass are skipped during
the second pass. To avoid this problem, turn Intelligent Calculation off or perform a CALC
DIM for each dimension (rather than a CALC ALL for the database). A CALC ALL requires
two passes through the database in either of these situations:
m
415
however, need to use a calculation script to calculate some formulas twice. When you use a
calculation script, disable Intelligent Calculation before recalculating formulas.
l
For Intelligent Calculation, set the index cache size large enough to fit the whole index and to
account for future index growth due to data load or calculation.
Caution!
Recalculating
When you do a full recalculation of a database with Intelligent Calculation turned on, Essbase
checks each block to see whether it is marked as clean or dirty. See Intelligent Calculation and
Data Block Status on page 414.
Checking data blocks has a 5% to 10% performance overhead, which is insignificant when
compared to the performance gained by enabling Intelligent Calculation.
If, however, you recalculate a database in which more than approximately 80% of the values
have changed, the overhead of Intelligent Calculation may outweigh the benefits. In this case,
disable Intelligent Calculation.
blocks as clean for purposes of Intelligent Calculation, use the SET CLEARUPDATESTATUS
command in a calculation script. Read this section, and also see Intelligent Calculation and
Data Block Status on page 414.
418
In this example, Essbase searches for dirty parent data blocks for New York (for example New
York -> Colas, in which Colas is a parent member on the Product dimension). It calculates these
dirty blocks and marks them as clean. Essbase does not mark the level 0 data blocks as clean,
because they are not calculated. For information on level 0 blocks, see Chapter 25, Defining
Calculation Order.
Essbase searches for dirty parent data blocks for New York (for example New York -> Colas, in
which Colas is a parent member on the Product dimension). Essbase marks the dirty parent data
blocks as clean but does not calculate the data blocks. Essbase does not mark the level 0 data
blocks as clean because they are not calculated. For example, if New York -> 100-10 (a level 0
block) is dirty, it remains dirty.
In this example, Essbase first calculates all the dirty data blocks in the database. The calculated
data blocks remain dirty. Essbase does not mark them as clean.
Essbase then calculates the members tagged as two-pass that are in the dimension tagged as
accounts. Because the data blocks are still marked as dirty, Essbase recalculates them. Again, it
does not mark the calculated data blocks as clean.
Essbase then searches for all the dirty blocks in the database and marks them as clean. It does
not calculate the blocks, although a CALC ALL command is used.
419
This script calculates the Year dimension, which is a dense dimension. Because Year is dense,
every data block in the database includes members of the Year dimension. Therefore, Essbase
calculates data values in every data block. Because the script uses the SET
CLEARUPDATESTATUS AFTER command, Essbase marks all data blocks as clean.
This script calculates the Product dimension, which is a sparse dimension. Because Product is
sparse, a data block exists for each member on the Product dimension. For example, one data
block exists for New York -> Colas and another for New York -> 100-10.
Level 0 Effects
The data block New York -> 100-10 is a level 0 block; it does not represent a parent member on
either sparse dimension (Market or Product). The data values for New York -> 100-10 are input
values; they are loaded into the database. Therefore, Essbase does not need to calculate this data
block. Nor does Essbase mark the data block for New York -> 100-10 as clean, even though the
script uses the SET CLEARUPDATESTATUS AFTER command.
420
Note: Essbase calculates level 0 data blocks if a corresponding sparse, level 0 member has a
Upper-Level Effects
Colas is a parent-level member on the Product dimension. Essbase must calculate values for
Colas, so Essbase calculates this data block. Because the script uses the SET
CLEARUPDATESTATUS AFTER command, Essbase marks the data block as clean.
When Essbase calculates a sparse dimension, it recalculates an upper-level data block if the block
is dependent on one or more dirty child blocks.
Unnecessary Calculation
You can avoid unnecessary calculation by calculating at least one dense dimension. When you
calculate a dense dimension and do not use the FIX command, data values are calculated in every
data block, including the level 0 blocks. So the level 0 blocks are marked as clean.
If User 2 runs the following calculation script to calculate the Budget values for New York, Essbase
does not recalculate the specified data blocks, because they are already marked as clean. The
calculation results for Budget are not correct.
SET CLEARUPDATESTATUS AFTER;
FIX(New York, Budget)
421
One way to solve this problem is to make the Scenario dimension sparse. Then the Actual and
Budget values are in different data blocks; for example, New York -> Colas -> Actual and New
York -> Colas -> Budget. In this case, the second calculation script correctly calculates Budget
data block.
Running concurrent calculations might require an increase in the data cache. See Sizing the
Data Cache on page 827.
Error
Essbase calculates the dirty data blocks in the database and marks all the data blocks as clean.
Essbase then needs to recalculate the members tagged as two-pass in the dimension tagged as
accounts. However, Essbase does not recalculate the specified data blocks because they are
already marked as clean. The calculation results are not correct.
Solution
You can calculate the correct results by disabling Intelligent Calculation for the two-pass
calculation.
422
Error
Essbase performs the following processes:
1. Essbase cycles through the database calculating the dirty data blocks that represent New
York. The calculation is based on the Product dimension. Thus, Essbase calculates only the
blocks that represent a parent member on the Product dimension (for example, New York
-> Colas, New York -> Root Beer, and New York -> Fruit Soda), and then only calculates
the aggregations and formulas for the Product dimension.
2. Because the SET CLEARUPDATESTATUS AFTER command is used, Essbase marks the
calculated data blocks as clean, although not all data values in each calculated block have
been calculated.
3. Essbase should recalculate the members tagged as two-pass in the dimension tagged as
accounts; however, some of these data blocks are already marked as clean from the
calculation in the previous step. Essbase does not recalculate the data blocks that are marked
as clean. The calculation results are not correct.
Solution
You can calculate the correct results by disabling Intelligent Calculation for the two-pass
calculation.
Error
Essbase performs the following processes:
1. Essbase cycles through the database calculating the dirty data blocks. The calculation is based
on the Product dimension, as in Example 2: SET CLEARUPDATESTATUS and FIX on
page 423.
423
2. Because the SET CLEARUPDATESTATUS AFTER command is used, Essbase marks the
calculated data blocks as clean, although not all data values in each calculated block have
been calculated.
3. Essbase should recalculate the data blocks. The recalculation is based on the Year dimension.
However, as a result of the calculation in the previous step, some data blocks are already
marked as clean, and Essbase does not recalculate them. The calculation results are not
correct.
Solution
You can calculate the correct results by using one CALC DIM command to calculate the Product
and Year dimensions. Essbase calculates both dimensions in one calculation pass through the
database.
The following calculation script calculates the correct results:
SET CLEARUPDATESTATUS AFTER;
CALC DIM(Product, Year);
Note: When you calculate several dimensions in one CALC DIM command, Essbase calculates
the dimensions in the default calculation order and not in the order in which you list them
in the command. See Member Calculation Order on page 395.
Essbase calculates the data blocks that include New York. Because the calculation is based on
the Product dimension, Essbase calculates only the dirty blocks that include a parent member
on the Product dimension (for example, New York -> Colas, New York -> Root Beer, and New
York -> Fruit Soda), and calculates only the aggregations and formulas for the Product
dimension.
Because of the CLEARUPDATESTATUS AFTER command, Essbase marks the calculated data
blocks as clean, although not all data values in each calculated block have been calculated.
The second calculation script calculates the Year dimension:
SET CLEARUPDATESTATUS AFTER;
FIX(New York)
CALC DIM(Year);
ENDFIX
Essbase calculates the data blocks that represent New York. Because the calculation is based on
the Year dimension, which is a dense dimension, Essbase should calculate all data blocks that
include New York, although within each block Essbase calculates only the aggregations and
formulas for the Year dimension.
424
Error
As a result of the first calculation, some data blocks for New York are already marked as clean.
Essbase does not recalculate these data blocks with the second calculation script because the data
blocks are marked as clean. The calculation results are not correct.
Solution
You can calculate the correct results by telling Essbase not to mark the calculated data blocks as
clean. The following calculation script calculates the correct results:
SET CLEARUPDATESTATUS OFF;
FIX(New York)
CALC DIM(Product);
ENDFIX
SET CLEARUPDATESTATUS AFTER;
FIX(New York)
CALC DIM(Year);
ENDFIX
With the SET CLEARUPDATESTATUS OFF command, Essbase calculates dirty data blocks but
does not to mark them as clean, unlike the SET CLEARUPDATESTATUS AFTER command.
This solution assumes that the data blocks are not marked as clean from a previous partial
calculation of the database.
You can ensure that all data blocks are calculated, regardless of their status, by disabling
Intelligent Calculation. The following calculation script calculates all specified data blocks,
regardless of their clean or dirty status:
SET UPDATECALC OFF;
FIX(New York)
CALC DIM(Year, Product);
ENDFIX
Because you have not used the SET CLEARUPDATESTATUS AFTER command, Essbase does
not mark calculated data blocks as clean.
425
When you subsequently run a default calculation with Intelligent Calculation turned on, the
changes are not calculated. To recalculate the appropriate data blocks, use a calculation script
to perform any of the following tasks:
l
Disable Intelligent Calculation and calculate the member formula that has changed.
Disable Intelligent Calculation and use the FIX command to calculate the appropriate subset
of a database.
Disable Intelligent Calculation and perform a default CALC ALL on a database.
Restructuring Databases
When you restructure a database (for example, by adding a member to a dense dimension), all
data blocks potentially need recalculating. Therefore, Essbase marks all data blocks as dirty.
When you calculate the restructured database, all blocks are calculated.
Note: Changing a formula in the database outline or changing an accounts property in the
database outline does not cause Essbase to restructure the database. You must recalculate
the appropriate data blocks. See Changing Formulas and Accounts Properties on page
425.
Converting Currencies
When you convert currencies using the CCONV command, the resulting data blocks are marked
as dirty. Essbase calculates all converted blocks when you recalculate a database.
426
27
In This Chapter
Understanding Dynamic Calculation ................................................................... 427
Benefitting from Dynamic Calculation.................................................................. 429
Using Dynamic Calculation.............................................................................. 430
Choosing Values to Calculate Dynamically ............................................................ 430
Choosing Between Dynamic Calc and Dynamic Calc and Store..................................... 433
Understanding How Dynamic Calculation Changes Calculation Order.............................. 435
Reducing the Impact on Retrieval Time ................................................................ 438
Using Dynamic Calculations with Standard Procedures.............................................. 441
Creating Dynamic Calc and Dynamic Calc and Store Members ..................................... 442
Restructuring Databases ................................................................................ 442
Dynamically Calculating Data in Partitions ............................................................ 443
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Dynamic Calc
427
Essbase does not store the calculated value; it recalculates the value for each subsequent retrieval.
Recalculation of Data
When Essbase detects that the data value for a Dynamic Calc and Store member needs
recalculating, it places an indicator on the data block that contains the value, so that Essbase
knows to recalculate the block on the next retrieval of the data value.
Essbase places the indicator on the data block containing the value and not on the data value
itself, meaning that Essbase tracks Dynamic Calc and Store members at the data block level. See
Data Blocks and the Index System on page 72.
If the data block needs recalculating, Essbase detects the need and places an indicator on the data
block when any of the following situations occur:
l
Essbase recalculates the indicated data blocks when you next retrieve the data value.
428
If you load data into the children of a Dynamic Calc and Store member, and the member is a
consolidation of its child members, Essbase does not know to recalculate the Dynamic Calc and
Store member during the next retrieval. The parent member is recalculated only during the next
batch calculation.
After loading data, you must perform a batch calculation of the database or use the
CLEARBLOCK DYNAMIC calculation command to ensure that the Dynamic Calc and Store
members are recalculated. See the Oracle Essbase Technical Reference.
Batch calculation time of the database, because Essbase has fewer member combinations to
calculate.
Disk usage, because Essbase stores fewer calculated data values. Database size and index size
are also reduced.
Database restructure time. For example, adding or deleting a Dynamic Calc member in a
dense dimension does not change the data block size, so Essbase does not need to restructure
the database. See Restructuring Databases on page 442.
Time required to back up the database. Because database size is reduced, Essbase takes less
time to perform a backup.
Data values that Essbase calculates dynamically can take longer to retrieve. You can estimate the
retrieval time for dynamically calculated members. See Reducing the Impact on Retrieval Time
on page 438.
429
Label-only members
Shared members
Which members you choose to calculate dynamically depends on the database structure and on
the balance between (1) the need for reduced calculation time and disk usage and (2) the need
for speedy data retrieval for users. See Choosing Values to Calculate Dynamically on page
430.
In Outline Editor, you can see which members are Dynamic Calc and which are Dynamic Calc
and Store. Figure 125 shows Dynamic Calc members.
Figure 125
In Smart View, users can display visual cues to distinguish dynamically calculated values. See
the Oracle Smart View for Office User's Guide.
When developing spreadsheets that include dynamically calculated values, spreadsheet designers
may want to use the spreadsheet Navigate Without Data option, so that Essbase does not
dynamically calculate and store values while test spreadsheets are built.
430
Tag some upper-level members of sparse dimensions that have six or fewer children as
Dynamic Calc or Dynamic Calc and Store.
Tag sparse-dimension members with complex formulas as Dynamic Calc or Dynamic Calc
and Store.
A complex formula requires Essbase to perform an expensive calculation. For example, any
formula that contains a financial function is a complex formula. See Using Complex
Formulas on page 867.
Tag upper-level members in a dimension that you frequently restructure as Dynamic Calc
or Dynamic Calc and Store.
Do not tag upper-level, sparse-dimension members that have 20 or more descendants as
Dynamic Calc or Dynamic Calc and Store.
See Choosing Between Dynamic Calc and Dynamic Calc and Store on page 433.
431
Similarly, if a member set function (for example, @CHILDREN or @SIBLINGS) is used to specify
the list of members to calculate, Essbase bypasses the calculation of any Dynamic Calc or
Dynamic Calc and Store members in the resulting list.
If you specify a Dynamic Calc or Dynamic Calc and Store member explicitly in a calculation
script, the calculation script fails. You cannot do a calculation script calculation of a Dynamic
Calc or Dynamic Calc and Store member. To use a calculation script to calculate a member
explicitly, do not tag the member as Dynamic Calc.
For example, the following calculation script is valid only if Qtr1 is not a Dynamic Calc member:
FIX (East, Colas)
Qtr1;
ENDFIX
You cannot make a dynamically calculated member the target of a formula calculation in a
calculation script; Essbase does not reserve memory for a dynamically calculated value and,
therefore, cannot assign a value to it. For example, if Qtr1 is a Dynamic Calc or Dynamic Calc
and Store member, Essbase displays a syntax error if you include the following formula in a
calculation script:
Qtr1 = Jan + Feb;
If Qtr1 is a Dynamic Calc or Dynamic Calc and Store member and Year is neither Dynamic Calc
nor Dynamic Calc and Store, you can use the following formula in a calculation script:
Year = Qtr1 + Qtr2;
This formula is valid because Essbase does not assign a value to the dynamically calculated
member.
Note: When you reference a dynamically calculated member in a formula in the database outline
432
433
Essbase calculates and stores the Market -> Cola data block. To calculate and store Market ->
Cola, Essbase calculates the intermediate data blocksEast -> Cola, West -> Cola, South ->
Cola, and Central -> Cola. Essbase does not store these intermediate data blocks.
For example, in the Sample.Basic database, if most users retrieve data at the Market level, you
probably want to tag Market as Dynamic Calc and Store and its children as Dynamic Calc.
Figure 127
434
Dynamic Calc and Store member retrieval time increases as the number of concurrent user
retrievals increases. However, Dynamic Calc member retrieval time does not increase as
concurrent user retrievals increase.
If many users are concurrently accessing data, you may see significantly faster retrieval times if
you use Dynamic Calc members instead of Dynamic Calc and Store members.
If the dimension tagged as time is sparse and the database outline uses time series data,
Essbase bases the sparse calculation on the time dimension.
Otherwise, Essbase bases the calculation on the dimension that it normally uses for a
batch calculation.
2. Dense dimensions
a. Dimension tagged as accounts, if dense
b. Dimension tagged as time, if dense
c. Time series calculations
d. Remaining dense dimensions
e. Two-pass calculations
f.
Attributes
435
If your data retrieval uses attribute members, the last step in the calculation order is the
summation of the attributes. Attribute calculation performs on-the-fly aggregation on data
blocks that match the attribute members specified in the query. When the query contains twopass calculation members, attribute calculation applies the two-pass calculation member
formula after all the aggregated values are collected. This two-pass calculation uses the data
values from the attribute calculation, not the values in a real data block.
The use of attribute members in your query causes Essbase to disregard the value of the Time
Balance member in the dynamic calculations. During retrievals that do not use attributes, the
value of the Time Balance member is applied to the calculations. The difference in calculation
procedure between the use and nonuse of attribute members generates different results for any
upper-level time members that are dynamically calculated.
During retrievals that do not use attributes, these dynamically calculated members are calculated
in the last step and, therefore, apply the time balance functionality properly. However, during
retrievals that do use attributes, the summation of the attribute is the last step applied. The
difference in calculation order produces two different, predictable results for upper-level time
members that are dynamically calculated.
Margin% in the dense Measures dimension (the dimension tagged as accounts) is tagged as
Dynamic Calc and two-pass.
Variance in the dense Scenario dimension is tagged as Dynamic Calc and two-pass.
Essbase calculates the accounts dimension member first. So, Essbase calculates Margin% (from
the Measures dimension) and then calculates Variance (from the Scenario dimension).
If Scenario is a sparse dimension, Essbase calculates Variance first, following the regular
calculation order for dynamic calculations. Essbase then calculates Margin%. See Calculation
Order for Dynamic Calculation on page 435.
436
This calculation order does not produce the required result, because Essbase needs to calculate
Margin % -> Variance using the formula on Margin %, and not the formula on Variance. You
can avoid this problem by making Scenario a dense dimension. This problem does not occur if
the Measures dimension (the accounts dimension) is sparse, because Essbase still calculates
Margin% first.
Calculating along the accounts dimension, subtract Qtr1 -> COGS from Qtr1 -> Sales:
600300=300
Table 75
Jan
Feb
Mar
Qtr1
Sales
100
200
300
600
COGS
50
100
150
300
50
100
150
300
Calculating along the accounts dimension, multiplying the value East -> Price by the value East
-> UnitsSold produces incorrect results:
15 * 50 = 750
Table 76
New York
Florida
Connecticut
East
UnitsSold
10
20
20
50
437
New York
Florida
Connecticut
East
Price
15
50
100
100
250
In the following outline, East is a sparse dimension, and Accounts is a dense dimension:
If East and Sales are tagged as Dynamic Calc, Essbase calculates a different result than it does if
East and Sales are not tagged as Dynamic Calc.
If East and Sales are not Dynamic Calc members, Essbase produces the correct result by
calculating these dimensions:
1. Dense Accounts dimensioncalculating the values for UnitsSold, Price, and Sales for New
York, Florida, and Connecticut
2. Sparse East dimensionaggregating the calculated values for UnitsSold, Price, and Sales for
New York, Florida, and Connecticut to obtain the Sales values for East
If East and Sales are Dynamic Calc members, Essbase produces an incorrect result by calculating
these dimensions:
1. Sparse East dimensionaggregating the values for UnitsSold, Price, and Sales for New York,
Florida, and Connecticut to obtain the values for East
2. Values for East -> Salestaking the aggregated values in the East data blocks and performing
a formula calculation with these values to obtain the value for Sales
To avoid this problem and ensure that you obtain the required results, do not tag the Sales
member as Dynamic Calc or Dynamic Calc and Store.
438
This message tells you that Essbase needs to retrieve one block to calculate the most expensive
dynamically calculated data block.
This message tells you that there are eight Dynamic Calc members in the first dimension of the
database outline, six in the second dimension, and two in the fifth dimension. Dynamic Time
Series members are included in this count.
This example does not include Dynamic Calc and Store members.
439
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATEITEM
optimizing calculation performance. See Sizing the Calculator Cache on page 828.
440
If a dynamic calculator cache is used, a second message displays the number of blocks calculated
within the data calculator cache (Dyn.Calc.Cache: [n]) and the number of blocks calculated in
memory outside dynamic calculator cache (non-Dyn.Calc.Cache: [n]).
To determine whether the dynamic calculator cache is being used effectively, review both
messages and consider your essbase.cfg settings. For example, if the message indicates that
blocks were calculated outside and in a dynamic calculator cache, you may increase the
DYNCALCCACHEMAXSIZE setting. If the specified maximum size is all that you can afford
for all dynamic calculator caches on the server, and if using memory outside the calculator cache
to complete dynamically calculated retrievals results in unacceptable delays (for example,
because of swapping or paging activity), set DYNCALCCACHEWAITFORBLK to TRUE.
You can use the query database MaxL statement with the performance statistics grammar to
view a summary of dynamic calculator cache activity. See the Oracle Essbase Technical
Reference.
Copying data
You cannot copy data to a dynamically calculated data value. You cannot specify a Dynamic
Calc or Dynamic Calc and Store member as the target for the DATACOPY calculation
command.
Converting currencies
You cannot specify a Dynamic Calc or Dynamic Calc and Store member as the target for
the CCONV command.
Loading data
When you load data, Essbase does not load data into member combinations that contain a
Dynamic Calc or Dynamic Calc and Store member. Essbase skips these members during
data load and does not display an error message.
To place data into Dynamic Calc and Dynamic Calc and Store members, after loading data,
ensure that Essbase recalculates Dynamic Calc and Store members. See Effect of Updated
Values on Recalculation on page 428.
Exporting data
Essbase does not calculate dynamically calculated values before exporting data. Essbase does
not export values for Dynamic Calc members. Essbase exports values for Dynamic Calc and
441
Store members only if a calculated value exists in the database from a previous user retrieval
of the data.
l
Reporting data
Essbase cannot use the SPARSE data extraction method for dynamically calculated members.
The SPARSE data extraction method optimizes performance when a high proportion of the
reported data rows are #MISSING. See the <SPARSE command in the Oracle Essbase
Technical Reference.
Restructuring Databases
When you add a Dynamic Calc member to a dense dimension, Essbase does not reserve space
in the data block for the members values. Therefore, Essbase does not need to restructure the
database. However, when you add a Dynamic Calc and Store member to a dense dimension,
Essbase does reserve space in the relevant data blocks for the members values and, therefore,
must restructure the database.
When you add a Dynamic Calc or a Dynamic Calc and Store member to a sparse dimension,
Essbase updates the index but does not change the relevant data blocks. See Index Manager
on page 757.
Essbase can save changes to the database outline significantly faster if it does not have to
restructure the database.
In the following cases, Essbase does not restructure the database or change the index (Essbase
saves only the database outline, which is very fast):
l
442
Essbase does restructure the database if the member is Dynamic Calc and Store.
l
Change the storage property of a dense dimension member from Dynamic Calc and Store
member to a nondynamic storage property.
Change the storage property of a sparse dimension Dynamic Calc or Dynamic Calc and
Store member to a nondynamic storage property.
Rename any Dynamic Calc or Dynamic Calc and Store member.
In the following cases, Essbase does not restructure the database but does restructure the database
index, which is significantly faster:
l
Add, delete, or move sparse dimension Dynamic Calc or Dynamic Calc and Store members.
Change the storage property of a dense dimension member from a nondynamic value to
Dynamic Calc and Store.
Add, delete, or move a dense dimension Dynamic Calc and Store member.
Essbase does not restructure the database if the member is Dynamic Calc.
Change a dense dimension Dynamic Calc and Store member to a Dynamic Calc member.
Change a dense dimension Dynamic Calc member to a Dynamic Calc and Store member.
443
In a transparent partition, the definition on the remote database takes precedence over any
definition on the local database. For example, if a member is tagged as Dynamic Calc in the local
database but not in the remote database, Essbase retrieves the value from the remote database
and does not do the local calculation.
If you are using a replicated partition, consider using Dynamic Calc members instead of Dynamic
Calc and Store members. When calculating replicated data, Essbase does not retrieve the child
blocks from the remote database; therefore, the impact on retrieval time is not great.
Note: When Essbase replicates data, it checks the time stamp on each source data block and
each corresponding target data block. If the source data block is more recent, Essbase
replicates the data in the data block. However, for dynamically calculated data, data blocks
and time stamps do not exist. Therefore, Essbase always replicates dynamically calculated
data.
444
28
In This Chapter
Introduction............................................................................................... 445
Calculating First, Last, and Average Values ........................................................... 445
Calculating Period-to-Date Values...................................................................... 449
Using Dynamic Time Series Members in Transparent Partitions..................................... 453
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Introduction
Time series calculations assume that you have Dynamic Time Series members defined in the
outline. Calculating time series data is helpful in tracking inventory by calculating the first and
last values for a time period, and in calculating period-to-date values.
445
For cells of time balance account members, a member in any dimension other than the time
dimension that is set with the ^ consolidation operator is excluded from the Average calculation;
the member is, however, included in First and Last calculations.
Note: If you are using Intelligent Calculation, changing accounts tags in the database outline
does not cause Essbase to restructure the database. You may have to tell Essbase explicitly
to recalculate the required data values. See Changing Formulas and Accounts Properties
on page 425.
See Creating a Time Dimension on page 142 and Creating an Accounts Dimension on page
142.
446
Figure 129
For information on tagging an accounts member as Last, see Setting Time Balance Properties
on page 143.
By default, Essbase does not skip #MISSING or zero (0) values when calculating a parent value.
You can choose to skip these values. For a discussion of how and why to skip #MISSING values,
see Skipping #MISSING and Zero Values on page 448.
For information on tagging an accounts member as First, see Setting Time Balance Properties
on page 143.
By default, Essbase does not skip #MISSING or zero (0) values when calculating a parent value.
You can choose to skip these values. See Skipping #MISSING and Zero Values on page 448.
447
Jan
Feb
Mar
Qtr1
60
70
#MI
70
Tagging an account as Average and Skip Missing may produce different results from tagging
that account as Average and Skip None. A calculation performed with Average and Skip None
produces correct results because no data is skipped. But because grandparents with children are
consolidated by summing the averages, results of a calculation on an account with Average and
Skip Missing is incorrect unless you use Dynamic Calc or Two-Pass tags.
448
Table 78
Jan
Feb
Mar
Qtr1
Accounts Member1
11
12
13
36
20
25
21
20
Value of Jan
25
21
30
30
Value of Mar
20
30
28
26
Jan
Feb
Mar
Qtr1
30000
28000
27000
30000
Because Opening Inventory is tagged as First, Essbase calculates Opening Inventory for Qtr1 by
taking the Opening Inventory for Jan value. Any member formula that is placed on Qtr1 in the
database outline is overwritten by this time balance calculation.
Dynamically, when a user requests the values, using Dynamic Time Series members
This section explains how to use Dynamic Time Series members to dynamically calculate periodto-date values. Using Dynamic Time Series members is almost always the most efficient method.
For an example, see Calculating Period-to-Date Values on page 387.
449
HTD (history-to-date)
Y-T-D (year-to-date)
S-T-D (season-to-date)
P-T-D (period-to-date)
Q-T-D (quarter-to-date)
M-T-D (month-to-date)
W-T-D (week-to-date)
D-T-D (day-to-date)
These members provide up to eight levels of period-to-date reporting. How many and which
members you use depends on the data and the database outline.
For example, if the database contains hourly, daily, weekly, monthly, quarterly, and yearly data,
you can report day-to date (D-T-D), week-to-date (W-T-D), month-to-date (M-T-D), quarterto-date (Q-T-D), and year-to-date (Y-T-D) information.
450
If the database contains monthly data for the last five years, you can report year-to-date (Y-TD) and history-to-date (H-T-D) information, up to a specific year.
If the database tracks data for seasonal time periods, you can report period-to-date (P-T-D) or
season-to-date (S-T-D) information.
You can associate a Dynamic Time Series member with any generation in the time dimension
except the highest generation number, regardless of the data. For example, you can use the PT-D member to report quarter-to-date information. You cannot associate Dynamic Time Series
members with level 0 members of the time dimension.
Note: Oracle recommends that you avoid assigning time balance properties (First, Last, Average,
Skip Missing) to members set for dynamic calculations if you plan to use these members
in Dynamic Time Series calculations. Doing so may retrieve incorrect values for the parent
members in your accounts dimension.
dimension. You cannot associate Dynamic Time Series members with the highest
generation (level 0 members).
After you enable Dynamic Time Series members in the database outline, Essbase adds a comment
to the dimension tagged as time; for example, the Year dimension from Sample.Basic showing
H-T-D and Q-T-D defined:
Year Time (Active Dynamic Time Series Members: H-T-D, Q-T-D) (Dynamic Calc)
451
Member
Generation Name
D-T-D
Day
H-T-D
History
M-T-D
Month
P-T-D
Period
Q-T-D
Quarter
S-T-D
Season
W-T-D
Week
Y-T-D
Year
452
These member and generation names are reserved for use by Essbase. If you use one of these
generation names to create a generation name on the time dimension, Essbase automatically
creates and enables the corresponding Dynamic Time Series member for you.
For example, in Sample.Basic, you can create a generation name called Quarter for generation
number 2. Quarter contains quarterly data in the members Qtr1, Qtr2, and so on. When you
create the generation name Quarter, Essbase creates and enables a Dynamic Time Series member
called Q-T-D.
For a specific member, in Smart View, specify the latest period member name. Place that
name after the Dynamic Time Series member or alias name. For example, Q-T-D(May)
returns the quarter-to-date value by adding values for April and May.
For a retrieval, use one of the following methods to specify the latest time period:
m
In the example in Figure 132, Q-T-D(May) displays the period-to-date value for May that is
obtained by adding the values for Apr and May (8644 + 8929 = 17573).
Figure 132
See the Oracle Essbase Technical Reference and Chapter 16, Creating and Maintaining
Partitions.
454
29
In This Chapter
Using Calculation Scripts................................................................................ 456
Process for Creating Calculation Scripts ............................................................... 457
Understanding Calculation Script Syntax .............................................................. 458
Using Calculation Commands .......................................................................... 461
Using Formulas in Calculation Scripts ................................................................. 464
Using a Calculation Script to Control Intelligent Calculation......................................... 466
Grouping Formulas and Calculations .................................................................. 467
Using Substitution, Runtime Substitution, and Environment Variables in Calculation Scripts
............................................................................................................. 468
Clearing and Copying Data.............................................................................. 473
Calculating a Subset of a Database ................................................................... 474
Exporting Data Using the DATAEXPORT Command.................................................... 477
Enabling Calculations on Potential Blocks ............................................................ 480
Using Calculation Scripts on Partitions ................................................................ 482
Saving, Executing, and Copying Calculations Scripts................................................. 483
Checking Calculation Results ........................................................................... 485
Estimating Disk Size for a Calculation ................................................................. 486
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
Chapter 30, Reviewing Examples of Calculation Scripts for Block Storage Databases
All of the examples in this chapter are based on the Sample.Basic database.
For more information about the calculation commands referenced in this chapter, see the Oracle
Essbase Technical Reference.
455
Change the calculation order of the dense and sparse dimensions in a database
Perform a complex calculation in a specific order or perform a calculation that requires
multiple iterations through the data (for example, some two-pass calculations require a
calculation script)
Perform any two-pass calculation on a dimension without an accounts tag
See Using Two-Pass Calculation on page 876.
Calculate member formulas that differ from formulas in the database outline (formulas in
a calculation script override formulas in the database outline)
Use an API interface to create a custom calculation dynamically
Use control of flow logic in a calculation (for example, to use the IFELSEENDIF or the
LOOPENDLOOP commands)
Clear or copy data from specific members
See Copying Data on page 474.
Force a recalculation of data blocks after you have changed a formula or an accounts property
on the database outline
Control how Essbase uses Intelligent Calculation when calculating a database
See Chapter 26, Understanding Intelligent Calculation.
The following calculation script calculates the Actual values from the Year, Measures, Market,
and Product dimensions:
FIX (Actual)
CALC DIM(Year, Measures, Market, Product);
ENDFIX
Using Calculation Script Editor in Administration Services Console, you can create calculation
scripts by:
456
Entering the calculation script in the text area of the script editor
Using the user interface features of the script editor to build the script
Creating the script in a text editor and pasting the script text into Calculation Script Editor
See About Calculation Script Editor in the Oracle Essbase Administration Services Online
Help.
Calculation scripts created using Administration Services are given a .csc extension by default.
If you run a calculation script from Administration Services or Smart View, the file must have
a .csc extension. However, because a calculation script is a text file, you can use MaxL or
ESSCMD to run any text file as a calculation script.
A calculation script can also be a string defined in memory and accessed through the API on an
Essbase client or an Essbase Server. Therefore, from dialog boxes, you can dynamically create a
calculation script that is based on user selections.
Executing scripts
Changing fonts
457
Copying Scripts
Renaming Scripts
Deleting Scripts
Printing Scripts
End each formula or calculation script command with a semicolon (;). For example:
Example 1
CALC DIM(Product, Measures);
Example 2
DATACOPY Plan TO Revised_Plan;
Example 3
"Market Share" = Sales % Sales -> Market;
Example 4
IF (Sales <> #MISSING)
Commission = Sales * .9;
ELSE
Commission = #MISSING;
ENDIF;
458
ENDEXCLUDE
LOOP
ENDLOOP
Note: Although not required, Oracle recommends ending each ENDIF statement in a
Enclose a member name in double quotation marks (" "), if that member name meets any
of the following conditions:
m
Contains spaces.
For example, in the following formula, Opening Inventory and Ending Inventory are
enclosed in double quotation marks:
"Opening Inventory" = "Ending Inventory" - Sales + Additions;
Begins with an ampersand (&). The leading ampersand (&) is reserved for substitution
variables. If a member name begins with &, enclose the name in quotation marks.
Note: Do not enclose substitution variables in quotation marks in a calculation script.
If you are using an IF statement that is nested within another IF statement, end each IF with
an ENDIF statement.
For example:
459
"Opening Inventory"
(IF (@ISMBR(Budget))
IF (@ISMBR(Jan))
"Opening Inventory" = Jan;
ELSE
"Opening Inventory" = @PRIOR("Ending Inventory");
ENDIF;
ENDIF;)
l
You do not need to end ELSE or ELSEIF statements with ENDIF statements.
For example:
Marketing
(IF (@ISMBR(@DESCENDANTS(West)) OR @ISMBR(@DESCENDANTS(East)))
Marketing = Marketing * 1.5;
ELSEIF(@ISMBR(@DESCENDANTS(South)))
Marketing = Marketing * .9;
ELSE
Marketing = Marketing * 1.1;
ENDIF;)
Note: If you use ELSE IF (with a space) rather than ELSEIF (one word) in a formula, you
When you write a calculation script, use the Calculation Script Editor syntax checker to validate
the syntax. See Checking Syntax on page 460.
Adding Comments
You can include comments to annotate calculation scripts. Essbase ignores these comments
when it runs the calculation script.
To include a comment, start the comment with /* and end the comment with */. For example:
/* This calculation script comment
spans two lines. */
Checking Syntax
Essbase includes a syntax checker that flags syntax errors (such as a mistyped function name) in
a calculation script. The results are displayed in the messages panel in Administration Services
Console.
If syntax errors are not found, Essbase indicates the syntax check succeeded.
460
If syntax errors are found, Essbase indicates the syntax check failed and displays one error at a
time. Typically, an error message includes the line number in which the error occurred and a
brief description. For example, if a semicolon end-of-line character is missing at the end of a
calculation script command, Essbase displays a message similar to this one:
Error: line 1: invalid statement; expected semicolon
When you reach the last error, Essbase displays the following message:
No more errors
script does not work as you expect. To find semantic errors, run the calculation and check
the results to ensure they are as you expect. See Checking Calculation Results on page
485.
Command
Calculation
CALC ALL
CALC DIM
CALC TWOPASS
membername
The formula applied to a member in the database outline, where membername is the name of the member to which
the formula is applied
CALC AVERAGE
CALC FIRST
461
Command
Calculation
CALC LAST
CCONV
Currency conversions
Command
Calculation
FIXENDFIX
EXCLUDEENDEXCLUDE
LOOPENDLOOP
FIXPARALLEL...ENDFIXPARALLEL
You can also use the IF and ENDIF commands to specify conditional calculations.
Note: Essbase does not allow branching from one calculation script to another calculation script.
Command
Calculation
ARRAY
VAR
Values stored in temporary variables exist only while the calculation script is running. You
cannot report on the values of temporary variables.
Variable and array names are character strings that contain any of the following characters:
l
Letters az
Numerals 09
462
Typically, arrays are used to store variables as part of a member formula. The size of the array
variable is determined by the number of members in the corresponding dimension. For example,
if the Scenario dimension has four members, the following command creates an array called
Discount with four entries:
ARRAY Discount[Scenario];
Command
Calculation
SET AGGMISSG
SET CACHE
SET CALCPARALLEL
Enable parallel calculation. See Enabling CALCPARALLEL Parallel Calculation on page 507.
SET CALCTASKDIMS
Increase the number of dimensions used to identify tasks for parallel calculation. See Identifying
Additional Tasks for Parallel Calculation on page 508.
SET CLEARUPDATESTATUS
Control how Essbase marks data blocks for Intelligent Calculation. See Using the SET
CLEARUPDATESTATUS Command on page 417.
SET CREATEBLOCKEQ
Turn on and turn off the Create Blocks on Equation setting, which controls the creation of blocks when you
assign nonconstant values to members of a sparse dimension. See Nonconstant Values Assigned to
Members in a Sparse Dimension on page 869.
SET CREATENONMISSINGBLK
Enable calculations on potential data blocks and save these blocks when the result is not #MISSING.
SET FRMLBOTTOMUP
Optimize the calculation of sparse dimension formulas in large database outlines. See Optimizing
Formulas on Sparse Dimensions in Large Database Outlines on page 868.
SET LOCKBLOCK
Specify the maximum number of blocks that Essbase can lock concurrently when calculating a sparse
member formula.
SET MSG
SET NOTICE
SET RUNTIMESUBVARS
Declare runtime substitution variables that are used in a calculation script. See Using Runtime
Substitution Variables in Calculation Scripts on page 469.
SET UPDATECALC
Turn on and turn off Intelligent Calculation. See Turning Intelligent Calculation On and Off on page
416.
SET UPTOLOCAL
For currency conversions, restrict consolidations to parents that have the same defined currency. See
Calculating Databases on page 215.
463
A SET command in a calculation script stays in effect until the next occurrence of the same SET
command.
In the following calculation script, Essbase displays messages at the detail level (SET MSG
DETAIL;) when calculating the Year dimension and displays messages at the summary level
(SET MSG SUMMARY;) when calculating the Measures dimension:
SET MSG DETAIL;
CALC DIM(Year);
East;
Also see Using Two-Pass Calculation on page 876.
Define a formula
To calculate a formula that is applied to a member in the database outline, use the member name
followed by a semicolon (;). For example, the following command calculates the formula applied
to the Variance member in the database outline:
Variance;
To override values that result from calculating an outline, manually apply a formula that you
define in a calculation script. For example, the following formula cycles through the database,
adding the values in the members Payroll, Marketing, and Misc, and placing the result in the
Expenses member. The formula overrides any formula placed on the Expenses member in the
database outline:
Expenses = Payroll + Marketing + Misc;
Note: You cannot apply formulas to shared members or label only members.
464
See:
l
Also see Chapter 23, Developing Formulas for Block Storage Databases.
Basic Equations
You can use equations in a calculation script to assign a value to a member. The syntax for an
equation:
member = mathematical_expression;
member is a member name from the database outline and mathematical_expression is any valid
mathematical expression.
Essbase evaluates the expression and assigns the value to the specified member.
In the following example, Essbase cycles through the database, subtracting the values in COGS
from the values in Sales, and placing the result in Margin:
Margin = Sales - COGS;
In this example, Essbase cycles through the database, subtracting the values in Cost from the
values in Retail, calculating the resulting values as a percentage of the values in Retail, and placing
the results in Markup:
Markup = (Retail - Cost) % Retail;
You can also use the > (greater than) and < (less than) logical operators in equations.
In the following example, if February sales are greater than January sales, Sales Increase Flag
results in a value of 1; if false, the result is a value of 0:
Sales Increase Flag = Sales -> Feb > Sales -> Jan;
Conditional Equations
When you use an IF statement as part of a member formula in a calculation script, you must:
l
In the following example, the entire IFENDIF statement is enclosed in parentheses and
associated with the Profit member, Profit (IF(...)...):
Profit
(IF (Sales > 100)
Profit = (Sales - COGS) * 2;
ELSE
465
Essbase cycles through the database and performs the following calculations:
1. The IF statement checks whether the value of Sales for the current member combination is
greater than 100.
2. If Sales is greater than 100, Essbase subtracts the value in COGS from the value in Sales,
multiplies the difference by 2, and places the result in Profit.
3. If Sales is less than or equal to 100, Essbase subtracts the value in COGS from the value in
Sales, multiplies the difference by 1.5, and places the result in Profit.
Interdependent Formulas
When you use an interdependent formula in a calculation script, the same rules apply as for the
IF statement. You must:
l
In the following example, the entire formula is enclosed in parentheses and associated with the
Opening Inventory member:
"Opening Inventory"
(IF(NOT @ISMBR (Jan))
"Opening Inventory" = @PRIOR("Ending Inventory");
ENDIF;)
"Ending Inventory" = "Opening Inventory" - Sales + Additions;
Essbase always recalculates the data block that contains the formula, even if the data block is
marked as clean for the purposes of Intelligent Calculation.
See Calculating Data Blocks on page 420 and Chapter 26, Understanding Intelligent
Calculation.
466
In contrast, the following configurations cause Essbase to cycle through the database only once,
calculating the formulas on the members Qtr1, Qtr2, and Qtr3:
Qtr1;
Qtr2;
Qtr3;
or
(Qtr1;
Qtr2;
Qtr3;)
Similarly, the following formulas cause Essbase to cycle through the database once, calculating
both formulas in one pass:
Profit = (Sales - COGS) * 1.5;
Market = East + West;
In contrast, the following syntax causes Essbase to cycle through the database twice, once for
each CALC DIM command:
CALC DIM(Year);
CALC DIM(Measures);
467
Substitution variables are used to reference information that changes frequently; environment
variables are used as placeholders for user-specific system settings.
For general information on substitution variables, see Using Substitution Variables on page
120.
Create a substitution variable for the current quarter (&CurQtr) and assign it the value
Qtr1
Create a calculation script that uses the &CurQtr substitution variable. For example:
FIX(&CurQtr)
CALC DIM(Measures, Product);
ENDFIX
Also see Using Runtime Substitution Variables in Calculation Scripts on page 469.
468
At runtime, values can be provided for runtime substitution variables that do not have a default
value, and default values that are specified in the SET RUNTIMESUBVARS command can be
overwritten, using one of these methods:
l
MaxL execute calculation statement with the with runtimesubvars grammar, in which
runtime substitution variables are specified as a string of key/value pairs.
EssCalcWithRuntimeSubVars API, in which runtime substitution variables are specified as
a string of key/value pairs.
EssCalcFileWithRuntimeSubVars API, in which runtime substitution variables can be
specified in a text file on the client computer or as a string of key/value pairs.
When specifying runtime substitution variables as a string of key/value pairs, the string must be
enclosed with single quotation marks, and key/value pairs must be separated by a semicolon,
including a semicolon after the last runtime substitution variable in the string and before the
terminal single quotation mark. In this example of a runtime substitution variable string, the
name and value of four runtime substitution variables are specified (for example, the value of
the runtime substitution variable named a is 100):
'a=100;b=@CHILDREN("100");c="Actual"->"Final";d="New York";'
469
When specifying runtime substitution variables in a text file, create the text file with an .rsv
extension on the client computer. (Essbase does not support runtime substitution variable files
located on the Essbase Server computer.) Each line in the file specifies one runtime substitution
variable as a key/value pair and must end with a semicolon. In this example of an .rsv file, the
name and value of four runtime substitution variables are specified (for example, the value of
the runtime substitution variable named a is 100):
a=100;
b=200;
c=@CHILDREN("100");
d=@TODATE("DD/MM/YY","10/11/12");
When a calculation is executed, runtime substitution variable values are determined in the
following order:
1. Values specified through the MaxL execute calculation statement with the with
runtimesubvars grammar, or the EssCalcWithRuntimeSubVars, or
EssCalcFileWithRuntimeSubVars APIs.
2. Default values specified in the SET RUNTIMESUBVARS calculation command.
Consider these guidelines when using runtime substitution variables:
l
If you declare a runtime substitution variable in SET RUNTIMESUBVARS but do not use
the runtime substitution variable in the calculation script, Essbase ignores the unused
runtime substitution variable declaration (no warning or exception is generated).
Runtime substitution variables have a higher precedence than substitution variables.
Therefore, if a substitution variable and a runtime substitution variable have the same name
(for example, myProduct), the value of the runtime substitution variable overwrites the
value of the substitution variable.
If multiple runtime substitution variables have the same name but have different values,
only the value of the first instance of the runtime substitution variable is used; all other
subsequent values are ignored.
The rules for setting names and values for runtime substitution variables are the same as for
substitution variables. See Rules for Setting Substitution Variable Names and Values on page
122.
470
Specifying Data Type and Input Limit for Runtime Substitution Variables
In the SET RUNTIMESUBVARS calculation command, the runtime substitution variable
declaration can include the <RTSV_HINT>rtsv_description</RTSV_HINT> tag, in which
rtsv_description is a string that describes the data type and data input limit (for example,
an integer not greater than 100) for the runtime substitution variable. The </RTSV_HINT> string
is not used in the calculation.
The EssGetRuntimeSubVars API retrieves all of the information (name, value, and description)
that is specified in the runtime substitution variable declaration in SET RUNTIMESUBVARS.
The <RTSV_HINT> string can then be used to prompt a user to input a value at runtime or to
validate input data before passing the value to the calculation script.
In this example of SET RUNTIMESUBVARS, each declaration specifies only the name and
description of the runtime substitution variable; a default value is not specified:
SET RUNTIMESUBVARS
{
myMarket <RTSV_HINT>myMarket: Input the value as a string, such as "New York"</
RTSV_HINT>;
salesNum <RTSV_HINT>salesNum: Input the value as an integer, such as 100</RTSV_HINT>;
pointD <RTSV_HINT>pointD: Input the value as a member combination, such as "Actual">"Final"</RTSVVAR_HINT>;
};
471
Cannot include nonalphanumeric characters, such as hyphens (-), asterisks (*), and
slashes (/)
Cannot exceed 320 bytes for Unicode-mode applications and 320 characters for nonUnicode mode applications
For non-numeric values, if you do not enclose the value in quotation marks when you
define the environment variable, Essbase automatically encloses the value with
quotation marks when the environment variable is passed.
For numeric values, Essbase does not automatically enclose the value with quotation
marks when the variable is passed because Essbase cannot determine if you intend to
pass a numeric value or a member name. For example, if you use a calculation script
statement such as 'Sales = $MY_SALES' where MY_SALES=700, the intent is to pass
the numeric value of 700. If, however, Essbase encloses MY_SALES in quotation marks,
MY_SALES is treated as a member name. The member name would be passed, not the
numeric value, causing an error. If you want the numeric value of the variable to be
treated as a string, you must enclose the value with quotation marks when you define
the environment variable.
m
Cannot exceed 256 bytes for Unicode-mode applications and 256 characters for nonUnicode mode applications
For example, you can use an environment variable to define the path and filename for an export
file when exporting a block of data to a flat file. In the following calculation script, the path and
filename (E:\temp\export1.txt) are explicitly defined:
SET DATAEXPORTOPTIONS
{
DATAEXPORTLEVEL "ALL";
DATAEXPORTOVERWRITEFILE ON;
};
FIX ("New York", "100-10");
DATAEXPORT "File" "," "E:\temp\export1.txt";
ENDFIX;
You can declare an environment variable (ENV_FILE) to reference the path and filename
(ENV_FILE="E:\temp\export1.txt") and use the following syntax in the calculation script:
DATAEXPORT "File" "," $ENV_FILE;
Essbase replaces the environment variable with the value taken from the user's environment.
In the following example, another environment variable (CurrMbr) is defined to export only
Sales values (CurrMbr="Sales"):
472
SET DATAEXPORTOPTIONS
{
DATAEXPORTLEVEL "ALL";
DATAEXPORTOVERWRITEFILE ON;
};
FIX ("New York", "100-10", $CurrMbr);
DATAEXPORT "File" "," $ENV_FILE;
ENDFIX;
Environment variables can also be used to parse arguments passed to RUNJAVA, an Essbase
utility in which custom-defined functions can be called directly from a calculation script. For
example, you can use environment variables to get user e-mail addresses.
In the following example, the RUNJAVA statement sends an e-mail notification to explicitlydefined users (to@somedomain.com and cc@mydomain.com):
RUNJAVA com.hyperion.essbase.calculator.EssbaseAlert "localhost" to@somedomain.com
"cc@mydomain.com" "" "" "Mail Subject" "Mail Body" "";
Clearing Data
Copying Data
You can clear a subset of data from a database and copy data values from one set of members to
another set of members.
Clearing Data
Table 85 lists the commands that clear data:
Table 85
Command
Calculation
CLEARDATA
Change the values of the cells you specify to #MISSING; the data blocks are not removed.
Use the FIX command with the CLEARDATA command to clear a subset of a database.
CLEARBLOCK
Remove the entire contents of a block, including all the dense dimension members.
Essbase removes the entire block, unless CLEARBLOCK is inside a FIX command on members within the block.
CLEARBLOCK UPPER
473
Command
Calculation
CLEARBLOCK
NONINPUT
Remove blocks containing derived values. Applies to blocks that are completely created by a calculation
operation, not to blocks into which any values were loaded.
CLEARBLOCK
DYNAMIC
CLEARBLOCK EMPTY
The following calculation script command yields different results depending on whether the
Scenario dimension is dense or sparse:
FIX(Actual)
CLEARBLOCK NONINPUT;
ENDFIX
l
Dense: The command removes all data cells that do not contain input data values and that
intersect with the member Actual from the Scenario dimension.
Sparse: The command removes only the blocks whose Scenario dimension member is
Actual.
The following formula clears all the Actual data values for Colas:
CLEARDATA Actual -> Colas;
To clear an entire database, see Clearing Data in the Oracle Essbase Administration Services
Online Help.
Copying Data
The DATACOPY calculation command copies data cells from one range of members to another
range of members in a database. The two ranges must be the same size. For example, the following
formula copies Actual values to Budget values:
DATACOPY Actual TO Budget;
You can use the FIX command to copy a subset of values. For example, the following formula
copies Actual values to Budget values for the month of January only:
FIX (Jan)
DATACOPY Actual TO Budget;
ENDFIX
474
Note: When Intelligent Calculation is turned on, the newly calculated data blocks are not
marked as clean after a partial calculation of a database. When you calculate a subset of
a database, you can use the SET CLEARUPDATESTATUS AFTER command to ensure
that the newly calculated blocks are marked as clean. Using this command ensures that
Essbase recalculates the database as efficiently as possible using Intelligent Calculation.
See Chapter 26, Understanding Intelligent Calculation.
The following example fixes on member combinations for the children of East that have a UDA
of New Mkt:
FIX(@CHILDREN(East) AND @UDA(Market,"New Mkt"))
Marketing = Marketing * 1.1;
ENDFIX
The following example uses a wildcard match (???) to fix on member names that end in the
characters -10, which are members 100-10, 200-10, 300-10, and 400-10:
FIX(@MATCH(Product, "???-10"))
Price = Price * 1.1;
ENDFIX
475
When you use the FIX command only on a dense dimension, Essbase retrieves the entire block
that contains the required value or values for the members that you specify. I/O is not affected,
and the calculation performance time is improved.
When you use the FIX command on a sparse dimension, Essbase retrieves the block for the
specified sparse dimension members. I/O may be greatly reduced.
Essbase cycles through the database once for each FIX command that you use on dense
dimension members. When possible, combine FIX blocks to improve calculation performance.
For example, by using one FIX command, the following calculation script causes Essbase to cycle
through the database only once, calculating both the Actual and the Budget values:
FIX(Actual,Budget)
CALC DIM(Year, Measures);
ENDFIX
In contrast, by using two FIX commands, the following calculation script causes Essbase to cycle
through the database twice: once calculating the Actual data values and once calculating the
Budget data values:
FIX(Actual)
CALC DIM(Year, Measures);
ENDFIX
FIX(Budget)
CALC DIM(Year, Measures);
ENDFIX
You cannot FIX on a subset of a dimension that you calculate within a FIX command. For
example, the following calculation script returns an error message because the CALC DIM
operation calculates the entire Market dimension, although the FIX above it fixes on specific
members of the Market dimension:
FIX(@CHILDREN(East) AND @UDA(Market,"New Mkt"))
CALC DIM(Year, Measures, Product, Market);
ENDFIX
FIX commands can be nested within other FIX command blocks. However, using nested FIX
commands incorrectly can result in incorrect results. For example, the intent of the following
calculation script is to assign 1 to all children of East and then assign 2 to New York:
FIX (@CHILDREN(EAST))
''100-10''=1;
FIX (''New York'')
''100-10''=2;
ENDFIX
ENDFIX
However, the nested FIX command fixes on a subset of the dimension that is specified by the
FIX command above it (which is not allowed); therefore, the script assigns 2 to all children of
East because the script runs as if it were written as:
FIX (@CHILDREN(EAST),''New York'')
''100-10''=1;
''100-10''=2;
ENDFIX
476
Rather than using nested FIX commands, use two separate FIX command blocks. For example:
FIX (@CHILDREN(EAST))
''100-10''=1;
ENDFIX
FIX (''New York'')
''100-10''=2;
ENDFIX
The FIX command has restrictions. See the Oracle Essbase Technical Reference.
477
DATAEXPORT parameters;
ENDFIX;
The following tables list the SET DATAEXPORTOPTIONS commands, which are all optional:
l
Table 86
Command
Calculation
DATAEXPORTLEVEL
The values are case-insensitive. For example, you can specify LEVEL0 or level0.
Enclosing the value in quotation marks is optional. For example, you can specify LEVEL0 or
LEVEL0.
If the value is not specified, Essbase uses the default value of ALL.
If the value is incorrectly expressed (for example, LEVEL 0 or LEVEL2), Essbase uses the default
value of ALL.
DATAEXPORTDYNAMICCALC
DATAEXPORTNONEXISTINGBLOCKS
Specify whether to export data from all potential data blocks or only from existing data blocks
DATAEXPORTDECIMAL
DATAEXPORTPRECISION
Table 87
Command
Calculation
DATAEXPORTCOLFORMAT
DATAEXPORTCOLHEADER
DATAEXPORTDIMHEADER
Include a header record that lists all dimension names in the same order as the data in the file
DATAEXPORTRELATIONALFILE
Format the text export file for importing the data into a relational database
Table 88
Command
Calculation
DATAEXPORTOVERWRITEFILE
Specify whether an existing file with the same name and location is replaced
DATAEXPORTDRYRUN
Enable validating the set of calculation commands and viewing export statisticsincluding a time estimate
without having to perform the entire export process
478
Specify the SET DATAEXPORTOPTIONS command to define options for export content (see Table 86 on
page 478), format (see Table 87 on page 478), and process (see Table 88 on page 478).
If you are using the DATAEXPORT command to insert the exported data directly into a
relational database, see Exporting Data into a Relational Database on page 479.
Use the DATAIMPORTBIN calculation command to import a previously exported binary export file.
Note: DATAIMPORTBIN is not supported across Essbase releases or between 32-bit and
The table to which the data is to be written must exist prior to data export
By default, when inserting exported data, Essbase uses the row-insert method, in which each
row is inserted one at a time. To improve performance, you can use the batch-insert method if
your relational database and the ODBC driver support the functionality.
Note: 64-bit Essbase does not support using the DATAEXPORT batch-insert method to export
479
set to 1, batch insert is disabled (as a DEXPSQLROWSIZE setting of 1 inserts rows one
at a time).
Advantages
m
Supports multiple targets: flat files, relational databases, and binary files
Disadvantages
m
480
In the following example, assume that you want to create budget sales and expense data from
existing actual data. Sales and Expenses are members in the dense Measures dimension; Budget
and Actual are members in the sparse Scenario dimension.
FIX(Budget)
(Sales = Sales -> Actual * 1.1;
Expenses = Expenses -> Actual * .95;)
ENDFIX
Sales and Expenses, the results of the equations, are dense dimension members; the operand,
Actual, is in a sparse dimension. Because Essbase executes dense member formulas only on
existing data blocks, the calculation script does not create the required data blocks and Budget
data values are not calculated for blocks that do not already exist.
You can solve the problem using the following techniques:
l
Essbase creates blocks that contain the Budget values for each corresponding Actual block that
exists. After the DATACOPY commands are finished, the remaining part of the script changes
the values.
Using DATACOPY works well in these situations:
l
There is a mathematical relationship between values in existing blocks and their counterparts
created by the DATACOPY.
For example, in the preceding example, the Budget values can be calculated based on the
existing Actual values.
Caution!
DATACOPY creates the new blocks with identical values in all cells from the
source blocks. If the formula performs only on a portion of the block, these
copied cells remain at the end of the calculation, potentially resulting in
unwanted values.
None of the blocks that are copied contain only #MISSING values.
If #MISSING values exist, blocks are written that contain only #MISSING values. Unneeded
#MISSING blocks require Essbase resource and processing time.
481
482
Redesign the overall calculation to avoid referencing remote values that are in a
transparent partition in a remote database.
Dynamically calculate a value in a remote database.
See Dynamically Calculating Data in Partitions on page 443.
Ensure that a referenced value is up-to-date when Essbase retrieves it. Choose one of the
options previously discussed (redesign, dynamically calculate, or replicate) or calculate the
referenced database before calculating the formula.
See Chapter 15, Designing Partitioned Applications and Chapter 16, Creating and
Maintaining Partitions.
Calculating Partitions
West, Central, and East contain only actual values. Corporate contains actual and budgeted
values. Although you can view West, Central, and East data in the Corporate database, the data
exists only in the West, Central, and East databasesit is not duplicated in the Corporate
database.
Therefore, when Essbase calculates Corporate, it must take the latest values from West, Central,
and East. To obtain the required results, you must calculate West, Central, and East before you
calculate Corporate.
As an artifact on an Essbase Server, which allows other users to access the calculation script.
You can associate the script with the following artifacts:
An application and all the databases within the application, which lets you run the script
against any database in the application.
Calculation scripts associated with an application are saved in the ARBORPATH/app/
appname directory on the Essbase Server computer.
A database, which lets you run the script against the specified database.
Calculation scripts associated with a database are saved in the ARBORPATH/app/
appname/dbname directory on the Essbase Server computer.
Topic
Location
Administration Services
MaxL
execute calculation
484
Tool
Topic
Location
ESSCMD
RUNCALC
Smart View
Calculating Data
Topic
Location
Administration Services
Copying Scripts
MaxL
create calculation as
ESSCMD
COPYOBJECT
Calculation order of the dimensions for each pass through the database
To display more-detailed information, you can use the SET MSG SUMMARY, SET MSG
DETAIL, and SET NOTICE commands in a calculation script. See Specifying Global Settings
for a Database Calculation on page 463.
You can use these messages to understand how the calculation is performed and to tune it for
the next calculation.
Where you view this information depends on the tool used to execute the calculation script.
l
485
486
30
Reviewing Examples of
Calculation Scripts for Block
Storage Databases
In This Chapter
About These Calculation Script Examples ............................................................. 487
Calculating Variance ..................................................................................... 487
Calculating Database Subsets.......................................................................... 488
Loading New Budget Values ............................................................................ 489
Calculating Product Share and Market Share Values................................................. 490
Allocating Costs Across Products....................................................................... 491
Allocating Values within a Dimension.................................................................. 492
Allocating Values Across Multiple Dimensions ........................................................ 494
Goal-Seeking Using the LOOP Command.............................................................. 496
Forecasting Future Values............................................................................... 499
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see Chapter 60, Comparison of Aggregate and Block Storage.
Calculating Variance
This example includes a calculation of the variance percentage between Budget and Actual
values.
Figure 134 shows an outline in which Variance and Variance % are tagged as Dynamic Calc,
two-pass members.
487
Figure 134
During a default calculation, Essbase aggregates the values on the Market and Product
dimensions. Because percentage values do not aggregate correctly, the Variance % formula must
be recalculated after the default calculation.
Because Variance % is tagged as a Dynamic Calc, two-pass member, Essbase dynamically
calculates Variance % values when they are retrieved. The dynamic calculation overwrites the
incorrect values with the correctly calculated percentages.
If you choose not to tag Variance % as a Dynamic Calc, two-pass member, use the following
calculation scriptwhich assumes that Intelligent Calculation is turned on (the default)to
perform a default calculation and to recalculate the formula on Variance %:
CALC ALL;
SET UPDATECALC OFF;
SET CLEARUPDATESTATUS AFTER;
"Variance %";
488
Figure 135
Example script:
/* Calculate the Budget data values for the descendants of East */
FIX(Budget, @DESCENDANTS(East))
CALC DIM(Year, Measures, Product);
ENDFIX
/* Consolidate East */
FIX(Budget)
@DESCENDANTS(East);
ENDFIX
Market Share
Product Share
Market %
Product %
Example script:
/* First consolidate the Sales values to ensure that they are accurate */
FIX(Sales)
CALC DIM(Year, Market, Product);
ENDFIX
/* Calculate each market as a percentage of the total market for each product */
"Market Share" = Sales % Sales -> Market;
/* Calculate each product as a percentage of the total product for each market */
"Product Share" = Sales % Sales -> Product;
/* Calculate each market as a percentage of its parent for each product */
"Market %" = Sales % @PARENTVAL(Market, Sales);
/* Calculate each product as a percentage its parent for each market */
"Product %" = Sales % @PARENTVAL(Product, Sales);
490
2. Cycles through the database and calculates Market Share by taking the Sales value for each
product in each market for each month and calculating this Sales value as a percentage of
total Sales in all markets for each product (Sales -> Market).
3. Calculates Product Share by taking the Sales value for each product in each market for each
month and calculating this Sales value as a percentage of total Sales of all products in each
market (Sales -> Product).
4. Calculates Market % by taking the Sales value for each product in each market for each
month and calculating this Sales value as a percentage of the Sales value of the parent of the
current member on the Market dimension.
The @PARENTVAL function is used to obtain the Sales value of the parent on the Market
dimension.
5. Calculates Product % by taking the Sales value for each product in each market for each
month, and calculating this Sales value as a percentage of the Sales value of the parent of the
current member on the Product dimension.
The @PARENTVAL function is used to obtain the Sales value of the parent on the Product
dimension.
Example script:
/* Declare a temporary array called ALLOCQ based on the Year dimension */
ARRAY ALLOCQ[Year];
/* Turn the Aggregate Missing Values setting off. If this is your system default, omit
this line */
SET AGGMISSG OFF;
/* Allocate the overhead costs for Actual values */
FIX(Actual)
OH_Costs (ALLOCQ=Sales/Sales->Product; OH_Costs =
OH_TotalCost->Product * ALLOCQ;);
/* Calculate and consolidate the Measures dimension */
CALC DIM(Measures);
ENDFIX
491
Cycles through the member combinations for Actual and calculates OH_Costs.
Takes the Sales value for each product in each market for each month and calculates it
as a percentage of total Sales for all products in each market (Sales -> Product). The
result is placed in ALLOCQ.
Takes the total overhead costs for all products (OH_TotalCost -> Product) and
multiplies it by the value it has just placed in ALLOCQ. The result is placed in OH_Costs.
Note that both equations are enclosed in parentheses ( ) and associated with the
OH_Costs member: OH_Costs (equation1; equation2;).
Removed the Dynamic Calc tag from the Total Expenses member
492
Figure 136
Assume that data values of 1000 and 2000 are loaded into Budget -> Total Expenses for Colas
and Root Beer, respectively. These values must be allocated to each expense category, evenly
spreading the values based on the nonmissing children of Total Expenses from PY Actual. The
allocated values must be rounded to the nearest dollar.
Example script:
/* Allocate budgeted total expenses based on prior year */
FIX("Total Expenses")
Budget = @ALLOCATE(Budget->"Total Expenses",
@CHILDREN("Total Expenses"),"PY Actual",,
spread,SKIPMISSING,roundAmt,0,errorsToHigh)
ENDFIX
Root Beer
Marketing
Payroll
Lease
Misc
Total Expenses
Marketing
Payroll
Lease
Misc
Total Expenses
Budget
334 *
#MI
333
333
1000
500
500
500
500
2000
PY Actual
150
#MI
200
100
450
300
200
200
400
1100
493
In this case, 1 is divided by 3, because there are 3 nonmissing expense values for Budget ->
Colas.
3. Takes the value from step 2 (.333), multiplies it by the value for Budget -> Colas -> Total
Expenses (1000), and rounds to the nearest dollar (333). The result is placed in Budget ->
Colas -> Marketing.
4. Repeats steps 2 and 3 for each expense category for Budget -> Colas and then for Budget > Root Beer.
5. As specified in the calculation script, rounds allocated values to the nearest whole dollar.
Essbase makes a second pass through the block to make the sum of the rounded values equal
to the allocation value (for example, 1000 for Budget -> Colas -> Total Expenses). In this
example, there is a rounding error of 1 for Budget -> Colas -> Total Expenses, because the
expense categories add up to 999, not 1000, which is the allocation value. Because all allocated
values are identical (333), the rounding error of 1 is added to the first value in the allocation
range, Budget -> Colas -> Marketing (thus a value of 334).
For this example, a value of 750 (for Budget -> Total Expenses -> Product -> East -> Jan) must
be allocated to each expense category for the children of product 100 across the states in the East.
The allocation uses values from PY Actual to determine the percentage share that each category
should receive.
Example script:
/* Allocate budgeted total expenses based on prior year, across 3 dimensions */
SET UPDATECALC OFF;
FIX (East, 100, Total Expenses)
BUDGET = @MDALLOCATE(750,3,@CHILDREN(100),@CHILDREN("Total
Expenses"),@CHILDREN(East),"PY Actual",,share);
ENDFIX
494
New York
Massachusetts
Marketing
94
23
Payroll
51
31
Misc
0
1
Total Expenses
145
55
100-20
100-30
100
Florida
Connecticut
New Hampshire
New York
Massachusetts
Florida
Connecticut
New Hampshire
New York
Massachusetts
Florida
Connecticut
New Hampshire
New York
Massachusetts
Florida
Connecticut
New Hampshire
East
27
40
15
199
#MI
#MI
26
#MI
#MI
26
#MI
#MI
#MI
#MI
12
12
94
23
237
31
31
31
175
#MI
#MI
23
#MI
#MI
23
#MI
#MI
#MI
#MI
22
22
51
31
220
0
0
1
2
#MI
#MI
0
#MI
#MI
0
#MI
#MI
#MI
#MI
1
1
0
1
3
58
71
47
376
#MI
#MI
49
#MI
#MI
49
#MI
#MI
#MI
#MI
35
35
145
55
460
New York
Massachusetts
Marketing
153.26
37.50
Payroll
83.15
50.54
Misc
0
1.63
Total Expenses
236.41
89.67
495
100-20
100-30
100
Florida
Connecticut
New Hampshire
New York
Massachusetts
Florida
Connecticut
New Hampshire
New York
Massachusetts
Florida
Connecticut
New Hampshire
New York
Massachusetts
Florida
Connecticut
New Hampshire
East
44.02
65.22
24.26
#MI
#MI
42.39
#MI
#MI
#MI
#MI
#MI
#MI
19.57
153.26
37.50
86.41
65.22
44.02
386.41
50.54
50.54
50.54
#MI
#MI
37.50
#MI
#MI
#MI
#MI
#MI
#MI
35.87
83.15
50.54
88.04
50.54
86.41
358.70
0
0
1.63
#MI
#MI
0
#MI
#MI
#MI
#MI
#MI
#MI
1.63
0
1.63
0
0
3.26
4.89
94.56
115.76
76.63
#MI
#MI
79.89
#MI
#MI
#MI
#MI
#MI
#MI
57.07
236.41
89.67
174.46
115.76
133.70
750
Measures Dimension
Assume that, before running the goal-seeking calculation script, the data values are:
Product, Market, Budget
Profit
Margin
Sales
COGS
Total Expenses
Marketing
Payroll
496
Jan
12,278.50
30,195.50
49,950.00
19,755.00
17,917.00
3,515.00
14,402.00
Misc
Inventory
Ratios
Margin %
Profit %
0
Label Only member
Label Only member
60.45
24.58
Example script:
/* Declare the temporary variables and set their initial values*/
VAR
Target = 15000,
AcceptableErrorPercent = .001,
AcceptableError,
PriorVar,
PriorTar,
PctNewVarChange = .10,
CurTarDiff,
Slope,
Quit = 0,
DependencyCheck,
NxtVar;
/*Declare a temporary array variable called Rollback based on the Measures dimension */
ARRAY Rollback [Measures];
/* Fix on the appropriate member combinations and perform the goal-seeking calculation*/
FIX(Budget, Jan, Product, Market)
LOOP (35, Quit)
Sales (Rollback = Budget;
AcceptableError = Target * (AcceptableErrorPercent);
PriorVar = Sales;
PriorTar = Profit;
Sales = Sales + PctNewVarChange * Sales;);
CALC DIM(Measures);
Sales (DependencyCheck = PriorVar - PriorTar;
IF(DependencyCheck <> 0) CurTarDiff = Profit - Target;
IF(@ABS(CurTarDiff) > @ABS(AcceptableError))
Slope = (Profit - PriorTar) / (Sales - PriorVar);
NxtVar = Sales - (CurTarDiff / Slope);
PctNewVarChange = (NxtVar - Sales) / Sales;
ELSE
Quit = 1;
ENDIF;
ELSE
Budget = Rollback;
Quit = 1;
ENDIF;);
ENDLOOP
CALC DIM(Measures);
ENDFIX
497
g. Subtracts the PriorTar value from the PriorVar value, and places the result in the
DependencyCheck temporary variable.
h. Checks that DependencyCheck is not 0 (zero) (IF).
l
If DependencyCheck is not 0, subtracts the Target value (15000) from the current
Profit and places the result in the CurTarDiff temporary variable.
The IF command checks whether the absolute value (irrespective of the + or
sign) of CurTarDiff is greater than the absolute value of AcceptableError:
m
498
Jan
15,000.00
32,917.00
52,671.50
19,755.00
Total Expenses
Marketing
Payroll
Misc
Inventory
Ratios
Margin %
Profit %
17,917.00
3,515.00
14,402.00
0
Label Only member
Label Only member
28.47839913
62.49489762
Parameters Used in the Example Calculation Script for Forecasting Future Values
Parameter
Description
@LIST(Jan,Mar,Apr)
Represents the Ylist, or the members that contain the known data values.
The @LIST function groups the three members as a comma-delimited list and keeps the list separate from
other parameters.
@LIST(1,3,4)
Represents the Xlist, or the underlying variable values. Because Feb and May are skipped, Essbase
numbers the Ylist values as 1,3,4.
The extra comma after the Xlist parameter indicates that a parameter (weightList) was skipped.
This example uses a default weight of 1.
@RANGE(ErrorLR,
@LIST(Jan,Mar,Apr)
Represents the errorList, or the member list where results of the goodness of fit of the trend line to
Ylist are placed.
The values placed in errorList are the differences between the data points in Ylist and the data points
on the trend line that is produced.
The @RANGE function combines the ErrorLR member with Ylist (Jan, Mar, Apr) to produce a member list.
@LIST(6,7,8,9,10,11,12)
Represents the XforecastList, or the underlying variable values for which the forecast is sought. This
example forecasts values consecutively for JunDec, so the values are 6,7,8,9,10,11,12.
499
Parameter
Description
Jun:Dec
Represents the YforecastList, or the member list into which the forecast values are placed. This example
forecasts values for JunDec, based on the values for Jan, Mar, and Apr.
LR
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
Sep
Oct
Nov
Dec
500
31
In This Chapter
Using CALCPARALLEL Parallel Calculation............................................................. 502
Using FIXPARALLEL Parallel Calculation ............................................................... 511
Regardless of how a calculation is triggered, Essbase can execute the calculation in one of two
modes:
l
Serial calculation is the default. With serial calculation, each calculation pass is scheduled to
run on a single processor. If invoked from a calculation script, the calculations are executed
sequentially in the order in which they appear in the calculation script.
Parallel calculation breaks each calculation pass into sub-tasks. The sub-tasks that can run
independently of one another are scheduled to run simultaneously on up to 64 or 128
threads. Block storage databases running on 32-bit platforms support up to 64 threads. Block
storage databases running on 64-bit platforms and aggregate storage databases (whether
running on 32-bit or 64-bit platforms) support up to 128 threads. Each thread may be on a
different processor.
Note: Parallel calculation operations do not dynamically create threads, but instead use a set
number of threads from a pre-created pool of threads. You can customize the size of the
thread pool. For more information, see the WORKERTHREADS configuration setting
topic in the Oracle Essbase Technical Reference.
501
To change from the default serial calculation to CALCPARALLEL parallel calculation, you
change one or two configuration settings and restart the server, or add an instruction to the
calculation script.
See Enabling CALCPARALLEL Parallel Calculation on page 507.
The following topics discuss the details of parallel calculation.
502
Use the uncommitted access isolation level. Parallel calculation is not supported if you use
the committed access isolation level. See Uncommitted Access on page 781.
One or more formulas present in a calculation may prevent Essbase from using
CALCPARALLEL parallel calculation even if it is enabled. For a description of formulas that
may force serial calculation regardless of parallel calculation settings, see Formula
Limitations on page 504.
Calculation tasks are generated along the last n sparse dimensions of an outline. These sparse
dimensions used to identify tasks are called task dimensions. The number of task
dimensions, n, is either selected dynamically by Essbase, or you can override the number by
specifying a value for CALCTASKDIMS in the essbase.cfg file.
Order the sparse dimensions in an outline from smallest to largest, based on actual size of
the dimension (as reported by the MaxL statement query database DBS-NAME get dbstats
dimension). This ordering recommendation is consistent with recommendations for
optimizing calculator cache size and consistent with other outline recommendations. For a
description of situations that may need to use additional dimensions (more than the last
sparse dimension) and for instructions on how to increase the number of sparse dimensions
used, see Identifying Additional Tasks for Parallel Calculation on page 508.
Replicated partitions
Linked partitions
Transparent partitions if the calculation occurs at the target database. The number of
sparse dimensions specified by CALCTASKDIMS in the essbase.cfg file or by SET
CALCTASKDIMS in a calculation script must be set at 1. For information on limitations
imposed by the use of parallel calculation with transparent partitions, see Transparent
Partition Limitations on page 505; for information on using CALCTASKDIMS or
SET CALCTASKDIMS, see Identifying Additional Tasks for Parallel Calculation on
page 508.
If you have selected incremental restructuring for a database and have made outline changes
that are pending a restructure, do not use parallel calculation. Unpredictable results may
occur.
Update transactions, such as calculations and data updates, are more resource-consuming
requests than MDX queries or report scripts. When a storage device is fast, Essbase allows
more parallel calculation threads to get reasonable throughput; when a storage device is
slower, Essbase may need to have a smaller number of parallel calculation or other update
threads. You can use the Essbase.cfg setting MAXACTIVEUPDATETRANSACTIONS
to control the number of update transactions. For more information, see the topic for
MAXACTIVEUPDATETRANSACTIONS in the Oracle Essbase Technical Reference.
503
Retrieval Performance
Placing the largest sparse dimension at the end of the outline for maximum parallel calculation
performance may slow retrieval performance. See Optimizing Query Performance on page
93.
Formula Limitations
The presence of some formulas may force serial calculation. The following formula placements
likely will force serial calculation:
l
A formula on a dense member, including all stored members and any Dynamic Calc
members upon which a stored member may be dependent, that causes a dependence on a
member of the dimension that is used to identify tasks for parallel calculation.
A formula that contains references to variables declared in a calculation script that uses
@VAR, @ARRAY, @XREF, or @XWRITE. Consider using FIXPARALLEL.
A sparse dimension member formula using @XREF, and the dimension for the sparse
member is fully calculated. @XREF does not force serial calculation when it is on dense
Dynamic Calc members that are not dependent on other stored members during the batch
calculation.
A member formula that causes a circular dependence. For example, member A has a formula
referring to member B, and member B has a formula referring to member C, and member
C has a formula referring to member A.
A formula on a dense or sparse member with a dependency on a member or members from
the dimension used to identify tasks for parallel processing.
A sparse dimension member formula that contains references to members from other sparse
dimensions.
If you need to use a formula that might prevent parallel calculation, consider using
FIXPARALLEL. Otherwise, you can either mark the member of the formula as Dynamic Calc,
or exclude the formula from the scope of the calculation. To see whether a formula is preventing
parallel calculation, check the application log. For relevant error messages, see Monitoring
CALCPARALLEL Parallel Calculation on page 509.
Calculator Cache
At the start of a calculation pass, Essbase checks the calculator cache size and the degree of
parallelism and then uses the calculator cache bitmap option appropriate for maximum
performance. Therefore, the bitmap option used for parallel calculation may be different from
that used for serial calculation.
For example, assume Essbase performs a serial calculation and uses multiple bitmaps and a single
anchoring dimension. Without explicit change of the calculator cache size, Essbase might
perform a parallel calculation using only a single bitmap and a single anchoring dimension.
You can determine the calculator cache mode that controls the bitmap options by checking the
application log at the start of each calculation pass for an entry similar to the following:
504
Multiple bitmap mode calculator cache memory usage has a limit of [50000] bitmaps.
When using parallel calculation in multiple bitmap mode, you may encounter high memory
usage. If so, you can use the configuration setting PARCALCMULTIPLEBITMAPMEMOPT to
optimize memory use in multiple bitmap mode. This setting can be used with, or separately
from, MULTIPLEBITMAPMEMCHECK. To enable
PARCALCMULTIPLEBITMAPMEMOPT, add the following line to your essbase.cfg file:
PARCALCMULTIPLEBITMAPMEMOPT TRUE
You cannot use parallel calculation across transparent partitions unless the calculation
occurs at the target.
You must set CALCTASKDIMS or SET CALCTASKDIMS to 1 so that there is only one task
dimension.
You must increase the calculator cache so that multiple bitmaps can be used. You can identify
the calculator cache mode that controls the bitmap options by checking the application log
at the start of each calculation pass for an entry similar to the following:
Multiple bitmap mode calculator cache memory usage has a limit of [50000] bitmaps.
Restructuring Limitation
Do not use parallel calculation if you have selected incremental restructuring. Parallel calculation
does not support incremental restructuring.
505
Topic
Location
Administration Services
MaxL
ESSCMD
Topic
Location
Administration
Services
MaxL
ESSCMD
SETDBSTATEITEM 21
Topic
Location
Administration Services
MaxL
ESSCMD
SETDBSTATEITEM 18
To check whether parallel calculation has been enabled in the server configuration file:
1
Search for the parameter CALCPARALLEL, and check its specified value.
The number of threads that can simultaneously perform tasks to complete a calculation is
specified by a value between 1 and 128. Block storage databases running on 32-bit platforms
support up to 64 threads. Block storage databases running on 64-bit platforms and aggregate
storage databases (whether running on 32-bit or 64-bit platforms) support up to 128 threads.
See the Oracle Essbase Technical Reference.
To check whether a calculation script sets parallel calculation, look for the SET CALCPARALLEL
command. Review the script carefully, because the script may enable or disable parallel
calculation more than once. Alternately, a script can use FIXPARALLEL command blocks for
parallel calculation.
Setting parallel calculation at the server level enables it for all calculations performed on all
applications and databases on the server. You can disable parallel calculation for individual
applications or databases by setting parallel calculation at the server level in the configuration
file and then adding application-specific or database-specific entries in a calculation script.
Caution!
If you plan to enable parallel calculation in the configuration file, check the current status to see whether
an entry exists.
Use the process described in Checking Current CALCPARALLEL Settings on page 506.
507
Add or modify CALCPARALLEL in the essbase.cfg file on the server, or add SET CALCPARALLEL to
a calculation script.
If needed, enable Essbase to use more than the one sparse dimension to identify tasks for parallel
calculation.
Use the process described in Identifying Additional Tasks for Parallel Calculation on page
508 and Tuning CALCPARALLEL with Log Messages on page 509.
Oracle recommends that you set the value of CALCPARALLEL to be one less than the number
of processors available for calculation. This extra processor can then be used by either the
operating system or by the Essbase process responsible for writing out dirty blocks from the
cache.
Tip: You can combine the use of CALCPARALLEL and SET CALCPARALLEL if the site requires
it. For example, you can set CALCPARALLEL as off at the server level, and use a calculation
script to enable and disable parallel calculation as needed.
Optional: Essbase selects a default number, n, of task dimensions to use for parallel calculation and
this number is printed in the application log file as an informational message; for example:
Parallelizing using [2] task dimensions. To override the default n setting, add or
modify CALCTASKDIMS in the essbase.cfg file on the server, or use the calculation script command
SET CALCTASKDIMS at the top of the script.
If you add or modify CALCTASKDIMS in the essbase.cfg file on the server, restart Essbase.
Note: In some cases, Essbase uses fewer dimensions to identify tasks than is specified by
508
If this message is encountered, it means that during a parallel calculation, Essbase refrained from
increasing the number of task dimensions, in case that would have resulted in tasks becoming
too small. When tasks become too small, calculation scheduling overhead could overtake the
benefits of parallelism. However, when tasks are too large, there might not be enough tasks for
parallel calculation threads to work on.
If the next potential task dimension is not the first sparse dimension, consider increasing the
number of task dimensions by one using SET CALCTASKDIMS, and observe whether that
improves the speed of the calculation. Also, consider using FIXPARALLEL to make custom task
selections that are different from CALCPARALLEL (see Using FIXPARALLEL Parallel
Calculation on page 511).
Current number of task dimensions [n] for parallel calculation might
have caused too many tasks [n] to be generated. See whether calculation
time can be improved by decreasing the number of task dimensions by one
(see SET CALCTASKDIMS topic in the Technical Reference). Also, consider
using FIXPARALLEL to make custom task selections that are different
from CALCPARALLEL.
For parallel calculation, having a sufficient number of tasks helps to reduce the effects of data
skew. However, too many tasks (even for appropriately sized tasks) can cause the scheduling
overhead to outweigh the benefits. Essbase targets an optimal range. If you see the above message,
it means that Essbase tried to meet the recommended minimum number of tasks by adding one
more task dimension; in doing so, it is possible that the upper boundary for task count may have
been crossed.
If the last task dimension selected by Essbase is not the only task dimension, consider decreasing
task dimensions by one using SET CALCTASKDIMS, and observe whether that improves the
speed of the calculation. Also, consider using FIXPARALLEL to make custom task selections
that are different from CALCPARALLEL (see Using FIXPARALLEL Parallel Calculation on
page 511).
509
If you have enabled parallel calculation and Essbase has determined that parallel calculation
can be performed, Essbase writes a message in the application log:
Calculating in parallel with n threads
SETCALCPARALLEL.
l
For each formula that prevents parallel calculation (forces serial calculation), Essbase writes
a message to the application log:
Formula on ((or backward dependence from) mbr memberName prevents calculation from
running in parallel.
memberName represents the name of the member where the relevant formula exists. You
can look in the application log for such messages and consider removing the formula or, if
possible, tagging the relevant member or members as Dynamic Calc so they do not feature
in the calculation pass.
l
Essbase writes a message to the application log specifying the number of tasks that can be
executed concurrently (based on the data, not the value of CALCPARALLEL or
SETCALCPARALLEL):
Calculation task schedule [576,35,14,3,2,1]
The example message indicates that 576 tasks can be executed concurrently. After the 576
tasks complete, 35 more can be performed concurrently, and so on.
The benefit of parallel calculation is greatest in the first few steps and diminishes as fewer
concurrent tasks are performed.
The degree of parallelism depends on the number of tasks in the task schedule. The greater
the number, the more tasks that can run in parallel, and the greater the performance gains.
l
Essbase writes a message to the application log file indicating how many tasks are empty
(contain no calculations):
[Tue Jun 27 12:30:44 2007]Local/CCDemo/Finance/essexer/
Info(1012681) Empty tasks [291,1,0,0,0,0]
In the example, Essbase indicates that 291 of the tasks at level 0 were empty.
If the ratio of empty tasks to the tasks specified in the calculation task schedule is greater
than 50% (for example, 291 / 576), parallelism may not be giving you improved performance
because of the high sparsity in the data model.
You can change dense-sparse assignments to reduce the number of empty tasks and increase
the performance gains from parallel calculation.
510
For detailed information about FIXPARALLEL and related commands, see the Oracle Essbase
Technical Reference.
511
512
32
Developing Custom-Defined
Calculation Macros
In This Chapter
Understanding Custom-Defined Macros ............................................................... 513
Naming Custom-Defined Macros ....................................................................... 513
Creating Custom-Defined Macros ...................................................................... 514
Using Custom-Defined Macros ......................................................................... 515
Viewing Custom-Defined Macros ....................................................................... 515
Updating Custom-Defined Macros ..................................................................... 515
Copying Custom-Defined Macros....................................................................... 516
Removing Custom-Defined Macros..................................................................... 516
Refreshing the Catalog of Custom-Defined Macros................................................... 517
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Start the macro name with the @ symbol; for example, @MYMACRO. The rest of a name
can contain letters, numbers, and the following symbols: @, #, $, and _. Macro names must
not contain spaces.
For macros that are called only by other macros, start the macro name with @_, to
distinguish it from general-use macros and functions.
513
Give macros unique names. Additionally, a macro name must be different from the names
of custom-defined functions and from the names of existing calculation functions.
Note: If an application contains a local macro that has the same name as a global macro,
AppName.@MacroName
For example:
Sample.@MYMACRO
Because global macros are available to any application running on the Essbase Server where
the macro was created, you do not assign an application name to it.
As global, in which the macro is available to all Essbase applications running on the Essbase
Server where the macro was created
Topic
Location
Administration Services
MaxL
create macro
The following MaxL statement creates a local macro named @COUNTRANGE for use in the
Sample application:
create macro Sample.'@COUNTRANGE'(Any) AS
'@COUNT(SKIPMISSING, @RANGE(@@S))'
spec '@COUNTRANGE(MemberRange)'
comment 'counts all non-missing values';
514
If it was registered locally, you must use a calculation script or formula within the
application in which the macro was created.
If it was registered globally, you can use any calculation script or formula within any
application on the Essbase Server.
For example, to use the @COUNTRANGE custom-defined macro shown earlier in this
chapter, create the following calculation script:
CountMbr = @COUNTRANGE(Sales, Jan:Dec);
Use this calculation script with the Sample.Basic database, or replace Sales, Jan:Dec with
a range of members in a test database.
Topic
Location
Administration Services
MaxL
display macro
515
Tool
Topic
Location
Administration Services
MaxL
The following MaxL statement changes the local macro @COUNTRANGE, which is used only
in the Sample application:
create or replace macro Sample.'@COUNTRANGE'(Any)
as '@COUNT(SKIPMISSING, @RANGE(@@S))';
Topic
Location
Administration Services
MaxL
create macro
Verify that no calculation scripts or formulas are using the custom-defined macro.
516
Tool
Topic
Location
Administration Services
MaxL
drop macro
517
518
33
Developing Custom-Defined
Calculation Functions
In This Chapter
Process for Creating Custom-Defined Functions ...................................................... 519
Custom-Defined Function Requirements .............................................................. 520
Creating and Compiling a Java Class .................................................................. 521
Installing Java Classes on Essbase Server............................................................. 522
Registering Custom-Defined Functions ................................................................ 523
Using Registered Custom-Defined Functions.......................................................... 524
Updating Custom-Defined Functions................................................................... 524
Viewing Custom-Defined Functions .................................................................... 525
Removing Custom-Defined Functions.................................................................. 526
Copying Custom-Defined Functions .................................................................... 526
Performance Considerations for Custom-Defined Functions......................................... 527
Memory Considerations for Custom-Defined Functions ............................................. 527
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Write a public Java class that contains at least one public, static method to be used as a custom-defined
function.
boolean
byte
char
com.hyperion.essbase.calculator.CalcBoolean
float, double
java.lang.String
CalcBoolean is an Essbase-specific data type that can include three valuesTRUE, FALSE, and
#MISSING. For information about the other listed data types, see the JDK documentation.
The method return data type can be void or any of the preceding data types. Returned data types
are converted to Essbase-specific data types. Strings are mapped to a string type. Boolean values
are mapped to the CalcBoolean data type. All other values are mapped to a double type.
520
Note: Essbase does not support double variables returned with infinite or Not-a-Number values.
If these values are returned from a Java program, they may not be recorded or displayed
correctly in Essbase. Double variables should be checked for infinite or Not-a-Number
values and set to finite values before being returned to Essbase. See the entry for the class,
Double, in the JDK documentation.
For creating, deleting, and managing custom-defined functions, Essbase requires these security
permissions:
l
When you register a custom-defined function in Essbase, you give the function a name, which
is used in calculation scripts and formulas and is distinct from the Java class and method name
used by the function.
Follow these requirements for naming custom-defined functions:
l
Start the name with the @ symbol. The rest of a function name can contain letters, numbers,
and the following symbols: @, #, $, and _. Function names cannot contain spaces.
For example: @MYFUNCTION
Start the names of custom-defined functions that are called only by custom-defined macros
with @_, to distinguish them from general-use functions and macros.
For example: @_MYFUNCTION
Custom-defined functions must have unique names. Function names must be different from
each other, from the names of custom-defined macros, and from the names of existing
calculation functions.
If an Essbase application contains a local function that has the same name as a global
function, the local function is used for calculation.
For example:
public class CalcFunc {
public static double sum (double[] data) {
int i, n = data.length;
double sum = 0.0d;
for (i=0; i<n; i++) {
double d = data [i];
sum = sum + d;
}
521
return sum;
}
}
For example:
CalcFunc.java
Navigate to the directory where the .java file resides; at a command prompt, enter this command:
javac java_filename
For example:
javac CalcFunc.java
Resolve any compiling errors until the compiler creates a new file with a .class extension.
For example:
CalcFunc.class
Navigate to the directory where the .class file resides; at a command prompt, enter this command:
jar cf jar_filename class_filename
For example:
jar cf CalcFunc.jar CalcFunc.class
On the computer running Essbase Server, copy the .jar file to one of the following directories (if the
directory does not exist, create it):
l
where appName is the name of the application where the local custom-defined function
will be used.
If the .jar file is subsequently placed in another location, you must modify the
CLASSPATH variable to include the full path and filename for the .jar file.
522
If the functions will be used only by specific applications, restart those applications in Essbase.
Otherwise, restart Essbase Server.
Do not register global functions for testing; doing so makes changing them more
difficult if you encounter problems.
Topic
Location
Administration Services
MaxL
create function
To register a custom-defined function with local scope, include the application name as a prefix.
For example, the following MaxL statement registers the custom-defined function, @JSUM, in
the CalcFunc class as a local function for use within the Sample application:
create function Sample.'@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';
To register a custom-defined function with global scope, do not include the application name
as a prefix. For example, the following MaxL statement registers the custom-defined function,
@JSUM, in the CalcFunc class as a global function for use in any application on Essbase Server:
create function '@JSUM'
as 'CalcFunc.sum'
spec '@JSUM(memberRange)'
comment 'adds list of input members';
Note: Specifying input parameters for the Java method is optional. If you do not specify input
parameters, Essbase reads them from the method definition in the Java code. If, however,
you are registering multiple custom-defined functions with the same method name but
with different parameter sets, you must register each version of the function separately,
specifying the parameters for each version of the function.
523
Use this calculation script with the Sample.Basic sample database, or replace New York
with the name of a member in a test database.
Typically, to update a custom-defined function, you must replace the .jar file that contains the
code for the function, and then re-register the function. If, however, the signature of the customdefined function has not changed, and the function has only one set of input parameters (it is
not an overloaded method), you can replace the .jar file that contains the function.
Note: Only DBAs should update global custom-defined functions.
Make the changes to the Java class for the custom-defined function and use Java test programs to test
its output.
Compile the Java classes and archive them in a new .jar file, using the same name as the
previous .jar file.
524
Include any other classes and methods for custom-defined functions that were included in
the previous .jar file.
Perform an action, depending on whether you are updating a local or global custom-defined function:
a. Local: Shut down any Essbase applications that use the functions in the .jar file.
b. Global: Shut down all Essbase applications
If you are unsure which Essbase applications use which functions in the .jar file, shut down
all Essbase applications.
Copy the new .jar file to Essbase Server, replacing the existing .jar file with the same name.
If the signature of the custom-defined function has not changed, skip to step 8.
Local:
create or replace function sample.'@JSUM'
as 'CalcFunc.sum';
Global:
create or replace function '@JSUM'
as 'CalcFunc.sum';
Restart the applications that you shut down, which updates the catalog.
Topic
Location
Administration Services
MaxL
display function
For example, use the following MaxL statement to view the custom-defined functions in the
Sample application and any registered global functions:
display function Sample;
The display function statement lists global functions without an application name to indicate
that they are global. If the application contains a function with the same name as a global
function, only the local function is listed.
525
Local: Application Manager permission for the application, or any wider permission
Before removing custom-defined functions, you should verify that no calculation scripts or
formulas are using them. Global custom-defined functions can be used in calculation scripts
and formulas across Essbase Server, so you must verify that no calculation scripts or formulas
on Essbase Server are using a global custom-defined function before removing it.
Caution!
Remove global custom-defined functions only when users are not accessing Essbase
databases and calculation routines are not being performed.
Perform an action, depending on whether you are removing a local or global custom-defined function:
a. Local: Shut down any Essbase applications that use the functions in the .jar file.
b. Global: Shut down all Essbase applications.
Local:
drop function Sample.'@JSUM';
Global:
drop function '@JSUM';
Restart the applications that you shut down, which updates the catalog.
Topic
Location
Administration Services
526
Tool
Topic
Location
MaxL
create function
527
528
Part V
Retrieving Data
In Retrieving Data:
l
l
l
l
l
529
530
34
Understanding
Report Script Basics
In This Chapter
Working With a Simple Report Script .................................................................. 531
Understanding How Report Writer Works .............................................................. 533
Planning Reports ......................................................................................... 536
Considering Security and Multiple-User Issues ....................................................... 537
Reviewing the Process for Creating Report Scripts.................................................... 537
Creating Report Scripts .................................................................................. 538
Saving Report Scripts.................................................................................... 538
Executing Report Scripts ................................................................................ 539
Copying Report Scripts .................................................................................. 539
Developing Free-Form Reports.......................................................................... 539
All report script examples in this chapter are based on the Sample.Basic database.
531
100
200
300
400
Product
Actual
========
9,211
6,542
6,483
4,725
26,961
Qtr1
Budget
========
6,500
3,700
4,500
2,800
17,500
Variance
========
2,711
2,842
1,983
,925
9,461
Actual
========
10,069
6,697
6,956
4,956
28,678
Qtr2
Budget
========
6,900
3,700
5,200
3,200
19,000
Variance
========
3,169
2,997
1,756
1,756
9,678
Qtr2
Budget
========
6,500
6,200
7,600
6,300
26,600
Variance
========
1,442
2,324
1,983
2,588
8,337
Qtr2
Budget
========
4,900
4,000
3,800
#MISSING
12,700
Variance
========
1,394
1,535
770
#MISSING
3,699
West Sales
100
200
300
400
Product
Actual
========
7,660
8,278
8,599
8,403
32,940
Qtr1
Budget
========
5,900
6,100
6,800
5,200
24,000
Variance
========
1,760
2,178
1,799
3,203
8,940
Actual
========
7,942
8,524
9,583
8,888
34,937
South Sales
100
200
300
400
Product
Actual
========
5,940
5,354
4,639
#MISSING
15,933
Qtr1
Budget
========
4,100
3,400
4,000
MISSING
11,500
Variance
========
1,840
1,954
639
#MISSING
4,433
Actual
========
6,294
5,535
4,570
#MISSING
16,399
Central Sales
Qtr1
532
Qtr2
100
200
300
400
Product
Actual
========
9,246
7,269
10,405
10,664
37,584
Budget
========
,500
6,800
6,200
5,200
24,700
Variance
========
2,746
469
4,205
5,464
12,884
Actual
========
9,974
7,440
10,784
11,201
39,399
Budget
========
7,300
7,000
6,800
5,800
26,900
Variance
========
2,674
440
3,984
5,401
12,499
Qtr2
Budget
========
25,600
20,900
23,400
15,300
85,200
Variance
========
8,679
7,296
8,493
9,745
34,21
Market Sales
100
200
300
400
Product
Actual
========
32,057
27,443
30,126
23,792
113,418
Qtr1
Budget
========
23,000
20,000
21,500
13,200
77,700
Variance
========
9,057
7,443
8,626
10,592
35,718
Actual
========
34,279
28,196
31,893
25,045
119,413
Report Script Editor is a text editor that you use to write report scripts. Report commands
define formatted reports, export data subsets from a database, and produce free-form
reports. Execute the saved script to generate a report. Saved report scripts have the file
extension .rep.
Report Extractor retrieves data information from the Essbase database when you run a report
script.
Report Viewer displays the complete report. Saved reports have the file extension .rpt.
533
Figure 138
Report Extractor
The Report Extractor processes the report script and retrieves data, performing the following
actions:
Composes the member list, based on all possible member combinations. For example,
<IDESCENDANTS East retrieves member East and all of its descendants.
Applies member restrictions. For example, <LINK refines the member selection.
Orders the member output. For example, <SORT determines the order in which members are sorted.
Local regions
Partitioned regions
Restricts data. For example, the following command suppresses the display of all rows that contain only
missing values:
{SUPMISSINGROWS}
Sorts data. For example, <TOP returns rows with the greatest values of a specified data column.
Formats output. For example, {SKIP} skips one or more lines in the final output report.
The order in which Report Extractor retrieves data affects the execution of complex extraction
and formatting commands. For example, because the Report Extractor restricts data (step 5)
before sorting data (step 6), if you place conditional retrieval commands in the wrong order,
534
report output results can be unexpected. Be aware of the data retrieval process when designing
report scripts.
Parts of a Report
Understanding the parts of a report is essential as you plan and design your own reports.
Figure 139
Page Headings list dimensions represented on the current page. All data values on the page
have the dimensions in the page heading as a common property.
<PAGE (Market, Measures)
Column Headings list members across a page. You can define columns that report on data
from multiple dimensions, which results in nested column headings.
<COLUMN (Year, Scenario)
Row Headings list members down a page. You can define a member list that includes rows
from multiple levels within a dimension or from multiple dimensions. The rows are indented
below the dimension name.
<ROW (Product)
Titles contain user-defined text, date and time stamp, the user name of the person running
the report, page numbers, the name of the source database, or any other descriptive
information. Titles are user-generated and optional. Page, column, and row headings are
automatically generated, because they are necessary to clearly describe the data on the report
page.
{ STARTHEADING
TEXT
1 "Prepared by:"
14 "*USERNAME"
535
TEXT
SKIP
ENDHEADING }
l
Data values are the values contained in the database cells; they are the lookup results of
member combinations or the results of calculations when the report is run through the
Report Extractor. Each data value is the combination of the members in the page heading,
column heading, and row name.
All data values in a row share the properties of the row names of that row. A report can have
zero or more row name dimensions, each of which produces column of row names, with
the innermost row name column cycling the fastest.
Extraction commands deal with the selection, orientation, grouping, and ordering of raw
data extracted from the database. These commands begin with less-than signs (<).
Formatting commands allow customization of the report format and appearance, the
creation of new columns, and calculation of columns and rows. These commands are
generally contained within braces ({ }), although some begin with less-than signs (<).
The bang character (!) terminates a series of commands and requests information from the
database. You can place one or more report scripts, each terminated by its own ! command,
in the same report file.
For information about report commands, see the Oracle Essbase Technical Reference.
Planning Reports
Report design is important to presenting information. Include the proper elements and arrange
information in an attractive, easy-to-read layout.
To plan a report:
1
Consider the reporting needs and the time required to generate the report.
536
Layout
Number of columns
Members
Titles, if applicable
Review the sketch; it is often apparent at this stage if additional data or formatting is needed.
See Chapter 58, Optimizing Reports and Other Types of Retrieval for a comprehensive
discussion of how to optimize a report script.
Note: As you plan the report, minimize use of numeric row names; instead, to avoid
Report Script Editor. Use Report Script Editor to create large-scale reports comprising many
pages of multidimensional data. Reports of this scale often can exceed the capabilities of
even the most robust spreadsheet. Report Writer commands let you define formatted
reports, export data subsets from an Essbase database, and produce free-form reports. See
Creating Scripts in the Oracle Essbase Administration Services Online Help.
A text editor.
Through a spreadsheet. Use report commands in a spreadsheet in free-form mode or
template-retrieval mode.
Essbase APIs. See Generating Reports Using the C, Visual Basic, and Grid APIs on page
576 and see the Oracle Essbase API Reference.
Third-party reporting tools.
For information about creating and editing report scripts in Administration Services, see About
Report Script Editor in the Oracle Essbase Administration Services Online Help.
An application and all the databases within the application, which lets you run the script
against any database in the application.
A database, which lets you run the script against the specified database.
Report scripts have a .rep extension by default. If you run a report script from Administration
Services, the script must have a .rep extension.
538
Topic
Location
Administration Services
Copying Scripts
MaxL
alter object
ESSCMD
COPYOBJECT
539
Colorado
{UCHARACTERS}
Central
!
Resulting report:
Sales 100
Jan
Actual
Budget
======= =======
Illinois
829
700
Ohio
430
300
Wisconsin
490
300
Missouri
472
300
Iowa
161
0
Colorado
643
500
========
===
===
Central
3,025
2,100
Feb
Actual
Budget
======= =======
898
700
397
300
518
400
470
300
162
0
665
500
===
===
3,110
2,200
Mar
Actual
Budget
======= =======
932
700
380
300
535
400
462
300
162
0
640
500
===
===
3,111
2,200
You can use formatting commands to add specific formats to a free-form report. When PAGE,
COLUMN, and ROW commands are omitted, Essbase formats free-form reports according to
the following rules:
1. The Report Extractor finds the last member or members of a single dimension defined in
the report specification (before the report output operator !). This dimension becomes the
ROW dimension for the report. All remaining selections become PAGE or COLUMN
dimensions, as defined by rules 2 and 3.
2. The Report Extractor searches for any single-member selections. If a single member is found
that does not satisfy rule 1, that dimension becomes a PAGE dimension.
3. The Report Extractor searches for all remaining dimension members that do not satisfy rules
1 or 2. If any remaining members are found, those dimensions become COLUMN
dimensions. COLUMN dimensions are nested in the order of selection in the free-form
script.
4. The Report Extractor searches the database outline for any dimensions not specified in the
report specification. If unspecified dimensions are found, they become PAGE dimensions
(the default for single-member selections, as defined in rule 2).
5. A subsequent selection of one or more consecutive members from a given dimension
overrides any previous selection for that dimension.
For example, the following report recognizes California, Oregon, Washington, Utah, Nevada,
and West as members of Market.
Sales
Jan Feb Mar
Actual Budget
Apr May Jun
California
Oregon
Washington
Utah
Nevada
540
{UCHARACTERS}
West
!
California
Oregon
Washington
Utah
Nevada
======
West
Apr
=======
3,814
1,736
1,868
1,449
2,442
=====
11,309
Actual
May
Jun
====== ======
4,031
4,319
1,688
1,675
1,908
1,924
1,416
1,445
2,541
2,681
===== =====
11,584 12,044
Apr
======
3,000
1,100
1,500
900
1,900
=====
8,400
Budget
May
Jun
====== ======
3,400
3,700
1,000
1,100
1,600
1,700
800
800
2,000
2,100
=====
=====
8,800
9,400
541
542
35
In This Chapter
Understanding Extraction Commands.................................................................. 543
Understanding Formatting Commands................................................................. 544
Understanding Report Script Syntax ................................................................... 544
Designing the Page Layout.............................................................................. 545
Formatting ................................................................................................ 549
Selecting and Sorting Members ........................................................................ 560
Restricting and Ordering Data Values .................................................................. 571
Converting Data to a Different Currency ............................................................... 575
Generating Reports Using the C, Visual Basic, and Grid APIs ....................................... 576
All report script examples in this chapter are based on the Sample.Basic database.
Also see:
l
543
Separate commands with at least one space, tab, or new line for readability. Report
processing is unaffected by extra blank lines, spaces, or tabs.
Enter commands in uppercase or lowercase. Commands are not case-sensitive. If the
database outline is case-sensitive, the members in the report script must match the outline.
To start report processing, enter the bang (!) report output command or one or more
consecutive numeric values. You can place one or more report scripts, each terminated by
its own ! command, in the same report file.
You can group multiple format commands within one set of braces. For example, these
formats are synonymous:
{UDATA SKIP}
{UDATA} {SKIP}
544
Duplicate member names, which must be entered as qualified member names (for
example, [2006].[Qtr1])
Names containing one or more numerals at the beginning of the name (for example,
100-Blue)
Names containing any of the characters listed in Table 90:
Table 90
Character
Description
asterisks
at signs
{}
braces
[]
brackets
commas
colons
<
less-than signs
()
parentheses
plus signs
semicolons
slashes
545
In addition, the <ASYM and <SYM commands override the default method of interpreting the
column dimension member lists, and produce either an asymmetric or symmetric report format.
See Formatting Page, Column, and Row Headings on page 550.
where dimensioNname lists dimensions represented on the current page. All data values on
the page have the dimensions in the page heading as a common property. Example:
<PAGE (Measures, Market)
Press Enter.
Enter <COLUMN(dimensionName)
where dimensionName equals the name of each dimension to display across the page. For
example:
<COLUMN (Year)
Press Enter.
Enter <ROW(dimensionName)
where dimensionName equals the name of each dimension to display down the page. For
example:
<ROW (Market)
Press Enter.
Note: You can select additional members to associate with the heading commands. Using
a member name as a parameter for the PAGE, COLUMN, or ROW commands causes
Report Extractor to associate the member with the appropriate dimension.
Example report script:
<PAGE (Product, Measures)
<COLUMN (Scenario, Year)
Actual
<ICHILDREN Qtr1
<ROW (Market)
<IDESCENDANTS East
!
Resulting report:
Product Measures Actual
Jan
========
546
Feb
========
Mar
========
Qtr1
========
New York
Massachusetts
Florida
Connecticut
New Hampshire
East
512
519
336
321
44
1,732
601
498
361
309
74
1,843
543
515
373
290
84
1,805
1,656
1,532
1,070
920
202
5,380
You can create page, column, and row headings with members of attribute dimensions.
Example report script:
<PAGE (Measures,Caffeinated)
Profit
<COLUMN (Year,Ounces)
Apr May
"12"
<ROW (Market,"Pkg Type")
Can
<ICHILDREN East
!
Resulting report:
Profit Caffeinated 12 Scenario
Apr
May
======== ========
New York
Can
276
295
Massachusetts
Can
397
434
Florida
Can
202
213
Connecticut
Can
107
98
New Hampshire
Can
27
31
East
Can
1,009
1,071
Modifying Headings
You can perform the following modifications to headings in the report using the commands
listed in Table 91:
Table 91
Report Command
Description
STARTHEADING
Create a custom page heading in place of the default heading, which is displayed at the top of each page in the
report or immediately following a HEADING command. Use the ENDHEADING command to specify the end of the
custom heading.
HEADING
Display the page heading, either the default heading or the heading as defined with the STARTHEADING and
ENDHEADING commands.
Use this command to re-enable the page heading display if the SUPHEADING command has been used.
IMMHEADING
Force the immediate display of the heading without waiting for the next unsuppressed data row, when heading
suppression commands are in use.
COLHEADING
PAGEHEADING
Display the page heading before the next data output row.
547
Also see Suppressing Page, Column, and Row Formatting on page 552.
West
Actual
Q1 Q2 Q3
Budget
Q1 Q2 Q3
Q1
Actual
Q2 Q3
An asymmetric report, shown below, is characterized by groups of nested members that differ
by at least one member in the nested group. There can be a difference in the number of members
or the names of members.
East
Budget
Q1 Q2 Q3
Actual
Q1 Q2 Q3
West
Budget
Q1 Q2 Q3
By default, Essbase creates a symmetric report unless you select the same number of members
for all column dimensions.
For an example of an asymmetric report, see Sample 13, Creating Asymmetric Columns, in
the Examples of Report Scripts page of the Oracle Essbase Technical Reference.
The Essbase evaluation of symmetry versus asymmetry takes place before any ordering,
restriction on columns, or application of the effects of calculated columns.
548
Use the <BLOCKHEADERS formatting command to change the pyramid-style headers used
in symmetric reports to block-style headers such as those used in asymmetric reports. A
symmetric report uses the <PYRAMIDHEADERS mode of column layout by default.
Use the <PYRAMIDHEADERS formatting command to change the block-style headers used
in asymmetric reports to pyramid-style headers such as those used in symmetric reports. An
asymmetric report uses the <BLOCKHEADERS mode of column layout.
Formatting
Formatting commands, usually enclosed in braces ({ }), define the format of data and labels in
the final report and can be either global or member-specific.
l
Global commands are executed when they occur in the report script file and stay in effect
until the end of the report file or until another global command replaces them.
For example, the {SUPMISSINGROWS} command suppresses all rows in the report script
file that contain only missing values.
Member-specific commands are executed as they are encountered in the report script,
usually the next member in the report script, and affect only that member. A format attached
to a member is executed before that member is processed.
For example, the {SKIP} command skips the specified number of rows between row
dimensions in a report script. If you want additional rows to skip lines, you must use the
SKIP command again.
Report Command
Description
WIDTH
LMARGIN
SETCENTER
549
Report Command
Description
PAGELENGTH
NEWPAGE
Force a page break regardless of how many lines have been generated for the current page.
PAGEONDIMENSION
Insert a page break whenever a member from the same dimension as the member in the command changes from
one line in the report to the next. Use the NOPAGEONDIMENSION command to turn off this function.
FEEDON
Enable page breaks in a report when the number of lines on a page is greater than the current PAGELENGTH setting.
Resulting report:
550
Sales Texas
Actual
Budget
Jan
Feb
Mar
Jan
Feb
Mar
===
===
===
===
===
===
100-10
452.0
465
467.00
560.0
580
580.00
100-20
190.0
190
193.00
230.0
230
240.00
100-30 #MISSING #MISSING #MISSING #MISSING #MISSING #MISSING
The following scripts demonstrate two approaches to column formatting that produce identical
results. In the first script, the first two {DECIMAL} commands are positioned to format every
first and third column by distributing the formats when Jan Feb displays after processing the
{DECIMAL} command.
Example report script: Format columns by distributing the formats
California Sales
<COLUMN (Scenario, Year)
Actual Budget Variance
{DECIMAL 1 1 }
{DECIMAL 2 3 }
Jan Feb
//
{DECIMAL 1 1 4 }
//
{DECIMAL 2 3 6 }
<ROW (Product)
<DESCENDANTS "100"
!
The two {DECIMAL} commands are positioned to format the individual columns 1, 3, 4, and
6.
Example report script: Format columns by direct assignment
<PAGE (Measures, Market)
California Sales
<COLUMN (Scenario, Year)
Actual Budget Variance
//
{DECIMAL 1 1 }
//
{DECIMAL 2 3 }
Jan Feb
{DECIMAL 1 1 4 7 }
{DECIMAL 2 3 6 9 }
<ROW (Product)
<DESCENDANTS "100"
!
100-10
100-20
100-30
Actual
Jan
Feb
=====
====
678.0
645
118.0
122
145.0
132
Budget
Jan
Feb
====
====
840.00
800.0
140.00
150.0
180.00
160.0
Variance
Jan
Feb
=====
====
(162) (155.00)
(22)
(28.00)
(35)
(28.00)
551
Note: By default, attribute calculation dimension members (for example, SUM, AVG) are
displayed as columns. To display them in rows, you must include them in the ROW
command.
Report Command
Description
NAMEWIDTH
Define the column width for all row members in the column.
NAMESCOL
Change where the row member column is displayed and shift the remaining columns left or right to allow long member
names.
Report Command
Description
SUPCOLHEADING
SUPEMPTYROWS
SUPMISSINGROWS
All rows that contain missing values. Use INCMISSINGROWS, INCZEROROWS, or INCEMPTYROWS to display rows
that are empty or have missing data or zeros.
SUPPAGEHEADING
SUPALL
The page and column headings, all member names, page breaks, commas, and brackets in the final report. To turn
on the display of columns of row member names, use the NAMESON command. To turn on the use of commas and
brackets, use the COMMAS and BRACKETS commands.
SUPHEADING
The default heading (page header and column headers) or custom header, if defined, at the top of each page.
SUPNAMES
Row member names in the final report. Use the NAMESON command to include row member names in the report.
SUPOUTPUT
All output while continuing to process all operations, such as calculations and format settings.
Use the OUTPUT command to reverse the actions of SUPOUTPUT.
SUPCURHEADING
552
Currency information when you use the CURRENCY command to convert data values in a report to a specified
currency.
Totaling Columns
The CALCULATE COLUMN command lets you create a report column, perform on-the-fly
calculations, and display the calculation results in the newly created column.
Table 96 lists column calculation commands:
Table 96
Report Command
Description
CALCULATE COLUMN
Create a report column, perform dynamic calculations, and display the calculation results in the newly created
column. Use the OFFCOLCALCS command to temporarily disable column calculations in the report, and
ONCOLCALCS to re-enable calculations.
REMOVECOLCALCS
CALCULATE COLUMN adds up to 499 ad hoc column calculations to a report. Each new
calculated column is appended to the right of the existing columns in the order in which it is
created and is given the next available column number. These columns calculate the sum of data
across a range of columns or an arithmetic expression composed of simple mathematical
operators.
The CALCULATE COLUMN command supports standard mathematical operations.
553
If you use the same name for multiple columns, Essbase creates only the last column specified
in the CALCULATE COLUMN command. Use a leading space with the second name (and two
leading spaces with the third name, and so on) to create a unique column name.
Alternately, you can add descriptive text far enough to the right that it is truncated to the column
width. You can, for example, use the names Q1 Actual and Q1 Budget to distinguish similar
column names without affecting the appearance of the report. Column names are printed with
right justification until the column header space is filled. Excess characters are then truncated
to the right.
Divide lengthy column name labels into multiple lines. The maximum number of lines across
which you can divide a label is equal to the number of column dimensions designated in the
report specification. To break a column name, insert a tilde (~) in the name at the point where
you want the break. You must also specify at least two members for each column dimension to
use the maximum number of lines.
Example report script:
{CALCULATE COLUMN "Year to Date~Actual Total" = 1 : 2}
{CALCULATE COLUMN "Year to Date~Budget Total" = 3 : 4}
Resulting report:
Sales East
Actual
Year to Date
Budget
Year to Date
Jan
Feb Actual Total
Jan
Feb Budget Total
===== ====== ============= ====== ====== =============
400-10
562
560
1,122
580
580
1,702
400-20
219
243
462
230
260
722
400-30
432
469
901
440
490
1,391
As a rule, in symmetric reports, if a calculated column name has fewer levels than the number
of column dimensions, the previous member (to the left) of each of the column dimensions,
above the top level supplied in the calculated column name, is attributed to the calculated
column. If normal PYRAMIDHEADERS mode is in use, the centering of those higher-level
column members shifts to the right to include the calculated column or columns. Column header
members on the same level as calculated column names are not applied to the new calculated
column or columns, and their centering does not shift.
If BLOCKHEADERS mode is in use; that is, if every member applying to a column is repeated
above that column, the same rules apply, except that instead of shifting column header member
centering, they are repeated in the appropriate higher levels of the calculated column name.
Asymmetric reports do not have groups of columns that share a member property. These reports
still allow multiple-level column names up to the number of column levels defined, but member
properties from preceding columns are not automatically shared and used for those levels that
are undefined.
If there are fewer column header dimensions than the number of levels that you want, you can
create multiline column labels. In this case, use TEXT, STARTHEADING, ENDHEADING, and
other formatting commands to create a custom heading.
554
Numbering Columns
If the number of regular (not calculated) columns varies in the report because multiple sections
in the report have different numbers of columns, the column numbers used to identify the
calculated columns shift accordingly, as illustrated:
l
If the first section of a report has 12 columns (including row name columns), and three
calculated columns are declared, column numbers 011 are the regular columns, and
columns 1214 are the calculated columns.
If a second section of the report reduces the number of regular columns to six, then the
regular columns are columns 05, and the same calculated columns are columns 68.
Similarly, if the number of regular columns is increased, the numbering of the calculated
columns starts at a higher number.
In the example, CC1, CC2, and CC3 represent the names of three calculated column names. The
column numbering for a report with two different sections with varying numbers of regular
columns:
internal
col # s: 0
Sales
Expense
1
Jan
===
1
1
2
Feb
===
3
2
3
Mar
===
5
5
4
Apr
===
3
3
5
CC1
===
22
23
6
CC2
===
55
65
7
CC3
===
26
33
1
Qtr1
===
Sales
2
Expense
4
2
YTD
===
9
8
3
CC1
===
22
56
4
CC2
===
57
45
5
CC3
===
36
33
If you do not want the calculated columns in the second section, or if you need a different set
of column calculation, use the command REMOVECOLCALCS to clear the old ones out. You
can then define new column calculations.
This example assumes that all three column calculations had no references to regular columns
other than columns 1 and 2. If CC3's calculation were = 1 + 3 + 6, when the second section of
the report starts, an error occurs stating that the column calculation referred to a nonexistent
column (6).
Totaling Rows
Row calculations create summary rows in a report. You can use summary rows to calculate the
sum of data across a range of rows or to calculate an arithmetic expression composed of simple
mathematical operators.
Table 97 lists row calculation commands:
555
Table 97
Report Command
Description
CALCULATE ROW
Create a row and associate it with a row name or label. This process is similar to declaring a variable. You can also
perform simple calculations with CALCULATE ROW. For more complex calculations, use SETROWOP. See also
OFFROWCALCS and ONROWCALCS.
OFFROWCALCS
Temporarily disable row calculations in the report. See also CALCULATE ROW and ONROWCALCS.
ONROWCALCS
Re-enable calculations after using OFFROWCALCS. See also CALCULATE ROW and OFFROWCALCS.
SETROWOP
Define complex calculations for the row specified in CALCULATE ROW. SETROWOP defines a calculation operator
to be applied to all subsequent output data rows. You can display the calculation results in the newly created row
with the PRINTROW command.
PRINTROW
CLEARROWCALC
Reset the value of the calculated row to #MISSING. See also CLEARALLROWCALC.
CLEARALLROWCALC
Reset the value of all calculated rows after using the CLEARROWCALC command.
SAVEROW
SAVEANDOUTPUT
Capture data and output the result after using the SAVEROW command.
Commands that designate columns must use valid data column numbers, as determined by the
original order of the columns.
l
The CALCULATE ROW command can specify an operation (+, -, *, /, or OFF) as an equation
consisting of constants, other calculated rows, and operators. Equations are evaluated at the time
of declaration. Member names are not supported in expressions with the CALCULATE ROW
command.
If you specify an operator, the operator applies to subsequent output rows and stores the result
in the calculated row. Specifying an operator is useful for aggregating a series of rows to obtain
a subtotal or total. To reset the operator, use SETROWOP. If the CALCULATE ROW command
does not specify either an equation or an operator, the + operator is assumed.
The CALCULATE ROW command supports the standard mathematical operations.
Example report script:
{ CALC ROW "Total Sales" = "Sales..Group1"
+ "Sales..Group2" }
The example creates Total Sales based on two other calculated rows.
556
Underlining
Use underlining as a visual aid to break up blocks of information in a report, using the commands
listed in Table 98 on page 557:
Table 98
Report Command
Description
UNDERLINECHAR
UCHARACTERS
Underline all characters that are not blank in the preceding row.
UCOLUMNS
UDATA
Underline all the data columns for a row, while not underlining the row name columns.
UNAME
Underline all the row name columns in the preceding row while not underlining the data columns.
UNAMEONDIMENSION
Underline the row member names in a row whenever a member from the same dimension as the member in the
command changes. Use the NOUNAMEONDIM command to turn off underlining for new rows.
Report Command
Description
SUPBRACKETS
Brackets around negative numbers. Use the BRACKETS command to re-enable brackets.
SUPCOMMAS
Commas in numbers greater than 999. Use the COMMAS command to re-enable commas.
SUPZEROROWS
Rows that have only zero data values. Use INCZEROROWS or INCEMPTYROWS to re-enable the display.
SUPEUROPEAN
The European method for displaying numbers (2.000,01 whereas the non-European equivalent is 2,000.01). Use
the EUROPEAN command to re-enable European number display.
SUPFEED
The automatic insertion of a page break whenever the number of lines on a page exceeds the current PAGELENGTH
setting.
SUPFORMATS
Formats that produce output such as underlines and skips. Use INCFORMATS to re-enable the display.
SUPMASK
Text masks that were defined in the report using the MASK command. Use INCMASK to re-enable the display.
See Suppressing Page, Column, and Row Formatting on page 552 for descriptions of the
SUPPRESS commands used to suppress formats.
557
Indenting
Use indenting to provide visual clues to row levels of the script. Table 100 on page 558 lists the
indenting commands:
Table 100
Report Command
Description
INDENT
Shift the first-row names column in column output order by a specified number of characters.
INDENTGEN
Indent subsequent row members in the row names column based on the generation in the database outline. Use the
NOINDENTGEN command to left-justify row member names based on generation name.
Page numbers
To add a title to the report, use the TEXT command, combined with any of the following:
l
information.
where text is the text string that to be displayed in the data cells.
You can place the MISSINGTEXT command at any point in the report script; the command
applies throughout the script.
558
Note: You can also suppress #MISSING labels from appearing in the report. See Suppressing
Data Formatting on page 557 for descriptions of SUPPRESS commands used to suppress
labels.
To replace zeros with a text label, at the point in the script where you want to replace zeros with
a text label, type:
{ZEROTEXT ["text"]}
command does not print. AFTER strings also do not print if you replace #MISSING with
some other value (such as 0).
Report Command
Description
SKIP
SKIPONDIMENSION
Add a blank line when a member from the same dimension as the specified member in the command changes on
the next line in the report.
Use the NOSKIPONDIMENSION command to turn off insertion of a new line.
Report
Command
Description
COMMAS
Turn on the display of commas for numbers greater than 999 after commas have been suppressed with either a
SUPCOMMAS or SUPALL command.
BRACKETS
Turn on the display of brackets around negative numbers instead of negative signs, after using the SUPBRACKETS
command earlier in the script.
AFTER
BEFORE
559
Report
Command
Description
EUROPEAN
Use the European method for displaying numbers where decimal points are used as the thousands separator character
and commas separate the decimal portion of the number from the integer portion (2.000,01; the non-European
equivalent is 2,000.01).
MASK
Overwrite text in each output row with a specified characters and position.
Selecting Members
Member selection commands are extraction commands that select ranges of members based on
database outline relationships, such as sibling, generation, and level. Using member selection
commands ensures that any changes to the outline are automatically reflected in the report,
unless you change the member name on which the member selection command is based.
Attribute dimensions can be included in member selection commands.
Table 103 lists the member selection commands:
Table 103
Report Command
Description
ALLINSAMEDIM
ALLSIBLINGS
ANCESTORS
ATTRIBUTE
CHILDREN
DESCENDANTS
Include descendants of the specified member to the report, excluding the dimension top.
DIMBOTTOM
Select all level 0 members for the dimension to which a given member belongs.
DIMTOP
IANCESTORS
ICHILDREN
Select the specified member and members in the level immediately below it.
IDESCENDANTS
IPARENT
560
Report Command
Description
OFSAMEGEN
Include members from the same dimension and generation as the specified member.
ONSAMELEVELAS
Include members from the same dimension and on the same level as the specified member.
PARENT
TODATE
Extract data for a specified date or for a time period before or after a specific date.
WITHATTR
Include base dimension members associated with the specified attribute dimension.
When you use generation and level names, changes to the outline are automatically reflected in
the report. You can define your own generation and level names or use the default names
provided by Essbase. See Generations and Levels on page 63.
Using generation or level names whenever possible makes the report easier to maintain. Because
you do not have to specify a member name in the report, you need not change the report if the
member name is changed or deleted from the database outline.
Note: Generation and level names are standalone commands. You cannot use them in place of
For example, Lev1,Year selects all the level 1 members of the Year dimension.
To use default generation names, at the point in the script where you want to select a member
by the default generation name, use the format:
Genn,dimensionName
561
For example, Gen2,Year selects all the generation 2 members of the Year dimension.
Note: These default generation and level names are not displayed in Outline Editor.
The following example report script uses the default generation name Gen2,Year to generate a
report that includes the members Qtr1, Qtr2, Qtr3, and Qtr4 from the Year dimension:
<PAGE(Product)
<COLUMN(Year)
<ROW (Measures)
{OUTALTNAMES}
Cola
Gen2,Year
Sales Profit
!
Resulting report:
Sales
Profit
Report Command
Description
REPQUALMBR
Displays member names for any unique member names and a qualified name for any duplicate member names.
REPMBR
REPMBRALIAS
REPALIAS
Displays alias names followed by member names for members in the report output.
REPALIASMBR
Displays aliases followed by member names for members of the dimension specified.
OUTPUTMEMBERKEY
562
Generation Name
Reserved Names
Explanation
History
H-T-D
History-to-Date
Year
Y-T-D
Year-to-Date
Season
S-T-D
Season-to-Date
Period
P-T-D
Period-to-Date
Quarter
Q-T-D
Quarter-to-Date
Month
M-T-D
Month-to-Date
Week
W-T-D
Week-to-Date
Day
D-T-D
Day-to-Date
See Applying Predefined Generation Names to Dynamic Time Series Members on page 452.
Note: The database header message for the outline identifies the number of dynamic members
<LATEST memberName
reservedName(memberName)
where reservedName is the reserved Dynamic Time Series generation name and the
memberName is the name of the member in the time dimension.
If you use this syntax to specify a Dynamic Time Series, the time series name is associated
only to the member listed in the argument.
When you run the report script, the members are dynamically updated and the information is
incorporated into the final report.
563
Note: You must enter the Dynamic Time Series string exactly as it is displayed in the database
outline; you cannot create a string and incorporate it into the final report. You can create
an alias table for the Dynamic Time Series members in the database outline and use the
aliases instead of the predefined generation names.
To create a Boolean expression using operators, at the point in the script where you want to use
linking, enter the format:
<LINK (extractionCommand [operator extractionCommand])
where extractionCommand is the member selection command to retrieve data from, and
operator is either the AND or OR operator.
Note: Select members from the same dimension. All extraction command arguments must be
enclosed in parentheses, as in the example above. NOT can be associated only with an
extraction command and does not apply to the entire expression.
You can use Boolean operators with member selection commands, such as UDA and wildcards.
For a list of all valid extraction commands that can be used with the LINK command, see the
Oracle Essbase Technical Reference.
Examples:
The following example selects sweet products from the 100 subtree, plus all products on the
same level as 100-10:
<LINK ((<IDESCENDANTS("100") AND <UDA(Product,Sweet)) OR ONSAMELEVELAS "100"-10")
The following example selects products that are not sweet from the 100 subtree, plus all
products on the same level as 100-10.
<LINK ((<IDESCENDANTS("100") AND NOT <UDA (Product,Sweet)) OR ONSAMELEVELAS "100"-10")
For additional examples of narrowing member selection criteria, see the Oracle Essbase Technical
Reference.
564
Server, providing access to the variable from all applications and databases on the server
Application, providing access to the variable from all databases within the application
To use a substitution variable, at the point in the script where you want to use the variable, use
the format:
&variableName
where variableName is the same as the substitution variable set on the server.
For example,
<ICHILDREN &CurQtr
becomes
<ICHILDREN Qtr1
Note: The substitution variable must be accessible from the application and database against
which you are running the report. Also, the variable name can be an alphanumeric
combination (for variable name size limit, seeAppendix A, Limits). You cannot use
spaces or punctuation in the variable name.
When you run the report script, Essbase replaces the variable name with the substitution value,
and that information is incorporated into the final report.
You can also perform crosstab reporting based on multiple attributes. Using the <ATTRIBUTE
command, you can select all the base dimension members associated with an attribute. For
example, you can query the Sample.Basic database on how many 12-ounce units of grape and
orange juice were sold in New York during the first quarter.
To select a member based on a specific attribute, at the point in the script where you want to
select members based on a specific attribute, use the format:
<ATTRIBUTE memberName
Attribute types can be text, numeric, date, and Boolean. See Understanding Attribute Types
on page 166.
For a sample report, see Sample 20: Using Attributes in Member Selection in the Oracle Essbase
Technical Reference.
The following command returns all base dimension members that are associated with the
attribute Small from the Population attribute dimension.
<WITHATTR (Population, "IN", Small)
The following command returns all base dimension members that are associated with the
attribute 32 from the Ounces attribute dimension.
<WITHATTR (Ounces, "<", 32)
Note: The <WITHATTR command can be used within the LINK command to refine member
selections, as illustrated in the following example: <LINK ((<WITHATTR (Ounces,
"<", 32) AND <WITHATTR ("Pkg Type", "=", Can))
For a sample report, see Sample 21: Using the WITHATTR Command in Member Selection
in the Oracle Essbase Technical Reference.
566
The following format returns data on all products that were introduced before December 10,
1996.
<WITHATTR ("Intro Date", "<", <TODATE ("mm-dd-yyyy", "12-10-1996")
The following format returns data on all products that were introduced after December 10, 1996.
<WITHATTR ("Intro Date", ">", <TODATE ("mm-dd-yyyy", "12-10-1996")
Note: The types of date format supported are mm-dd-yyyy or dd-mm-yyyy. The date must be
where dimensionName is the dimension of the member that you select, and UDAstring is the
UDA that is set on the server. The following example selects members of the Product dimension
with the Sweet attribute.
<UDA (product,"Sweet")
When you run the report script, Essbase incorporates the UDA members into the final report.
567
Note: You must type the UDA string exactly as it is displayed in the database outline; you cannot
Trailing asterisks (*) at the end of the string to search for common member properties
Pattern-matching question marks (?) anywhere in the string to represent any singlecharacter member property
To select members using a trailing wildcard, at the point in the script where you want to select
members using a trailing wildcard, use the format:
<MATCH (memberName,"character*")
where memberName is the name of the member that you select, and character is the beginning
character in the following member. The following report script:
<MATCH (Year,"J*")
where memberName is the name of the member to select, and characters are the characters in
the following member. The following report script:
<MATCH (Product,"???-10")
characters in the string. If two question marks were used in the example, no matches were
found. You can place question mark wildcards anywhere in the match string.
568
Generation names
Level names
DIMBOTTOM command
OFSAMEGEN command
ONSAMELEVELAS command
Suppress shared members to eliminate unnecessary data duplication within the report.
To suppress shared members, at the point in the script from which you want to suppress a shared
member, use:
<SUPSHARE
<SUPSHARE suppresses the display of shared members for the duration of the report script.
Use <SUPSHAREOFF to reset the display of shared members.
Report Command
Description
<REPALIAS
<REPALIASMBR
<REPMBRALIAS
<REPMBR
<REPQUALMBR
Display member names for unique member names and display qualified names for duplicate member names
<OUTPUTMEMBERKEY
Display member identifiers for duplicate member names, and member and alias names.
the table. The member identifier, and the member name, alias name, or both, are included in
the report output.
Example Displaying a Member Name and Alias
You can display members in a report as a combination of the member name and its alias.
Combining the member name and alias enables you to display more descriptive page, column,
and row names, such as Diet Cola 100-20 or 100-30 Caffeine Free Cola.
To display member names and aliases, use the <REPALIASMBR command or REPMBRALIAS
command in a report script.
This example uses <REPALIASMBR to display the alias name ahead of the member name:
<PAGE (Product, Measures)
<COLUMN (Scenario, Year)
Actual
<ICHILDREN Qtr1
<ROW (Market)
<IDESCENDANTS "300"
<REPALIASMBR Product
!
Resulting report:
Market
Market
Market
Market
Sorting Members
When you sort the members you include in a report, be aware that sorting commands affect
members differently, depending on whether they are referenced by member selection commands
or by static member definitions. Report Writer commands sort members by member name or
data values.
Member selection commands such as <CHILDREN and <DESCENDANTS, select members in
the order specified by the database outline. By default, a report that includes member selection
570
commands displays members in their hierarchical database outline order. You can override this
default by specifying a sort order with a sort command.
Because sort commands affect the order of the members selected by the member selection
commands, they must precede any member selection commands to which they apply. If you
specify a sort command, the sort order is preserved until another sort command overrides it.
Sort commands modify member selection commands, such as <CHILDREN and
<DESCENDANTS. Sort commands do not perform final sorting of rows during formatting. Be
careful when you place a sort command in the report script that you do not start the sort too
soon, and that you override it to turn it off, if necessary, before the next selection command.
Sort commands have no effect on static member definitions.
Table 107 lists the member sort commands:
Table 107
Report Command
Description
SORTALTNAMES
Sort members alphabetically by the alias name of the member, if aliases are used in the report script.
SORTASC
Sort following members in ascending order starting with the lowest generation and moving toward the highest
generation.
SORTDESC
Sort following members in descending order starting with the highest generation and moving toward the lowest
generation.
SORTGEN
Sort following members according to the generation of the member in the database outline.
SORTLEVEL
Sort following members according to the level of the member in the database outline.
SORTMBRNAMES
SORTNONE
Disable all previous sorting commands so that members added to the report follow the normal hierarchical order
based on the database outline.
Report Command
Description
TOP
Specify the number of rows to return. These rows must contain the top values of a specific data column.
BOTTOM
Specify the number of rows to return. These rows must contain the lowest values of a specific data column.
RESTRICT
Specify the conditions the columns of a data row must satisfy before the row is returned.
ORDERBY
Specify the ordering of the rows of a report, based on the data values of data columns.
571
Configurable variables are used during conditional retrievals. See Changing Buffer Size on
page 889.
Using RESTRICT
The arguments of the <RESTRICT command let you specify qualifications for selecting rows.
Essbase includes only qualified rows in the resulting report output.
<RESTRICT works only on the range of rows that you specify in a row member selection.
Essbase processes the restrictions from left to right, and does not allow grouping with parentheses
in the list of arguments.
For example, the following example is not a valid syntax:
RESTRICT (... (@DATACOLUMN(1) > 300 AND @DATACOLUMN(2) < 600)...)
Use only one <RESTRICT per report, as terminated by the ! command. If a report script contains
multiple reports, each <RESTRICT overwrites the one in the previous report. For example:
RESTRICT (@DATACOLUMN(1) > @DATACOLUMN(2) AND 800 < @DATACOLUMN(3)
OR @DATACOLUMN(4) <> #MISSING)
572
Using ORDERBY
The <ORDERBY command orders the output rows according to the data values in the specified
columns. Using an optional direction argument to the ORDERBY command, you can specify
either an ascending order using the ASC flag, or descending order using the DESC flag. You can
specify different sorting directions in different columns of the same report. If no direction
argument is used, ascending (ASC) is the default order.
To determine the set of rows to be ordered, specify the row grouping dimension in the command.
The default row grouping is the innermost row dimension.
Only one <ORDERBY is allowed per report, as terminated by the ! command. If a report script
contains multiple reports, each <ORDERBY overwrites the one in the previous report.
Avoid using row formatting commands when you are using <ORDERBY in a report.
Formatting commands scheduled for a given point in the report may show up unexpectedly
because <ORDERBY shifted the row that contained the member with formatting.
In general, avoid using row formatting commands, and place overall script formatting before
column members or commands that expand the column members (such as ICHILDREN
column dimension, <column ..., column member).
<ORDERBY does not have to be the same as the data column of the <TOP or the
<BOTTOM.
573
Essbase discards rows that contain #MISSING values in their sorting column from
the set of extracted data rows before the applying the TOP or BOTTOM sort.
For example, this command returns two rows with the highest data values in col2 (Actual, Qtr2)
per row group:
1- TOP (2, @DATACOLUMN(2))
When you run this command against the Sample.Basic database, the row grouping is Product,
which implies that for Florida, the report returns 100-10 and 100-30 product rows, and for
Maine, the report returns 100-10, 100-40 product rows, and so on:
Florida
Maine
New York
100-10
100-20
100-30
100-40
100-10
100-20
100-30
100-40
100-10
100-20
100-30
100-40
100-50
Qtr1
570
235
655
342
600
734
324
432
1010
960
324
880
#MI
Actual
Qtr2
670
345
555
342
800
334
321
342
1210
760
550
980
#MI
Budget
Qtr1
Qtr2
570
650
321
432
455
865
432
234
800
750
734
534
235
278
289
310
1110
910
650
870
432
321
880
1080
#MI
#MI
This example returns rows with the highest data values in col2 (Actual, Qtr2) per report, because
the row grouping is the market.
2- TOP("market", 3, @DATACOLUMN(2))
Resulting rows:
New York
Maine
100-10
100-40
100-10
1010
880
600
1210
980
800
1110
880
800
910
1080
750
This example returns two rows with the lowest data values in col2 (Actual, Qtr2) per row group.
3- BOTTOM ("market", 2, @DATACOLUMN(2))
Resulting rows:
Maine
100-20
100-30
734
324
334
321
734
235
534
278
Note: <TOP and <BOTTOM put an upper limit on the number of (qualified) rows returned
after all restrictions are applied. This upper limit equals the number of rows in the <TOP
plus the number of rows in the <BOTTOM commands.
574
SCRIPT 2
....
{UCOLUMNS}
< Florida
(row member)
Script 2, appends {UCOLUMNS} to the row member Florida. Essbase executes {UCOLUMNS}
whenever it encounters a row that has row member Florida. If the TOP or BOTTOM command
returns a row that does not contain Florida, the formatting commands appended to the rows
are never executed.
Therefore, it is a good idea to place all general formatting commands before a <COLUMN
command, or a command that expands into column members to guarantee that the formatting
is executed. However, do not use formatting commands that work on rows, because these rows
may never be picked up by the <TOP or <BOTTOM command. Also avoid using <SAVEROW
and <CALCULATE ROW with the <TOP and <BOTTOM commands.
For information about creating a currency conversion application, see Building Currency
Conversion Applications and Performing Conversions on page 211.
575
Report APIs
Task
C API Function
ESSBEGINREPORT
ESBBEGINREPORT
ESSGBEGINREPORT
ESSENDREPORT
ESBENDREPORT
N/A
ESSREPORT
ESBREPORT
N/A
ESSREPORTFILE
ESBREPORTFILE
ESSGREPORTFILE
See the Oracle Essbase API Reference for descriptions and syntax.
576
36
In This Chapter
Introduction............................................................................................... 577
Understanding Elements of a Query.................................................................... 577
Using Functions to Build Sets........................................................................... 583
Working with Levels and Generations .................................................................. 586
Using a Slicer Axis to Set Query Point-of-View ........................................................ 588
Common Relationship Functions ....................................................................... 589
Performing Set Operations .............................................................................. 590
Creating and Using Named Sets and Calculated Members.......................................... 592
Using Iterative Functions ................................................................................ 594
Working with Missing Data .............................................................................. 595
Using Substitution Variables in MDX Queries ......................................................... 597
Querying for Properties .................................................................................. 597
Introduction
MDX, the data manipulation language for Essbase, is a query language for multidimensional
databases that can be used to execute grid retrievals. MDX expressions can also be used to define
formulas on Essbase aggregate storage databases, to query metadata, to qualify member names,
and to describe data or outline subsets for conditional triggers and other Essbase functionality.
This chapter provides an introduction to MDX with a series of practice exercises.
To complete the exercises, which are based on the Sample.Basic database, use the MaxL Shell.
Before continuing, start Essbase and log on to MaxL Shell. Additionally, be prepared to use a
text editor to create the sample queries as presented in this chapter.
Note: You can use the MDX Script Editor in Administration Services Console instead of the
MaxL Shell. However, the instructions in this chapter use the MaxL Shell.
577
SELECT
{}
ON COLUMNS
FROM Sample.Basic
SELECT in line 1 is the keyword that begins the main body of all MDX statements.
The braces { } in line 2 are a placeholder for a set. In the above query, the set is empty, but the
braces remain as a placeholder.
Create a folder to store sample queries that can be run against the Sample.Basic database.
Using a text editor, type the following code into a blank file:
SELECT
{}
ON COLUMNS
FROM Sample.Basic
Cola
Actual
COGS
[100]
If the member name starts with number or contains spaces, it should be within brackets; for
example, [100]. Brackets are recommended for all member names, for clarity and code
readability.
If the member name starts with an ampersand (&) , it should be within quotation marks;
for example, ["&xyz"]. This is because the leading ampersand is reserved for substitution
578
variables (see Using Substitution Variables in MDX Queries on page 597). You can also
specify it as StrToMbr("&100").
For attribute members, the long name (qualified to uniquely identify the member) should
be used; for example, [Ounces_12] instead of [12].
l
By specifying dimension name or any one of the ancestor member names as a prefix to the
member name; for example, [Product].[100-10] and [Diet].[100-10]. This practice
is recommended for all member names, as it eliminates ambiguity and enables you to refer
accurately to shared members.
Note: Do not use multiple ancestors in the member name qualification. Essbase returns an
error if multiple ancestors are included. For example, [Market].[New York] and
[East].[New York] are valid names for New York; however, [Market].[East].
[New York] returns an error.
Open qry_blank.txt.
Because a set can be as simple as one tuple, add Jan as a set to the query template. Retain the braces
(required for all set specifications except for sets that are produced by a function call).
In order for Essbase to receive MDX statements, pass the statements to Essbase using either the MaxL
Shell or MDX Script Editor in Administration Services. The examples in this chapter use the MaxL Shell.
Start the MaxL Shell and log on with a valid user name and password. For example,
essmsh -l admin passwd
Copy and paste the entire SELECT query into the MaxL Shell, but do not press Enter yet.
Enter a semicolon at the end, anywhere after Basic but before pressing Enter. The semicolon is not part
of MDX syntax requirements, but it is required by MaxL Shell to indicate the end of a statement that is
ready to execute.
579
Note: If you are using the MDX Script Editor in Administration Services, do not terminate
with a semicolon.
Press Enter.
In the following query, {([100-10], [Actual])} is a also a set consisting of one tuple, though in
this case, the tuple is not one member name. Rather, ([100-10], [Actual]) represents a tuple
consisting of members from two dimensions, Product and Scenario.
SELECT
{([100-10], [Actual])}
ON COLUMNS
FROM Sample.Basic
When a set has multiple tuples, the following rule applies: In each tuple of the set, members must
represent the same dimensions as do the members of other tuples of the set. Additionally, the
dimensions must be represented in the same order. In other words, each tuple of the set must
have the same dimensionality. For example:
l
The following set breaks the dimensionality rule, because Feb and Sales are from different
dimensions:
{(West, Feb), (East, Sales)}
The following set breaks the dimensionality rule, because although the two tuples contain
the same dimensions, the order of dimensions is reversed in the second tuple:
{(West, Feb), (Mar, East)}
Note: If an MDX query contains references to members that do not exist in the outline, the
unresolved member names can be skipped so that the query can continue without error.
In the Oracle Essbase Technical Reference, see MDX Member Specification.
580
Axes
ON COLUMNS
ON ROWS
ON PAGES
ON CHAPTERS
ON SECTIONS
For example, in the following query, the axis specification is {Jan}ON COLUMNS:
SELECT
{Jan} ON COLUMNS
FROM Sample.Basic
Open qry_blank.txt.
Add a comma after ON COLUMNS; then add a placeholder for a second axis by adding ON ROWS:
SELECT
{}
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
As the set specification for the column axis, enter the Product members 100-10 and 100-20. For
example:
581
SELECT
{[100-10],[100-20]}
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
Because these member names contain special characters, you must use brackets. The
convention used here, to enclose all member names in brackets even if they do not contain
special characters, is recommended.
As the set specification for the row axis, enter the Year members Qtr1 through Qtr4.
SELECT
{[100-10],[100-20]}
ON COLUMNS,
{[Qtr1],[Qtr2],[Qtr3],[Qtr4]}
ON ROWS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
100-20
Qtr1
5096
1359
Qtr2
5892
1534
Qtr3
6583
1528
Qtr4
5206
1287
Open qry_blank_2ax.txt.
On the column axis, specify two tuples, each of which is a member combination rather than a single
member. Enclose each tuple in parentheses, because multiple members are represented in each tuple.
SELECT
{([100-10],[East]), ([100-20],[East])}
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
On the row axis, specify four two-member tuples, nesting each Quarter with Profit:
SELECT
{([100-10],[East]), ([100-20],[East])}
582
ON COLUMNS,
{
([Qtr1],[Profit]), ([Qtr2],[Profit]),
([Qtr3],[Profit]), ([Qtr4],[Profit])
}
ON ROWS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
100-20
East
East
Qtr1
Profit
2461
212
Qtr2
Profit
2490
303
Qtr3
Profit
3298
312
Qtr4
Profit
2430
287
Cube Specification
A cube specification is the part of the query that determines which database is being queried.
The cube specification fits into an MDX query as follows:
SELECT <axis> [, <axis>...]
FROM <database>
The <database> section follows the FROM keyword and should consist of delimited or
nondelimited identifiers that specify first an application name and a then database name; for
example, the following specifications are valid:
l
FROM Sample.Basic
FROM [Sample.Basic]
FROM [Sample].[Basic]
FROM'Sample'.'Basic'
where the first argument you provide is the member that begins the range, and the second
argument is the member that ends the range. The layertype argument is optional. See the
Oracle Essbase Technical Reference.
Note: An alternate syntax for MemberRange is to use a colon between the two members, instead
of using the function name: member1 : member2.
Open qry_blank.txt.
Delete the braces {}, which are unnecessary when you are using a function to return the set.
Use the colon operator to select a member range of Qtr1 through Qtr4:
SELECT
[Qtr1]:[Qtr4]
ON COLUMNS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
Use the MemberRange function to select the same member range, Qtr1 through Qtr4.
SELECT
MemberRange([Qtr1],[Qtr4])
ON COLUMNS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
Results: The same results should be returned when running the queries listed in step 3 and
step 5.
The CrossJoin function takes two sets from different dimensions as input and creates a set that
is a cross product of the two input sets, useful for creating symmetric reports.
584
Open qry_blank_2ax.txt.
Add two comma-separated pairs of braces as placeholders for the two set arguments you will provide
to the CrossJoin function:
SELECT
CrossJoin ({}, {})
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
In the first set, specify the Product member [100-10]. In the second set, specify the Market members
[East], [West], [South], and [Central].
SELECT
CrossJoin ({[100-10]}, {[East],[West],[South],[Central]})
ON COLUMNS,
{}
ON ROWS
FROM Sample.Basic
On the row axis, use CrossJoin to cross a set of Measures members with a set containing Qtr1:
SELECT
CrossJoin ({[100-10]}, {[East],[West],[South],[Central]})
ON COLUMNS,
CrossJoin (
{[Sales],[COGS],[Margin %],[Profit %]}, {[Qtr1]}
)
ON ROWS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
When using CrossJoin, the order of arguments affects the order of tuples in the output.
Note: Consider using CrossJoinAttribute if the input sets are a base dimension and its attribute
585
Table 113
100-10
100-10
100-10
East
West
South
Central
Sales
Qtr1
5731
3493
2296
3425
COGS
Qtr1
1783
1428
1010
1460
Margin %
Qtr1
66.803
59.118
56.01
57.372
Profit %
Qtr1
45.82
29.974
32.448
24.613
Note: An alternate syntax for Children is to use it as an operator on the input member, as follows:
member.Children. We will use the operator syntax in this exercise.
To use the Children function to introduce a shortcut in the first axis specification:
1
Open qry_crossjoin_func.txt.
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
Results: You should see the same results as those shown in returned for Table 113 on page 586.
586
Level numbers begin with 0 at the leaf-most part of the hierarchy, and the highest level number
is a dimension name.
A number of MDX functions take a layer you specify as an input argument and perform set
operations based on the generation or level represented in the layer argument.
You can specify a layer argument in the following ways:
l
Note: In the Sample.Basic database, Qtr1 and Qtr4 are in the same layer. This means that Qtr1
and Qtr4 are also in the same generation. However, in a different database with a ragged
hierarchy, Qtr1 and Qtr4 might not necessarily be in the same level, although they are in
the same generation. For example, if the hierarchy of Qtr1 drills down to weeks, and the
hierarchy of Qtr4 stops at months, Qtr1 is one level higher than Qtr4, but they are still in
the same layer.
where the layer argument you provide indicates the generation or level of members you want
returned.
Note: An alternate syntax for Members is layer.Members.
Open qry_blank.txt.
Use the Members function and the Levels function to select all level 0 members in the Market dimension
of Sample.Basic:
587
SELECT
Members(Market.levels(0))
ON COLUMNS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
Use the slicer axis to set the context of the query; it is usually the default context for all the other
axes.
For example, for a query to select only Actual Sales in the Sample.Basic database, excluding
budgeted sales, the WHERE clause might look like the following:
WHERE ([Actual], [Sales])
Because (Actual, Sales) is specified in the slicer axis, you need not include them in the ON
AXIS(n) set specifications.
Note: The same dimension cannot appear on other axes and the slicer axis. To filter an axis
using criteria from its own dimension, you can use a sub select. For more information,
see MDX Sub Select in Oracle Essbase Technical Reference.
Open gry_crossjoin_func.txt.
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query.
Note the results in one of the data cells; for example, notice that the first tuple,
([100-10],[East],[Sales],[Qtr1]), has a value of 5731.
Add a slicer axis to limit the data returned to budgeted values only.
SELECT
CrossJoin ({[100-10]}, {[East],[West],[South],[Central]})
588
ON COLUMNS,
CrossJoin (
{[Sales],[COGS],[Margin %],[Profit %]}, {[Qtr1]}
)
ON ROWS
FROM Sample.Basic
WHERE (Budget)
Paste the query into the MaxL Shell and run it.
Results: You should see different results for the queries listed in step 1 and step 3.
Relationship Function
Description
Children
Siblings
Descendants
Table 115 on page 589 lists the relationship functions that return a single member rather than
a set:
Table 115
Relationship Function
Description
Ancestor
Cousin
Returns a child member at the same position as a member from another ancestor.
Parent
FirstChild
LastChild
FirstSibling
LastSibling
For examples using relationship functions, see the MDX examples in the MaxL section of the
Oracle Essbase Technical Reference.
589
Description
CrossJoin, CrossJoinAttribute
Distinct
Except
Generate
Head
Intersect
Subset
Returns a subset from a set, in which the subset is a numerically specified range of tuples.
Tail
Union
Use the Intersect function to compare sets by finding tuples that are present in both sets.
Open qry_blank.txt.
Delete the braces {} from the axis, and replace them with Intersect() . For example:
SELECT
Intersect (
)
ON COLUMNS
FROM Sample.Basic
Add two comma-separated pairs of braces to use as placeholders for the two set arguments you will
provide to the Intersect function. For example:
SELECT
Intersect (
{ },
{ }
)
590
ON COLUMNS
FROM Sample.Basic
For the second set argument, specify all members of the Market dimension that have a UDA of Major
Market. For example:
SELECT
Intersect (
{ [East].children },
{ UDA([Market], "Major Market") }
)
ON COLUMNS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query on
page 579.
Results: All children of East that have a UDA of Major Market are returned. For example:
New York
Massachusetts
Florida
8202
6172
5029
Use the Union function to lump two sets together into one set.
Open qry_intersect_func.txt.
Paste the query into the MaxL Shell and run it.
Results: A comparison of theses query results with the results using the Intersect function (see
Exercise: Using the Intersect Function on page 590) shows that while Intersect returns a set
591
containing only those children of East that have a UDA of Major Market, Union returns {all
children of east) + (all Market Members that have a UDA of Major Market).
For more examples using pure set-operative functions, see the Oracle Essbase Technical
Reference.
Calculated Members
A calculated member is a hypothetical member that exists for the duration of the query execution.
Calculated members enable complex analysis without necessitating adding new members to the
database outline. Calculated members are a storage place for calculation results performed on
actual members.
Use the following guidelines for calculated member names:
l
Associate the calculated member with a dimension; for example, to associated the member
MyCalc with the Measures dimension, name it [Measures].[MyCalc].
Do not use actual member names to name calculated members; for example, do not name
a calculated member [Measures].[Sales], because Sales already exists in the Measures
dimension.
Setting the solve order for each calculated member is recommended when you use multiple
calculated members to create ratios or custom totals. For more information about solve order,
see the MDX section of the Oracle Essbase Technical Reference.
Open qry_blank_2ax.txt.
On the row axis set, specify the children of Product. For example:
SELECT
{}
ON COLUMNS,
592
{[Product].children}
ON ROWS
FROM Sample.Basic
At the beginning of the query, add a placeholder for the calculated member specification. For example:
WITH MEMBER [].[]
AS ''
SELECT
{}
ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
To associate the calculated member with the Measures dimension and name it Max Qtr2 Sales, add
this information to the calculated member specification. For example:
WITH MEMBER [Measures].[Max Qtr2 Sales]
AS ''
SELECT
{}
ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
After the AS keyword and inside the single quotation marks, define the logic for the calculated member
named Max Qtr2 Sales.
Use the Max function with the set to evaluate (Qtr2) as the first argument, and the measure
to evaluate (Sales) as the second argument. For example:
WITH MEMBER [Measures].[Max Qtr2 Sales]
AS '
Max (
{[Year].[Qtr2]},
[Measures].[Sales]
)'
SELECT
{}
ON COLUMNS,
{[Product].children}
ON ROWS
FROM Sample.Basic
The calculated member Max Qtr2 Sales is defined in the WITH section. To use it in a query, include it
on one of the axes in the SELECT portion of the query. Select the predefined calculated member on the
columns axis. For example:
WITH MEMBER [Measures].[Max Qtr2 Sales]
AS '
Max (
{[Year].[Qtr2]},
[Measures].[Sales]
)'
SELECT
{[Measures].[Max Qtr2 Sales]}
ON COLUMNS,
{[Product].children}
593
ON ROWS
FROM Sample.Basic
Paste the query into the MaxL Shell and run it, as described in Exercise: Running Your First Query on
page 579.
27187
200
27401
300
25736
400
21355
Diet
26787
Named Sets
You define named sets in the WITH section of the query. Doing so is useful because you can
reference the set by name when building the SELECT section of the query.
For example, the named set Best5Prods identifies a set of the five top-selling products in
December:
WITH
SET [Best5Prods]
AS
'Topcount (
[Product].members,
5,
([Measures].[Sales], [Scenario].[Actual], [Year].[Dec])
)'
SELECT [Best5Prods] ON AXIS(0),
{[Year].[Dec]} ON AXIS(1)
FROM Sample.Basic
594
Table 118
Function
Description
Filter
Returns the subset of tuples in set for which the value of the search condition is TRUE.
IIF
Performs a conditional test and returns an appropriate numeric expression or set depending on whether the test evaluates to
TRUE or FALSE.
Case
Generate
The Filter function in MDX is comparable to the RESTRICT command in Report Writer.
For more examples of Filter and other iterative functions, see the Oracle Essbase Technical
Reference.
Including the optional keywords NON EMPTY before the set specification in an axis causes
suppression of slices in that axis that would contain entirely #MISSING values.
For any given tuple on an axis (such as (Qtr1, Actual)), a slice consists of the cells arising
from combining this tuple with all tuples of all other axes. If all of these cell values are #MISSING,
the NON EMPTY keyword causes elimination of the tuple.
For example, if even one value in a row is not empty, the entire row is returned. Including NON
EMPTY at the beginning of the row axis specification would eliminate the following row slice
from the set returned by a query:
595
Qtr1
Actual
#MISSING
#MISSING
#MISSING
#MISSING
#MISSING
In addition to suppressing missing values with NON EMPTY, you can use the following MDX
functions to handle #MISSING results:
l
CoalesceEmpty, which searches numeric value expressions for non #MISSING values
IsEmpty, which returns TRUE if the value of an input numeric-value-expression evaluates
to #MISSING
Avg, which omits missing values from averages unless you use the optional IncludeEmpty
flag
The NonEmptyCount MDX function returns the count of the number of tuples in a set that
evaluate to non-#Missing values. Each tuple is evaluated and included in the count returned by
this function. If the numeric value expression is specified, it is evaluated in the context of every
tuple, and the count of non-#Missing values is returned.
On aggregate storage databases only, the NonEmptyCount MDX function is optimized so that
the calculation of the distinct count for all cells can be performed by scanning the database only
once. Without this optimization, the database is scanned as many times as the number of cells
corresponding to the distinct count. The NonEmptyCount optimization is triggered when an
outline member formula has the following syntax:
NONEMPTYCOUNT(set, measure, exclude_missing)
Given an input set, the NonEmptySubset MDX function returns a subset of that input set in
which all tuples evaluate to nonempty. An optional value expression may be specified for the
nonempty check. This function can help optimize queries that are based on a large set for which
the set of nonempty combinations is known to be small. NonEmptySubset reduces the size of
the set in the presence of a metric; for example, you might request the nonempty subset of
descendants for specific Units.
For more information and examples, see the MDX section of the Oracle Essbase Technical
Reference.
596
The substitution variable must be accessible from the application and database you are
querying.
A substitution variable has two components: the name and the value.
The variable name can be an alphanumeric combination whose maximum size is specified
in Appendix A, Limits. Do not use spaces, punctuation, or brackets ([ ]) in substitution
variable names used in MDX.
At the point in the expression where you want to use the variable, show the variable name
preceded by an ampersand (&); for example, where CurMonth is the name of the substitution
variable set on the server, include &CurMonth in the MDX expression.
When you perform the retrieval, Essbase replaces the variable name with the substitution
value, and that value is used by the MDX expression.
For example, the expression is written showing the variable name CurQtr preceded with the &:
SELECT
{[&CurQtr]}
ON COLUMNS
FROM Sample.Basic
When the expression is executed, the current value (Qtr1) is substituted for the variable name,
and the expression that is executed is:
SELECT
{[Qtr1]}
ON COLUMNS
FROM Sample.Basic
597
of members in the Product dimension. This information can be queried in MDX using the
property name [Pkg Type].
Attribute properties are defined only for specific dimensions and only for a specific level in each
dimension. For example, in the Sample.Basic outline, [Ounces] is an attribute property defined
only for members in the Product dimension, and this property has valid values only for the level
0 members of the Product dimension. The [Ounces] property does not exist for other
dimensions, such as Market. The [Ounces] property for a non level 0 member in the Product
dimension is a NULL value. The attribute properties in an outline are identified by the names
of attribute dimensions in that outline.
The custom properties also include UDAs. For example, [Major Market] is a UDA property
defined on Market dimension members. It returns a TRUE value if [Major Market] UDA is
defined for a member, and FALSE otherwise.
You can list the dimension and property combinations for each axis set. When a query is
executed, the specified property is evaluated for all members from the specified dimension
and included in the result set.
For example, on the column axis, the following query returns the GEN_NUMBER
information for every Market dimension member. On the row axis, the query returns
MEMBER_ALIAS information for every Product dimension member.
SELECT
[Market].Members
DIMENSION PROPERTIES [Market].[GEN_NUMBER] on columns,
Filter ([Product].Members, Sales > 5000)
DIMENSION PROPERTIES [Product].[MEMBER_ALIAS] on rows
FROM Sample.Basic
When querying for member properties using the DIMENSION PROPERTIES section of an
axis, a property can be identified by the dimension name and the name of the property, or
by using the property name itself. When a property name is used by itself, that property
information is returned for all members from all dimensions on that axis, for which that
property applies. In the following query, the MEMBER_ALIAS property is evaluated on the
row axis for Year and Product dimensions.
SELECT [Market].Members
DIMENSION PROPERTIES [Market].[GEN_NUMBER] on columns,
CrossJoin([Product].Children, Year.Children)
DIMENSION PROPERTIES [MEMBER_ALIAS] on rows
FROM Sample.Basic
l
Properties can be used inside value expressions in an MDX query. For example, you can
filter a set based on a value expression that uses properties of members in the input set.
The following query returns all caffeinated products that are packaged in cans.
SELECT
Filter([Product].levels(0).members,
598
[Product].CurrentMember.Caffeinated and
[Product].CurrentMember.[Pkg Type] = "Can")
xDimension Properties
[Caffeinated], [Pkg Type] on columns
FROM Sample.Basic
The following query calculates the value [BudgetedExpenses] based on whether the current
Market is a major market, using the UDA [Major Market].
WITH
MEMBER [Measures].[BudgetedExpenses] AS
'IIF([Market].CurrentMember.[Major Market],
[Marketing] * 1.2, [Marketing])'
SELECT {[Measures].[BudgetedExpenses]} ON COLUMNS,
[Market].Members ON ROWS
FROM Sample.Basic
WHERE ([Budget])
When a property is used in a value expression, you must use it appropriately based on its value
type: string, numeric, or Boolean.
You can also query attribute dimensions with numeric ranges.
The following query retrieves Sales data for Small, Medium, and Large population ranges.
SELECT
{Sales} ON COLUMNS,
{Small, Medium, Large} ON ROWS
FROM Sample.Basic
599
When attributes are used as properties in a value expression, you can use range members to
check whether a member's property value falls within a given range, using the IN operator.
For example, the following query returns all Market dimension members with the population
range in Medium:
SELECT
Filter(
Market.Members, Market.CurrentMember.Population
IN "Medium"
)
ON AXIS(0)
FROM Sample.Basic
none of the members in the Year dimension have aliases defined for them. Therefore, the query
returns NULL values for the MEMBER_ALIAS property for members in the Year dimension.
The attribute properties are defined for members of a specific dimension and a specific level in
that dimension. In the Sample.Basic database, the [Ounces] property is defined only for level 0
members of the Product dimension.
Therefore, if you query for the [Ounces] property of a member from the Market dimension, as
shown in the following query, you will get a syntax error:
SELECT
Filter([Market].members,
[Market].CurrentMember.[Ounces] = 32) ON COLUMNS
FROM Sample.Basic
Additionally, if you query for the [Ounces] property of a non level 0 member of the dimension,
you will get a NULL value.
When using property values in value expressions, you can use the function IsValid() to check
for NULL values. The following query returns all Product dimension members with an [Ounces]
property value of 12, after eliminating members with NULL values.
SELECT
Filter([Product].Members,
IsValid([Product].CurrentMember.[Ounces]) AND
[Product].CurrentMember.[Ounces] = 12)
600
ON COLUMNS
FROM Sample.Basic
601
602
37
In This Chapter
Process for Creating a Database Subset .............................................................. 603
Exporting Data............................................................................................ 607
603
To stop a database:
See Stopping Databases in the Oracle Essbase Administration Services Online Help.
If you can connect, use any of the following methods to copy the outline:
Tool
Topic
Location
Administration Services
Copying Outlines
MaxL
create database
ESSCMD
COPYDB
If you can not connect, use the operating system to copy the outline file.
1. Use the operating system to copy the source outline file; for example, copy
basic.otl to westmkts.otl.
2. Give the copied outline exactly the same name as the new database.
3. Save the outline file in the ARBORPATH/app/appname/dbname directory on the Essbase
Server 2 computer, where ARBORPATH is the directory in which you installed Essbase,
and appname and dbname are the new application and database that you have created.
For example, copy basic.otl to a disk, renaming it to westmkts.otl. Then copy
westmkts.otl from the disk to the following directory on Essbase Server 2:
Oracle/Middleware/EPMSystem11R1/products/Essbase/EssbaseServer/app/west/westmkts/
westmkts.otl
604
Note: Ensure that the new outline file overwrites the existing, empty outline file, which
Essbase created automatically when you created the new application and
database.
4. Stop and restart the new database.
See Starting Databases and Stopping Databases in the Oracle Essbase Administration
Services Online Help.
You now have a copy of the database outline on Essbase Server 2.
See Navigating and Selecting Objects in the Oracle Essbase Administration Services Online
Help.
l
If you can connect to the Essbase Server 1 database from the Essbase Server 2 computer,
you can select the source database from Essbase Server 2.
If you cannot connect, use a different computer from the Essbase Server 2 computer to
select the source database.
Create a report.
See Creating Scripts in the Oracle Essbase Administration Services Online Help.
Write a report script that selects the required data subset. For information about writing report scripts,
see Chapter 34, Understanding Report Script Basics.
For example, the following report script selects the Actual, Measures data for the West
market from Sample.Basic:
{TABDELIMT}
QUOTEMBRNAMES
Actual
<IDESC West
<IDESC Measures
l
Use TABDELIMIT to place tab stops between data, instead of spaces, to ensure that no
member names or data values are truncated.
Use QUOTEMBRNAMES to place quotation marks (" ") around member names that
contain blank spaces. Essbase then recognizes the member names when it loads the data.
See Executing Report Scripts in the Oracle Essbase Administration Services Online Help.
605
Save the report script with a .txt extension; for example, westout.txt.
If you are not using the Essbase Server 2 computer, save the output file anywhere on the
current computer. By default, Essbase saves the file on the Essbase client computer and not
on the server. When you run the report, use the operating system to copy the file to the
ARBORPATH/app/appname/dbname directory on Essbase Server 2. For example, use a disk
to copy the file.
If you are not using the Essbase Server 2 computer, download and copy the file from the
Essbase client directory to the ARBORPATH/app/appname/dbname directory on Essbase
Server 2. For example, copy the output file to:
Oracle/Middleware/EPMSystem11R1/products/Essbase/EssbaseServer/app/west/westmkts/
westout.txt
You are now ready to load the text file into the new database.
606
If required, you can copy report scripts and other artifact files to the Essbase Server 2 computer
to use with the database subset that you have created.
Exporting Data
To export data from a database to move data between Essbase databases or to a format that
can be read by programs other than Essbase, use a tool:
Tool
Topic
Location
Smart View
MaxL
export data
Calculation scripts
Report scripts
Note: When you use MaxL, calculation scripts, or Administration Services Console to export
text data, and the end fields of the last record have no values, those fields will not contain
the missing value marker (such as #MI). To improve overall processing time, the fields
are left blank in the last output record.
Export files from databases in Unicode-mode applications are in UTF-8 encoding. If Essbase
finds insufficient disk space for the export file, no data is exported.
If you plan to import Essbase data into a program that requires special delimiters, use the Report
Writer MASK command or the delimiter parameter of the DATAEXPORT calculation
command to specify the delimiter.
For more information about exporting data for backup purposes, see the Oracle Hyperion
Enterprise Performance Management System Backup and Recovery Guide.
You can use report scripts or calculation scripts to export Essbase data in text format. Both tools
enable you to create text files that meet the import format specifications of most other programs.
Block storage databases: You can export all data, level-0 data, or input-level data, which does
not include calculated values.
To export data in parallel, specify a comma-separated list of export files, up to a maximum
of 1024 file names. The number of file names determines the number of export threads. The
607
number of available block-address ranges limits the number of export threads that Essbase
actually uses. Essbase divides the number of actual data blocks by the specified number of
file names (export threads). If there are fewer actual data blocks than the specified number
of export threads, the number of export threads that are created is based on the number of
actual data blocks. This approach results in a more even distribution of data blocks between
export threads.
Note: In specifying the number of export files, it is important to consider the number of
available CPU cores and I/O bandwidth on the computer on which Essbase Server
runs. Specifying too large a number can result in poor performance.
Note: Parallel export operations on block storage databases do not dynamically create
threads, but instead use a set number of threads from a pre-created pool of threads.
You can customize the size of the thread pool. For more information, see the
WORKERTHREADS configuration setting topic in the Oracle Essbase Technical
Reference.
l
Aggregate storage databases: You can export only level-0 data, which does not include
calculated values. (Level-0 data is the same as input data in aggregate storage databases.)
You cannot perform upper-level data export or columnar export on an aggregate storage
database.
To export data in parallel, specify a comma-separated list of export files, from 1 to 8 file
names. The number of threads Essbase uses typically depends on the number of file names
you specify. However, on a very small aggregate storage database with a small number of
data blocks, it is possible that only a single file will be created (in effect, performing serial
export), even though parallel export to multiple files is requested.
Export files are stored in the ARBORPATH/app directory on the server unless an absolute path is
specified.
608
DATAEXPORTCOLFORMAT ON;
DATAEXPORTCOLHEADER Scenario;
};
FIX ("100-10","New York","Actual","Qtr1");
DATAEXPORT "File" "," "C:\exports\actual.txt" "NULL";
ENDFIX;
These commands specify inclusion of all levels of data and indicate that data is to be repeated
in columns, with the Scenario dimension set as the dense dimension column header for the
output. The FIX command defines the data slice, and then the data is exported to a text file at
C:\exports\actual.txt. Commas are used as delimiters, and missing data values are
indicated by consecutive delimiters. Running this script against Sample.Basic generates the
following data:
"Actual"
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
"100-10","New
York","Sales","Qtr1",1998
York","COGS","Qtr1",799
York","Margin","Qtr1",1199
York","Marketing","Qtr1",278
York","Payroll","Qtr1",153
York","Misc","Qtr1",2
York","Total Expenses","Qtr1",433
York","Profit","Qtr1",766
York","Opening Inventory","Qtr1",2101
York","Additions","Qtr1",2005
York","Ending Inventory","Qtr1",2108
York","Margin %","Qtr1",60.01001001001001
York","Profit %","Qtr1",38.33833833833834
York","Profit per Ounce","Qtr1",63.83333333333334
For information about DATAEXPORT calculation commands, see the Oracle Essbase Technical
Reference.
609
Sales
<ICHILDREN "400"
East
Budget
!
Resulting report:
Qtr1
Qtr1
Qtr1
Qtr1
Qtr2
Qtr2
Qtr2
Qtr2
Qtr3
Qtr3
Qtr3
Qtr3
Qtr4
Qtr4
Qtr4
Qtr4
Year
Year
Year
Year
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
400-10
400-20
400-30
400
400-10
400-20
400-30
400
400-10
400-20
400-30
400
400-10
400-20
400-30
400
400-10
400-20
400-30
400
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
900
1,100
800
2,800
1,100
1,200
900
3,200
1,200
1,100
900
3,200
1,000
1,200
600
2,800
4,200
4,600
3,200
12,000
To create a two-dimensional report that contains only bottom-level (level 0) data, use
CHILDREN or DIMBOTTOM to select level 0 members.
l
To list only level 0 data for specific members, use the CHILDREN command with the level
1 member as a parameter above the data that you want to print.
To list all level 0 data for the dimension to which a given member belongs, use the
DIMBOTTOM command with any member in the dimension that contains the data that
you want to print.
For example, the following script uses the CHILDREN command to select the children of Qtr1,
which is a level 1 member, and the DIMBOTTOM command to select all level 0 data in the
Product dimension.
<ROW (Year, Measures, Product, Market, Scenario)
{ROWREPEAT}
{DECIMAL 2}
<CHILDREN Qtr1
Sales
<DIMBOTTOM Product
East
Budget
!
Resulting report:
Jan
Jan
Jan
610
Sales
Sales
Sales
100-10
100-20
100-30
East
East
East
Budget
Budget
Budget
1,600.00
400.00
200.00
Jan
Jan
Jan
Jan
Jan
Jan
Jan
Jan
Jan
Jan
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Feb
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Mar
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
Sales
200-10
200-20
200-30
200-40
300-10
300-20
300-30
400-10
400-20
400-30
100-10
100-20
100-30
200-10
200-20
200-30
200-40
300-10
300-20
300-30
400-10
400-20
400-30
100-10
100-20
100-30
200-10
200-20
200-30
200-40
300-10
300-20
300-30
400-10
400-20
400-30
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
East
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
Budget
300.00
200.00
#MISSING
700.00
#MISSING
400.00
300.00
300.00
400.00
200.00
1,400.00
300.00
300.00
400.00
200.00
#MISSING
700.00
#MISSING
400.00
300.00
300.00
300.00
300.00
1,600.00
300.00
400.00
400.00
200.00
#MISSING
600.00
#MISSING
400.00
300.00
300.00
400.00
300.00
For another example of formatting for data export, see Sample 12 on the Examples of Report
Scripts page in the Report Writer Commands section of the Oracle Essbase Technical
Reference.
611
612
38
In This Chapter
Integrating Relational Databases with Essbase ....................................................... 613
XOLAP Overview .......................................................................................... 613
XOLAP Workflow .......................................................................................... 614
Guidelines for Using XOLAP ............................................................................. 614
Optimizing XOLAP ........................................................................................ 615
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
XOLAP Overview
XOLAP (extended online analytic processing) is a variation on the role of OLAP in business
intelligence. Specifically, XOLAP is an Essbase multidimensional database that stores only the
outline metadata and retrieves data from a relational database at query time. XOLAP thus
integrates a source relational database with an Essbase database, leveraging the scalability of the
relational database with the more sophisticated analytic capabilities of a multidimensional
613
database. Your business needs determine whether OLAP or XOLAP is best suited to your
environment.
OLAP and XOLAP store the metadata outline and the underlying data in different locations:
l
In OLAP, the metadata is located in the Essbase database, and the underlying data is also
located in the Essbase database.
In XOLAP, the metadata is located in the Essbase database while the underlying data remains
in your source relational database.
The differences in the locations of the metadata and data are key to understanding how XOLAP
can be of benefit because these differences affect the functionality of OLAP and XOLAP.
OLAP lends itself to traditional relational data storage and data analysis. XOLAP lends itself to
operations supported in mixed or hybrid environments.
For information on guidelines and restrictions in using XOLAP and how to designate models
for XOLAP, see the Oracle Essbase Studio User's Guide.
XOLAP Workflow
The workflow of data retrieval in an XOLAP environment is much like that of a non-XOLAP
environment:
1. The model is designated as XOLAP-enabled in Essbase Studio.
2. The cube is deployed in Essbase Studio; however, no data is loaded at that time.
3. The Essbase database is queried using Smart View or other reporting tools that can access
Essbase databases.
4. Essbase dynamically generates the required SQL to retrieve the data from the source
relational database.
XOLAP has several restrictions. There are also several usages not supported in XOLAP.
614
No editing of an XOLAP cube is allowed. If you wish to modify an outline, you must, instead,
create a new outline in Essbase Studio. XOLAP operations will not automatically incorporate
any changes in the structures and the contents of the dimension tables after an outline is
created.
l
When derived text measures are used in cube schemas to build an Essbase model, XOLAP
is not available for the model.
XOLAP can be used only with aggregate storage. The database is automatically duplicatemember enabled.
XOLAP supports dimensions that do not have a corresponding schema-mapping in the
catalog; however, in such dimensions, only one member can be a stored member.
XOLAP is supported for these data sources only:
m
IBM DB2
Netezza
Teradata
Flat files
Ragged hierarchies
Alternate hierarchies
Recursive hierarchies
Calendar hierarchies
Filters
Typed measures
Optimizing XOLAP
Use the following Essbase configuration settings to optimize XOLAP performance:
l
615
616
Part VI
617
618
39
In This Chapter
Using Essbase in EPM System Security Mode ........................................................ 619
Security for Users and Groups in EPM System Security .............................................. 620
Essbase User Roles for Shared Services............................................................... 623
Essbase Projects, Applications, and Databases in Shared Services................................ 624
Essbase Users and Groups in Shared Services ....................................................... 626
Assigning Access to Users in Shared Services ........................................................ 626
Migrating Essbase from Native Security to EPM System Security ................................... 629
User and Group Identities ............................................................................... 633
Security Information Recovery in EPM System Security Mode....................................... 634
Also see:
l
619
In EPM System security mode, Essbase obtains user and group details (including user and group
information and provisioning to Essbase applications) from Shared Services. Essbase no longer
stores all users and groups in the Essbase security file (essbase.sec); therefore, an Essbase
Administrator does not need to explicitly synchronize security between Essbase and Shared
Services.
When a user logs on to Essbase, Essbase queries Shared Services for that users information. The
privileges with which a user starts a session are preserved throughout the session, regardless of
whether the users privileges are changed in Shared Services during the session.
A user or group is stored in the Essbase security file only under the following circumstances:
l
To remove users or groups from the Essbase security file without de-provisioning them from
Shared Services, use the drop user or drop group MaxL statements with the from security_file
grammar. Calculation and filter associations also are removed.
Note: The drop user and drop group MaxL statements are deprecated, except when using the
from security_file grammar. Oracle recommends using Shared Services Console, Java
API, or Lifecycle Management to remove users and groups instead of using MaxL or C
API.
For display operations, Essbase queries Shared Services.
620
The user's access level for a specific database before migration to Shared Services
The users access level after migration to Shared Services, including access acquired through
groups and other means
The users filter assignments
In Shared Services, if an Essbase application contains multiple databases, the databases must
have the same user security access levels (however, users can have different calculation script
and database filters assigned for databases within the same application). During migration to
Shared Services, if a user has different access levels for two databases in the same application,
the user is given the more restrictive access level for both databases.
When migrating Shared Services users with the option to have user passwords automatically
generated, those user names and passwords are written to a text file named
MigratedUsersPassword.txt, which is located in the ARBORPATH/bin directory. If the
Administrator designated a specific password for the migrated users, the password is not listed
in the file. This file is created when performing an upgrade or migration.
To log on to Essbase and access the Essbase agent, a user no longer must have the Server
Access role on the global Essbase Server application. A user with any role (whether directly
or indirectly provisioned) on an Essbase application can log on to Essbase and access the
Essbase agent.
To prevent users who do not have a role on the global Essbase Server application from
accessing the Essbase agent, you must manually modify users roles. Be sure to evaluate the
roles that a user inherits from a group.
When a user logs on to Essbase, Essbase queries Shared Services for the users roles. The
more roles that a user has, the longer it takes to complete the login process. To improve
login performance, users should not be assigned unneeded roles.
Essbase no longer assigns the Application Manager role, which is unnecessary, to an Essbase
Administrator when he creates an Essbase application. If, in your Essbase deployment, the
Application Manager role is assigned to Essbase Administrators, you must manually remove
the Application Manager role from the Essbase Administrators.
621
Also, an Essbase Administrator who has an Administrator role on the global Essbase Server
application might be assigned application roles that are not needed. Essbase provides a
migration utility that can remove the application roles for Essbase Administrators only.
The migration utility (which runs on 32-bit Windows only), identifies the users who are affected
by both security issues. Additionally, if specified, the utility can correct the issue of Essbase
Administrators having application roles.
In the MigrationTools subdirectory, edit the migration.properities file with the following
information:
l
EssbaseProjectNameThe project name for the Essbase Server on which you want to
run the migration utility
SavedToFileWhen set to TRUE, specifies that the results of the migration script should
be written to the following text files, which are located in the MigrationTools
subdirectory:
m
application roles but do not have a role on the global Essbase Server application
m
622
Note: When running the utility for the first time against an Essbase Server, Oracle
Product-specific roles
Examples of Essbase roles are Administrator and Database Manager. All Essbase roles are
specific to a Shared Services application (the permissions granted to the user by the role
apply only to the specific application for which the role is assigned, and not to all
applications).
The following Essbase roles provide different levels of authority to perform tasks in Essbase.
You can provision a user with the following roles for an Essbase Server:
l
Administrator
Create/Delete Application
Server Access
You can provision a user with the following roles for an application:
l
Application Manager
Database Manager
Calc
Write
Read
Filter
Start/Stop Application
In Shared Services Console, roles belonging to Essbase are grouped under the Essbase node; roles
belonging to Essbase applications are grouped under the application nodes.
623
User Role
Task Description
Project Manager
(A Shared Services role) Creates and manages projects within Shared Services.
Administrator
(previously Supervisor)
Create/Delete
Application
Ability to create and delete applications and databases within applications. Includes Application Manager and
Database Manager permissions for the applications and databases created by this user.
Server Access
Ability to access any application or database that has a minimum access permission other than none.
Application Manager
(previously Application
Designer)
Ability to create, delete, and modify databases and application settings within the particular application. Includes
Database Manager permissions for databases within the application.
Note: The Provisioning Manager role, which is a Shared Services application-specific role, is automatically
assigned when you migrate Essbase Administrators (previously known as Supervisors). However, when you create
an Essbase Administrator in Shared Services Console, you must manually assign the Provisioning Manager role.
Users with the Provisioning Manager role can provision users and groups with roles for applications.
An Application Manager can delete only those applications and databases that he created.
Note: The Provisioning Manager role is automatically assigned when you migrate Essbase Application
Managers. However, when you create an Essbase Application Manager in Shared Services Console, you must
manually assign the Provisioning Manager role.
Database Manager
(previously Database
Designer)
Ability to manage databases (for example, to change the database properties or cache settings), database
artifacts, locks, and sessions within the assigned application.
Calc
Ability to calculate, update, and read data values based on the assigned scope, using any assigned calculations
and filter.
Write
Ability to update and read data values based on the assigned scope, using any assigned filter.
Read
Filter
Ability to access specific data and metadata according to the restrictions of a filter.
Start/Stop Application
for an application. See the Oracle Enterprise Performance Management System User Security
Administration Guide.
Shared Services and Essbase both use the term application. Essbase uses application to refer
to a container for databases. Shared Services uses application to refer to an artifact for which
you provision users. In this topic, application refers to a Shared Services application, unless
an Essbase application is specifically stated. In most cases, an Essbase application maps to a
Shared Services application, so the distinction is unnecessary.
For Essbase, migration is done at the Essbase Server level. When you migrate an Essbase Server
to Shared Services, a Shared Services project is created for the Essbase Server. The project is
named Essbase:machineName:EssbaseServer#, where machineName is the Essbase Server
computer name and EssbaseServer# is the sequence number. The sequence number for the
first Essbase Server that is migrated is 1. When migrating multiple Essbase Servers on the same
computer, the sequence number is incremented by 1. Also, if you delete the security file and
remigrate an Essbase Server, each successful migration creates a new server project with a new
sequence number. You can delete unwanted projects in Shared Services Console.
Essbase automatically creates the following applications within the project and automatically
registers the applications with Shared Services:
l
After you have migrated to Shared Services, when you create an application and database in
Essbase, a corresponding Shared Services application is created within the Essbase Server project,
and the application is automatically registered with Shared Services.
625
EPM System security mode, user and group security is not copied with the application.
Use the copy provisioning functionality in Shared Services Console to copy security for
an application.
Shared Services Console provides a centralized UI where you can perform user management
tasks for EPM System products. The Shared Services Console launches Essbase screens, which
allow you to assign security access to database filters and calculation scripts. In EPM System
security mode, you use Shared Services Console, MaxL, or the API to manage security.
Note: Some restrictions exist when managing security using MaxL or the C API. It is
recommended to use Shared Services Console, Java API, or Oracle Hyperion Enterprise
Performance Management System Lifecycle Management for user and group
management tasks, instead of using MaxL or C API. For specific restrictions on MaxL,
see the MaxL section of Oracle Essbase Technical Reference.
In Administration Services Console, you can only view security information.
626
For information on assigning access to users and groups and viewing a report of users, groups,
and provisioned roles for each application, see the Oracle Enterprise Performance Management
System User Security Administration Guide.
When you launch Shared Services Console, you log on as whichever user is appropriate. For
example, you must log on as a Shared Services Administrator to provision an Essbase
Administrator with the Directory Manager role, so that he or she can create and delete users.
627
Note: When you provision a user with the Essbase Administrator role, you must also manually
provision the user with the Provisioning Manager role for the Essbase Server and for each
Essbase application on the server. (When you migrate an Essbase Administrator, the
Provisioning Manager role is automatically assigned.)
provision the user with the Provisioning Manager role for the appropriate application.
(When you migrate an Essbase Application Manager, the Provisioning Manager role is
automatically assigned.)
You can set minimum permissions for an application, for example, if you want all users to have
at least write access to all databases in an application. The default setting is None, meaning that
no minimum permission is set; all users can access the application according to their roles.
628
Topic
Location
Administration Services
MaxL
grant
When you assign database calculation and filter access, you automatically log on to
Administration Services and Essbase as the Shared Services Console logged-in user. This user
must be an Essbase Administrator, Application Manager, or Database Manager. The user must
have the Provisioning Manager role for the appropriate applications.
You cannot assign database calculation or filter access to an Essbase Administrator or
Application Manager.
If Essbase and Administration Services use Essbase native security mode, you must migrate each
deployment to EPM System security mode. For Essbase, migration is done at the Essbase Server
629
level. After you have converted to EPM System security mode, you cannot convert back to
Essbase native security mode. Essbase native security mode is no longer supported.
You must be an Essbase Administrator to run a migration.
To migrate Essbase Server, Essbase Administration Server, and users and groups to EPM
System security, use a tool:
Tool
Topic
Location
Administration Services
MaxL
alter system
For Essbase Administration Server, if you ran Oracle Hyperion Enterprise Performance
Management System Configurator after installation and specified a Shared Services server and
login, at that point, Essbase Administration Server is converted to EPM System security mode.
You can view the Shared Services configuration information in the Essbase Administration
Server properties window (Configuration tab). You can then migrate Administration Services
users to Shared Services.
You must be an Administration Services Administrator to migrate Administration Services
users.
To migrate Administration Services users or to remigrate any Essbase users and groups that
failed migration, use a tool:
Tool
Topic
Location
Administration Services
MaxL
alter group
alter user
display group
display user
Note: Before migrating users, groups, and applications to Shared Services, ensure that the
630
Essbase automatically creates a backup of the security file before and after migration
(essbase.bak_preUPM and essbase.bak_postUPM). Oracle suggests that you manually back
up these files to a safe location.
The Administration Services Essbase Server Properties window displays information on whether
the server is in EPM System security mode.
631
Shared Services cannot contain two groups at different levels in the same hierarchy (an
ancestor-child relationship) when the groups exist in Essbase (see Example 2). If it does, the
entire migration process fails.
The Shared Services group cannot contain a user that does not exist in the Essbase group of
the same name. If it does, the Essbase group, and all users in the group, do not migrate.
The Essbase group cannot contain a user that exists in Shared Services, unless the Shared
Services user belongs to the Shared Services group of the same name. If it does, the Essbase
group, and all users in the group, do not migrate.
Shared Services has two identical groups and also has a group 3, which contains group 1 and
group 2:
group 3
|
group 1, group 2
The groups migrate successfully because group 1 and group 2 are at the same level as each other
in Shared Services and because Essbase does not have a group 3.
Note: If group 3 has Administrator (previously known as Supervisor) access to the Essbase Server
instance and Essbase group 1 and group 2 have user access, the resulting group 1 and
group 2 in Shared Services will have Administrator access.
632
Example 2: The migration in this example fails because Shared Services contains group 1 and
group 2 at different levels.
Essbase has groups named group 1 and group 2:
group 1, group 2
Shared Services has group 1 and group 2, but group 1 contains group 2:
group 1
|
group 2
Example 3: The migration in this example fails because Essbase contains group 1, group 2, and
group 3 and Shared Services contains group 3 at a different level from group 1 and group 2.
Essbase has groups named group 1, group 2, and group 3:
group 1, group 2, group 3
Shared Services has group 1 and group 2, but has a group 3, which contains group 1 and group
2:
group 3
|
group 1, group 2
or else Shared Services considers the @ character as a delimiter indicating a provider name.
For example, if you want to log in user admin@msad, who is on a Native Directory
provider, you must specify 'admin@msad@Native Directory'.
633
l
l
If a discrepancy occurs between the security information in Shared Services and the security
information in the Essbase security file, the type of discrepancy determines whether Shared
Services information or the Essbase security file information takes precedence.
scripts, and application access type are lost if the Shared Services backup does not have
that information. If the Essbase security backup file does not have that information, the
filters and calc scripts themselves are lost (not just the associations to the users or groups).
Application Information
Essbase takes precedence for application and database information. If an application is deleted
from Shared Services, the application is still available in Essbase. You must reregister the
application with Shared Services. If an application is deleted in Essbase, it is automatically deleted
from Shared Services.
Topic
Location
Administration Services
MaxL
alter application
634
40
In This Chapter
About the Essbase Security File ........................................................................ 635
Managing Essbase Security Backup Files ............................................................. 636
Restoring the Essbase Security File .................................................................... 637
Changing Essbase Security Backup File Comparison Frequency .................................... 638
Reconciling the Essbase Security File to the State of Essbase on an External Disk ............... 639
Managing Essbase Security File Fragmentation....................................................... 639
Exporting the Essbase Security File to a Readable Format .......................................... 640
Users
Groups
Passwords
Filter access
The content of essbase.sec is encrypted; however, the contents can be exported to a readable,
text file format, which is useful for review purposes. When exporting the essbase.sec file,
follow your companys security procedures to ensure the integrity of the data. See Exporting
the Essbase Security File to a Readable Format on page 640.
635
By default, Essbase creates a new security backup file every 300 seconds (which is five
minutes).
ENABLESWITCHTOBACKUPFILE configuration setting: Specifies whether Essbase
automatically loads a valid security backup file at startup if the essbase.sec file is invalid.
By default, Essbase does not load a security backup file at startup if the security file is invalid.
Also see Reconciling the Essbase Security File to the State of Essbase on an External Disk
on page 639.
The content of essbase_timestamp.bak is encrypted.
Topic
Location
Administration Services
MaxL
essbase.cfg
NUMBEROFSECFILEBACKUPS
SECFILEBACKUPINTERVAL
ENABLESWITCHTOBACKUPFILE
Note: Essbase automatically creates a backup of the security file before and after migration
(essbase.bak_preUPM and essbase.bak_postUPM). See Migrating Essbase from
636
To start Essbase in EPM System security mode, remove the Essbase project (for example,
EssbaseCluster-1) from Shared Services and then restart Essbase.
If the essbase.sec file is invalid, messages similar to the following ones are logged in the
essbase.log file:
[Mon Oct 08 15:35:19 2012]Local/ESSBASE0///2600/Warning(1056801)
Validation of security file [C:\Oracle\Middleware\user_projects\epmsystem1\EssbaseServer
\essbaseserver1\BIN\ESSBASE.SEC] failed
[Mon Oct 08 15:35:19 2012]Local/ESSBASE0///2600/Warning(1056801)
Validation of security file [C:\Oracle\Middleware\user_projects\epmsystem1\EssbaseServer
\essbaseserver1\bin\ESSBASE_1349731009.BAK] failed
637
If all security backup files are invalid, messages similar to the following ones are logged in the
essbase.log file:
...
rtype = 50630 rlen
Read Error:Part of
Read Error:Invalid
rtype = 12849 rlen
Read Error:Part of
Read Error:Invalid
= 50116 rindex =
security file is
security file
= 13363 rindex =
security file is
security file
49602
missing
32513
missing
Fatal Error: The security file is not valid and there are no valid back up files to use.
Restart Essbase after deleting the security file, a new security file will be created.
Again, remove the Essbase project (for example, EssbaseCluster-1) from Shared Services and
then restart Essbase.
For information on backup procedures for Shared Services and Essbase, see the Oracle Hyperion
Enterprise Performance Management System Backup and Recovery Guide and the documentation
for the appropriate external user directories.
Caution!
In Administration Services, the same check box manages how often the security backup file
is checked against the security file and how often user inactivity is checked.
The default value is five minutes, the recommended setting to ensure that the security backup
file is checked frequently enough to capture security changes. Five minutes is also the
recommended value for the inactivity check.
If you set the value to zero, the inactivity check is disabled, and the
essbase_timestamp.bak file is compared to essbase.sec every five minutes (and
updated if necessary).
Enter a larger value if your security file does not need to be updated frequently. Enter a
smaller value if performance is not an issue.
You can also update the security backup file anytime, not only at specified intervals.
638
To manually update the security backup file or change the frequency of backup file
comparisons, use a tool:
Tool
Topic
Location
Administration Services
MaxL
An application or database folder is on the disk but not in the security file
An application or database is in the security file but not on the disk. In this scenario, using
the alter system reconcile force grammar removes the application or database from the
security file.
Changing or deleting Essbase security entities, such as filters, users, groups, applications,
databases, substitution variables, disk volumes, passwords, and other Essbase artifacts, can cause
fragmentation in the security file (essbase.sec). Too much fragmentation in files can slow
down security-related performance.
Essbase compacts the security file automatically each time the Agent is stopped. You can check
the fragmentation status of the security file and you can compact the security file without
stopping the Agent.
To compact the security file without stopping the Agent, use a tool:
Tool
Topic
Location
Agent
COMPACT
Enter the Agent command at the command prompt in the Essbase Server window
MaxL
essbase.cfg
SECURITYFILECOMPACTIONPERCENT
Note: Compacting the security file while the Agent is running slows down Agent activity until
The export security file command, which can be run from Administration Services Console or
as a MaxL statement, is run against the Essbase Server session for which you are currently logged
in. The Essbase Server session can be run as a service.
Topic
Location
Administration Services
MaxL
export security_file
Note: The DUMP agent command is similar to the export security file command, except that
the DUMP command cannot be executed against an Essbase Server running as a service.
See Table 128 on page 691.
640
41
Controlling Access
to Database Cells Using Security
Filters
In This Chapter
About Security Filters .................................................................................... 641
Defining Permissions Using Security Filters ........................................................... 641
Creating Filters ........................................................................................... 643
Managing Filters.......................................................................................... 647
Assigning Filters .......................................................................................... 648
641
Filters comprise one or more access settings for database members. You can specify the following
access levels and apply them to data ranging from a list of members to one cell:
l
None: No data can be retrieved or updated for the specified member list.
Read: Data can be retrieved but not updated for the specified member list.
Write: Data can be retrieved and updated for the specified member list.
Metaread: Metadata (dimension and member names) can be retrieved and updated for the
corresponding member specification.
Note: The metaread access level overrides all other access levels. If additional filters for data are
defined, they are enforced within any defined metaread filters. If you have assigned a
metaread filter on a substitution variable and then try to retrieve the substitution variable,
an unknown member error occurs, but the value of the substitution variable is displayed.
This behavior is expected. Metadata security cannot be completely turned off in partitions.
Therefore, do not set metadata security at the source database; otherwise, incorrect data
may result at the target partition. When drilling up or retrieving on a member that has
metadata security turned on and has shared members in the children, an unknown
member error occurs because the original members of the shared members have been
filtered. To avoid this error, give the original members of the shared members metadata
security access.
Any cells that are not specified in the filter definition inherit the database access level. Filters
can, however, add or remove access assigned at the database level, because the filter definition,
being more data-specific, indicates a greater level of detail than the more general database access
level.
Data values not covered by filter definitions default to the access levels defined for users..
Calculation access is controlled by permissions granted to users and groups. Users who have
calculate access to the database are not blocked by filtersthey can affect all data elements that
the execution of their calculations would update.
Note: During the calculation of MDX calculated members, cells to which a user does not have
642
Creating Filters
Subtopics
l
l
l
l
You can create a filter for each set of access restrictions you need to place on database values.
You need not create separate filters for users with the same access needs. After you have created
a filter, you can assign it to multiple users or groups of users. However, only one filter per database
can be assigned to a user or group.
Note: If you use a calculation function that returns a set of members, such as children or
descendants, and it evaluates to an empty set, the security filter is not created. An error is
written to the application log stating that the region definition evaluated to an empty set.
Before creating a filter, perform the following actions:
l
Connect to the server and select the database associated with the filter.
Topic
Location
Administration Services
MaxL
create filter
Filtering members separately affects whole regions of data for those members.
643
Figure 141
Note: Filtering on member combinations (AND relationship) does not apply to metaread.
The next time user KSmith connects to Sample.Basic, her spreadsheet view of the profit margin
for Qtr1 (Figure 142) shows that she has no access to data values for the member Sales or the
member Jan, which are marked with #NOACCESS. All data for Sales is blocked from view, as
well as all data for January, inside and outside of the Sales member. Data for COGS (Cost of
Goods Sold), a sibling of Sales and a child of Margin, is available, with the exception of COGS
for January.
Figure 142
644
645
Metadata Filtering
Metadata filtering provides data filtering and an additional layer of security. With metadata
filtering, an administrator can remove outline members from a user's view, providing access
only to those members that are of interest to the user.
When a filter is used to apply MetaRead permission on a member:
1. Data for all ancestors of that member are hidden from the filter users view.
2. Data and metadata (member names) for all siblings of that member are hidden from the
filter users view.
646
Managing Filters
Subtopics
l
l
l
l
l
Viewing Filters
Editing Filters
Copying Filters
Renaming Filters
Deleting Filters
Viewing Filters
To view a list of filters, use a tool:
Tool
Topic
Location
Administration Services
MaxL
display filter
ESSCMD
LISTFILTERS
Editing Filters
To edit a filter, use a tool:
Tool
Topic
Location
Administration Services
MaxL
create filter
Copying Filters
You can copy filters to applications and databases on any Essbase Server, according to your
permissions. You can also copy filters across servers as part of application migration.
Topic
Location
Administration Services
Copying Filters
MaxL
create filter
ESSCMD
COPYFILTER
647
Renaming Filters
To rename a filter, use a tool:
Tool
Topic
Location
Administration Services
Renaming Filters
MaxL
create filter
ESSCMD
RENAMEFILTER
Deleting Filters
To delete a filter, use a tool:
Tool
Topic
Location
Administration Services
Deleting Filters
MaxL
drop filter
Assigning Filters
Subtopics
l
l
l
l
After you define filters, you can assign them to users or groups, which lets you manage multiple
users who require the same filter settings. Modifications to the definition of a filter are
automatically inherited by users of that filter.
Filters do not affect users who have the Administrator role. Only one filter per database can be
assigned to a user or group.
The third specification defines security at a greater level of detail than the other two. Therefore,
read access is granted to all Actual data for members in the New York branch.
Because write access is a higher access level than none, the remaining data values in Actual are
granted write access.
All other cells, such as Budget, are accessible according to the minimum database permissions.
If you have write access, you also have read access.
Note: Changes to members in the database outline are not reflected automatically in filters. You
In the first row, applying MetaRead to California has the effect of allowing access to California
but blocking access to its ancestors. Therefore, the MetaRead access to West is ignored; users
who are assigned this filter will have no access to West.
If you wish to assign MetaRead access to West, as well as California, the appropriate method is
to combine them into one row: Access: MetaRead. Member specification: California, West.
649
R
W
N
N
N
W
R
W
W
Example 2:
User Mary is defined with the following database access:
FINPLAN
PRODPLAN
R
N
She is assigned to Group Marketing, which has the following database access:
FINPLAN
PRODPLAN
N
W
R
W
In addition, Mary uses the filter artifact RED (for the database FINPLAN). The filter has two
filter rows:
l
The Group Marketing also uses a filter artifact BLUE (for the database FINPLAN). The filter has
two filter rows:
l
650
Marys effective rights from the overlapping filters, and the permissions assigned to her and her
group:
l
651
652
Part VII
653
654
42
In This Chapter
About Unicode ........................................................................................... 655
When to Use Unicode-Mode Applications ............................................................. 656
Locales and the ESSLANG Variable .................................................................... 657
Unicode and Non-Unicode Application Modes........................................................ 657
Unicode and Non-Unicode Essbase Server Modes ................................................... 658
Increased Name Lengths ................................................................................ 658
Compatibility Between Different Versions of Client Programs and Essbase Applications ......... 658
Unicode-Enabled C API.................................................................................. 659
Identification of Text Encoding and Locale ............................................................ 659
Unicode-Enabled Administration Tools ................................................................ 659
Retrieval Tools............................................................................................ 660
SQL Interface ............................................................................................. 660
Sample_U.Basic ......................................................................................... 661
The information in this chapter applies to block storage and aggregate storage databases.
About Unicode
Sharing data across national and language boundaries is a challenge for multinational businesses.
Traditionally, each computer stores and renders text based on its locale specification. A locale
identifies the local language and cultural conventions, such as currency and date format, data
sort order, and character-set encoding. Encoding refers to the bit combinations used to store the
character text as data, as defined by a code page or an encoding format. In Essbase, code pages
map characters to bit combinations for non-Unicode encodings.
Because different encodings can map the same bit combination to different characters, a file
created on one computer can be misinterpreted by another computer with a different locale.
The Unicode Standard enables computers with different locales to share character data. Unicode
provides encoding forms with thousands of bit combinations, enough to support the character
sets of multiple languages simultaneously. By combining all character mappings into one
encoding form, Unicode enables users to correctly view character data created on computers
with different locale settings.
655
Essbase conforms to version 2.1 of the Unicode Standard and uses UTF-8 encoding. See
www.unicode.org.
Through its Unicode implementation, Essbase enables employees of global businesses to view,
in their own languages, company information stored in Essbase databases. For example, using
alias tables in their respective languages, users in Taiwan can view database reports in Chinese
characters, and users in France can view the same reports in French characters.
The following topics describe the characteristics of the Essbase implementation of Unicode.
Note: In Essbase, user-defined character sets (UDC) are not supported.
You need to enable users with different languages to view, in their own languages and
character sets, information from a common database.
For example, using alias tables in Japanese and German, users in Japan and Germany can
view information about a common product set in their own languages.
You need to handle artifact names longer than non-Unicode-mode applications support.
For example, application and database names need to include more than eight characters,
or you are working with a multibyte character set, and you need to handle more characters
in artifact names.
See Appendix A, Limits.
When deciding whether to use Unicode-mode applications, consider the following points:
l
To work with Unicode-mode applications, custom client programs that were written to
support non-Unicode-mode applications must be built to use the longer strings used by
Unicode-mode applications. This task may be a simple rebuild or may involve
reprogramming, depending on the design of the applications. Depending on how modified
programs are coded, more memory may be required.
See the Oracle Essbase API Reference.
656
657
Unicode-mode and non-Unicode-mode applications can reside on the same Essbase Server.
programs.
To take advantage of longer name sizes, users may decide to work with Unicode-mode
applications, even if all users work in the same locale (see When to Use Unicode-Mode
Applications on page 656).
658
Unicode-mode client programs (for example, Administration Services Console and Smart View):
l
Note: If you use Administration Services Console or another tool to create a MaxL script and
save it in UTF-8 and then execute the script in MaxL Shell, MaxL Shell assumes the role
of a Unicode-mode client. You can use this approach, for example, to update outlines
through dimension builds. When you create the script, remember to include the UTF-8
signature. See Encoding Indicators on page 669.
Unicode-Enabled C API
Custom-written client programs used with pre-7.0 Essbase releases cannot be used with
Unicode-mode applications because these custom programs use short strings and short buffers.
To provide restricted access to Unicode-mode applications, these older custom client programs,
depending on how they are written, can be recompiled in a Unicode-enabled release of Essbase.
When recompiled, the programs work with long buffers but short strings.
For complete access to Unicode-mode and non-Unicode-mode applications, existing custom
applications must be modified using the Essbase API functions for Unicode. Rewritten and
compiled clients work with long buffers and long strings for full Unicode support. See the Oracle
Essbase API Reference.
659
Retrieval Tools
Essbase provides several methods for retrieving data from Unicode-mode and non-Unicodemode applications.
Report Script
Report script output files are encoded to the encoding of the application. For example, if a report
script is run against a database in a Unicode-mode application, the report script output is
encoded in UTF-8; if run against a database in a non-Unicode-mode application, the output is
encoded in the encoding of the application.
Spreadsheet
With Smart View, you can view data in Unicode-mode and non-Unicode-mode applications.
To run Smart View, you connect to Provider Services. To install these programs, see the Oracle
Enterprise Performance Management System Installation and Configuration Guide.
For information about working with Smart View, see the Oracle Smart View for Office User's
Guide.
SQL Interface
With SQL Interface, you can load data from a Unicode-mode relational database to a Unicodemode Essbase application. Table 120 shows supported encodings for Unicode-mode and nonUnicode-mode applications:
Table 120
Application mode
Non-Unicode
Unicode
Unicode
UTF-8
SQL Interface accepts user authentication (user name and password) and application
information in UTF-8 encoding.
See Supported Locales on page 671.
660
Sample_U.Basic
To learn more about Unicode-mode applications, use the Sample_U.Basic application. Member
names in Sample_U.Basic are in English.
Table 121 lists the non-English alias tables and their import files included in the Sample_U.Basic
database:
Table 121
Language
Chinese
nameschn.alt
German
namesger.alt
Japanese
namesjpn.alt
Russian
namesrsn.alt
661
662
43
Administering Unicode-Mode
Applications
In This Chapter
Setting Up a Computer for Unicode Support .......................................................... 663
Defining Password Security ............................................................................. 663
Naming Applications and Databases .................................................................. 664
Managing Unicode-Mode Essbase Servers ............................................................ 664
Managing Unicode-Mode Applications ................................................................ 665
Using Control Characters in Report Scripts ............................................................ 667
Working with Partitions .................................................................................. 667
Working with Logs........................................................................................ 667
Managing File Encoding ................................................................................. 668
The information in this chapter applies to block storage and aggregate storage databases.
UTF-8 fonts: For viewing UTF-8 encoded text that contains non-ASCII characters
(Optional) Unicode editor (which includes the UTF-8 signature): For manual editing of
data sources or other text files
Essbase provides the Essbase Unicode File Utility, which converts text files to UTF-8 encoding.
See Essbase Unicode File Utility on page 673.
663
127, which includes the uppercase and lowercase letters in the standard English alphabet and
the numerals 0 through 9. These characters are common to all code pages and to UTF-8.
Topic
Location
Administration Services
MaxL
alter system
Note: The UNICODEENABLE setting, when added to essbase.cfg, enables you to create
Unicode-mode applications without needing to set the Essbase Server to Unicode mode.
You can also work with Unicode-mode applications without Essbase Server being set to
Unicode mode.
664
Topic
Location
Administration Services
MaxL
display system
Topic
Location
Administration Services
MaxL
create application
If needed, apply the outline change files and then remove them.
If present, outline change files reside in each database directory, with the database name as
the file name and a .chg extension; for example, /sample/basic/basic.chg.
To avoid mixing Unicode encoding and non-Unicode encoding in log files, back up log files
and then clear or remove them.
Log files end with any of the following extensions: .log, .xcp, and .olg.
Grant Essbase Server permission to migrate applications to Unicode mode. See Setting
Essbase Server to Unicode Mode on page 664.
665
Topic
Location
Administration Services
MaxL
alter application
Text files, such as calculation scripts, report scripts, and data sources, are not converted to UTF-8
encoding. For Unicode-mode applications, text files can be encoded in UTF-8 or in non-Unicode
locales. You can use Essbase Unicode File Utility to convert non-Unicode-encoded files to
UTF-8. See Essbase Unicode File Utility on page 673.
Note: If you choose to work with non-Unicode text files in your Unicode-mode application,
ensure that you understand how Essbase determines the locales of non-Unicode text files.
See Managing File Encoding on page 668.
Topic
Location
Administration Services
Monitoring Applications
MaxL
display application
666
Unicode-mode applications and non-Unicode-mode applications that use multibyte code pages
support the following Hexadecimal control characters in report scripts:
x20, x09, x0A, x0C, x0D
Application logs, use Log Viewer or Log Analyzer in Administration Services, or a UTF-8
editor
Outline change logs, use a UTF-8 editor
667
You cannot change the encoding of log files related to Unicode-mode applications to nonUnicode encoding.
across multiple locales. Using UTF-8 encoding is simpler, because you need not keep track
of locales and encoding, and it can be more efficient, because Essbase Administration
Server uses Unicode encoding internally, and no internal conversion between formats is
needed.
The following topics describe how Essbase determines the encoding of files and how you manage
files with different encoding.
be encoded in UTF-8.
Essbase and Administration Services use file-encoding indicators (UTF-8 signature or locale
indicator) to know whether a file is encoded in UTF-8 or in a supported non-Unicode encoding.
A locale indicator is optional for a non-Unicode input file whose encoding matches the locale
of Essbase Server. If, however, the encoding does not match, you must provide a locale indicator.
See Encoding Indicators on page 669.
UTF-8-encoded text files must include the UTF-8 signature.
Administration Services uses the following process to determine the encoding of a non-Unicodeencoded file:
1. If a locale indicator is present in the file, Administration Services uses the specified encoding.
668
2. If a locale indicator is not present, and the file is located within an application,
Administration Services uses the encoding specified in the Essbase Server locale.
3. It a locale indicator is not present, and the file is not located within an application,
Administration Services determines the encoding based on the type of file:
l
When Essbase performs a dimension build or data load, the rules file and data file can have
different encodings. For example, the text in a rules file can be in UTF-8 encoding, and the data
source can be encoded to a non-Unicode computer locale.
Note: When you use Administration Services Console to create script files or data sources, the
appropriate encoding indicator is automatically included in the file. If you use any other
tool to create Unicode-encoded text files, you must ensure that the UTF-8 signature is
included. Non-Unicode-encoded text files require a locale indicator if the encoding is
different from the Essbase Server locale.
The following Essbase system text files are encoded to the locale specified by the ESSLANG value
defined for Essbase Server:
l
essbase.cfg
ESSCMD scripts
Encoding Indicators
To properly interpret text, such as member names, Essbase must know how it is encoded. Many
files contain an encoding indicator, but occasionally you may be prompted to specify the
encoding; for example, in the following cases:
l
Administration Services creates a file and stores it in a different location than the Essbase
Server
Administration Services reads a file created by a non-Unicode, pre-7.0 release of Essbase
Files that are internal to applications and databases and that users cannot directly edit are
primarily binary files and do not contain encoding indicators.
Character text in these files is encoded based on the application mode:
m
Binary files that you can edit (such as outline and rules files)
669
As needed, Essbase keeps track internally of whether the character text is in UTF-8 encoding.
If not UTF-8, Essbase uses an internal locale indicator to identify the locale used for character
text encoding.
l
The following text files that you can edit use a UTF-8 signature or a locale indicator to
indicate their encoding:
m
Calculation scripts
Report scripts
MaxL scripts
Caution!
Alias table import files (Administration Services requires alias table import files to be
UTF-8 encoded)
Do not use non-Unicode-encoded files containing locale indicators with pre-7.0
release Essbase Server installations, which are not Unicode enabled. To remove the
locale indicators, use Essbase Unicode File Utility. See Essbase Unicode File Utility
on page 673.
UTF-8 Signature
UTF-8-encoded text files must contain the UTF-8 signature, which is a mark at the beginning
of a text file. This signature is visible in some third-party UTF-8 text editors.
Many UTF-8 text editors can create the UTF-8 signature, or you can use the Essbase Unicode
File Utility to insert the UTF-8 signature into a file (see Essbase Unicode File Utility on page
673).
When you create a file using Administration Services Console, a UTF-8 signature is automatically
inserted in the file.
Do not insert a locale header record in a UTF-8 encoded file. If a text file contains
both types of encoding indicators, the locale header is read as the first data record.
locale-name is a supported Global C locale in the format that is used for the ESSLANG variable:
language_territory.code_page_name@sortsequence
670
The following example displays a locale header record for a specific Russian code page:
//ESS_LOCALE Russian_Russia.ISO-8859-5@Default
Note: Essbase consults only the code_page_name portion of the record. The sortsequence
After locale-name, use a blank, tab or <end of line> to end the header.
For compatibility, Administration Services Console saves calculation scripts on a pre-7.0 release
Essbase Server installation in a different format. Instead of prefixing the locale with //,
Administration Services Console inserts the locale header between calculation script comment
indicators:
/* */
Supported Locales
The following supported locales can be used in locale header records, in Essbase Unicode File
Utility, and as ESSLANG variable values:
Arabic_SaudiArabia.ISO-8859-6@Default
Arabic_SaudiArabia.MS1256@Default
Croatian_Croatia.ISO-8859-2@Croatian
Croatian_Croatia.MS1250@Croatian
CyrillicSerbian_Yugoslavia.ISO-8859-5@Default
CyrillicSerbian_Yugoslavia.MS1251@Default
Czech_CzechRepublic.ISO-8859-2@Czech
Czech_CzechRepublic.MS1250@Czech
Danish_Denmark.ISO-8859-15@Danish
Danish_Denmark.IBM500@Danish
Danish_Denmark.Latin1@Danish
Danish_Denmark.MS1252@Danish
Dutch_Netherlands.IBM037@Default
Dutch_Netherlands.IBM500@Default
Dutch_Netherlands.ISO-8859-15@Default
Dutch_Netherlands.Latin1@Default
Dutch_Netherlands.MS1252@Default
English_UnitedStates.IBM037@Binary
English_UnitedStates.IBM285@Binary
English_UnitedStates.IBM500@Binary
English_UnitedStates.MS1252@Binary
English_UnitedStates.Latin1@Binary
English_UnitedStates.US-ASCII@Binary
Finnish_Finland.IBM500@Finnish
671
Finnish_Finland.ISO-8859-15@Finnish
Finnish_Finland.Latin1@Finnish
Finnish_Finland.MS1252@Finnish
French_France.IBM297@Default
French_France.IBM500@Default
French_France.ISO-8859-15@Default
French_France.Latin1@Default
French_France.MS1252@Default
German_Germany.IBM273@Default
German_Germany.IBM500@Default
German_Germany.ISO-8859-15@Default
German_Germany.Latin1@Default
German_Germany.MS1252@Default
Greek_Greece.ISO-8859-7@Default
Greek_Greece.MS1253@Default
Hebrew_Israel.ISO-8859-8@Default
Hebrew_Israel.MS1255@Default
Hungarian_Hungary.ISO-8859-2@Hungarian
Hungarian_Hungary.MS1250@Hungarian
Italian_Italy.IBM280@Default
Italian_Italy.IBM500@Default
Italian_Italy.ISO-8859-15@Default
Italian_Italy.Latin1@Default
Italian_Italy.MS1252@Default
Japanese_Japan.IBM930@Binary
Japanese_Japan.JapanEUC@Binary
Japanese_Japan.MS932@Binary
Korean_Korea.MS1361@Binary
Korean_Korea.MS949@Binary
Norwegian_Norway.IBM500@Danish
Norwegian_Norway.ISO-8859-10@Danish
Norwegian_Norway.ISO-8859-15@Danish
Norwegian_Norway.ISO-8859-4@Danish
Norwegian_Norway.Latin1@Danish
Norwegian_Norway.MS1252.Default
Portuguese_Portugal.IBM037@Default
Portuguese_Portugal.IBM500@Default
Portuguese_Portugal.ISO-8859-15@Default
Portuguese_Portugal.Latin1@Default
Portuguese_Portugal.MS1252@Default
Romanian_Romania.ISO-8859-2@Romanian
Romanian_Romania.MS1250@Romanian
Russian_Russia.ISO-8859-5@Default
Russian_Russia.MS1251@Default
Serbian_Yugoslavia.ISO-8859-2@Default
Serbian_Yugoslavia.MS1250@Default
SimplifiedChinese_China.IBM935@Binary
SimplifiedChinese_China.MS936@Binary
Slovak_Slovakia.ISO-8859-2@Slovak
Slovak_Slovakia.MS1250@Slovak
Slovenian_Slovenia.ISO-8859-10@Slovenian
Slovenian_Slovenia.ISO-8859-2@Slovenian
Slovenian_Slovenia.ISO-8859-4@Slovenian
Slovenian_Slovenia.MS1250@Slovenian
Spanish_Spain.IBM500@Spanish
Spanish_Spain.ISO-8859-15@Spanish
Spanish_Spain.Latin1@Spanish
672
Spanish_Spain.MS1252@Spanish
Swedish_Sweden.IBM500@Swedish
Swedish_Sweden.ISO-8859-15@Swedish
Swedish_Sweden.Latin1@Swedish
Swedish_Sweden.MS1252@Swedish
Thai_Thailand.MS874@Thai
TraditionalChinese_Taiwan.EUC-TW@Binary
TraditionalChinese_Taiwan.IBM937@Binary
TraditionalChinese_Taiwan.MS950@Binary
Turkish_Turkey.ISO-8859-3@Turkish
Turkish_Turkey.ISO-8859-9@Turkish
Turkish_Turkey.MS1254@Turkish
Ukrainian_Ukraine.ISO-8859-5@Ukrainian
Ukrainian_Ukraine.MS1251@Ukrainian
Removing locale indicators from files (the utility cannot remove UTF-8 signatures).
Calculation scripts
Report scripts
MaxL scripts
Outline files
Rules files
For information about this utility and its command syntax, see the Oracle Essbase Technical
Reference.
673
674
Part VIII
Maintaining Essbase
In Maintaining Essbase:
l
l
l
l
l
l
l
l
675
676
44
In This Chapter
About OPMN.............................................................................................. 677
About OPMN Failover Functionality..................................................................... 677
Starting and Stopping Essbase Using OPMN.......................................................... 679
Logging In to Essbase Using Logical Names .......................................................... 680
Understanding Essbase Failover Clusters.............................................................. 680
Conditions for Agent and Server Terminations ........................................................ 684
Universal/Uniform Naming Convention (UNC) Paths ................................................. 686
Configuration for SSL Encrypted Communication with Provider Services ........................... 687
About OPMN
Oracle Process Manager and Notification server (OPMN) enables you to monitor and control
the Essbase Agent process. You add Essbase Agent information to the opmn.xml file to enable
Oracle Process Manager and Notification Server to start, stop, and restart the agent using the
OPMN command line interface. OPMN can automatically restart the Essbase Agent when it
becomes unresponsive, terminates unexpectedly, or becomes unreachable as determined by ping
and notification operations. OPMN is installed in EPM_HOME.
Figure 145 shows how Essbase integrates with OPMN.
Note: In the opmn.xml file, the essbase-port-range, agent-port, and agent-secure-port
parameters take precedence over similar configuration settings in the essbase.cfg file.
677
Figure 145
Oracle Process Manager Modules (PM Modules) communicate with the Essbase Agent for
process administration and health monitoring. As a managed component, the Essbase Agent
and OPMN communicate using Oracle Notification Server (ONS), which is the transport
mechanism for notifications between components.
When you start Essbase using the OPMN command line interface (see Starting and Stopping
Essbase Server on page 692), OPMN spawns the agent process and sets the status to
initialized (a message is logged in the opmn.log file). Whether this state transitions to alive
depends on whether OPMN receives a response (a reverse ping) from the agent, which implies
that the agent is active.
After Essbase is up and running, OPMN periodically sends a TCP-based forward ping to the
agent. If a ping attempt fails, OPMN retries up to three times to contact the agent. If all ping
attempts fail, OPMN stops the agent. OPMN attempts to restart the agent for these scenarios:
l
678
Failover mode is on, which supersedes the restart-on-death value. If restart-ondeath is FALSE and failover mode is on, OPMN may bring up Essbase on the active or
passive node.
When you stop Essbase using the OPMN command line interface, OPMN shuts down the agent,
thereby releasing all resources held by the agent. Essbase Servers shut down when they detect
that the parent agent process has shut down.
opmnctl startall
opmnctl stopall
opmnctl status
If you did not implement failover clustering, EssbaseInstanceName is the name of the
Essbase instance that you entered when you configured Essbase Server.
If you implemented failover clustering, EssbaseInstanceName is the name of the Essbase
cluster that you entered when you set up the Essbase cluster.
Note that the Essbase Server start and stop scripts redirect to OPMN. See the Oracle Enterprise
Performance Management System Installation and Configuration Guide.
679
For more information on OPMN commands, see the Oracle Process Manager and Notification
Server Administrator's Guide.
For troubleshooting and logging information, see Oracle Enterprise Performance Management
System Installation and Configuration Troubleshooting Guide.
To simplify login, Essbase clients should use the logical cluster name directly, in the form
<name>:<secure>, instead of the URL. If you want to enable client login using the cluster name,
you must first specify a property to configure Provider Services. The cluster name is resolved by
the Provider Services servers specified in configuration files:
l
680
Figure 146
Why Leases?
How Leases Work
How Leases are Implemented
Logging
681
Why Leases?
Essbase failover uses a leasing mechanism to solve the problem of split-brain. A split-brain
situation can develop when both instances in an active-passive clustered environment think they
are active and are unaware of each other, which violates the basic premise of active-passive
clustering. Situations where split-brain can occur include network outages or partitions.
Shared resources
Lease ownership
Lease validity
The set of tables used for this purpose is created during Essbase installation and configuration.
These tables reside in the same database and schema as the Shared Services Registry.
On startup, Essbase Agent and servers inspect the database table to see if any other process
currently owns the lease for its shared resource . If yes, the agent and servers wait until the lease
expires and retries. If not, the agent and servers take ownership of the shared resource; that is,
they get a lease.
The agent and servers acquires a lease on startup and surrender the lease on termination. The
agent and servers periodically renew the lease to indicate its health. If the lease cannot be renewed,
the agent and servers self-terminate.
Lease ownership grants exclusive right to update a set of shared resources residing on a shared
disk. The lease owner (Essbase Agent or Essbase Server) attempts to renew the lease within a
preconfigured interval of time. See the AGENTLEASERENEWALTIME and
SERVERLEASERENEWALTIME configuration settings in the Oracle Essbase Technical
Reference.
Logging
Diagnostic messages specific to lease management are logged in Lease Manager logs. See the
Oracle Enterprise Performance Management System Installation and Configuration
Troubleshooting Guide.
682
Agent Parameter
Value
20 seconds
10 seconds
Table 123
Server Parameter
Value
20 seconds
10 seconds
The time delay between each lease acquire failed attempt until maximum retry is calculated based
on how much time is left for the lease to expire. If the lease is available and acquire fails, then
the delay could be one second. See the Oracle Essbase Technical Reference.
Table 124
OPMN Parameter
Default Value
restart-on-death
FALSE. If FAILOVERMODE is set to TRUE (in essbase.cfg), you must change this value to TRUE so that OPMN
restarts Essbase Agent if it terminates abnormally.
shutdown-forceenabled
FALSE. You must set this to TRUE if you enabled Essbase failover clustering.
20 seconds
OPMN PROC_
READY (reverse
ping) Interval
20 seconds
Agent Start or
Restart Retries
10 minutes
Setting this to TRUE enables you to forcibly kill Essbase if graceful shutdown by OPMN fails.
This means that OPMN tolerates two failures to start or restart the agent before marking this instance as nonfunctional
for this service, which is when the agent service failover begins in failover mode; otherwise it will throw an error.
683
OPMN Parameter
Default Value
OPMN Agent
Restart Timeout
10 minutes
10 minutes
See the Oracle Process Manager and Notification Server Administrator's Guide.
Failure Condition
Assumed
Working
Failover Functionality
Essbase Agent
Software bug
Network
Lease expired
Shared disk
Abnormal error
condition
Software bug
Lease expired
Abnormal error
condition
Network
Shared disk
684
Failure Condition
Assumed
Working
Failover Functionality
Network outage
Essbase Agent
(on current active
node)
(network partition,
that is. primary IP
[eth0] down on active
node)
Essbase Servers
(on current active
node)
Shared disk
Lease database
(potentially, if
reachable using
from a different
network interface
not eth0)
Essbase.lck file
Not applicable
Not applicable
Essbase.sec file is
Network
Shared disk
(non-unique scenario;
could be a follow on to
Essbase Agent crash
or network partition)
Disk outage
Network
Network
Shared disk
Service unavailable.
Both active and passive nodes are
unable to run Essbase.
685
Failure Condition
Assumed
Working
Failover Functionality
Node failure
(catastrophic
hardware failure)
Network
Shared disk
Network
Shared disk
Essbase Agent
Essbase Servers
Essbase Agent and
server hang
(application bug)
Network
Shared disk
Essbase Agent
For Essbase running on Windows, UNC paths are supported to specify network shared paths
for the following Essbase Server application artifacts:
l
ARBORPATH
UNC paths are not supported for all other file paths, including client side paths for data load
and dimension build.
For full documentation of UNC syntax, see MSDN.
686
Set this variable if the connection goes through SSL, but does not need a certificate. Essbase
provides data encryption, but not authentication.
If API_DISABLE_PEER_VERFICATION is not set, or is set to 0, you must set up a certificate. To
establish a secure connection with Provider Services, Essbase requires a CA signing of a Provider
Services certificate, to provide authentication for the Provider Services server. You can specify
either a file or a directory which includes the certificate. Choose one of the following options:
API_CAINFO=CA certificate file path
or
API_CAPATH=directory path containing CA certificates
The environment variables described are only applied when logging with a Provider Services
URL that starts with https. Logins with the http URL are directed through TCP/IP.
687
688
45
In This Chapter
Essbase Executable Files................................................................................ 689
Understanding the Agent ................................................................................ 690
Starting and Stopping Essbase Server ................................................................. 692
Starting and Stopping Applications .................................................................... 694
Starting and Stopping Databases ...................................................................... 696
Managing Ports........................................................................................... 698
Communicating with Essbase Using SSL .............................................................. 700
Controlling Query Size and Duration ................................................................... 701
Increasing Agent Connections to Essbase Server..................................................... 701
Limiting the Number of User Sessions ................................................................. 702
Executable File1
Description
Location
See
essbase.exe
ESSBASEPATH/bin
esssvr.exe
Application process
ESSBASEPATH/bin
essmsh.exe
MaxL Shell
ESSBASEPATH/bin
esscmd.exe
ESSCMD command-line
client interface
ESSBASEPATH/bin
adminsvr.exe or
startEAS.exe
Essbase Administration
Server executable
EPM_ORACLE_HOME/
products/Essbase/eas/
server/bin
admincon.bat
Administration Services
Console application
EPM_ORACLE_HOME/
products/Essbase/eas/
server/bin
1On
689
Multithreading
essbase.exe and esssvr.exe (ESSBASE and ESSSVR on UNIX) are multithreading and
Number of Ports
15 ports
610 ports
10
11+ ports
20
You can set the number of threads for the Agent or Essbase Server in the essbase.cfg file using
the AGENTTHREADS, AGTSVRCONNECTIONS, and SERVERTHREADS configuration
settings. See the Oracle Essbase Technical Reference.
690
Table 128
Agent
Command
Function
START appname
ESSCMD: LOADAPP
ESSCMD: UNLOADAPP
STOP appname
USERS
Number of connections
(lists all users and shows which users are logged on)
l
PORTS
l
l
LOGOUTUSER
user
PASSWORD
COMPACT
ESSCMD: LISTUSERS
ESSCMD: N/A
Administration Services: Edit, then Properties (Essbase
Server Properties window, Statistics tab) on the server node
in Enterprise View
ESSCMD: LOGOUTUSER
ESSCMD: SETPASSWORD
ESSCMD: N/A
691
Agent
Command
DUMP filename
Function
Dumps information from the Essbase security file
(essbase.sec) to a specified file in text (ASCII)
format. If you do not supply a path with the filename,
the file is saved to the ARBORPATH/bin directory.
This command requires the Essbase system
password.
Note: You cannot use the DUMP command against
an Essbase Server that is run as a service. If the server
is running as a service, use the Export Security File
command in Administration Services or the export
security_file MaxL statement.
VERSION
ESSCMD: N/A
ESSCMD: GETVERSION
HELP
N/A
ESSCMD: SHUTDOWNSERVER
opmnctl startall
opmnctl stopall
692
For additional methods for starting and stopping Essbase Server, see the Oracle Enterprise
Performance Management System Installation and Configuration Guide. Note that the Essbase
Server start and stop scripts redirect to OPMN.
Note: You cannot start Essbase Server from ESSCMD or MaxL. If you attempt to use MaxL to
shut down an Essbase instance that was started using OPMN, you are warned to use
OPMN to shut down Essbase.
In a Windows environment, before you launch Essbase, change the OPMN service (Oracle
Process Manager (instanceName)) to start as a named user so that the shared network
files are accessible.
To have the script to return to a command prompt without manually entering a carriage
return or to imbed the script within a larger script, execute the script with this command:
essbase.secure &
(Optional) To redirect the standard output to a file named nohup.out, which is useful
when running the script in a nonactive terminal session, use this command:
nohup essbase.secure &
693
system Administrator.
Topic
Location
Agent
password
MaxL
ESSCMD
SETPASSWORD
Starting an Application
When you start an application, the following actions can happen:
l
694
Topic
Location
Agent
START appname
Administration Services
Starting Applications
MaxL
ESSCMD
LOADAPP or SELECT
The application starts and, if you are running on Windows, opens the application server window
on the Essbase Server computer.
You can also start an application by completing any of these actions:
l
Saving an outline to Essbase Server. (Opening an outline does not start an application.)
startup (Allow user to start application): If an application is stopped, and a user attempts to
retrieve data from any databases within that application, the application starts on the Essbase
Server computer automatically.
autostartup (Start application when Essbase starts): Users may experience better initial
performance when they make requests of databases in that application, because the
application and databases are already loaded into memory on the Essbase Server computer.
Topic
Location
Administration Services
MaxL
Stopping an Application
Stop applications properly to prevent the databases within them from becoming corrupt. When
you stop an application, transactions may be running. If you stop an application using any of
the proper methods (see the following table), the application does not stop if a calculation or
data load is in progress. Instead, Essbase displays a message in the Agent window.
If you stop the Agent by closing the window or by pressing Ctrl+C, the application stops, and
the next time you start the application, Essbase rolls back any transactions that were in progress.
See Rollback with Committed Access on page 781 or Rollback with Uncommitted Access
on page 782.
695
Topic
Location
Agent
stop appname
Administration Services
Stopping Applications
MaxL
ESSCMD
UNLOADAPP
To stop the application improperly, use a method for the operating system on which Essbase
Server runs
You can use the ps output to identify individual applications. If an application freezes, you
can stop the application by using this command:
kill -9 <pid>
696
Starting a Database
When Essbase starts a database and loads it to memory, the entire index cache for that database
is allocated in memory automatically. The data cache and data file cache are allocated as blocks
requested from Essbase clients.
When you start an application, Essbase loads the application and its databases into memory on
the Essbase Server computer. When you start a database from an application that is not started,
the application is loaded into memory along with all its related databases.
Topic
Location
Agent
START appname
Administration Services
Starting Databases
MaxL
ESSCMD
LOADDB or SELECT
To configure a database to start automatically when its parent application starts, use a tool:
Tool
Topic
Location
Administration Services
MaxL
Stopping a Database
Stopping a database unloads all data from memory and commits any updated data to disk. If a
database is stopped and a user attempts to retrieve data from it, the database starts on Essbase
Server automatically, without any explicit commands issued.
When you stop a database, transactions may be currently running. If you stop a database using
any of the proper methods (see the following table), the database does not stop if a calculation
or data load is in progress. Instead, Essbase displays a message in the Essbase Server window.
If you stop the Agent by closing the Essbase Server window or by pressing Ctrl+C, the database
stops, and the next time you start the database, Essbase rolls back any transactions that were in
progress. See Rollback with Committed Access on page 781 or Rollback with Uncommitted
Access on page 782.
697
Topic
Location
Agent
STOP appname
Administration Services
Stopping Databases
MaxL
ESSCMD
UNLOADDB
Managing Ports
Subtopics
Viewing a List of Users and Available Ports
Specifying Nondefault Port Values
Changing Port Default Values
Viewing Port Statistics
Managing Essbase Administration Server Communication Ports
l
l
l
l
l
Topic
Location
Agent
USERS
Enter the Agent command in the Oracle Process Manager and Notification
Server command line interface.
Administration Services
MaxL
display user
ESSCMD
LISTUSERS
698
To view the number of ports installed on Essbase Server, as well as the number of ports in
use, use a tool:
Tool
Topic
Location
Agent
PORTS
Administration Services
display user
ESSCMD
LISTUSERS
You may want to change the default value. Two possible reasons:
l
PORTUSAGELOGINTERVAL n
where n represents the number of minutes between each check of the number of ports in use.
The value of n can be any whole number from 1 to 60, with 5 being the recommended minimum
and default value. Essbase ignores any portion of a nonwhole number. For example, Essbase
evaluates 2.5 as 2 minutes. Statistics are written to the Essbase Server log immediately after each
check. The log file will resemble the following output:
[Mon Apr 22 00:48:50 2003]Local/ESSBASE0///Info(1056214)
[3] ports in use, [10] ports allowed
AGENTSECUREPORT
CLIENTPREFERREDMODE
ENABLECLEARMODE
ENABLESECUREMODE
NETSSLHANDSHAKETIMEOUT
SSLCIPHERSUITES
WALLETPATH
The partition source and target must have the same security protocol; for example, both or
neither use SSL.
To enable Essbase to use SSL connectivity, you must set ENABLESECUREMODE to TRUE.
700
The following considerations apply when using location aliases in secure (SSL) mode:
l
To enable Essbase to use SSL connectivity, you must set ENABLESECUREMODE to TRUE.
If the location alias is being set up to a secure port, you must append :secure to the server
name specification. For example, using MaxL,
create location alias EasternDB from Sample.Basic to East.Sales at Easthost:
6423:secure as User1 identified by password1;
To configure Essbase for encrypted (SSL) communication with Provider Services, you must
perform a configuration task to enable the Essbase libcurl library to set up a secure channel
to Provider Services. See Configuration for SSL Encrypted Communication with Provider
Services on page 687.
For more information on using SSL with Essbase, see the Oracle Enterprise Performance
Management System User Security Administration Guide.
Limits the time Essbase Server allows a query to run before terminating the query.
l
Limits the number of blocks a query can access before terminating the query.
You can apply these settings to all the applications and databases on Essbase Server, to all the
databases on a single application, or to one database. See the Oracle Essbase Technical
Reference.
701
AGENTTHREADS maximum_number_of_threads
AGTSVRCONNECTIONS maximum_number_of_threads
configuration setting and are not related to the threads whose maximum is controlled by
AGENTTHREADS and AGTSVRCONNECTIONS.
702
46
In This Chapter
Understanding Applications and Databases .......................................................... 703
Understanding How Essbase Files Are Stored......................................................... 704
Managing Applications, Databases, and Database Artifacts ........................................ 708
Migrating Applications Using Administration Services................................................ 715
Porting Applications Across Platforms ................................................................. 715
Also see the Oracle Hyperion Enterprise Performance Management System Backup and Recovery
Guide.
Data sources
Rules for loading data and building dimensions dynamically (rules files)
Security definitions
Security filters
703
LROs
Partition definitions
Some of these artifacts are optional, such as calculation scripts, filters, and LROs.
For a complete description of each database artifact, see Understanding Database Artifacts on
page 116.
For example:
Oracle/Middleware/EPMSystem11R1
l
For a list of directories that are created under ESSBASEPATH, see the Oracle Enterprise
Performance Management System Installation and Configuration Guide.
l
ARBORPATH:
m
704
The app directory location where Essbase application files (as they are created) and
sample applications and databases (provided with Essbase) are stored.
The bin directory location where Essbase configuration setting (essbase.cfg) and
security (essbase.sec and essbase_timestamp.bak) files (as they are created) are
stored.
File Extension
Location
Description
bak
ARBORPATH/bin
bnd
ESSBASEPATH/bin
Microsoft ODBC file for SQL Interface installation using a DB2 database
cfg
ARBORPATH/bin
cnt
ESSBASEPATH/bin
cpl
ESSBASEPATH/bin
dll
ESSBASEPATH/bin
eqd
ESSBASEPATH/bin
exe
ESSBASEPATH/bin
Executable file
hlp
ESSBASEPATH/bin
lck
ESSBASEPATH/bin
Lock file
lic
ESSBASEPATH/bin
pl
ESSBASEPATH/bin
pm
ESSBASEPATH/bin
Perl Module
mdb
ESSBASEPATH/bin
sec
ARBORPATH/bin
Security file
705
File Extension
Location
Description
sl
ESSBASEPATH/bin
so
ESSBASEPATH/bin
File Extension
Description
alg
apb
app
Application file, defining the name and location of the application and other application settings
arc
Archive file
atx
chg
csc
db
Database file, defining the name, location, and other database settings
dbb
ddb
ddm
ddn
esm
Essbase kernel file that manages pointers to data blocks and contains control information used for database recovery
esr
esn
ind
inn
log
lro
lst
mxl
706
File Extension
Description
ocl
ocn
oco
olb
olg
otl
otm
otn
oto
pag
pan
rep
rul
scr
sel
tct
Essbase database transaction control file that manages all commits of data and follows and maintains all transactions
tcu
trg
txt
Text file, such as a data file to load or a text document to link as a LRO
xcp
xls
File Extension
Description
bas
Microsoft Visual Basic program source file, containing header definitions for the Essbase API
707
File Extension
Description
C or C++ header file, containing header definitions for the Essbase API
lib
np
tcp
For a description of Essbase applications, databases, and database artifacts, see Understanding
Applications and Databases on page 116 and Understanding Database Artifacts on page
116.
Automated database backup and restore and transaction logging and replay
Backup and restore provides the equivalent functionality of manually backing up and
restoring a database. When a backed-up database is restored, transactions that occurred after
the backup procedure are not recovered. However, with transaction logging and replay,
post-backup transactions are captured and can be replayed. Thus, a backed-up database can
be recovered to the most-recent state before the interruption occurred.
The use of the database backup and restore and transaction logging and replay features
eliminates the need for various manual steps and, therefore, enables administrators to back
up and recover databases more efficiently. Oracle recommends incorporating these features
in your backup and recovery strategy.
708
Essbase customers who have designed a backup and restore strategy that uses manual
procedures and who do not need the functionality of transaction logging and replay can
continue using their manual strategy.
To back up and restore aggregate storage applications, you must use manual procedures.
See the Oracle Hyperion Enterprise Performance Management System Backup and Recovery
Guide.
Do not move, copy, modify, or delete any of these files: essn.ind, essn.pag,
dbname.ind, dbname.esm, or dbname.tct. Doing so may result in data
corruption.
Certain application and database files can be managed successfully through the file system:
l
To copy or move an outline file (.otl), you must use Administration Services.
See Copying Outlines in the Oracle Essbase Administration Services Online Help.
The only time the file system should be used to manage applications and databases is during
backup, when the entire directory for an application or database is copied and stored elsewhere.
See the Oracle Hyperion Enterprise Performance Management System Backup and Recovery
Guide.
Monitoring Applications
Each application that is loaded is an open task or process in the operating system. On Windows
platforms, the application is displayed in a command-line window. On UNIX platforms, the
application server is a child process of ESSBASE. When the application starts, ESSBASE starts
the esssvr process. See Starting an Application on page 694.
709
On Windows platforms, when an application starts, a new icon is displayed in the taskbar.
Double-click the icon to view the server window.
Essbase Server records application-level activities in an application log. See Using Essbase Logs
on page 726.
To view application activities as they occur, use a tool:
Tool
Instruction
Select the command-line window that bears the name of the application.
UNIX
tail -f logfile
To create an application:
See Creating Applications in the Oracle Essbase Administration Services Online Help.
Administration Services provides a Migration Wizard that helps you migrate applications. See
Migration Wizard in Oracle Essbase Administration Services Online Help.
Topic
Location
Administration Services
Copying Applications
MaxL
create application as
ESSCMD
COPYAPP
Renaming Applications
When you rename an application, the application and its associated directory (ARBORPATH/
app/appname) are renamed. All artifacts within the application (for example, databases or
calculation scripts) with the same name as the application are not renamed. Before you rename
an application, see Naming Conventions for Applications and Databases on page 1093.
Topic
Location
Administration Services
Renaming Applications
MaxL
alter application
ESSCMD
RENAMEAPP
Deleting Applications
When you delete an application, all artifacts within the application also are deleted. The
ARBORPATH/app/appname directory and all files in the directory are deleted.
Topic
Location
Administration Services
Deleting Applications
MaxL
drop application
ESSCMD
DELETEAPP
Copying Databases
You can copy a database in an application to any Essbase Server and application to which you
have appropriate access. You can copy (migrate) an entire database to another Essbase Server,
711
or you can copy a database on the same Essbase Server. For example, you may need to migrate
an entire database from a development server to a production server. Or, you may want to copy
a database on the same server for testing or for backup purposes. Essbase copies databases
differently depending on whether you are copying to the same Essbase Server or to a different
Essbase Server. See Copying Databases in Oracle Essbase Administration Services Online Help.
Administration Services provides a Migration Wizard that helps you migrate applications and
databases. See Migration Wizard in Oracle Essbase Administration Services Online Help.
When you copy a database, all files associated with the database, except data files (.pag
and .ind), are copied to the destination application. Before copying, make sure you have enough
disk space to contain a full copy of the database and its related files.
Topic
Location
Administration Services
Copying Databases
MaxL
create database as
ESSCMD
COPYDB
Renaming Databases
When you rename a database, the database and its associated directory (ARBORPATH/app/
appname/dbname), and the outline file (.otl) are renamed. All other artifacts in the database
(for example, calculation scripts) with the same name as the database are not renamed.
Topic
Location
Administration Services
Renaming Databases
MaxL
alter database
ESSCMD
RENAMEDB
712
Deleting Databases
When you delete a database, all artifacts within it are also deleted. The ARBORPATH/app/
appname/dbname directory and all files located in the directory are deleted.
Topic
Location
Administration Services
Deleting Databases
MaxL
drop database
ESSCMD
DELETEDB
The only time the file system should be used to manage applications is during backup,
when the entire directory for an application or database is copied and stored
elsewhere.
Copying Artifacts
You can copy any database artifact, except an outline, to another application, database, server,
or client location. For instructions on copying outlines, see Creating and Editing Outlines on
page 128.
Topic
Location
Administration Services
MaxL
alter object
ESSCMD
COPYOBJECT
Renaming Artifacts
You can rename any artifact except an outline. An outline always has the same name as the
database, so you must rename the database to rename the outline.
713
Topic
Location
Administration Services
MaxL
alter object
ESSCMD
RENAMEOBJECT
Deleting Artifacts
You can delete any artifact except an outline. An outline is a required part of a database, so you
must delete the database to delete the outline.
Topic
Location
Administration Services
MaxL
drop object
ESSCMD
for data blocks but not for artifacts. See Data Locks on page 778.
By default, whenever you open a database artifact, Essbase prompts you to lock the artifact. You
can change this default behavior for some artifacts; see Setting Essbase Default Options in
Oracle Essbase Administration Services Online Help.
When an artifact is locked, Essbase does not allow other users to save over, rename, or delete
the artifact. You can open a locked artifact and edit it, but you cannot save over the existing
artifact. To save changes made to a locked artifact, save the modified artifact to a different
location. You can execute and copy locked artifacts.
Unlocking Artifacts
You can unlock artifacts according to your permissions. In Administration Services, you can
view all artifact locks for an Essbase Server, application, or database.
714
Topic
Location
Administration Services
MaxL
alter object
ESSCMD
UNLOCKOBJECT
To migrate an application:
See Copying Applications in Oracle Essbase Administration Services Online Help.
Text files. The Essbase text files are calculation scripts (.csc) and report scripts (.rep), and
any MaxL or ESSCMD scripts you have developed. Also, data files can be text files.
715
Rules files. These files are binary files, but they are compatible between operating systems.
Rules files have the extension .rul.
Outline files. These files are binary files, but they are compatible between operating systems.
Outline files have the extension .otl.
The following file types are incompatible between operating systems and must be redefined or
reloaded on the new server:
l
Note: If you are using the Linked Reporting Objects feature, you must relink any files or cell
notes on the new server. For a comprehensive discussion of how LROs are used, see
Chapter 11, Linking Objects to Essbase Data.
Executable files have no extension and are uppercase (for example, ESSBASE, ESSCMD).
Static library files have the file extension .a and are in lowercase (for example,
libessnet.a).
Shared library files have the file extension .sl on HP-UX, .so on Solaris, and .a on AIX.
These file names are in lowercase (for example, libesscur.sl).
Security files have the file extension .sec and are in lowercase (for example,
essbase.sec).
Message database files have the file extension .mdb and are in lowercase (for example,
essbase.mdb).
Online help files have the file extension .hlp and are in lowercase (for example,
esscmd.hlp).
Essbase files on UNIX systems are capitalized with proper casethe first letter is uppercase, and
the remaining letters are lowercase. Table 132 gives examples of names for different file types:
716
Table 132
File Type
Example
Database files
Mydb.db
Data files
Mydb.pag
Index files
Mydb.ind
Outline files
Mydb.otl
Rules files
Atlanta.rul
Atlanta.txt
Calculation scripts
Mycalc.csc
Report scripts
Myrepo.rep
Archive files
Mydb.arc
Application logs
Myapp.log
Note: The application name is an exception to the above rule. The application name can be in
lowercase.
Table 133 lists several examples of valid and invalid file names on UNIX systems:
Table 133
Model.csc
MODEL.CSC
Monthly.rep
Monthly.Rep
Forecast.otl
forecast.otl
Actuals.rul
AcTuAlS.rUl
My_File.txt
My_File.Txt
Note: Essbase does not allow long file names for applications, databases, calculation scripts,
reports, and other database files. All file names for artifacts you create must conform to
the Windows 8.3 convention.
717
compatible application files. If the servers are not connected, you must redefine server
information on the new server before reloading the database.
To create users and specify their permissions, use Administration Services on the new server.
To create the applications and databases that you want to port, use Administration Services on the new
server.
Copy the outline files (.otl) for the databases that you want to port from the old server to the same
directory location on the new server. Ensure that the application is not running while you copy these
files.
Copy compatible files from the old server to the new server.
718
719
720
47
In This Chapter
Monitoring Data Changes Using Triggers .............................................................. 721
Using Essbase Logs...................................................................................... 726
Administering Triggers
Effect of Triggers on Performance and Memory Usage
Trigger Examples
The triggers feature provided by Essbase enables efficient monitoring of data changes in a
database.
If data breaks rules specified in a trigger, Essbase can log relevant information in a file or, for
some triggers, can send an e-mail alert (to a user or system administrator); for example, to notify
the sales manager if, in the Western region, sales for a month fall below sales for the equivalent
month in the previous year.
There are two types of triggers. On-update triggers are activated during the update process, when
the block containing the data referenced by the trigger is brought into memory. After-update
triggers are activated after the update transaction is complete.
Note: On-update triggers are supported only on block storage databases.
Administering Triggers
Subtopics
l
l
To administer triggers, a user must have Database Manager security privilege. Essbase monitors
and potentially activates triggers during the following activities:
l
Data load
721
Calculation
Lock and send from Oracle Essbase Spreadsheet Add-in (available only for on-update
triggers on block storage databases)
Topic
Location
Administration Services
Creating Triggers
Editing Triggers
Viewing Triggers
Enabling and Disabling Triggers
Viewing Trigger Spool Files
Deleting Triggers
create trigger
MaxL
You can see information on enabled and disabled triggers in the application log file when you
start Essbase Server.
You must use a symmetric WHERE clause when defining the area specification for a trigger.
See the MDX documentation in the MaxL section of the Oracle Essbase Technical
Reference.
To enable Essbase to send e-mail alerts, you must have JVM installed on your system.
Note: E-mails related to Unicode-mode applications are encoded in UTF-8 and require a
722
You cannot define a trigger that requires data from the following Essbase features:
m
Dynamic Calc
Partitioning
You can specify whether all trigger data values are stored in the spool file or whether only
the most current values are stored (for example, use the a log_value parameter on the MaxL
create trigger statement or create and replace trigger statement). If the log_value parameter
is set to ON, both the new value and old value are logged to the spool file. If the log_value
parameter is set to OFF, values are not logged to the spool file. The log_value parameter is
active only for data load and lock-and-send activities.
Consider data security when sending e-mail alerts. When Essbase activates a trigger and sends
an e-mail, it cannot check whether the e-mail recipient is authorized to see the data referenced
by the trigger condition.
Avoid referencing a sparse dimension member in a trigger condition. When Essbase executes a
trigger on one data block, it must read another data block that may or may not be updated.
Depending on the state of the second block, Essbase may activate the trigger in error.
The following example is based on the Sample.Basic database. Assume that East and West are
sparse dimensions and that the following statement defines the trigger condition:
FIX (East, West, Sales, Jan, Actual, Cola)
IF ((Sales -> East + Sales -> West) > 20)
EMAIL sales@.com
Assume that the following Sales data values are stored for East and West:
l
Now assume that a user does a lock-and-send request to update the data values:
l
When Sales->East is updated to 15, temporarily, the database contains the following values:
l
So Essbase activates the trigger because 15 plus 6 is greater than 20. Subsequently, Essbase updates
Sales -> West to 3. Now the data does not meet the trigger condition, because 15 + 3 < 20.
However, Essbase has already activated the trigger.
When a data load is followed by a calculation, if both the loaded data and the calculated data
meet the trigger condition, Essbase activates the trigger twice, once on the data load and once
on the calculation.
You must use a symmetric WHERE clause when defining the area specification for a trigger.
See the MDX documentation in the MaxL section of the Oracle Essbase Technical
Reference.
Spreadsheet lock-and-send operations do not activate after-update triggers.
723
Trigger Examples
Subtopics
l
l
l
When the member being calculated is Jan, and when the Actual, Sales value of Colas for January
exceeds 20, the example sends an e-mail to two e-mail accounts.
create trigger Sample.Basic.Trigger_Jan_20
where "(Jan,Sales,[100],East,Actual)"
when Jan > 20 and is(Year.currentmember,Jan) then
mail ([Docs.Company.com],[trgsales@company.com],
[inventory@company.com],
[Mail sent by trigger_Jan_20])
end;
January, February, and March (the children of Year dimension member Qtr1)
724
When the member being calculated is Jan, Feb, or Mar, and when the Actual, Sales value of Colas
for the month January, February, or March exceeds 20, the example logs an entry in the file
Trigger_Jan_Sales_20, Trigger_Feb_Sales_20, or Trigger_Mar_Sales_20. On subsequent trigger
activations, both old and new log values are retained in the log files.
create or replace trigger Sample.Basic.Trigger_Qtr1_Sales
log_value on
Where "(crossjoin(Qtr1.children, {(Measures.Sales, [100],
East, Scenario.Actual)}))"
When Year.Jan > 20 and is(Year.currentmember, Jan) then
spool Trigger_Jan_Sales_20
When Year.Feb > 20 and is(Year.currentmember, Feb) then
spool Trigger_Feb_Sales_20
When Year.Mar > 20 and is(Year.currentmember, Mar) then
spool Trigger_Mar_Sales_20
end;
The trigger is activated after the update action is complete. If the inventory of Colas in the eastern
region falls below 500,000, the example logs an entry in the file Inventory_East.
create after update trigger Sample.Basic.Inventory_east
where "(crossjoin ({children([Qtr1])},
{([Market].[East], [Product].[100],
[Inventory].[Ending Inventory])}))"
when [Ending Inventory] < 500000 then
spool Inventory_East
end;
725
l
l
l
l
l
l
l
l
l
l
l
This topic describes the logs that Essbase Server creates to record information about server,
application, and database activities. Table 134 briefly describes each log.
Essbase also uses the Oracle Diagnostic Logging framework (ODL) for logging purposes. For
information on the Essbase implementation of ODL, see the Oracle Hyperion Enterprise
Performance Management System Installation and Configuration Troubleshooting Guide.
Table 134
Summary of Logs
Log Type
Log Location
Information Included
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
ESSBASE.LOG
Application log
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
app/appname/appname.LOG
Query log
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
app/appname/dbname/dbname00001.qlg
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
app/appname/dbname/dbname.olg
Exception log
ARBORPATH/log00001.xcp
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
app/log00001.xcp
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
app/appname/log00001.xcp
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/
app/appname/dbname/log00001.xcp
726
Log Type
Log Location
Information Included
Dimension build
and data load error
logs
EAS_HOME/client/dataload.err
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/app/appname/
appname.log
The following topics describe the information written to a log and explains how you can use
that information to maintain, tune, or troubleshoot Essbase Server.
For information about Administration Services logs, see About the Administration Server Log
in Oracle Essbase Administration Services Online Help.
Each application on Essbase Server has its own application log, named after the application. For
example, the log file for the Sample application is named sample.log. In a standard Essbase
installation, application logs are located in one of these directories, depending on the value of
the DEFAULTLOGLOCATION configuration parameter:
l
EPM_ORACLE_INSTANCE/diagnostics/logs/essbase/essbase_0/app/appname
ARBORPATH/app/appname
Information in application logs can help you pinpoint where and why an error occurred.
For information about the actions that you can perform on server and application logs, see
Using Essbase Server and Application Logs on page 736. For information on viewing or
analyzing logs using Administration Services, see About Log Viewer or About Log Analyzer
in Oracle Essbase Administration Services Online Help. For information about specific error
messages, see Oracle Essbase Error Message Reference.
Table 135 lists the types of actions logged and the information included in the log message. For
information about specific error messages, see the Oracle Essbase Error Message Reference.
727
Table 135
Type of Action
Actions performed at the Essbase
Server level, such as logging on
Essbase Server or setting security
Information Included
l
User name
User name
User name
Returning artifacts
728
The following log shows a single error. The admin user tried to rename an application using a
name that already exists on Essbase Server. The log file includes information about the user
name, the time of the error, and the operation that failed and caused the error.
[Tue Nov 06 08:00:04 2001]Local/ESSBASE0///Info(1051001)
Received client request: Rename Application (from user admin)
[Tue Nov 06 08:00:04 2001]Local/ESSBASE0///Error(1051031)
Application Testing already exists
[Tue Nov 06 08:00:04 2001]Local/ESSBASE0///Warning(1051003)
Error 1051031 processing request [Rename Application] - disconnecting
The next log shows a shutdown. The log file includes information about the name of the
application shutdown and the time of the shutdown.
[Tue Nov 06 08:00:46 2001]Local/ESSBASE0///Info(1054005)
Shutting down application Sample
[Tue Nov 06 08:00:52 2001]Local/ESSBASE0///Info(1051052)
Essbase Server - finished
The name of an artifact used to execute an operation (such as a calc script or load file used
to perform a calculation or a data load) if the artifact resides on an instance of Essbase
Table 136 lists the types of actions logged and the information included in the log message.
729
Table 136
Type of Action
Actions performed at the
database level, such as
loading data, clearing data, or
calculating data
Information Included
l
User name
If starting applicationLoading Java modules, and reading and writing database and application
information
If starting databasesApplication and database setup information, including reading free space
information, writing database parameters, retrieving state information, writing application and
database definition information, retrieving database volumes, and writing database mapping
If loadingLoad command, parallel data load information, cells updated, elapsed load time, and the
name of the rules file and data file
Note: Essbase supplies the load rule name only if the client making the request (for example,
Administration Services) is at the same release level as Essbase; for example, Release 7.0.
User name
Information about dimension sizes, dynamic calculation members, blocks, cache sizes, index page
size, I/O information, and restructure elapsed time
User name
Action performed
730
After Essbase Server starts, it writes information about the dimensions and members in the
outline, such as the dimension sizes and dynamic calculation information, to the application
log, as shown in the following example:
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1019012)
Reading Outline For Database [Basic]
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1007043)
Declared Dimension Sizes = [20 17 23 25 5 3 5 3 15 8 6 ]
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1007042)
Actual Dimension Sizes = [20 14 20 25 4 3 5 3 15 8 5 ]
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1007125)
The number of Dynamic Calc Non-Store Members = [8 6 0 0 2 ]
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1007126)
The number of Dynamic Calc Store Members = [0 0 0 0 0 ]
Next, Essbase Server writes information about the blocks in the database, including the block
size, the number of declared and possible blocks, and the number of blocks needed to perform
calculations (you can use this information to estimate the retrieval performance for members
of sparse dimensions tagged as Dynamic Calc) to the application log:
731
Next, Essbase Server writes information about the caches set for each database to the application
log:
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1012736)
The Dyn.Calc.Cache for database [Basic] can hold a maximum of [2340] blocks.
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1012737)
The Dyn.Calc.Cache for database [Basic], when full, will result in [allocation from nonDyn.Calc.Cache memory].
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1019018)
Writing Parameters For Database [Basic]
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1019017)
Reading Parameters For Database [Basic]
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1070013)
Index cache size ==> [1048576] bytes, [1024] index pages.
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1070014)
Index page size ==> [8192] bytes.
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1070081)
Using buffered I/O for the index and data files.
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1070083)
Using waited I/O for the index and data files.
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1019019)
Reading Data File Free Space Information For Database [Basic]...
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1006025)
Data cache size ==> [3145728] bytes, [2048] data pages
[Tue Nov 06 08:47:15 2001]Local/Sample///Info(1006026)
Data file cache size ==> [0] bytes, [0] data file pages
732
733
734
Table 137
1001000-1001999
Report Writer
1002000-1002999
General server
1003000-1003999
Data load
1004000-1004999
General server
1005000-1005999
1006000-1006999
Data cache
1007000-1007999
Outline restructure
1008000-1008999
1009000-1009999
1010000-1010999
1011000-1011999
Internal (utilities)
1012000-1012999
Calculator
1013000-1013999
Requestor
1014000-1014999
Lock manager
1015000-1015999
Alias table
1016000-1016999
Report Writer
1017000-1017999
Currency
1018000-1018999
1019000-1019999
Database artifacts
1020000-102999
Spreadsheet extractor
1021000-1021999
1022000-1022999
Security
1023000-1023999
Partitioning
1024000-1024999
Query Extractor
1030000-1030999
API
1040000-1040999
General network
1041000-1041999
NetworkNamed Pipes
1042000-1042999
NetworkTCP
735
1043000-1049999
1050000-1055999
Agent
1056000-1059999
1060000-1060999
Outline API
106100-1069999
1070000-1070999
Index manager
1071000-1079999
1080000-1080099
Transaction manager
1081000-1089999
1090000-1099999
1010000-1019999
1100000-1100999
1110000-1119999
1120000-1129999
Grid API
1130000-1139999
Miscellaneous
1140000-1149999
1150000-1159999
Outline synchronization
1160000-1169999
1170000-1179999
Attributes
1180000-1189999
Showcase
1190000-1199999
1200000-1200999
Calculator framework
736
Setting the Maximum Log File Size for Essbase Server and Application Logs
You can specify the maximum log file sizes for Essbase Server (Agent) and application log files
in the essbase.cfg file using these settings:
l
AGTMAXLOGFILESIZE
APPMAXLOGFILESIZE
Error messages, such as trying to perform an action that Essbase Server cannot perform
In the following example, the rename operation failed because the application name already
existed.
[Fri Nov 02 13:38:14 2001]Local/ESSBASE0///Error(1051031)
Application Testing already exists
Table 138 lists the configuration settings that you specify in the essbase.cfg file to determine
what types of messages Essbase Server writes to the Essbase Server log or displays to the Essbase
Server window. If you change an essbase.cfg setting, restart Essbase Server to apply the
change.
737
Table 138
Setting
Definition
AGENTLOGMESSAGELEVEL
An essbase.cfg setting that determines the level of messages to be written to the Essbase Server
log.
AGENTDISPLAYMESSAGELEVEL
An essbase.cfg setting that determines the level of messages to be written to the Essbase Server
window.
PORTUSAGELOGINTERVAL
An essbase.cfg setting that specifies how often to check the number of ports in use.
In the following example, Essbase Server writes the time elapsed during a data load to the
application log:
[Fri Nov 02 13:04:15 2001]
Local/Sample/Basic/admin/Info(1003024)
Data Load Elapsed Time : [3.014] seconds
Warning messages that list conditions that are not deemed serious by Essbase Server
In the following example, Essbase Server writes a statement that no data values were changed
during a data load to the application log:
[Fri Nov 02 12:43:44 2001]
Local/Sample/Basic/admin/Warning(1003035)
No data values modified by load of this data file
Error messages that describe errors that occurred while performing the task
Error messages can range from serious, such as a file not loading correctly, to very serious,
such as a disk space error that causes Essbase Server to crash. In the following example,
Essbase Server writes a statement to the application log file indicating that a data value was
encountered before all dimensions in the outline were specified:
[Fri Nov 02 12:53:32 2001]
Local/Sample/Basic/admin/Error(1003007)
Data Value [678] Encountered Before All Dimensions Selected, [2] Records Completed
Table 139 lists settings that you specify in the essbase.cfg file and a command that you can
use in a calculation script to determine what types of messages Essbase Server writes to the
application log. If you change an essbase.cfg setting, restart Essbase Server to apply the
change.
Table 139
Setting
Definition
LOGMESSAGELEVEL
An essbase.cfg setting that determines whether Essbase Server writes all messages, warning messages, or error
messages to the application log
738
Setting
Definition
TIMINGMESSAGES
An essbase.cfg setting that determines whether Essbase Server writes the duration of each spreadsheet and
report query to the application log
SSLUNKNOWN
An essbase.cfg setting that determines whether Essbase Server writes error messages when it encounters an
unknown member name during a spreadsheet operation to the application log
SET MSG
A calculation script setting that determines whether Essbase Server writes the following items to the application log
during the duration of the calculation script:
l
Topic
Location
Administration Services
Viewing Logs
Output:
component
message_level
+------------------+------------------
739
system
lease_manager
info
error
To view the message level for an application, use the following MaxL statement:
Topic
Location
Administration Services
Deleting Logs
MaxL
DELETELOG "";
To delete the application log:
DELETELOG "appname";
Note: To clear a server or application log each time the server or application restarts, see
Clearing the Essbase Server and Application Logs Upon Restart on page 740. To
conserve space by limiting the items logged in the Essbase Server log or application log,
see Setting the Type of Essbase Server Messages Logged or Displayed in the Essbase Server
Window on page 737 or Setting the Type of Application Messages Logged on page
738.
log each time the server is restarted or the application log each time the application is restarted.
If you change the essbase.cfg file, restart Essbase Server to apply the change.
Note: To clear a server or application log without restarting the server or application, see
Clearing the Essbase Server and Application Logs Immediately on page 740. To conserve
space by limiting the items logged in the Essbase Server log or application log, see Setting
the Type of Essbase Server Messages Logged or Displayed in the Essbase Server Window
on page 737 or Setting the Type of Application Messages Logged on page 738.
You can also use tildes, carets, colons, ampersands, or asterisks to delimit the entries in the server
and application logs. If possible, choose a delimiter that does not occur frequently in the data,
application, or database. The following example shows a log entry delimited by tildes (~):
Thu~May~10~20:16:13~2005~Local~ESSBASE0~~~Info~(1051051)~ \\ Oracle Essbase Server started
Note: If you set delimiters to anything other than spaces, you can no longer sort the log entries
Setting
Description
DELIMITEDMSG
An essbase.cfg setting that, when set to TRUE, adds a tilde (~) between each field in the server and application
logs.
To specify a different delimiter, use the DELIMITER setting.
DELIMITER
An essbase.cfg setting that specifies the delimiter used between each field in the server and application logs.
Essbase Server enables you to use the following characters as log delimiters: tilde (~), the default delimiter; caret (^);
colon (:); ampersand (&); and asterisk (*).
The DELIMTER setting works only when DELIMITEDMSG is set to TRUE.
741
The following topics describe the outline change log and the actions that you can perform on it.
742
Table 141
Type of Change
Information Included
Add a dimension
Name of dimension
Delete a dimension
Name of dimension
Update a dimension
Name of dimension
Dimension tag
Name of dimension
New location
Rename a dimension
The outline change log program reads outline information from left to right. If you are looking
at an outline, the left sibling is the sibling directly above (to the left of) the newly added dimension
or member. This rule does not apply if the immediately preceding dimension or member is a
743
parent. If a newly added (or moved) member is the first child of its parent, or if the member is
the first dimension in the outline, the outline change log identifies the old location of the
dimension or member as None.
updates have been made to the outline change log. Turning on the outline change log
may, therefore, affect restructure performance. See Conditions Affecting Database
Restructuring on page 841.
744
Section of Log
Information Included
General information
Process type
Use this information to determine which component shut down abnormally and when it shut down.
745
Section of Log
Information Included
Machine registers
and stack information
General registers
Hex registers
Stack trace
Stack dump
Oracle Support can examine this section of the log to help determine why an abnormal shutdown may have
occurred.
Application-wide
configuration
Elapsed application time; that is, how long the application was running
List of modules
Use this information to determine whether the application shut down quickly and that all modules are correct.
More information about modules is in the system-wide configuration section of the exception log.
Operating system
resources
Elapsed operating system time; that is, how long the operating system was running
Resource information, including CPU type, memory information, swap information, and drive information
Use this information to see if it is an operating system problem, such as a lack of memory.
System-wide
configuration
Elapsed Essbase time; that is, how long Essbase was running
Network information
Environment variables
Use this information to ensure that the release is the same for Essbase and each module, and that environment
variables are set correctly.
essbase.cfg
values
License information
Use this information to ensure that the correct options of Essbase are installed and that you have purchased
enough ports.
746
Section of Log
Information Included
Server name
Application name
Request information
Detailed information about each thread, including the action it is performing, the database, user name, start
time, and end time
Use this information to determine how heavy the load on the server was, based on client requests.
File information
Use this information to determine whether the page file or the index is too large.
Database
information
Database statistics
Use this information to view dimension information and to see characteristics of data blocks in the database.
The next section of the log lists register and stack trace information. Oracle Support can examine
this section of the log to assist in determining why an abnormal shutdown occurred.
----- Machine Registers ----General Registers:
EAX=0x00000000 EBX=0x01358008
ECX=0x00002200
Control Registers:
CS =0x0000001B EIP=0x002D2249
Flg=0x00010202
Segment Registers:
DS =0x00000023 ES =0x00000023
FS =0x00000038
747
TWD=0xFFFFFFFF
DR1=0x75E07D39
DR6=0x0000E00B
DR2=0x1475FF16
DR7=0x00000000
Stack Trace:
0: 0x002D2249
1: 0x002D202D
...continued stack trace listings...
Stack Dump (Hex):
(Stack dump truncated from 1397 to 1024 bytes.)
0x0012EA2C: 00000000 01358008 01358008 FFFFFFFF
0x0012EA3C: 00002200 002D728C 0012EC6C 002D202D
...continued stack dump listings...
The following section of the log lists operating system information. You can determine how
much memory is available, how much swap space is used, and how much memory is available
on each drive:
----- Operating System Resources ----System Date & Time:
Elapsed OS Time:
OS Name & Version:
CPU Count:
CPU Type:
Total Physical Memory:
Free Physical Memory:
Used Physical Memory:
Swap Flags:
Enabled:
Disabled:
File Found:
Denied:
Swap file(s):
Total Swap Space:
748
The following section of the log lists system configuration information, such as paths or
essbase.cfg settings:
----- System-Wide Configuration ----Elapsed Essbase Time: 00:00:01:33
Essbase Version:
6.2.0
Essbase Description:
Ess62P0B128
Network Type:
Windows Sockets
Environment Variable: ARBORPATH = C:\HYPERION\ESSBASE
Environment Variable: ARBORMSGPATH = C:\HYPERION\ESSBASE\bin
Module Count:
13
Module 0:
Module Name:
C:\HYPERION\ESSBASE\BIN\ESSUTL.DLL
Module Version:
6.2.0.1
Module Description: Ess62P0B128.1
Module Use Count:
5
...continued module listings...
----- ESSBASE.CFG Configuration Values ----Configuration Value:
\jvm.dll
Configuration Value:
Configuration Value:
JvmModuleLocation = C:\Hyperion\Essbase\java\jre13\bin\hotspot
AuthenticationModule = LDAP essldap.dll x
OUTLINECHANGELOG = TRUE
The following section of the log lists license information (such as a serial number), Essbase
options (such as ports purchased) and Oracle Hyperion products purchased:
----- License Information ----Serial Number:
License Expiry Date:
Port Count:
Ports In Use Count:
Limited Use Version:
Read-Only SS:
xxx
10
0
N
N
The following section of the log lists client activity, such as using Administration Services to view
databases:
749
Component That
Shut Down
Essbase Server
Application
If the application name is unknown, the log is in the ARBORPATH/app directory. For example:
EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/app/log00001.xcp
If the application name is known, the log is in the application directory. For example, if the Sample application shut
down abnormally:
EPM_ORACLE_INSTANCE/EssbaseServer/essbaseserver1/app/Sample/log00001.xcp
750
Component That
Shut Down
Database
Understanding and Viewing Dimension Build and Data Load Error Logs
Reviewing an Example of a Dimension Build and Data Load Error Log
Setting the Maximum Number of Errors
Loading Dimension Build and Data Load Error Logs
Essbase Server writes errors that occur during a dimension build or data load in error logs. The
log that Essbase Server chooses for errors depends on the operation that you perform, such as a
dimension build or a data load, and how you perform it, such as using Administration Services,
or MaxL. The following topics describe the location of dimension build and data load errors and
the actions that you can perform on dimension build and data load error logs.
Understanding and Viewing Dimension Build and Data Load Error Logs
The dataload.err log contains errors that occurred during a dimension build or a data load.
The logs also contain the records that failed to load. After you fix the errors, you can reload the
logs. See Loading Dimension Build and Data Load Error Logs on page 753.
751
Essbase Server writes errors that occur during a dimension build or data load to the following
error logs:
Table 144
Operation
Dimension build
EAS_HOME/client/dataload.err
EAS_HOME/client/dataload.err
ARBORPATH/app/appname/appname.log
Note: If the data load or dimension build fails and there is no error log, see Checking Error
To resolve this problem, you can perform either of the following actions and restart the load:
l
Perform a dimension build to create the missing member. See Performing Data Loads or
Dimension Builds on page 305.
Add the missing member in Outline Editor. See Adding Dimensions and Members to an
Outline on page 129.
The following dimension build log entry indicates that the 600-20 member is not the parent of
the 600 member. Ensure that you use the correct rules file with the correct text file. The record
looks like it is for a level (bottom-up) build, but the error message indicates that Essbase Server
is trying to perform a generation (top-down) build. After you correct the problem, restart the
dimension build.
\\Record #2 - Incorrect Parent [600-20] For Member [600] (3307)
600-20-10
600-20
600
Using the DATAERRORLIMIT configuration setting, you can specify the number of records (1
to 65,000) that are logged in the dataload.err log files. If you change the essbase.cfg file,
restart Essbase Server to apply the change.
If you load from the server, change the file extension from .err to .txt. For example, change the
dataload.err file to dataload.txt.
If you load from the client, you can leave the .err extension.
Fix the problem that caused the dimension build or data load to fail. Fixing the problem might involve
changing the outline, the text in the error log, or the rules file.
753
754
48
In This Chapter
Understanding the Essbase Server Kernel............................................................. 755
Understanding Kernel Components .................................................................... 757
Understanding Kernel Startup .......................................................................... 760
Understanding the Precedence of Database Settings ................................................ 760
Understanding How Essbase Reads Settings ......................................................... 761
Viewing Most-Recently Entered Settings............................................................... 761
Customizing Database Settings......................................................................... 762
The kernel provides the foundation for a variety of functions of Essbase Server, including data
loading, calculations, spreadsheet lock and send, partitioning, and restructuring. The kernel
reads, caches, and writes data; manages transactions; and enforces transaction semantics to
ensure data consistency and data integrity.
The kernel has the following functions:
l
Issues locks
Manages transactions
755
Scalability and predictability. Essbase lets you customize the optimal cache sizes for its
databases.
If you set a database to use direct I/O, Essbase attempts to use direct I/O the next time the database
is started. If direct I/O is not available on your platform when the database is started, Essbase
uses buffered I/O, which is the default. However, Essbase will store the I/O access mode selection
in the security file and attempts to use that I/O access mode each time the database is started.
Note: Cache memory locking can only be used if direct I/O is used. You also must use direct I/
To view which I/O access mode a database is currently using or is currently set to, use a tool:
Tool
Topic
Location
Administration Services
MaxL
display database
ESSCMD
GETDBINFO
Topic
Location
Administration Services
756
Tool
Topic
Location
MaxL
alter database
ESSCMD
SETDBSTATEITEM
You may also need to increase the size of some caches. See Sizing Caches on page 824.
The Index Manager finds and tracks the location of requested data. See Index Manager
on page 757.
The Allocation Manager, part of the Index Manager, allocates space and manages some file
operations. See Allocation Manager on page 758.
The Data Block Manager retrieves the data pointed to by the index and stores the data. See
Data Block Manager on page 759.
The LRO Manager handles retrieval and storage of LROs. See LRO Manager on page
759.
The Lock Manager handles the locking of data blocks to regulate concurrent data access. See
Lock Manager on page 759.
The Transaction Manager tracks transactions and handles internal commit and abort
operations. See Transaction Manager on page 760.
Index Manager
Index Manager manages the database index and provides a fast way to look up Essbase data
blocks. Index Manager determines which portions of the database index to cache in the index
cache, and manages the index cache.
Table 145 lists the components that Index Manager controls:
Table 145
Component
Description
Index
The method that Essbase uses to locate and retrieve data. The term index also refers to the index file.
Index file
File that Essbase uses to store data retrieval information. It resides on disk and contains index pages. Essbase names index
files incrementally on each disk volume, using the naming convention essxxxxx.ind, where xxxxx is a number. The
first index file on each disk volume is named ess00001.ind.
Index page
A subdivision of an index file that contains index entries that point to data blocks.
Index entry
A pointer to a data block. An index entry exists for every intersection of sparse dimensions.
Index cache
757
The term index refers to all index files for a single database. The index can span multiple volumes,
and multiple index files can reside on a single volume. Use the disk volumes setting to specify
disk spanning parameters. For information on setting the index cache size, see Sizing the Index
Cache on page 825. For information about allocating storage space with the disk volumes
setting, see Specifying Disk Volumes on page 766.
Allocation Manager
Allocation Manager, part of the Index Manager, performs these tasks:
l
When one of these tasks must be performed, the Allocation Manager uses this process to allocate
space:
1. It attempts to use free space in an existing file.
2. If not enough free space is available, it attempts to expand an existing file.
3. If not enough free space is available in existing files, it creates a file on the current volume.
4. If it cannot expand a file or create a file on the specified volume, it attempts to use the next
specified volume.
5. If all specified volumes are full, an error message is displayed, and the transaction is aborted.
The Allocation Manager allocates space for index and data files based on the database settings
for storage.
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATEITEM 23
758
Component
Description
Data file
A file that contains data blocks. Essbase generates the data file upon data load and stores it on disk. Essbase names
data files incrementallyessxxxxx.pag, where xxxxx is a number, starting with 00001.
Data block
The primary storage unit within Essbase. A data block is a multidimensional array that represents cells of the dense
dimensions for a given intersection of sparse dimensions.
Data cache
The size of the data file cache determines how much of the data within the data files can fit into
memory simultaneously. The data cache size and the data block size determine how many data
blocks can fit into memory simultaneously. Data files for a single database can span multiple
volumes; multiple databases can reside on the same volume. See Sizing the Data File Cache
on page 826 and Sizing the Data Cache on page 827. Also see Specifying Disk Volumes
on page 766.
LRO Manager
LROs enable you to associate objects, such as flat files, with data cells. Using Smart View, users
can create and store LRO files, with an .lro extension.
LRO files are stored in the database directory (ARBORPATH/app/appname/dbname; for
example, app/Sample/Basic).
Essbase stores information about LROs in an LRO catalog. Each catalog resides in its own Essbase
index page and coexists in an index file with other, non-LRO Essbase index pages.
See Chapter 11, Linking Objects to Essbase Data and the Oracle Smart View for Office User's
Guide.
Lock Manager
The Lock Manager issues locks on data blocks, which in turn controls concurrent access to data.
The committed access and uncommitted access isolation levels use different locking schemes. For
more information on isolation levels and locking, see Chapter 50, Ensuring Data Integrity.
759
Transaction Manager
The Transaction Manager controls transactions and commit operations and manages database
recovery.
Essbase commits data automatically. Commits are triggered by transactions that modify data
data loading, calculating, restructuring, and spreadsheet lock and send operations.
How Essbase commits data depends on whether the transaction isolation level is set to committed
or uncommitted access (the default). See Committed Access on page 778 and Uncommitted
Access on page 781.
The Transaction Manager maintains a transaction control table, dbname.tct, to track
transactions.
For information about commit operations and recovery, see Recovering from a Crashed
Database on page 787.
You can define storage settings for all databases on the Essbase Server by changing values in
the essbase.cfg file.
You can define storage settings for a single database by using any of the methods specified
in Specifying and Changing Database Settings on page 762.
Changes made for an individual database permanently override essbase.cfg settings and
Essbase defaults for the relevant database until they are changed or withdrawn.
If you use MaxL or Administration Services Console to change settings at the database level, the
changes become effective at different times, as shown in Table 147:
760
Table 147
Setting
l
Index cache
Data cache
Disk volume
The first time after setting these values that there are no active transactions
Immediately
If you manually change these database settings in essbase.cfg, you must stop and restart the
relevant application to make them effective.
Note: The size of index pages is fixed at 8 KB to reduce input-output overhead, as well as to
Topic
Location
Administration Services
MaxL
display database
ESSCMD
GETDBSTATE
GETDBINFO
761
Setting
See
Disk volumes
Data compression
Isolation level
The following sections describe how to change kernel settings and list examples.
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATEITEM
SETDBSTATE
762
These methods provide different ways to change the same database settings. In rare cases, you
may want to use essbase.cfg to specify settings.
Caution!
In previous versions of Essbase, you can specify many database settings in the
essbase.cfg file on Essbase Server. In Version 5.x and later, Essbase overrides most
of the .cfg settings. For an explanation of how newer versions of Essbase handle
settings, see Understanding the Precedence of Database Settings on page 760 and
Understanding How Essbase Reads Settings on page 761.
Note: Terminate each MaxL statement with a semicolon when issuing them using the MaxL
Shell; however, if MaxL statements are embedded in Perl scripts, do not use the semicolon
statement terminator.
You can use MaxL to write batch scripts that automate database setting changes. See the MaxL
Language Reference, located in the Oracle Essbase Technical Reference.
For parameters that require multiple values, such as Isolation Level (item 18), specify multiple
values; in this case, all the values after BASIC:
SETDBSTATEITEM 18 "SAMPLE" "BASIC" "1" "Y" "-1";
If you do not know the parameter number, omit it, and Essbase lists all parameters and their
corresponding numbers. Essbase also prompts you for a database and an application name.
Use a separate SETDBSTATEITEM command for each parameter; you cannot string parameter
numbers together on the same line.
See the Oracle Essbase Technical Reference for information about the parameters for the
SETDBSTATE and SETDBSTATEITEM commands.
763
You can include SETDBSTATEITEM (or SETDBSTATE) in batch scripts. For a comprehensive
discussion of batch processing, see Using Script and Batch Files for Batch Processing on page
1086. For information on specific ESSCMD syntax, see the Oracle Essbase Technical Reference.
764
49
In This Chapter
Storage Allocation
Essbase uses a data file to store data blocks. By default, a data file is located in its associated
database folder. Data files follow the naming convention essn.pag, where n is greater than or
equal to one and less than or equal to 65,535.
Essbase uses an index file to store the index for a database. By default, an index file is located in
its associated database folder. Index files follow the naming convention essn.ind, where n is
greater than or equal to 1 and less than or equal to 65,535.
Essbase automatically allocates storage for data and index files. You can use disk volumes to
control how storage is allocated for these files.
Verify how much space Essbase uses to store index and data files. See Checking Index and Data File
Sizes on page 765 for information about how to check sizes.
Specify which volumes (drives) Essbase uses to store these files. See Specifying Disk
Volumes on page 766.
Install Essbase on one volume and store files on another.
Topic
Location
Administration Services
ESSCMD
LISTFILES
765
Note: The file size information that is provided by Windows for index and data files that reside
on NTFS volumes may not be accurate. The file size information provided by
Administration Services and by LISTFILES is accurate.
If you do not use the disk volumes setting, Essbase stores data only on the volume where the
ARBORPATH directory resides. If the ARBORPATH variable is not set, Essbase stores data only on
the volume where the server was started.
For new files, changes to the disk volumes setting take effect when you next start the database.
Existing files and volumes are not affected.
Note: For information about how to check the size of the index and data files, see Checking
Volume name
Maximum space to use on the volume (called Partition Size in Administration Services and
Volume Size in ESSCMD)
File type
You can specify index files, data files, or both. The default is index and data files on the same
volume.
If you specify a volume name but not a volume size, Essbase uses all available
space on the volume.
766
If the total sizes of all files reach the maximum size that you specified in the disk volumes
setting
By default, the total is the sum of all index and data file sizes. If you specify Index as the file
type, the total refers to the sum of all index files on a volume. If you specify Data as the file
type, the total refers to the sum of all data files on a volume.
For example, suppose you want to use up to 12 GB for Essbase files on volume E, 16 GB on
volume F, and 16 GB on volume G. Essbase creates a file on volume F when, on volume E,
the sizes of the index and data files reach 12 GB and more data needs to be written to disk.
l
Essbase names files consecutively, starting with ess00001.xxx, where xxx is ind for an index
file and pag for a data file, and continuing up to ess65535.xxx. This naming convention applies
to each volume, so in the above example, volumes E, F, and G each have files named
ess00001.pag and ess00001.ind.
Keep in mind the following guidelines when specifying disk volumes:
l
Specify the disk volumes in the order in which you want the volumes to be used. You do not
need to specify the volume on which Essbase is installed as one of the volumes; you can
install on one volume and store data on other volumes.
If a volume reaches capacity, Essbase moves to the next volume.
If all specified volumes reach capacity, Essbase stops ongoing database operations, issues an
error message, and performs fatal error handling. See Understanding Fatal Error Handling
on page 1049. If these events occur, shut down the database, allocate more disk space, and
restart the database.
You can tell Essbase to stop storing files on a volume. Essbase can still access the volume as
needed, but it no longer stores additional index and data information on the volume. To
stop storing information on a volume, select the volume definition that you want to remove
and click Delete.
You set disk volumes on a per-database basis. Multiple databases can use space on the same
volume, so allocate space carefully. For example, if you specify 7 GB on Volume A for
Database 1 and 7 GB on Volume A for Database 2, you have allocated 14 GB for Essbase
files on Volume A.
On Windows, you can use Universal/Uniform Naming Convention (UNC) to specify a disk
volume as the location of a network resource, such as a shared directory. Syntax:
\\ComputerName\SharedFolder\Resource
767
When you use ESSCMD, you can specify volume size in bytes (B), kilobytes (K), megabytes (M),
gigabytes (G), or terabytes (T). ESSCMD displays minimum, maximum, and current values and
0 for unlimited.
l
File type
You can specify index files, data files, or both. The default is 3 - Index + Data (index and
data files on the same volume).
File size (maximum size for each file specified in file type before Essbase creates a new file)
The default value is 2 GB; the minimum setting is 8 MB.
The following example allocates up to 10 GB on Volume E, sets a maximum file size of 2 GB,
and specifies that data files should be stored only on E:
SETDBSTATEITEM 23 "SAMPLE" "BASIC" "1" "E" "10G" "2" "2G"
Volume number
Use the GETDBSTATE command in ESSCMD to see a list of the currently defined disk
volumes and to see the number assigned to each volume.
768
Volume name
Volume size
File type
File size
The following example allocates up to 20 GB on Volume C and sets a maximum file size of 2
GB:
SETDBSTATEITEM 24 "SAMPLE" "BASIC" "1" "C" "20G" "3" "2G"
Note: If you delete an application or database, Essbase does not remove the directory containing
the application or database on a disk volume. The computer's operating system still shows
the folder and file labels on the disk. However, you can reuse the same name of the
application or database that you had removed on the disk volume.
For more syntax information, see the Oracle Essbase Technical Reference.
On UNIX, volume_name is a mounted UNIX file system. You must enter a fully qualified
pathname to the Essbase installation directory (ESSBASEPATH). Essbase automatically appends
the app directory to the path; you do not specify the app directory.
Consider the following example:
/vol2/EssbaseServer 10M
Volume size is the maximum space, in KB, allocated to the volume. The default value is unlimited
Essbase uses all available space on that volume.
769
Table 149
Disk Volume
Partition Size
File Type
File Size
20971520K
Index+Data
20971520K
26214400K
Index+Data
20971520K
26214400K
Index+Data
20971520K
Data Compression
Essbase allows you to choose whether data blocks that are stored on disk are compressed, as well
as which compression scheme to use. When data compression is enabled, Essbase compresses
data blocks when it writes them out to disk. Essbase fully expands the compressed data blocks,
including empty cells, when the blocks are swapped into the data cache.
Generally, data compression optimizes storage use. You can check compression efficiency by
checking the compression ratio statistic. See Checking the Compression Ratio on page 775.
Essbase provides several options for data compression:
l
zlib compression
Essbase builds a data dictionary based on the actual data being compressed.
No compression
Essbase does not compress data blocks when they are written to disk.
Because Essbase compresses data blocks as they are written to disk, it is possible for bitmap, RLE,
and uncompressed data blocks to coexist in the same data file. Keep in mind the following rules:
l
770
When a compressed data block is brought into the data cache, Essbase expands the block to
its full size, regardless of the scheme that was used to compress it.
When Essbase stores a block on disk, Essbase treats the block the same whether it was
compressed or uncompressed when it was brought into the data cache. In either case, Essbase
compresses the block according to the specified compression type (including not
compressing it if no compression is specified).
If compression is not enabled, Essbase writes out the fully expanded block to disk.
You may want to disable data compression if blocks have very high density (90% or greater) and
have few consecutive, repeating data values. Under these conditions, enabling compression
consumes resources unnecessarily.
#MISSING
16
#MISSING
7
#MISSING
#MISSING
When the data block is fully expanded in memory, Essbase uses 64 bytes (8 bytes * 8 cells). When
the data is stored uncompressed on disk, Essbase uses 24 bytes (8 bytes * 3 cells with datacells
1, 6, 7).
When the data is stored compressed on disk, Essbase uses 1 byte (1 bit * 8 cells; 8 bits = 1 byte)
to store the bitmap. The following is a representation of the bitmap of the uncompressed data
block described above:
Bitmap of compressed data block
1
0
0
1
0
1
0
0
In most cases, bitmap compression conserves disk space more efficiently. However, much
depends on the configuration of the data.
771
consecutively. Essbase tracks each repeating value and the number of times it repeats
consecutively.
With RLE compression, Essbase uses 8 bytes, plus a 16-byte repetition factor, for a total of 24
bytes for the set of three or more consecutive, repetitive cells. For values that are not repeated
or are repeated only twice, Essbase uses 8 bytes for each value.
In the following representation of a data block, Essbase considers the three consecutive
#MISSING values in the first row (cells 2, 3, and 4) and the left-most #MISSING value in the
second row (cell 5) as repeating values. The right-most #MISSING value in the second row (cell
8) is not a repeating value because it is separated from the cell 5 #MISSING value by cells 6 and
7, which have data values (16 and 7, respectively).
Data values in data block
25
#MISSING
#MISSING
16
#MISSING
7
#MISSING
#MISSING
When the data block is fully expanded in memory, Essbase uses 64 bytes (8 bytes * 8 cells). When
the data is stored uncompressed on disk, Essbase uses 24 bytes (8 bytes * 3 cells with datacells
1, 6, 7).
When the data is stored compressed on disk, Essbase uses 56 bytes:
l
Cell 18 bytes
Cell 68 bytes
Cell 78 bytes
Cell 88 bytes
Essbase also uses a 72-byte block header for each block, whether or not the block is compressed.
zlib Compression
This method is used in packages such as PNG, Zip, and gzip. Calculation and data loading are
faster with direct I/O and zlib compression than with buffered I/O and zlib compression. If data
storage is your greatest limiting factor, use zlib, but be aware that, under some circumstances,
data loads may be up to 10% slower than bitmap compression. The size of the database, however,
is generally significantly smaller when you use zlib compression.
In contrast to bitmap compression, which uses an algorithm to track which values are missing
and does not interact with any other type of data, zlib compression builds a data dictionary based
on the actual data being compressed (including any missing values). Therefore, zlib compression
should provide greater compression ratios over bitmap compression, given extremely dense
data. However, because the effectiveness of the zlib algorithm is dependent (at the bit level) on
the actual data being compressed, general guidelines about when zlib compression provides
greater compression than bitmap compression based solely on density are not available. Unlike
other compression methods, the storage space saved has little or no relationship to the number
of missing cells or the number of contiguous cells of equal value. Generally, the more dense or
772
heterogeneous the data is, the better zlib will compress it in comparison to bitmap or RLE
compression. However, under some circumstances, it is possible that zlib will not yield better
results than using bitmap or RLE compression. It is best to test with a representative data sample.
To estimate the storage savings you may obtain with zlib, create a small database using your
usual compression technique (bitmap or RLE) with a small sampling of real data and shut down
Essbase Server. Note the size of the created data files. Then clear the data in the sample database,
change the compression setting to zlib, reload the same sample data, and shut down Essbase
Server again. Now note the difference in the storage used. You can also use the small sample
database to estimate any changes in calculation or data loading speed.
None
None
Bitmap
RLE
zlib
zlib
For example, if the user selects RLE, Essbase reviews each block and evaluates the following
compression types for highest compression: RLE, bitmap, or Index Value Pair. If the user chooses
zlib, zlib is the only compression type applied.
database shrinks significantly using RLE compression, however, you may see a performance
improvement due to decreased I/O costs.
Databases usually shrink when using zlib compression, but not always. Using zlib compression
significantly increases CPU processing. For most databases, this extra processing outweighs the
benefits of the decreased block size. But if your database shrinks significantly using zlib
compression, you may see a performance improvement due to decreased I/O costs.
The None compression setting does not reduce the disk usage of a database compared to bitmap
compression. In fact, no compression may make no difference to improve the performance of
the database, because bitmap compression is extremely fast.
Remember that each database is unique, and the previous statements are general characteristics
of compression types. Although the default bitmap compression works well for most databases,
the best way to determine the best compression setting for your database is to try each one.
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
or:
SETDBSTATEITEM 14
To set the data compression type: SETDBSTATEITEM 15
To specify the data compression type, enter SETDBSTATEITEM 15 in ESSCMD and either
follow the prompts or supply the required values on the command line. ESSCMD prompts you
for a value of 1 (run length encoding) or 2 (bitmap, the default).
774
For more syntax information, see the Oracle Essbase Technical Reference.
Topic
Location
Administration Services
ESSCMD
GETDBSTATS
Note: The larger the number, the more compression. The compression ratio can vary widely
For information about determining the size of a data block, see Size of Expanded Data Block
on page 1057.
Topic
Location
Administration Services
ESSCMD
GETDBSTATS
775
776
50
In This Chapter
Understanding Transactions ............................................................................ 777
Understanding Isolation Levels ......................................................................... 777
Understanding How Essbase Handles Transactions .................................................. 783
Specifying Data Integrity Settings ...................................................................... 784
Accommodating Data Redundancy .................................................................... 785
Checking Structural and Data Integrity................................................................. 786
Using VALIDATE to Check Integrity...................................................................... 786
Recovering from a Crashed Database ................................................................. 787
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Understanding Transactions
When a database is in read/write mode, Essbase considers every update request to the server
(such as a data load, a calculation, or a statement in a calculation script) as a transaction. Essbase
tracks information about transactions in a transaction control file (dbname.tct).
The transaction control file contains an entry for each transaction and tracks the current state
of each transaction (Active, Committed, or Aborted).
See Understanding How Essbase Handles Transactions on page 783.
777
Note: Setting the isolation level to committed access may increase memory and time
Data Locks
Essbase issues write (exclusive) locks for blocks that are created, updated, or deleted, and issues
read (shared) locks for blocks that should be accessed but not modified. By issuing the
appropriate locks, Essbase ensures that data changed by one operation cannot be corrupted by
a concurrent update.
This section discusses locks on data blocks, not locks on database artifacts. For information
about locking and unlocking outlines and other artifacts, see Locking and Unlocking Artifacts
on page 714.
Table 151 explains the lock types:
Table 151
Lock
Description
Prevents any other transaction from accessing the locked data block. Used for all data block updates, including
spreadsheet lock and send operations.
Allows other transactions read-only access to the data block but prevents other transactions from modifying the
data block.
Table 152 shows the locks that Essbase issues for various types of operations.
Table 152
Type of Operation
Lock Issued
Spreadsheet retrieve
Write (exclusive) lock on all affected blocks. A subsequent send command commits the data.
Data load
Write lock
Restructure
Write lock
How Essbase handles locking depends on whether committed or uncommitted access is enabled.
Committed Access
Committed access provides a high level of data consistency because only one transaction at a
time can update data blocks. Under committed access, Essbase allows transactions to hold read/
778
write locks on all data blocks involved with the transaction until the transaction completes and
commits. However, you can still allow read-only access to the last committed data values.
Essbase provides options that determine when locks are issued on data blocks:
l
Pre-image access (enabled by default). Pre-image access provides users read-only access to
data blocks that are locked for the duration of a concurrent transaction. Users see the last
committed data values for the locked data blocks.
Wait, or timeout:
m
Indefinite wait (the default). The transaction waits to acquire a lock on the required
locked block.
Immediate access, or no wait. If a required block is locked by another transaction,
Essbase displays a lock timeout message, and the transaction aborts.
A number of seconds that you specify. The transaction waits that number of seconds to
acquire a lock on the required locked blocks. If the specified time runs out before the
transaction acquires a lock, Essbase displays a lock timeout message, and the transaction
aborts.
When pre-image access is enabled, you are not limited to read-only access to data blocks; if you
need write access to locked blocks, the transaction waits for write access or times out, depending
on the wait or timeout setting. The transaction gets immediate write access to data blocks that
are not locked by another transaction.
If pre-image access is not enabled, and if you need read or write access to locked blocks, the
transaction waits for write access or times out, depending on the wait or timeout setting.
Essbase retains redundant data until a transaction commits. Allow disk space for double the
size of the database to accommodate redundant data.
Models with a large number of blocks may experience memory problems under committed
access. Each lock (one lock per block) uses approximately 80 bytes of memory per
calculation, and each lock is held in memory until the transaction is complete. There is a
limit to the addressable memory space per process, and eventually models with a large
number of blocks may hit this limit, causing the transaction to terminate. In such cases,
consider using Uncommitted Access.
Note: Setting the isolation level to committed access may increase memory and time
779
For read access, the lock remains until another transaction requests it, whether or not the
transaction is complete. Other transactions can read the locked block, but none can alter it.
For write access, a transaction locks and holds the lock on each block that it modifies until
the transaction completes.
Table 153 illustrates locking behavior under committed access when multiple transactions are
contending for a lock on the same data. In this example, transaction Tx1 is running and
transaction Tx2 is requesting access to the same data. (Note that access to locked blocks depends
on what options are enabled. For a discussion of options, see Committed Access on page
778.)
Table 153
Pre-image
access
enabled
No preimage
access
No wait (timeout)
period specified
(immediate timeout)
No wait (timeout)
period specified
(immediate timeout)
Essbase issues
timeout message and
aborts the Tx2
transaction.
For information on setting concurrency parameters, see Specifying Data Integrity Settings on
page 784.
If you try to update a block that is locked by another user, Essbase behaves in these ways:
l
If wait is set to indefinite, the transaction waits to acquire the needed locks.
If wait is set to 0 (immediate), and if the required blocks are not immediately available,
Essbase displays an error message, and the transaction fails.
If wait is set to a user-specified number of seconds, and the time has expired, Essbase displays
an error message and aborts the transaction.
If the request times out, try the operation again.
For information about how to set concurrency options, see Specifying Data Integrity Settings
on page 784.
Uncommitted Access
With uncommitted access (enabled by default), the Essbase kernel allows transactions to hold
read/write locks on a block-by-block basis; Essbase releases a block after it is updated but does
not commit blocks until the transaction completes or until a specified limit (a synchronization
point) has been reached. You can set this limit, as described below.
Concurrent users accessing the same data blocks might experience unexpected results under
uncommitted access, because Essbase allows read-only access to data at its last commit point.
With uncommitted access, you can control when Essbase performs an explicit commit operation
by specifying synchronization point parameters:
l
Commit Blocks (number of blocks modified before a synchronization point occurs). The
default is 3,000.
If you set Commit Blocks to 0, the synchronization point occurs at the end of the transaction.
Commit Rows (number of rows to data load before a synchronization point occurs). The
default is 0, which means that the synchronization point occurs at the end of the data load.
If either Commit Blocks or Commit Rows has a nonzero value, a synchronization point
occurs when the first threshold is reached. For example, if Commit Blocks is 10 but Commit
Rows is 0 and you load data, a synchronization point occurs after 10 blocks are updated. If
Commit Blocks is 5 and Commit Rows is 5 and you load data, a synchronization point occurs
after 5 rows are loaded or 5 blocks are updated, whichever happens first.
781
feasibility for parallel calculation use. If Essbase finds the values set too low, it
automatically increases them.
For information about how to specify synchronization point parameters, see Specifying Data
Integrity Settings on page 784.
Caution!
Essbase retains redundant data to enforce transactional semantics. Allow disk space
for double the size of the database to accommodate redundant data, particularly if
both Commit Blocks and Commit Rows are set to 0.
Read lock
Write lock
committed. Whether transactions committed their updates the way users expected depends on
the order in which overlapping transactions updated and committed data.
If a transaction is aborted because of a nonfatal error, Essbase commits only the data that the
transaction finished processing before the abort of the transaction.
See Recovering from a Crashed Database on page 787.
Database performance.
Uncommitted access always yields better database performance than committed access.
When using uncommitted access, Essbase does not create locks that are held for the duration
of a transaction but commits data based on short-term write locks.
Data consistency.
Committed access provides a higher level of data consistency than uncommitted access.
Retrievals from a database are more consistent. Also, only one transaction at a time can
update data blocks when the isolation level is set to committed access. This factor is
important in databases where multiple transactions attempt to update the database
simultaneously.
Data concurrency.
Uncommitted access provides better data concurrency than committed access. Blocks are
released more frequently than during committed access. With committed access, deadlocks
can occur.
Database rollbacks.
If a server crash or other server interruption occurs during active transactions, the Essbase
kernel rolls back the transactions when the server is restarted. With committed access,
rollbacks return the database to its state before transactions began. With uncommitted
access, rollbacks may result in some data being committed and some data not being
committed.
See What to Expect if a Server Interruption Occurs on page 789.
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATEITEM 18
784
Pre-image access; Y (Yes) or N (No, the default). Pre-image access provides users read-only
access to data blocks that are locked for the duration of a transaction. Users see the last
committed data values for the locked data blocks.
Wait (in the Database Settings dialog box) or timeout (in ESSCMD): -1, 0, or n.
m
-1 is indefinite wait.
If you choose 2 (uncommitted access), ESSCMD prompts for the following values. See
Uncommitted Access on page 781 for explanations of these options.
l
You can also specify isolation level parameters (pre-image access and so on) by specifying
parameters 1922 on SETDBSTATEITEM. Enter SETDBSTATEITEM with no parameters;
ESSCMD displays a list that includes each parameter by number, with a description.
Here is an example of using SETDBSTATEITEM to set an isolation level. This example enables
committed access and pre-image access and specifies indefinite wait time.
SETDBSTATEITEM 18 "SAMPLE" "BASIC" "1" "Y" "-1"
785
Essbase maintains a file called dbname.esm, in which it stores crucial control information.
Caution!
The dbname.tct file, dbname.esm file, the index files, and the data files contain
information crucial for data recovery. Never alter or delete these files.
Perform a dense restructure. Because a dense restructure recreates all blocks within a
database, this method verifies index nodes and cells for each block.
Export all levels of data from the database. Exporting an entire database accesses blocks and
all data values across the entire database.
Use the ESSCMD VALIDATE command to check structural and data integrity. See Using
VALIDATE to Check Integrity on page 786.
If errors occur during any of these checks, restore the database from backups. See the Oracle
Hyperion Enterprise Performance Management System Backup and Recovery Guide.
Restructures data blocks whose restructure was deferred with incremental restructuring.
Checks every block in the database to make sure each value is a valid floating point number.
Note: When you issue the VALIDATE command, we recommend placing the database in read-
only mode.
As Essbase encounters mismatches, it records error messages in the VALIDATE error log. You
can specify a file name for error logging; Essbase prompts you for this information if you do not
provide it. The VALIDATE utility runs until it has checked the entire database.
You can use the VALIDATE command in ESSCMD to perform these structural integrity checks.
786
During index free space validation, the VALIDATE command verifies the structural integrity of
free space information in the index. If integrity errors exist, Essbase records them in the
VALIDATE log. The file that you specified on the VALIDATE command holds the error log.
If VALIDATE detects integrity errors regarding the index free space information, the database
must be rebuilt. You can rebuild in three ways:
l
See Chapter 55, Optimizing Database Restructuring and the Oracle Hyperion Enterprise
Performance Management System Backup and Recovery Guide.
Even if you do not use VALIDATE, Essbase automatically performs certain validity checking
whenever a read operation is performed, to ensure that the index is synchronized with the data.
For every read operation, Essbase compares the data block key in the index page with the data
block key in the corresponding data block and checks other header information in the block.
If Essbase encounters a mismatch, it displays an Invalid block header error message.
setting.
787
A media failure (faulty disk, disk failure, or head crash) requires that you restore data from
backups. See the Oracle Hyperion Enterprise Performance Management System Backup and
Recovery Guide.
Caution!
The Essbase kernel uses fatal error handling to display appropriate messages and to shut down
the server, depending on the error encountered. For an explanation of how fatal error handling
works, see Understanding Fatal Error Handling on page 1049.
For information about how transactions are rolled back after a crash, see Committed Versus
Uncommitted Access on page 783.
Note: If free space is recoverable, the block counters are estimates and do not necessarily match
788
Interruption
Result
Essbase Server stops. When you restart the server, Essbase recovers the
database.
Memory shortage
Server crash
Essbase performs fatal error handling. You may need to allocate more
memory or disk space and restart the server.
Essbase Exception Manager creates an error log of type .xcp. Server stops.
When you restart the server, Essbase recovers the database.
Table 156 shows what you must do if a server interruption occurs during a transaction. How
Essbase recovers from an interruption depends on the transaction isolation level setting
(committed or uncommitted access)see Rollback with Committed Access on page 781 and
Rollback with Uncommitted Access on page 782.
Table 156
Type of Request
Recommended Action
Lock
(spreadsheet update)
If the spreadsheet has been lost or does not exist, and if you are using SSAUDIT spreadsheet logging, reload
the dbname.atx file. See How to Use Spreadsheet Update Logging on page 790.
Calculation
Check the server and application logs to see where the calculation left off. See Viewing the Essbase Server
and Application Logs on page 739. Decide whether to start the calculation over. Repeat the last calculation.
Data load
Perform an action:
Repeat the last data load. See Chapter 20, Performing and Debugging Data Loads or Dimension Builds.
Load the error log. See Loading Dimension Build and Data Load Error Logs on page 753.
If the database is set to committed access, reload the data. (The transaction has been rolled back.)
If the database is set to uncommitted access, some of the data loaded, so if you reload all of the data, you
receive incorrect results for the data values that loaded twice. Therefore, perform the following actions:
l
789
Type of Request
Recommended Action
Restructure
Note: If the UPDATECALC parameter is set to FALSE, Essbase recalculates the entire database
To simplify loading the update log, prepare a batch file as described in Using Script and Batch
Files for Batch Processing on page 1086.
When SSAUDIT or SSAUDITR is specified, Essbase logs spreadsheet update transactions
chronologically. Essbase uses two files:
l
dbname.atx stores spreadsheet update transactions as a unit that can be used as the input
source for data loads.
dbname.alg contains historical information for each transaction, such as user name, date,
and timestamp, and the number of transaction rows from the .atx file.
790
When a database is started after a shutdown, if spreadsheet logging is enabled, Essbase writes
the following message to the database log:
Starting Spreadsheet Log
volumename\app\appname\dbname\dbname.atx for database dbname
To ensure successful spreadsheet update logging, stop and restart the application after either of
the following:
l
Any operation that causes a restructure. See Chapter 55, Optimizing Database
Restructuring.
Running any of the following ESSCMD commands:
m
CREATEAPP
CREATEDB
COPYDB
RENAMEDB
Essbase ensures that if you enable spreadsheet logging, updates cannot take place without being
logged. If for any reason Essbase cannot write to the update log, Essbase stops the transaction
and issues an error message.
SSAUDIT and SSAUDITR are available only from the essbase.cfg file.
791
792
51
In This Chapter
The MaxL DDL Language ................................................................................ 793
The MaxL Shell ........................................................................................... 799
The MaxL Perl Module ................................................................................... 804
Also see the MaxL DDL section of the Oracle Essbase Technical Reference.
Overview of Statements
All MaxL DDL scripts and interactive sessions comprise a login and a sequence of statements,
each terminated by a semicolon and consisting of grammatical sequences of keywords and
variables. Statements are similar to English sentences; for example,
create or replace user user-name identified by password;
MaxL statements begin with a verb, such as create or alter, which indicates the type of operation
to perform. Then you specify an artifact, such as database or user, which indicates the Essbase
elements you are working with. The rest of the statement provides details about the action to
perform, using a grammatically correct sequence of statement parts, or tokens.
For an overall picture of grammar requirements and the verb-artifact structure of MaxL
statements, see the MaxL DDL section of the Oracle Essbase Technical Reference.
793
Components of Statements
The MaxL parser recognizes and requires an ordered presentation of tokens, which are the
components of statements. A token is a space-delimited sequence of valid characters that is
recognized by MaxL as a single readable unit. Tokens can be any of the following:
l
Keywords
Names
Strings
Numbers
Keywords
Keywords are the reserved words that make up the MaxL vocabulary. These include verbs,
artifacts, and other words needed to construct statements. Keywords in MaxL are independent
of your data; conversely, you must define all other MaxL tokens (names, for example).
The MaxL parser expects to see MaxL keywords and other tokens in their correct grammatical
order, as diagrammed in MaxL topics in the Oracle Essbase Technical Reference.
Figure 147 shows a sample syntax diagram from the Oracle Essbase Technical Reference. Only the
lowercase words in the diagram represent keywords. The other elements are placeholders for
names or values that you provide.
Figure 147
Note: Keywords are not case-sensitive; the use of lowercase for keywords is a documentation
convention. See How to Read MaxL Railroad Diagrams in the Oracle Essbase Technical
Reference.
Names
Names in MaxL are used to uniquely identify databases and database artifacts, such as users,
applications, or filters.
794
When enclosed in single quotation marks, a name may contain white space and any of the
following special characters:
.
,
;
:
%
$
"
'
*
+
=
<
>
[
]
{
}
(
)
?
!
/
\
|
~
`
#
&
@
^
Note: Any name that is also a MaxL keyword must be enclosed in single quotation marks. For
795
Types of Names
Some Essbase artifacts have single names, and some require compound names known as
doubles and triples, which express the nesting of namespaces.
A singleton name can be meaningful in a system-wide contextthe artifact to which it refers
may be global to Essbaseor it needs no specified application or database context. For example,
an application has a singleton name because it need not be considered in the context of another
application or database.
A double is two names connected by a period, and a triple is three names connected by two
periods. Doubles and triples show the inherited namespace of the named entity. For example, a
database usually is identified using two names. The first identifies the application in which the
database resides, and the second is the database name; for example:
Sample.Basic
Database artifacts, such as filters, usually are identified using triple names: the first two names
identify the application and database, and the third is the artifact name. Therefore, a filter name
could look like this:
sample.basic.filter3
Table 157 shows the type of name required for the most common artifacts and provides an
example of the name used in a statement.
Table 157
Artifact
Name
Example
User
singleton
Group
singleton
Host
singleton
Application
singleton
Database
double
Calculation
triple
Filter
triple
Function (local)
double
Function (global)
singleton
Location alias
triple
Role
singleton
Substitution variable
singleton
796
Artifact
Name
Example
Disk volume
singleton to define,
triple to display
Strings
Strings are used in MaxL statements to represent the text of comments, member expressions,
calculation scripts, and file references. Strings can begin with any valid character. As with names,
strings containing white space or special characters must be enclosed in single quotation marks.
See Rules for Names on page 794 for a list of valid special characters.
Table 158 shows examples of statement elements that are strings:
Table 158
Type of String
Example
Password
Comment
Member expression
Body of a calculation
execute calculation
'"Variance"=@VAR(Actual, Budget);
"Variance %"=@VARPER(Actual, Budget);'
on Sample.basic;
File reference
spool on to '/homes/fiona/out.txt';
Numbers
You use numbers in MaxL statements to change certain database settings in Essbase. For
example, you can change cache and buffer sizes or set system-wide intervals such as the number
of days elapsing before users are required to change their passwords. To change numeric settings,
you can use positive integers, positive real numbers, and zero. Decimals and scientific notation
are permitted.
Examples:
1000
2.2
645e-2
For size settings, units must follow the number. Spaces between numbers and units are optional.
Units are case-insensitive and may include the following: B/b (bytes), KB/kb (kilobytes), MB/
797
mb (megabytes), GB/gb (gigabytes), and TB/tb (terabytes). If no units are given, bytes are
assumed.
Examples:
1000 b
5.5GB
645e-2 mb
145 KB
2,000e-3TB
Analysis of Statements
Subtopics
l
l
l
Altering a Database
Granting a Permission
Creating a Calculation
This section helps you review what you have learned about statements by illustrating MaxL
statements and their components, in template form. In the diagrams, lowercase words are
keywords, and uppercase words are intended to be replaced with the appropriate values, as shown
in the example following each illustration.
Altering a Database
Figure 148
Example:
alter database Sample.Basic set data_file_cache_size 32768KB;
Granting a Permission
Figure 149
798
Example:
grant designer on application Sample to Fiona;
Creating a Calculation
Figure 150
Example:
create calculation sample.basic.varcalc
'"Variance"=@VAR(Actual, Budget);
"Variance %"=@VARPER(Actual, Budget);'
;
This section shows you how to get started using most of the features of the MaxL Shell. Also see
the Oracle Essbase Technical Reference.
This section does not discuss using the Administration Services MaxL Script Editor. See the
Oracle Essbase Administration Services Online Help.
From a MaxL script file (statements are read from the file specified on the command line)
From standard input that is piped to the MaxL Shell from the output of another program
The MaxL Shell also accepts command-line arguments at invocation time. These can be used
with positional parameters to represent any name, or a password.
799
To enter MaxL statements interactively after logging in at invocation time, use the -l flag.
For example:
essmsh -l Admin password
...
49 - User logged in: [Admin].
In the above example, $1, $2, $3, and $4 are positional parameter variables representing
arguments entered after essmsh at invocation time, in the order in which they were entered.
If the MaxL script is not in the current directory, provide a path to the MaxL script. You can use
absolute paths or relative paths.
For example:
$ essmsh ../Oracle/Middleware/EPMSystem11R1/products/Essbase/EssbaseServer/test.msh
Note: MaxL scripts do not require a particularor anyfile extension. This document
uses.msh.
800
In UNIX shells, place single quotation marks around the path to avoid file-reading errors.
In a Windows command prompt, if the path to the script contains a space, you may have to use
double quotation marks around the entire path and file name to avoid file-reading errors.
The shell script program.sh may generate MaxL statements as output. The shell script output
is piped to essmsh -i, which uses that output as its input. This allows for efficient co-execution
of scripts.
User Admin is logged in, all user privileges are displayed, and the MaxL session is terminated.
Explanation:
1. MaxL grammar is piped to a MaxL Shell invocation and login, as the output of the UNIX
echo command.
2. The results of the MaxL session are tested by awk for pattern-matching with the MaxL status
message you would get if you entered display application on an empty system: Records
returned: [0] .
3. Awk matches the string 'Records returned: ', and then checks to see if that is equal to
'[0].'
801
4. If $7 (a variable representing the fifth token awk finds in the status string) is equal to
'[0].', there are no applications on the system; otherwise, $7 would equal '[1].' or
whatever number of applications exist on the system.
For more information and examples on invocation options, see the Oracle Essbase Technical
Reference. Invocation information is also contained in the essmsh man page. To view the man
page, enter essmsh -h | more at the operating-system command prompt.
Logging In to Essbase
The MaxL language interpreter requires a connection to an Essbase session before it can begin
parsing MaxL statements. Use the MaxL Shell to establish the connection to Essbase.
To log on to Essbase after the command shell has been started, use the shell login grammar.
For example:
essmsh
MAXL>login Fiona identified by sunflower on hostname;
Note: You can log out and change users without quitting the shell.
When a user logs in to Essbase through a MaxL Shell session and Essbase is restarted while
the user is still logged in, the next login through the same MaxL Shell session is delayed
by four seconds.
For more information about MaxL Shell invocation options, see the Oracle Essbase Technical
Reference.
802
Note: Because msh is a shell command, it is limited to the originating session. Therefore, you
should not reference MaxL scripts that contain new login statements.
MaxL statements and their output are logged to the output file when you issue the spool
command, either in an interactive session or in a script. However, MaxL Shell commands and
output are logged only if you spool during an interactive session. MaxL Shell commands and
output are ignored in log files created from script sessions. Additionally, output from any
operating-system commands you may have included is ignored in the log files of both interactive
and script sessions.
To escape to ESSCMD from within a MaxL session, use single quotation marks:
For example:
803
To exit from the MaxL Shell after using interactive mode, enter:
exit;
While you administer Essbase databases, Perl with MaxL enables you to take advantage of these
and other programmatic features:
l
Conditional testing
Interprocess communication
Message handling
E-mail notification
Web scripting
Essbase.pm contains methods that enable passing MaxL statements by means of Perl:
804
fetch_col (), fetch_desc (), and fetch_row () retrieve information from MaxL display output
tables
disconnect () terminates the connection to Essbase
To make the Perl methods available to Essbase, include a reference to Essbase.pm in the Perl
program. Place the following line at the top of each Perl script:
use Essbase;
Perl is not difficult to learn, especially if you have knowledge of UNIX shells or other
programming languages. To download Perl and learn more about it, visit the Comprehensive
Perl Archive Network Web site at http://www.cpan.org/.
See the MaxL DDL section of the Oracle Essbase Technical Reference and the Readme file in the
PERLMOD directory of your Essbase installation.
805
806
Part IX
Optimizing Essbase
In Optimizing Essbase:
l
l
l
l
l
l
l
l
Monitoring Performance
Improving Essbase Performance
Optimizing Essbase Caches
Optimizing Database Restructuring
Optimizing Data Loads
Optimizing Calculations
Optimizing Reports and Other Types of Retrieval
Running Essbase on Oracle Exalytics In-Memory Machine
807
808
52
Monitoring Performance
In This Chapter
Finding Diagnostic Information ......................................................................... 809
Viewing Essbase Server Information ................................................................... 810
Viewing Application Information ........................................................................ 810
Viewing Database Information .......................................................................... 810
Monitoring the Status of Applications and Databases ............................................... 811
Monitoring User Sessions and Requests............................................................... 811
Monitoring Applications from the Operating System ................................................. 811
Also see:
l
Adding users
Essbase displays information on a snapshot basis; to see the latest information, click Refresh. If
the Refresh button is displayed in a window or dialog box, it updates every tab in the window
or dialog box.
For a comprehensive discussion of Essbase Server, application, and outline logs, see Essbase
Server and Application Logs on page 727.
The following sections provide procedures for accessing information about Essbase Servers,
applications, and databases that are commonly used to diagnose performance or other issues.
809
Topic
Location
Administration Services
MaxL
display application
ESSCMD
GETAPPSTATE
Topic
Location
Administration Services
Monitoring Applications
MaxL
display application
ESSCMD
GETAPPSTATE
Instructions
See
Administration Services
Monitoring Databases
MaxL
display database
810
Tool
Instructions
See
ESSCMD
Instructions
Administration Services
ESSCMD
GETAPPINFO
GETDBINFO
Instructions
Administration Services
MaxL
811
new icon is displayed in the taskbar. Double-click the icon to view the application server
window.
l
812
On UNIX platforms, the application server is often a background process. When the
application starts, the ESSBASE command starts the ESSSVR process. To see activities, you
can route all messages to a file with the tail -f log command, where log is the name of
a file that you specify.
You can also view a snapshot of the Essbase Server or application log using Administration
Services. For information about viewing, filtering, searching, and analyzing logs, see Oracle
Essbase Administration Services Online Help. For information on server and application logs,
see Essbase Server and Application Logs on page 727.
53
In This Chapter
Recognizing Basic Design Issues That Affect Optimization........................................... 813
Resetting Databases to Improve Performance ........................................................ 813
Using Database Settings to Customize for Maximum Performance ................................. 814
Fragmentation and its Implications .................................................................... 818
Enabling Windows 4 GB Tuning (4GT) ................................................................. 819
Implementing 64-bit Essbase .......................................................................... 819
Configuring the JVM Heap Size for Essbase Running on Solaris 64-bit............................. 820
About the CLASSPATH Environment Variable.......................................................... 820
Finding Additional Optimization Information .......................................................... 820
For an introduction to basic concepts and how they relate to optimized performance, see
Chapter 3, Understanding Multidimensional Databases.
For a discussion of how to analyze a database design while it is still on paper and of how this
analysis can aid optimization, see Analyzing and Planning on page 79.
To understand how basic database outline issues affect performance, see Designing an
Outline to Optimize Performance on page 93.
Topic
Location
MaxL
813
Tool
Topic
Location
ESSCMD
RESETDB
l
l
l
l
You can customize Essbase for maximum performance, using database settings at the database
level in Administration Services, ESSCMD, or MaxL.
Note: If you are migrating a database, see the Oracle Enterprise Performance Management System
Installation and Configuration Guide for information about the default settings after
migration.
The following sections list performance settings and describe how to adjust them.
Setting
Topic
Location
MaxL:
alter database appname.dbname set index_cache_size n
ESSCMD: SETDBSTATEITEM 12
MaxL:
alter database appname.dbname set data_file_cache_size n
814
ESSCMD: SETDBSTATEITEM 27
Setting
Topic
Location
MaxL:
alter database appname.dbname set data_cache_size n
ESSCMD: SETDBSTATEITEM 5
Fixed size
N/A
Cache memory
locking
MaxL:
alter database appname.dbname enable cache_pinning
ESSCMD: SETDBSTATEITEM 26
See Setting Database Properties in Oracle Essbase Administration Services Online Help.
Setting
Topic
Location
Volume name
MaxL:
alter database appname.dbname set disk volume
ESSCMD:
SETDBSTATEITEM 23
SETDBSTATEITEM 24
Partition size
MaxL:
alter database appname.dbname set disk volume
ESSCMD:
SETDBSTATEITEM 23
SETDBSTATEITEM 24
File type
MaxL:
alter database appname.dbname set disk volume
ESSCMD: SETDBSTATEITEM 23
815
Setting
Topic
Location
MaxL:
alter database appname.dbname set disk volume
ESSCMD: SETDBSTATEITEM 23
See Setting Disk Volumes in Oracle Essbase Administration Services Online Help.
Setting
Topic
Location
Isolation level
MaxL:
alter database appname.dbname enable committed_mode
Commit Blocks
ESSCMD: SETDBSTATEITEM 18
MaxL:
alter database appname.dbname enable committed_mode
and
alter database appname.dbname set implicit_commit after n blocks
Commit Rows
ESSCMD: SETDBSTATEITEM 21
MaxL:
alter database appname.dbname enable committed_mode
and
alter database appname.dbname set implicit_commit after n rows
ESSCMD: SETDBSTATEITEM 22
MaxL:
alter database appname.dbname set lock_timeout
816
ESSCMD: SETDBSTATEITEM 20
Setting
Topic
Location
Pre-image access
MaxL:
alter database appname.dbname enable pre_image_access
ESSCMD: SETDBSTATEITEM 19
See Setting Data Integrity Options in Oracle Essbase Administration Services Online Help.
Setting
Topic
Location
MaxL:
alter database appname.dbname set retrieve_buffer_size n
ESSCMD SETDBSTATEITEM 16
MaxL:
alter database appname.dbname set retrieve_sort_buffer_size n
Data compression
ESSCMD: SETDBSTATEITEM 17
MaxL:
alter database appname.dbname enable compression
and
alter database appname.dbname set compression type
ESSCMD:
SETDBSTATEITEM 14
SETDBSTATEITEM 15
Understanding Triggers
Definitions on page 119
MaxL:
create or replace trigger, alter trigger display trigger, and drop trigger
See Setting Database Properties in Oracle Essbase Administration Services Online Help.
817
Fragmentation refers to free space within an Essbase database. There are two implications of
fragmentation. One is related to performance, and the other is related to size of the data files.
Historically, fragmentation has been perceived as degrading performance. However, with
advances in hardware, memory, and disk architectures, the correlation between fragmentation
and performance is no longer significant. Furthermore, several enhancements have been made
to algorithms within Essbase, making the older statistics pertaining to fragmentation less
relevant. Oracle recommends the use of the latest efficient storage systems to store Essbase data
files, such as Storage Area Network (SAN) or flash.
The second implication of fragmentation is related to increase in the size of data files. Oracle
recommends regular monitoring of the number of blocks and the data file size. If the size of the
data files increases even though the number of data blocks remains the same, and available disk
space is diminishing, consider taking steps to reduce fragmentation.
The database is under intensive update activity, such as heavy data loads and calculations
The database uses parallel update operations, such as parallel calculation and parallel
restructuring
The NUMBLOCKSTOEXTEND configuration setting is greater than 1 (the default is 2048)
Data load records are not sorted. Optimize data loads by sorting load records based on sparse
dimension members. For a comprehensive discussion of optimizing data load by grouping
sparse members, see Grouping Sparse Member Combinations on page 852.
Removing Fragmentation
You can remove fragmentation and compact an Essbase database using either of the following
methods:
l
818
Perform an export of the database, delete all data in the database with CLEARDATA, and
reload the export file. See the Oracle Hyperion Enterprise Performance Management System
Backup and Recovery Guide.
Run the MaxL statement alter database force restructure.
Essbase is configured to use direct I/O. Enabling 4GT on Essbase installations configured
for buffered I/O is not recommended.
The index and data caches are sized correctly, and Essbase performance is consistently
improved by increasing the data file cache, but further increases are bounded by the previous
2 GB addressability limitation. For information about setting cache values, see Chapter 54,
Optimizing Essbase Caches.
For additional information about the Microsoft Windows 4GT feature, see http://
www.microsoft.com.
Setting
32-bit Maximum
64-bit Maximum
AGENTTHREADS
500
1024
SERVERTHREADS
500
1024
DLTHREADSPREPARE
16
32
DLTHREADSWRITE
16
32
Default retrieval buffer settings for 64-bit Essbase are higher than for 32-bit Essbase.
Table 164 lists the default retrieval buffer settings for each. See Changing Buffer Size on page
889.
819
Table 164
Setting
32-bit Default
64-bit Default
Retrieval Buffer
10 KB
20 KB
10 KB
20 KB
Note: Because of internal data structure size changes, 64-bit Essbase requires a larger retrieval
sort buffer size than 32-bit Essbase. If you encounter the error, "Sort buffer limit
of [x] rows have been exceeded" (where x is the current maximum number of
rows allowed for the current buffer size), increase the retrieval sort buffer size by a factor
of two.
820
For information on optimizing performance for a particular function, see these chapters:
m
821
822
54
In This Chapter
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Cache
Description
Index cache
A buffer in memory that holds index pages. How many index pages are in memory simultaneously depends upon
the amount of memory allocated to the cache.
A buffer in memory that holds compressed data files (.pag files). Essbase allocates memory to the data file cache
during data load, calculation, and retrieval operations, as needed. The data file cache is used only when direct I/O
is in effect.
Data cache
A buffer in memory that holds uncompressed data blocks. Essbase allocates memory to the data cache during data
load, calculation, and retrieval operations, as needed.
Calculator cache
A buffer in memory that Essbase uses to create and track data blocks during calculation operations.
Dynamic calculator
cache
A buffer in memory that Essbase uses to store all of the blocks needed for a calculation of a Dynamic Calc member
in a dense dimension (for example, for a query).
Essbase provides default size settings for each cache; you can adjust the sizes as needed for each
database. Appropriate cache size is affected by many factors, including database size, block size,
index size, and available server memory. Cache size settings can significantly affect database and
general server performance.
The following topics provide information about sizing caches for performance.
823
Topic
Location
Administration Services
MaxL
ESSCMD
SETDBSTATEITEM 26
Sizing Caches
The settings that you should use for each of the caches that you can configure depend on data
distribution and the dense/sparse configuration of the database. The maximum combined total
size of the caches should equal the amount of available memory after the memory required by
Essbase is taken into account.
The needs for each site, even for a particular database, can vary. Depending on the complexity
and type of each operation, Essbase allocates as much memory for the data file cache and the
data cache as needed. Use the recommended values in this section to estimate enough memory
for optimal performance.
824
If you are using Essbase for the first time, cache sizes are set automatically to the default values
discussed in the following sections. Use these topics to find and understand recommendations
for each cache size.
Note: Changes made to cache sizes take effect the next time you start the database.
Minimum Value
Maximum Values
Default Values
Recommended Value
1 MB (1,048,576
bytes)
32-bit Essbase: 4 GB
Direct I/O: 10 MB
For information about changing the I/O access mode for a database, or about changing the
default for all newly created databases, see Understanding Buffered I/O and Direct I/O on page
756.
In general, if you are using direct I/O, make the index cache as large as system resources allow.
If you are using buffered I/O, make the index cache as small as possible.
For information on testing and fine-tuning cache settings, see Fine-Tuning Cache Settings on
page 836.
825
Topic
Location
Administration Services
MaxL
ESSCMD
SETDBSTATEITEM 12
SETDBSTATE
Minimum Value
Default Value
Recommended Value
In general, if you are using direct I/O, make the data file cache as large as system resources allow.
If you are using buffered I/O, the data file cache is not used.
For information on testing and fine-tuning cache settings, see Fine-Tuning Cache Settings on
page 836.
Topic
Location
Administration Services
MaxL
826
Tool
Topic
Location
ESSCMD
SETDBSTATEITEM 27
Minimum Value
Default Value
Recommended Value
3072 KB
(3145728 bytes)
3072 KB (3,
145,728 bytes)
0.125 * the value of data file cache size. Increase value if any of these conditions exist:
l
Calculation scripts contain functions on sparse ranges, and the functions require all
members of a range to be in memory (for example, when using @RANK and @RANGE).
For data load, the number of threads specified by the DLTHREADSWRITE setting is high
and the expanded block size is large.
In certain cases, you might need to increase the data cache when running concurrent calculations;
for example, when concurrent calculations do not share any common blocks and the sparse
member with the largest number of children has all its children blocks populated in the database.
To calculate the data cache for concurrent calculations, use the following formula:
(Size of big block in bytes) * max(Number of children for a Sparse member) * (Number of
concurrent batch calc processes) * 2
If other concurrent operations (such as data loads and queries) take place when running
concurrent calculations, increase the data cache even more to accommodate these requests.
Make the data cache as small as possible whether you are using buffered I/O or direct I/O.
For information on testing and fine-tuning cache settings, see Fine-Tuning Cache Settings on
page 836.
Note: When running Essbase on 64-bit platforms, optimal data cache and data file cache settings
may be larger than 4 GB. Although you cannot specify settings larger than 4 GB in Essbase
clients, you can enable larger settings using the MEMSCALINGFACTOR configuration
setting. See the Oracle Essbase Technical Reference.
827
Topic
Location
Administration Services
MaxL
ESSCMD
SETDBSTATEITEM 5
SETDBSTATE
The best size for the calculator cache depends on the number and density of the sparse
dimensions in your outline. Use the following topics to understand the calculator cache bitmap,
size the calculator cache, and change the size of the calculator cache (and therefore the largest
possible size for the bitmap), if required:
Bitmap dimensions: The sparse dimensions from the database outline that Essbase fits into
the bitmap until the bitmap is full. Each member combination of the sparse dimensions
placed in the bitmap occupies 1 bit of memory, and there must be enough space in the
bitmap for every member combination of a sparse dimension for it to be placed in the
bitmap.
Anchoring dimensions: The remaining one or more sparse dimensions in the database
outline that do not fit into the bitmap.
Essbase starts with the first sparse dimension in the database outline and fits as many sparse
dimensions as possible into the bitmap. The dimensions that fit are the bitmap dimensions.
Essbase stops the process when it cannot fit another complete sparse dimension into the bitmap.
Because the calculator cache controls the size of the bitmap, the number of sparse dimensions
828
that can fit in the bitmap depends on the size of the calculator cache (and the number and size
of the sparse dimensions).
The remaining sparse dimensions are the anchoring dimensions. For anchoring dimensions,
Essbase cannot use the bitmap to determine whether blocks exist.
To see which dimensions are anchoring dimensions and which are bitmap dimensions, use the
SET MSG DETAIL calculation command to display bitmap information in the application log.
Carefully order the sparse dimensions in your outline so that as many dimensions as possible
can be placed into the bitmap. Start with the dimension that contains the fewest members and
continue until the dimension with the most members is last. This order allows more dimensions
to fit into the bitmap and results in improved calculation performance.
Note: The order of sparse dimensions in the outline also affects query performance. See
A single bitmap uses the least memory but is less efficient than multiple bitmaps.
Multiple bitmaps use more memory but are faster than using a single bitmap. The
performance improvement is particularly high when you are calculating the database for
the first time.
The number of bitmaps used is determined by the maximum number of dependent parents
for any members in the anchoring dimension. A member has one dependent parent, unless
it has a shared member. For example, consider the Product dimension of the Sample.Basic
database. The member Cola (100-10) has one parent, Colas (100). However, Diet Cola
(100-20) has two parents, Diet Drinks (Diet) and Colas (100). No members of Product have
more than two dependent parents. Therefore, if Product is the anchoring dimension, the
maximum dependent parents is two.
Essbase chooses one of three options, as shown in Table 169, for the calculation:
Table 169
Option
Method
Performance Rating
829
Option
Method
Performance Rating
Essbase chooses the optimal performance method for a database calculation, based on the size
of the calculator cache. If the calculator cache size is too small for any of the above options,
Essbase does not use a calculator cache. Calculation performance may be significantly impaired.
Enabling parallel calculation may change which calculator cache option is used. See
Relationship Between CALCPARALLEL Parallel Calculation and Other Essbase Features on
page 503.
Caution!
If you are calculating the database for the first time, the size of the calculator cache
is particularly significant for calculation performance. If possible, ensure that the
calculator cache is large enough for Essbase to use the optimal calculator cache
option.
where
Bitmap size in bytes = Max ((member combinations on the bitmap dimensions / 8), 4)
and where
Number of bitmaps = Maximum number of dependent parents in the anchoring dimension + 2
constant bitmaps
Note: The minimum bitmap size is 4 bytes. If (member combinations on the bitmap
Sparse Dimension
Number of Members
Dependent Parents
S1
20
Not applicable
S2
20
Not applicable
S3
50
Not applicable
S4
50
Not applicable
830
Sparse Dimension
Number of Members
Dependent Parents
S5
200
Anchoring dimension: S5
For Essbase to use multiple bitmaps for this database with one anchoring dimension, the
calculator cache must be 625,000 bytes.
Anchoring dimension: S5
831
= 125,000 bytes
Number of bitmaps = Single bitmap
= 1
Calculator cache = Bitmap size * Number of bitmaps
= 125,000 * 1
= 125,000 bytes
For Essbase to use a single bitmap for this database with one anchoring dimension, the calculator
cache must be 125,000 bytes.
For Essbase to use a single bitmap for this database with multiple anchoring dimensions, the
calculator cache must be 2,500 bytes.
Option Selected
625,000 bytes
125,000 bytes
Option 2
832
Option Selected
2,500 bytes1
Option 3
1If
you specify a calculator cache size of less than 2,500 bytes, Essbase does not use a calculator cache during the calculation. Calculation
performance may be significantly impaired.
You can check which calculator cache option Essbase is able to use on a database by using the
SET MSG SUMMARY command in a calculation script. Run the following calculation script on
the empty database:
SET MSG SUMMARY;
CALC ALL;
Essbase displays the calculator cache setting in the ESSCMD window or in the application log.
See SET MSG SUMMARY and SET MSG DETAIL on page 862.
The maximum calculator cache size that you can specify is 200,000,000 bytes. The default is
200,000 bytes. The calculator cache size that you choose depends on available memory and the
configuration of the database.
Note: The sizes of the calculator, index, data file, and data caches usually have a greater effect
Sizing the Calculator Cache to Calculate the Database for the First Time
If you are calculating the database for the first time, the size of the calculator cache is particularly
significant. If possible, ensure that the calculator cache is large enough for Essbase to use the
optimal calculator cache option. See Calculating the Calculator Cache Size on page 830.
833
The first message describes the total time required for the retrieval. If a dynamic calculator cache
is used, the second message displays the number of blocks calculated within the data calculator
cache (DCC = n) and the number of blocks calculated in general memory (non-DCC = n).
DYNCALCCACHEMAXSIZE: This setting specifies the maximum size Essbase can allocate
to each dynamic calculator cache on the server.
Recommended setting value = C * S * U.
m
19 (Year, with 12 stored members and 7 Dynamic Calc members, including HTD
and QTD)
834
U is the maximum number of expected concurrent users on the database that has the
largest number of concurrent users.
WT is the maximum tolerable wait time for a query; for example, 5 seconds.
DYNCALCCACHEBLKRELEASE: If Essbase has waited the specified time and space still is
not available in the dynamic calculator cache, this setting tells Essbase whether to write and
calculate the blocks immediately outside the dynamic calculator cache or to create space in
the dynamic calculator cache by swapping out blocks and temporarily compressing the
swapped blocks in a dynamic calculator cache compressed-block buffer.
Recommended setting value = FALSE (default value).
Set to TRUE only if you are experiencing severe memory shortage problems.
C is the value of the current CALCLOCKBLOCK setting in the essbase.cfg file. The
SET LOCKBLOCK command specifies which CALCLOCKBLOCK configuration
setting is current.
S is the size of the largest expanded block across all databases on the machine. Calculate
S as described for the DYNCALCCACHEMAXSIZE setting.
835
Note: After changing any parameter in the essbase.cfg file, you must stop and restart Essbase
Index Cache
The advantages of a large index cache plateau at some point. When the index cache size equals
or exceeds the index size (including all index files on all volumes), performance does not
improve. However, to account for future growth of the index, you can set the index cache size
larger than the current index size. Because the index cache is filled with index pages, for optimum
use of storage, set the size of the index cache to be a multiple of the size of the index page (8 KB).
See Index Files on page 1062 for an example of estimating index size.
Data Cache
The data cache should be about 0.125 times the data file cache. However, certain calculations
require a larger data cache size. If many concurrent users are accessing different data blocks, this
cache should be larger.
836
In general, if you must choose between allocating memory to the data file cache or allocating it
to the data cache, choose the data file cache if you are using direct I/O. If upgrading from a
previous version of Essbase, see the Oracle Enterprise Performance Management System
Installation and Configuration GuideEnabling Windows 4 GB Tuning (4GT).
The cache hit ratio indicates the percentage of time that a requested piece of information is
already in the cache. A higher hit ratio indicates that the data is in the cache more often.
This improves performance, because the requested data need not be retrieved from disk for
the next process. A hit ratio of 1.0 indicates that every time data is requested, it is found in
the cache. This is the maximum performance possible from a cache setting.
The Hit Ratio on Index Cache setting indicates the Essbase kernel success rate in locating
index information in the index cache without having to retrieve another index page from
disk.
The Hit Ratio on Data File Cache setting indicates the Essbase kernel success rate in locating
data file pages in the data file cache without having to retrieve the data file from disk.
The Hit Ratio on Data Cache setting indicates the Essbase success rate in locating data blocks
in the data cache without having to retrieve the block from the data file cache.
Check memory allocation. Add smaller amounts of memory at a time , if needed, because
a smaller increment may have the same benefit as a large one. Large, incremental allocations
of memory usually result in very little gain in the hit ratio.
Checking Performance
You can check cache statistics for a database by using the query database MaxL statement with
the performance statistics grammar. See Chapter 52, Monitoring Performance.
837
838
55
Optimizing Database
Restructuring
In This Chapter
Database Restructuring ................................................................................. 839
Optimization of Restructure Operations................................................................ 843
Actions That Improve Performance ..................................................................... 843
Outline Change Quick Reference ....................................................................... 846
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
Database Restructuring
As your business changes, you change the Essbase database outline to capture new product lines,
provide information on new scenarios, reflect new time periods, and so on. Some changes to a
database outline affect the data storage arrangement, forcing Essbase to restructure the database.
Because changes that require restructuring the database are time-consuming (unless you discard
the data before restructuring), consider deciding on such changes based on how they affect
performance. This section provides the information necessary to understand how restructuring
affects performance and describes tasks you can perform related to database restructuring:
Note: For information about clearing data and thus avoiding some restructuring, see
839
Implicit Restructures
Explicit Restructures
Implicit Restructures
Essbase initiates an implicit restructure of the database files after an outline is changed using
Outline Editor or Dimension Build. The type of restructure that is performed depends on the
type of changes made to the outline:
l
If you use incremental restructuring, Essbase defers dense restructuring. If you change a database
outline frequently, consider enabling incremental restructuring. See Incremental Restructuring
and Performance on page 844 for a comprehensive discussion of incremental restructuring.
Note: How a database outline is changed (by using Outline Editor or using dimension build)
does not influence restructuring. Only the type of information change influences what
type of restructuring, if any, takes place. For information about outline changes and the
type of restructures they cause, see Outline Change Quick Reference on page 846.
Explicit Restructures
When you manually initiate a database restructure, you perform an explicit restructure. An
explicit restructure forces a full restructure of the database. A full restructure comprises a dense
restructure plus removal of empty blocks.
840
Topic
Location
Administration Services
MaxL
alter database
If you use Intelligent Calculation in the database, all restructured blocks are marked as dirty
whenever data blocks are restructured. Marking the blocks as dirty forces the next default
Intelligent Calculation to be a full calculation.
If you change a name or a formula, Essbase does not mark the affected blocks as dirty.
Therefore, you must use a method other than full calculation to recalculate the member or
the database.
Topic
Related Information
Intelligent Calculation
Sparse and Dense Dimensions on page 64, Selection of Dense and Sparse Dimensions on page
65
Attribute dimensions
Dimension building
Outline Editor
File
Description
essxxxxx.pag
essxxxxx.ind
841
File
Description
dbname.esm
Essbase kernel file that contains control information used for database recovery
dbname.tct
dbname.ind
dbname.otl
Outline file in which is defined all metadata for a database and how data is stored.
Dense Restructures
To perform a dense restructure, Essbase does the following:
1
Each temporary file substitutes either n or u for the last character of the file extension.
Temporary file names are:
essxxxxx.inn
essxxxxx.pan
dbname.otn
dbname.esn
dbname.tcu
Reads the blocks from the database files copied in step 1, restructures the blocks in memory, and stores
them in the new temporary files. This step takes the most time.
Renames the temporary files created in step 1 to the correct file names.
Sparse Restructures
When Essbase does a sparse restructure (restructures only the index), it uses the following files:
l
essxxxxx.ind
dbname.otl
842
dbname.esm
Creates index files (essxxxxx.ind) to store index information that is changed by the restructuring
operation.
Dense (index files and data files) as a result of adding, deleting, or moving members and
other operations. See Outline Change Quick Reference on page 846
Dense (index and data files) as a result of changing a dense dimension to sparse or changing
a sparse dimension to dense
843
Note: Setting the isolation level to committed access may increase memory and time
Whether or not incremental restructuring is enabled, if an outline has already been incrementally
restructured (a dense restructure is pending), adding shared members causes Essbase to perform
a dense restructure.
Note: Recalculate the database after any type of restructure operation.
844
Parallel Restructuring
By default, block storage restructuring is performed sequentially. Blocks are renumbered and
reshaped from first to last, a time-intensive process. Parallel restructuring can reduce
restructuring time by dividing block restructuring work across multiple concurrent threads to
use available processor cores. Because calculation is performed separately from restructuring,
each block can be restructured independently of other blocks.
Blocks are divided into n groups, where n is the number of restructuring threads. This division
is performed by traversing the breadth of the index BTree until the number of keys at a level is
equal to or greater than n. If there is no level with more than n keys, the number of restructuring
threads is reduced accordingly.
The number of restructuring threads to use is defined in essbase.cfg using the
RESTRUCTURETHREADS configuration setting. If RESTRUCTURETHREADS is not defined,
the default is one thread. For details, see the Oracle Essbase Technical Reference.
Note: Parallel restructuring operations do not dynamically create threads, but instead use a set
number of threads from a pre-created pool of threads. You can customize the size of the
thread pool. For more information, see the WORKERTHREADS configuration setting
topic in the Oracle Essbase Technical Reference.
845
connected.
Table 174
Action
846
Essbase deletes from the index file all pointers to blocks represented
by the deleted member. Because the blocks are no longer pointed to,
they become free space. No restructure.
None
Incremental Restructuring
Applies? (If Enabled)
For regular members, no. Essbase
restructures the index, overriding
incremental restructure.
For label-only members, yes,
restructuring is deferred.
No
Action
Incremental Restructuring
Applies? (If Enabled)
Yes. Changes to data and index
files are deferred.
No
No restructure.
Add member to sparse
dimension
Data for the new member must be loaded or calculated to derive new
values.
Data for the new member must be loaded or calculated to derive new
values. Data must be recalculated.
None
No
No
No restructure.
Move regular member within
a sparse dimension
None
Table 175
Action
Incremental Restructuring
Applies? (If Enabled)
None
No
Rename member
None
No
No
No restructure.
847
Table 176
Action
Define Dynamic Calc member as Dynamic Calc and
Store
None
No
None
No
Restructure deferred.
No restructure
No
No restructure
No
No
No restructure.
No
848
Table 177
Action
Incremental Restructuring
Applies? (If Enabled)
Essbase restructures index and data
files overriding incremental
restructure.
Yes. Changes to data and index files
are deferred.
Yes. Changes to data and index files
are deferred.
No
None
No
None
No
None
No
None
No
None
No
None
No
849
850
56
In This Chapter
Understanding Data Loads.............................................................................. 851
Grouping Sparse Member Combinations .............................................................. 852
Making the Data Source as Small as Possible........................................................ 854
Making Source Fields as Small as Possible ........................................................... 855
Positioning Data in the Same Order as the Outline................................................... 855
Loading from Essbase Server ........................................................................... 855
Using Parallel Data Load ................................................................................ 856
Some information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
To optimize data load performance, think in terms of database structure. Essbase loads data
block by block. For each unique combination of sparse dimension members, one data block
contains the data for all the dense dimension combinations, assuming that at least one cell
contains data. For faster access to block locations, Essbase uses an index. Each entry in the index
corresponds to one data block. See Sparse and Dense Dimensions on page 64, Selection of
Dense and Sparse Dimensions on page 65, and Dense and Sparse Selection Scenarios on page
67.
When Essbase loads a data source, Essbase processes the data in five stages of a pipeline.
For free form data load, the stages are:
1. InputEssbase collects input from file or SQL connection
2. TokenizeEssbase separates input fields from records, creating tokens
851
This process is repeated until all data is loaded. By using one or more processing threads in each
stage, Essbase can perform some processes in parallel. See Using Parallel Data Load on page
856.
Examples in this chapter assume that you are familiar with the information in this topic: Data
Sources on page 266.
Dense Dimensions
852
Dense Dimensions
Note: Because you do not load data into attribute dimensions, they are not relevant to this
Cola
"Root Beer"
"Root Beer"
Cola
Ohio
Florida
Ohio
Florida
Sales
Sales
Sales
Sales
25
28
18
30
This data loads slowly because Essbase accesses four blocks instead of one.
An optimally organized data source for the same Sample.Basic database shows different records
sorted by a unique combination of sparse-dimension members: Actual -> Cola -> Ohio. Essbase
accesses only one block to load these records.
Actual
Actual
Actual
Actual
Cola
Cola
Cola
Cola
Ohio
Ohio
Ohio
Ohio
Jan
Jan
Jan
Jan
Sales
Margin
COGS
Profit
25
18
20
5
You can use a data source that loads many cells per record. Ensure that records are grouped
together by unique sparse-dimension member combinations. Then order the records so that the
dimension in the record for which you provide multiple values is a dense dimension.
The next data source example uses a header record to identify the members of the Measures
dimension, which is dense. The data is sorted first by members of the dense dimension Year and
grouped hierarchically by members of the other dimensions. Multiple values for the Measures
dimension are provided on each record.
Jan
Jan
Jan
Jan
Actual
Actual
Actual
Actual
Cola
Cola
"Root Beer"
"Root Beer"
Ohio
Florida
Ohio
Florida
Sales
25
30
18
28
Margin
18
19
12
18
COG
20
20
10
20
Profit
5
10
8
8
Notice that the heading and first data line that requires two lines in this example; the previous
example needs four lines for the same data.
For information about arranging data in source files before loading, see Data Sources that Do
Not Need a Rules File on page 273.
853
"New
"New
Ohio
Ohio
"New
"New
Ohio
Ohio
York"
York"
York"
York"
Cola
"Diet
Cola
"Diet
Cola
"Diet
Cola
"Diet
4
3
8
7
6
8
7
9
Cola"
Cola"
Cola"
Cola"
The next example provides the same data optimized by grouping members in ranges. By
eliminating redundancy, this example contains only 23 fields that Essbase must read in order to
load the data values properly.
Profit
Jan
"New York"
Ohio
Feb
"New York"
Ohio
Cola
"Diet
Cola
"Diet
Cola
"Diet
Cola
"Diet
Cola"
Cola"
Cola"
Cola"
4
3
8
7
6
8
7
9
Essbase assigns the first value, 4, to Jan->New York->Cola; it assigns the next value, 3, to Jan>New York->Diet Cola and so on.
Although sorted efficiently, the data source sorted and grouped by dense dimensions shows a
lot of repetition that can slow down the load process. You can further optimize this data by
grouping the data into ranges. The optimized data source below eliminates the redundant fields,
reducing processing time.
Jan Actual
Cola
"Root Beer"
Sales
Ohio
25
Florida
30
Ohio
18
Florida
28
Margin
18
19
12
18
854
COG
20
20
10
20
Profit
5
10
8
8
Remove excess white space in the data source. For example, use tabs instead of blank spaces.
Round computer-generated numbers to the precision you need. For example, if the data
value has nine decimal points and you care about two, round the number to two decimal
points.
Use #MI instead of #MISSING.
data in the same order as the outline does not affect the speed of data loads.
See Sizing the Index Cache on page 825.
855
The following topics discuss parallel data load and how it might improve performance for your
site.
With the above configuration, the data load is set to run with 11 threads.
Note: Parallel data load operations do not dynamically create threads, but instead use a set
number of threads from a pre-created pool of threads. You can customize the size of the
thread pool. For more information, see the WORKERTHREADS configuration setting
topic in the Oracle Essbase Technical Reference.
Another aspect of parallel data load refers to the concurrent loading of multiple data files into
an Essbase database. When working with large data sets (for example, a set of ten 2 GB files),
loading the data sources concurrently enables you to fully utilize the CPU resources and I/O
channels of modern servers with multiple processors and high-performance storage subsystems.
You can also adjust the number of threads used in multiple-file data loads. For example,
specifying the above configuration while also specifying two data files results in the creation of
two data load pipelines, each having 11 threads.
856
Specify multiple files as the data source, by using a wildcard character (* and/or ?) to match all data
sources files you intend to use. In the Oracle Essbase Technical Reference, see the MaxL import data
statement.
If necessary, control the number of threads spawned by the parallel data load.
Windows XP, use Control Panel, then Administrative Tools, and then Performance
Windows Server 2008, use Control Panel, then Administrative Tools, and then Reliability and
Performance Monitor
Windows 7, use Control Panel, then Administrative Tools, then Performance Monitor, and then
Resource Monitor
Among the tools available on UNIX are top and vmstat; iostat is the most commonly used
utility to monitor I/O activity. You can also use third-party tools to view and analyze system use.
thread specified by that setting uses an area in the data cache equal to the size of an expanded
block.
Depending on the size of the block, the number of threads, and how much data cache is used
by other concurrent operations during a data load, it may be possible to need more data cache
than is available. In such circumstances, decrease the number of threads or increase the size of
the data cache.
See Changing the Data Cache Size on page 828.
858
57
Optimizing Calculations
In This Chapter
Designing for Calculation Performance ................................................................ 859
Monitoring and Tracing Calculations ................................................................... 861
Using Simulated Calculations to Estimate Calculation Time......................................... 862
Estimating Calculation Effects on Database Size ..................................................... 866
Using Formulas........................................................................................... 866
Using Bottom-Up Calculation ........................................................................... 871
Hybrid Aggregation Mode in Block Storage Databases .............................................. 873
Managing Caches to Improve Performance ........................................................... 873
Working with the Block Locking System ............................................................... 874
Using Two-Pass Calculation ............................................................................. 876
Choosing Between Member Set Functions and Performance........................................ 883
Consolidating #MISSING Values........................................................................ 884
Removing #MISSING Blocks ............................................................................ 886
Identifying Additional Calculation Optimization Issues ............................................... 886
The information in this chapter applies only to block storage databases and is not relevant to
aggregate storage databases.
Also see:
l
859
Run test calculations of the most promising configurations of a database that contains
representative data. Check results to determine the configuration that produces the best
calculation performance.
You can view information about a database, including the potential and actual number of data
blocks and the data block size.
Topic
Location
Administration Services
ESSCMD
GETDBINFO
860
To optimize calculation performance when you load data incrementally, make the dimension
tagged as time a sparse dimension. If the time dimension is sparse, the database contains a data
block for each time period. When you load data by time period, Essbase accesses fewer data
blocks because fewer blocks contain the relevant time period. Thus, if you have Intelligent
Calculation enabled, only the data blocks marked as dirty are recalculated. For example, if you
load data for March, only the data blocks for March and the dependent parents of March are
updated.
However, making the time dimension sparse when it is naturally dense may significantly increase
the size of the index, creating possibly slower performance due to more physical I/O activity to
accommodate the large index.
If the dimension tagged as time is dense, you still receive some benefit from Intelligent
Calculation when you do a partial data load for a sparse dimension. For example, if Product is
sparse and you load data for one product, Essbase recalculates only the blocks affected by the
partial load, although time is dense and Intelligent Calculation is enabled.
For information on incremental loads, see Loading Data into Aggregate Storage Databases on
page 954.
861
Display calculation settings, for example, whether completion notice messages are enabled
Provide statistics on the number of data blocks created, read, and written
SET MSG DETAIL also provides an information message every time Essbase calculates a data
block. SET MSG DETAIL is useful for reviewing the calculation order of data blocks and for
testing intelligent recalculations.
Caution!
Because SET MSG DETAIL causes a high processing overhead, use it only during
test calculations.
SET NOTICE
You can use the SET NOTICE calculation command in a calculation script to display calculation
completion notices that tell you what percentage of the database has been calculated. You can
use the SET MSG SUMMARY command with the SET NOTICE command to show calculation
progress between completion notices. Completion notices do not significantly reduce
calculation performance, except when used with a very small database.
862
were two messages total, then you would know that the real calculation will take approximately
60 seconds (20 / 10 * 30 = 60 seconds).
Use the following topics to learn how to perform a simulated calculation and how to use a
simulated calculation to estimate calculation time.
Create a data model that uses all dimensions and all levels of detail about which you want information.
Load all data. This procedure calculates only data loaded in the database.
If you are using dynamic calculations on dense dimensions, substitute the CALC ALL
command with the specific dimensions that you need to calculate; for example, CALC DIM
EAST.
Note: If you try to validate the script, Essbase reports an error. Disregard the error.
Find the first sparse calculation message in the application log and note the time in the message.
Calculate the dense dimensions of the model that are not being dynamically calculated:
CALC DIM (DENSE_DIM1, DENSE_DIM2, );
Project the intervals at which notices will occur, and then verify against sparse calculation results. You
can then estimate calculation time.
Note the times of all the intervals between application log messages generated by SET NOTICE HIGH.
863
Use the following calculation to estimate the time for a real calculation:
Total time required for simulated calculation, divided by the first simulated calculation
notice interval, multiplied by the first real calculation time interval.
Table 179
45
10
43
In this example, 43 / 7 * 45 = 276.4 seconds, so the real calculation should take 276.4 seconds.
When these factors are present, this estimating technique more closely predicts calculation time
when Essbase reaches 30%40% of the simulated calculations (30%40% of the messages
generated by SET NOTICE HIGH). See the Oracle Essbase Technical Reference.
2. The rate at which Essbase writes blocks to the disk differs, therefore
3. The rate at which blocks are processed in the cache differs, therefore
4. Actual results may differ from the predicted calculation time.
The model contains one or two sparse dimensions that are large in relation to the other
sparse dimensions.
Larger dimensions have member configurations that result in multiple shared roll-ups.
For example:
l
Use the simulated calculation to generate the upper block count. These numbers may be accurate
despite actual dimension sizes as noted next to the items above.
Caution!
865
To estimate the database size resulting from a calculation using interactive mode:
1
Load data and issue a CALC ALL command and note the average block size.
Start the MaxL shell, log on to Essbase, and start an application and database. For example:
essmsh
login username password;
alter system load application appname;
alter application appname load database dbname;
Providing the application and database name, enter the following MaxL statement and note the value
that is returned for the number of blocks:
query database appname.dbname get estimated size;
Multiply the number of blocks by the average size of the blocks in the database.
You must perform this query after a CALC ALL. Any other calculation will not produce
accurate results.
You can obtain accurate results with formulas only if they are on sparse dimensions.
You cannot obtain accurate results with top-down calculations on any member in
combination with a lock on data (committed access).
If you need to estimate partitions, you must query Essbase for a database size estimate on
every partition and add the results. If you query for the size of only the source database, the
estimate includes only the data on the source database server.
Using Formulas
You may achieve significant improvements in calculation performance by carefully using
formulas in the database outline. For example, you may achieve improved calculation
performance by placing formulas on members in the database outline instead of placing the
formulas in a calculation script. See Chapter 23, Developing Formulas for Block Storage
Databases.
The following sections discuss how to handle formula issues that affect performance.
Consolidating
Using the database outline to roll up values is more efficient than using a formula to calculate
values. For example, the consolidation of members 100-10, 100-20, and 100-30 into member
866
100, as shown in Figure 151, is more efficient than applying the following formula to member
100:
100-10 + 100-20 + 100-30
Figure 151
Consolidation Example
Does not reference values from a different dimension (sparse or dense). For example, a
simple formula cannot reference Product -> Jan.
Does not use range functions. For example, a simple formula cannot use @AVGRANGE,
@MAXRANGE, @MINRANGE, or @SUMRANGE.
Does not use relationship or financial functions. For example, a simple formula cannot use
@ANCESTVAL, @NEXT, @PARENTVAL, @SHIFT, @ACCUM, or @GROWTH. For a
complete list of relationship and financial functions, see the Oracle Essbase Technical
Reference.
For information on how formulas affect calculation performance, see Bottom-Up and TopDown Calculation on page 872.
867
When applied to sparse dimension members, complex formulas create more calculation
overhead and therefore slow performance. This problem occurs because the presence of complex
formulas requires Essbase to perform calculations on all possible as well as all existing data blocks
related to the member with the complex formula. The presence of a relationship or financial
function on a sparse dimension member causes Essbase to perform calculations on all blocks,
possible as well as existing, increasing the overhead even more.
Thus, a complex formula that includes a relationship or financial function creates a greater
overhead increase than does a complex formula that does not include a relationship or financial
function.
For a discussion about how complex formulas affect calculation performance, see Bottom-Up
and Top-Down Calculation on page 872.
Two examples illustrate complex formula overhead:
l
If a database has 90 existing data blocks and 100 potential data blocks, the overhead for
complex formulas is not large, not more than 10 extra blocks to read and possibly write
values to.
If a database has 10 existing data blocks and 100 potential data blocks, the overhead is as
much as ten times what it would be without the complex formula (depending on the outline
structure and other factors), as many as 90 extra blocks to read and possibly write to.
In all cases, the lower the ratio of existing data blocks to possible data blocks, the higher the
calculation performance overhead and the slower the performance.
868
In this formula, California is a member in a sparse dimension and 120 is a constant value. Essbase
automatically creates all possible data blocks for California and assigns the value 120 to all data
cells. Many thousands of data blocks may be created. To improve performance, create a formula
that does not create unnecessary values.
To assign constants in a sparse dimension to only those intersections that require a value, use
FIX in a manner similar to the following example:
FIX(Colas,Misc,Actual)
California = 120;
ENDFIX
In this example, Colas is a member of the sparse dimension, Product; Actual is a member of the
dense dimension, Scenario; and Misc is a member of the dense dimension, Measures. The value
120 is assigned to any intersection of California (in the Market dimension), Actual (in the
Scenario dimension), Misc (in the Measures dimension), Colas (in the Product dimension), and
any member in the Year dimension, because a specific member of Year is not specified in the
script.
Because Sample.Basic includes only two sparse dimensions, this example affects only one block.
If more sparse dimensions existed, Essbase would ensure data blocks for all combinations of the
sparse dimensions with California and Colas, creating blocks if necessary. Within the new blocks,
Essbase sets Measures and Scenario values (other than those assigned the value 120) to
#MISSING.
Unneeded blocks may be created for all sparse-member intersections with West, even if the
corresponding block value is #MISSING for all of the children of West. Especially in a large
database, creation and processing of unneeded blocks requires additional processing time.
869
To control creation of blocks when you assign nonconstant values to members of a sparse
dimension, use the SET CREATEBLOCKONEQ ON | OFF calculation command, as shown in
the following script:
FIX (Colas);
SET CREATEBLOCKONEQ
West = California +
SET CREATEBLOCKONEQ
East = New York +
ENDFIX
OFF
120;
ON
100;
Because the Create Block on Equation setting is disabled at the beginning of the script, West
blocks are created only when values exist for the children of West. Later, because the Create
Block on Equation setting is enabled, all blocks for East are created.
Note: Using SET CREATEBLOCKONEQ affects only creation of blocks during the execution
of the calculation script that contains this command. This command does not change the
overall database setting for Create Blocks on Equations.
With the FIX command, Essbase calculates the formula only for specified member combinations,
in this example, for combinations that include Jan.
Compare this technique to using the slower cross-dimensional operator approach. For the
previous example, you place the following formula on the Sales member in the database outline:
Sales(Sales -> Jan = Sales -> Jan * .05;)
As Essbase cycles through the database, it calculates the formula for every member combination
that includes a member from the dimension tagged as time (Jan, Feb, Mar, and so on), although
only January combinations need to be calculated.
870
See Using the FIX Command on page 475 and the Oracle Essbase Technical Reference.
You can use the following techniques to create the blocks and avoid the performance issue.
l
Ensure that the results members are from a sparse dimension, not from a dense dimension.
In this example, the results member Budget is from a sparse dimension:
FIX(Sales)
Budget = Actual * 1.1;
ENDFIX
FIX(Expenses)
Budget = Actual * .95;
ENDFIX
Use the DATACOPY calculation command to create and then calculate the required blocks.
See Using DATACOPY to Copy Existing Blocks on page 481.
Use a member formula that contains the dense member equations:
FIX(Sales, Expenses)
Budget (Sales = Sales -> Actual * 1.1;
Expenses = Expenses -> Actual * .95;)
ENDFIX
871
To calculate the formula, Essbase must examine every combination of A to see whether B -> D
or C -> D exists.
See Using Complex Formulas on page 867.
872
Location
Calculation function
@CALCMODE in a formula
SET FRMLBOTTOMUP
CALCOPTFRMLBOTTOMUP
or
CALCMODE
Forcing a bottom-up calculation on a formula usually increases performance time. If the formula
contains complex functions (for example, range functions) or if the formula's dependencies are
not straightforward, a bottom-up calculation may produce results different from those of a topdown calculation.
Caution!
873
Note: You can avoid excess memory use by combining calculation scripts. You can obtain good
performance by using parallel calculation with a single calculation script. See Chapter 31,
Using Parallel Calculation..
Essbase uses memory to optimize calculation performance, especially for large calculations. The
amount of memory used is not controllable, except by altering the size of the database outline.
However, you can ensure that the memory cache sizes enable Essbase to optimize the calculation.
Essbase uses memory caches to coordinate memory usage:
l
Calculator cache. Ensure that the calculator cache is large enough to optimize calculation
performance.
Dynamic calculator cache.
Index cache. If the database is large, the default index cache is not large enough to provide
optimum calculation performance.
Data cache.
Application cache. If hybrid aggregation mode is used in block storage databases, the
application cache can help you manage memory usage for retrievals. The application cache
is similar to the aggregate storage cache; for more information, see Managing the Aggregate
Storage Cache on page 1025.
Note: When you first calculate a database, the size of the calculator cache is significant for
calculation performance. If possible, ensure that the calculator cache is large enough for
Essbase to use the optimal calculator cache option.
See Sizing Caches on page 824. Read the entire topic before making changes.
874
Note: For consolidations in a sparse dimension, block locking is not a consideration, because
Essbase does not need to lock all blocks containing children concurrently.
For the data block to be released if the isolation level setting is Uncommitted Access.
For the calculation to complete if the isolation level setting is Committed Access.
Essbase does not provide a message to say that the calculation is waiting for the data block to be
released.
You can prevent calculation delays caused by waiting for locked blocks by using Essbase security
options to do either of the following:
l
For information on how Essbase handles locks and transactions, see Understanding How
Essbase Handles Transactions on page 783 and Data Locks on page 778.
Note: When Essbase locks a block for calculation, it does not put an exclusive lock on the
dependent child blocks, so another user can update values in the child blocks. If necessary,
you can use the above security options to prevent such updates.
875
Assume that Table 180 shows a subset of a data block with Measures and Year as dense
dimensions. Measures is tagged as accounts, and Year is tagged as time. The AGGMISSG
configuration setting is turned off (the default).
Data values have been loaded into the input cells. Essbase calculates the cells in which the
numbers 1 through 7 appear, in that order. For example, Profit % -> Jan is calculated first; Profit
% -> Qtr1 has multiple consolidation paths.
Table 180
Jan
Feb
Mar
Qtr1
Profit
75
50
120
Sales
150
200
240
876
Jan
Feb
Mar
Qtr1
Profit%
4, 7
Note: For information on how cell calculation order depends on database configuration, see
Measures/Year
Jan
Feb
Mar
Qtr1
Profit
75
50
120
245 (5)
Sales
150
200
240
590 (6)
Profit%
50% (1)
25% (2)
50% (3)
0% (4)
125% (7)
4. If you tag Profit% as two-pass in the database outline, Essbase uses the Profit % Sales
formula to recalculate the Profit% values and produce the correct results.
Table 182
Measures/Year
Jan
Feb
Mar
Qtr1
Profit
75
50
120
245 (5)
Sales
150
200
240
590 (6)
Profit%
50% (1)
25% (2)
50% (3)
0% (4)
125% (7)
42% (8)
For information about multiple calculation passes, see Calculation Passes on page 408.
877
Scenario A
In this scenario, you place formulas in the outline and, as appropriate, tag specific formulas as
two-pass for best performance.
Scenario B
In this scenario, you create a calculation script to perform the formula calculation for best
performance.
878
When you recalculate the database with Intelligent Calculation turned on, these data blocks may
be recalculated unnecessarily.
If the database configuration allows Essbase to use Scenario B, consider using a calculation script
to perform two-pass formula calculations. If you use a calculation script, Essbase still does an
extra calculation pass through the database; however, you can ensure that Essbase has marked
all the data blocks as clean after the calculation. See Creating Calculation Scripts for Two-Pass
and Intelligent Calculation on page 880.
You can tag a member as two-pass if it is in a dimension tagged as accounts. When you
perform a default calculation on the database, Essbase automatically recalculates any
formulas tagged as two-pass if they are in the dimension tagged as accounts in the database
outline.
You can tag a member as two-pass if it is a Dynamic Calc or Dynamic Calc and Store member
of any dimension. See Chapter 27, Dynamically Calculating Data Values.
You may need to use a calculation script to calculate a two-pass formula to obtain accurate
results, even if the two-pass tag would provide performance benefits. See Creating
Calculation Scripts for Two-Pass and Intelligent Calculation on page 880.
Use a calculation script instead of the two-pass tag to ensure efficient use of Intelligent
Calculation. See Understanding the Interaction of Two-Pass Calculation and Intelligent
Calculation on page 878.
You must use a calculation script to calculate a formula twice if the database configuration
means that Essbase uses Scenario A, as described in Scenario A on page 878, and if the
formula references values from another data block.
You may want to use a calculation script to calculate two-pass formulas if the database
configuration means that Essbase uses Scenario B, as described in Scenario B on page
878.
879
Topic
Location
Administration Services
MaxL
execute calculation
ESSCMD
CALCDEFAULT
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATE
Before the calculation script command that recalculates a two-pass formula, add the SET
UPDATECALC OFF command to disable Intelligent Calculation. If you have Intelligent
Calculation enabled (the default), Essbase calculates only the data blocks that are not marked
as clean, but when you perform a default calculation of the database with Intelligent
Calculation enabled, all data blocks are marked as clean, so Essbase does not perform the
two-pass formula recalculation.
When you use a calculation script, Essbase does not automatically recalculate two-pass
formulas. Use the CALC TWOPASS command.
If you have changed the default calculation of CALC ALL, and Intelligent Calculation is
enabled, the data blocks may not be marked as clean after the first calculation. See Chapter 26,
Understanding Intelligent Calculation. Also see Setting Default Calculations in the
Oracle Essbase Administration Services Online Help.
To obtain the performance benefits of Intelligent Calculation when performing the first, full
calculation of the database, use one of these methods, depending on the calculation needs and
outline structure:
l
The outline has a dimension tagged as accounts, and it is a dense dimension. You want to
calculate sales for each product as a percentage of sales for all products. Assume this formula
should calculate the dimension:
Sales % Sales -> Product
When Essbase calculates the data block for each product, it has not yet calculated the value Sales
-> Product, so the results for the sales of each product as a percentage of total sales are incorrect.
Place the formula on the appropriate member in the dimension tagged as accounts, in our example,
Share of Sales.
Create a calculation script that performs a full database calculation and then a two-pass calculation:
SET UPDATECALC ON;
CALC ALL;
SET UPDATECALC OFF;
881
Perform a full calculation, using any of the tools listed in Table 183 on page 882.
Use a calculation script similar to this example to disable Intelligent Calculation and calculate the
formula:
SET UPDATECALC OFF;
SET CLEARUPDATESTATUS AFTER;
"Share of Sales" = Sales % Sales -> Product;
or:
SET UPDATECALC OFF;
SET CLEARUPDATESTATUS AFTER;
CALC TWOPASS;
Table 183
Tool
Topic
Location
Administration Services
Calculating Databases
MaxL
execute calculation
ESSCMD
CALCDEFAULT
See Chapter 26, Understanding Intelligent Calculation, Chapter 23, Developing Formulas
for Block Storage Databases, and Chapter 29, Developing Calculation Scripts for Block Storage
Databases.
Create a calculation script to calculate the database, but tell Essbase not to mark the calculated data
blocks as clean.
Mark all data blocks as clean and do not recalculate the data blocks.
SET CLEARUPDATESTATUS OFF;
CALC ALL;
CALC TWOPASS;
SET CLEARUPDATESTATUS ONLY;
CALC ALL;
3
882
a. The SET CLEARUPDATESTATUS OFF command tells Essbase not to mark the
calculated data blocks as clean.
b. The first CALC ALL command causes Essbase to cycle through the database, calculating
all dirty data blocks. Essbase does not mark the calculated data blocks as clean. Essbase
does not automatically recalculate the formulas tagged as two-pass in the database
outline.
c. The CALC TWOPASS command causes Essbase to cycle through the database,
recalculating the formulas that are tagged as two-pass in the dimension tagged as
accounts in the database outline. Essbase recalculates the formulas because the required
data blocks are not marked as clean by the previous CALC ALL. Essbase does not mark
the recalculated data blocks as clean.
d. The SET CLEARUPDATESTATUS ONLY command tells Essbase to mark the data
blocks as clean but not to calculate the data blocks. This command disables calculation.
e. The last CALC ALL command causes Essbase to cycle through the database and mark
all the data blocks as clean. Essbase searches the index and marks the data blocks as clean.
It does not calculate the data blocks.
@CURRMBR
@PARENT
@SPARENTVAL
@ANCEST
@SANCESTVAL
883
If you are experiencing slow performance, consider either removing the dynamic calculation tag
or removing these functions from the attached formula.
Calculation/Operation
Result
X + #MISSING
X #MISSING
#MISSING X
-X
X * #MISSING
#MISSING
X / #MISSING
#MISSING
#MISSING / X
#MISSING
X/0
#MISSING
X % #MISSING
#MISSING
#MISSING % X
#MISSING
X%0
#MISSING
X == #MISSING
X != #MISSING
X <= #MISSING
(X <= 0)
X >= #MISSING
(X >= 0) or (X == #MISSING)
X > #MISSING
(X > 0)
X < #MISSING
(X < 0)
X AND #MISSING:
#MISSING
0 AND #MISSING
#MISSING
884
Calculation/Operation
Result
X OR #MISSING:
#MISSING
0 OR #MISSING
#MISSING
#MISSING OR #MISSING
IF (#MISSING)
IF (0)
f (#MISSING)
f (X)
#MISSING for any X not in the domain of f and any EssbaseEssbase function
of multiple variables (except where specifically noted)
By default, Essbase does not roll up #MISSING values. However, if you always load data at level
0 and never at parent levels, you should enable the setting for consolidating #MISSING values.
This setting provides a calculation performance improvement of 1%30%. The performance
improvement varies, depending on database size and configuration.
Caution!
The default, not consolidating #MISSING values, must be in effect if you load data
at parent, rather than child, levels, if any child member combinations have
#MISSING values. If all child member combinations have any other values, including
zero (0), Essbase rolls up the child values and overwrites the parent values correctly,
so you can safely change the default.
Topic
Location
Administration Services
Calculation script
SET AGGMISSG
MaxL
alter database
ESSCMD
SETDBSTATEITEM
Note: If you enable the setting for consolidating #MISSING values, the cell calculation order
within a data block changes. See Cell Calculation Order on page 402.
When the setting for consolidating #MISSING values is disabled, note that the performance
overhead is particularly high in the following situations:
885
When the ratio of calculated data blocks to input data blocks is low
When you load many data values at parent levels on sparse dimensions; for example, in the
Sample.Basic database, if you load many data values into East in a sparse Market dimension
Note: Removing empty blocks improves performance when data values already have been
loaded. However, data load process time increases if new values require that blocks be
created.
In Chapter 27, Dynamically Calculating Data Values, see the following topics:
m
Choosing Between Dynamic Calc and Dynamic Calc and Store on page 433
In Chapter 29, Developing Calculation Scripts for Block Storage Databases, see the
following topics:
m
For the relationship of two-pass calculation and the SET CLEARUPDATESTATUS command,
see the Oracle Essbase Technical Reference.
886
When you convert currencies using the CCONV command, the resulting data blocks are marked
as dirty for the purposes of Intelligent Calculation. This means that Essbase recalculates all the
converted blocks when you recalculate the database. See Chapter 26, Understanding Intelligent
Calculation.
887
888
58
In This Chapter
Changing Buffer Size..................................................................................... 889
Setting Numeric Precision............................................................................... 890
Generating Symmetric Reports ......................................................................... 891
Improving Retrieval Performance on Large Dimensions .............................................. 891
Organizing Members to Optimize Data Extraction..................................................... 892
Understanding Reports for Outlines That Contain Dynamic or Transparent Members ............. 892
Limiting LRO File Sizes................................................................................... 893
889
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATEITEM
Topic
Location
Administration Services
MaxL
alter database
ESSCMD
SETDBSTATEITEM
10010
10020
10030
100
Actual
Jan
Feb
======== ========
757
773
450
487
#MISSING #MISSING
1,207
1,260
Budget
Jan
Feb
======== ========
930
950
550
590
#MISSING #MISSING
1,480
1,540
With an asymmetric report, the Report Extractor must retrieve and process each block of possible
member combinations separately. In the following example, the data values (Actual Jan and
Budget Jan) are retrieved in two passes.
Asymmetric Report Member Combinations Requiring Multiple Passes
Sales South
10010
10020
10030
100
Actual
Jan
========
757
450
#MISSING
1,207
Budget
Jan
========
950
590
#MISSING
1,540
891
Creating the report script in the same order as Report Extractor extracts data
These strategies save the most time if used to create large production reports.
Report Extractor looks at data from bottom to top and right to left, starting from the bottom
column member to the top column member and proceeding from the innermost row member
(right) to the outermost row member (left).
In the following example, the column members come from dense dimensions and the row
members from sparse dimensions. The sequence in which the report is read is represented by
the numbers 13, which are in parentheses; for example, (1):
Sales South
(3) Actual
Jan
========
10010
757
10020
450
10030
#MISSING
100
1,207
Budget (2)
Jan (1)
========
950
590
#MISSING
1,540
To reduce the time to extract data, group dense dimensions first, then group sparse dimensions
in the sequence in which they are displayed in the outline.
When dense dimensions are nested in the report columns, Report Extractor examines each data
block only once, improving performance time.
Because attributes are sparse dimensions and are dynamically calculated, Essbase cannot use the
sparse data extraction method when a report contains attribute dimensions.
892
If you generate a report that accesses a database outline that contains Dynamic Calc or Dynamic
Time Series members, Essbase calculates the member every time a report is generated, increasing
the reporting time.
See Chapter 27, Dynamically Calculating Data Values.
If you run a report that contains transparent members, the report takes longer to generate,
because it must access multiple servers to retrieve the required data.
893
894
59
In This Chapter
About Running Essbase on Oracle Exalytics In-Memory Machine ................................... 895
Virtual Memory and Swap Space Considerations..................................................... 895
Increase in Page File Size when Essbase Runs on Oracle Exalytics In-Memory Machine ......... 895
The information in this chapter applies only to Essbase running on an Oracle Exalytics InMemory machine.
This setting must only be used when Essbase is deployed on the Exalytics In-Memory
machine. ORACLEHARDWAREACCELERATION is not supported and should
never be set to TRUE on deployments of Essbase on non-Exalytics In-Memory
machines.
Exalytics In-Memory machine, when blocks are created for the first time, Essbase adds a margin
to the compressed block size to account for future growth in the block as more dense data is
added. Therefore, the initial page file size on Exalytics will be slightly higher; however, this extra
allocation helps reduce fragmentation and the frequent need for restructuring.
896
Part X
897
898
60
In This Chapter
Introduction............................................................................................... 899
Inherent Differences ..................................................................................... 900
Outline Differences....................................................................................... 900
Calculation Differences .................................................................................. 902
Partitioning Differences.................................................................................. 902
Data Load Differences................................................................................... 903
Query Differences ........................................................................................ 903
Feature Differences ...................................................................................... 904
Hybrid Aggregation....................................................................................... 905
Introduction
Essbase provides an aggregate storage kernel as a persistence mechanism for multidimensional
databases. Aggregate storage databases enable dramatic improvements in both database
aggregation time and dimensional scalability. The aggregate storage kernel is an alternative to
the block storage kernel. Aggregate storage databases typically address read-only, rack and
stack applications that have large dimensionality, such as the following applications:
l
Customer analysis. Data is analyzed from any dimension, and there are potentially millions
of customers.
A sample application (ASOsamp), a data file, and a rules file are provided to demonstrate
aggregate storage functionality.
Aggregate storage applications, which differ from block storage applications in concept and
design, have limitations that do not apply to block storage applications. The following sections
describe the differences.
See also Hybrid Aggregation on page 905.
899
Inherent Differences
Table 185
Inherent Differences
Aggregate Storage
Block Storage
Storage kernel
Physical storage
definition
Create database
Note: Do not use the file system to copy a block storage outline
into an aggregate storage application. Use the migration wizard in
Administration Services to migrate the outline.
Copy database
Not supported
Supported
Databases supported
per application
One
Application and
database names
default
log
metadata
temp
Application and
database information
display
Configuration settings
(essbase.cfg)
Outline Differences
Table 186
Outline Functionality
Aggregate Storage
Block Storage
Dense or sparse
dimension designation
Not relevant
Relevant
900
Outline Functionality
Aggregate Storage
Block Storage
Multiple hierarchies
enabled, dynamic
hierarchy, or stored
hierarchy designation
Relevant
Irrelevant
Accounts dimensions
and members on
dynamic hierarchies
Full support
Members on stored
hierarchies
Full support
All dimension members at the same level as the member must be label only
Outline paging
Support
Support
When outline is
saved
No support
901
Outline Functionality
Aggregate Storage
Block Storage
Database restructure
Levels of restructure;
see Optimizing
Database
Restructuring on page
839
Calculation Differences
Table 187
Calculation
Functionality
Aggregate Storage
Block Storage
Database
calculation
Formulas
Calculation scripts
Not supported
Supported
Attribute
calculations
dimension
Calculation order
Partitioning Differences
Table 188
Partitioning Functionality
Aggregate Storage
Block Storage
Partitioning
Fully supported
No outline synchronization
902
Aggregate Storage
Block Storage
Only level 0 cells whose values do not depend on formulas in the outline
are loaded
Not supported
When loading data into an aggregate storage database, you can replace
the contents of the database or the contents of all incremental data
slices in the database
Not supported
Data slices
Not supported
In a date-time dimension, you can load data into level 0 members using
supported date-format strings instead of member names
Query Differences
Table 190
Query Functionality
Aggregate Storage
Block Storage
Report Writer
Fully supported
Smart View
Fully supported
API
Supported
Supported
Export
Supported
MDX queries
No columnar export
Supported
Supported
903
Query Functionality
Aggregate Storage
Block Storage
Query logging
Not supported
Supported
Query performance
Feature Differences
Table 191
Features
Aggregate Storage
Block Storage
Aliases
Supported
Supported
Currency conversion
Not supported
Supported
Supported
Supported
LROs
Not supported
Supported
Supported
Triggers
Unicode
Supported
Supported
Variance reporting
Not supported
Supported
Supported
Not supported
Supported
904
Hybrid Aggregation
Essbase hybrid aggregation combines block storage functionality with aggregate storage
performance. In hybrid aggregation mode, you retain the use of block storage elements while
enabling the use of more (and larger) sparse dimensions, while also reducing the database
footprint and improving performance.
In block storage databases, large, sparse dimensions must be stored: making them dynamic
would result in too much block I/O at query time, affecting performance. Very large stored sparse
dimensions can lead to lengthy batch aggregation times, as well as large database sizes that grow
in relation to the number and size of the sparse dimensions. Even with such drawbacks, block
storage is widely used for its powerful functionality.
Aggregate storage is designed specifically to enable large databases with more and larger
dimensions. Unlike block storage, it does not require large sparse dimensions to be preaggregated to achieve good query performance. The key lies in the aggregate storage query
processor, and in a bitmap index associated with every stored, level-0 cell. The bitmap index has
the information required for very fast retrievals and aggregations.
For all the benefits that aggregate storage offers, however, there are many applications that are
simply better suited to block storage. In such cases, hybrid aggregation might be the solution.
Hybrid aggregation is a combination of the best features of block storage and aggregate storage:
l
It enables the full block storage functionality of a block storage outline, utilizing calculation
order and calculation scripts.
It stores data in block storage data and index files.
It uses the aggregate storage query processor whenever possible. When there is a query that
the aggregate storage query processor cannot handle, the block storage query processor takes
over and accomplishes the task.
Note: The aggregate storage query processor does not interface directly with the block storage
data and index files; rather, it brings the data into an aggregate storage temporary
tablespace. Just as with aggregate storage mode, the temporary tablespace resides within
the aggregate storage cache to the largest extent possible, overflowing to the file system
only as needed. Aggregate storage-level performance is achieved whenever the aggregate
storage query processor is used. In some cases, hybrid aggregation query performance
may be even greater than the equivalent aggregate storage performance.
To get started with hybrid aggregation, follow these guidelines:
l
Read all content related to hybrid aggregation, in the Essbase documentation and Readme
files. Particularly, see the topic for the configuration setting ASODYNAMICAGGINBSO,
in the Oracle Essbase Technical Reference.
Set up a development environment, and migrate existing block storage applications to it.
905
906
Run test queries and examine the log, both before and after enabling hybrid aggregation.
This activity can reveal the extent to which the aggregate storage query processor was used,
and the benefits of hybrid mode that were gained.
If needed, optimize the application so that a greater percentage of queries can use the
aggregate storage query processor. For more information, see the section entitled Functions
Supported in Hybrid Aggregation Mode, in the Oracle Essbase Technical Reference.
61
In This Chapter
Introduction............................................................................................... 907
Process for Creating Aggregate Storage Applications ................................................ 907
Creating Aggregate Storage Applications, Databases, and Outlines ................................ 908
Developing Formulas on Aggregate Storage Outlines ................................................ 924
Using a Transparent Partition for Write-Back to Aggregate Storage Databases .................... 931
The information in this chapter applies to aggregate storage applications, databases, and outlines
and includes information on how these processes differ from block storage processes.
Also see:
l
Introduction
Aggregate storage applications and databases and block storage applications and databases differ
in concept and design. Some block storage outline features do not apply to aggregate storage.
For example, the concept of dense and sparse dimensions does not apply. See Chapter 60,
Comparison of Aggregate and Block Storage.
A new sample application (ASOsamp), a data file, and a rules file are provided to demonstrate
aggregate storage functionality.
907
Convert a block storage outline to an aggregate storage outline, and then create an aggregate
storage application to contain the converted database and outline.
Essbase supports the following scenarios for converting block storage outlines to aggregate
storage outlines:
m
908
Create an aggregate storage application and database. The aggregate storage outline is created
automatically when you create the database.
For information on loading dimensions and members into an aggregate storage outline, see
Building Dimensions in Aggregate Storage Databases on page 949 and Loading Data into
Aggregate Storage Databases on page 954.
Aggregate storage application and database information differs from block storage information,
and specific naming restrictions apply to aggregate storage applications and databases. See
Table 185.
Topic
Location
Administration Services
MaxL
Note: Do not use the file system to copy a block storage outline into an aggregate storage
Topic
Location
Administration Services
Creating Applications
Creating Databases
MaxL
create application
create database
When creating aggregate storage applications, databases, and outlines, consider the differences
between aggregate storage and block storage and issues specific to aggregate storage. See the
following sections, and also see Chapter 62, Aggregate Storage Time-Based Analysis.
Hierarchies
In aggregate storage outlines and block storage outlines, dimensions are structured to contain
one or more hierarchies of related levels and members within the levels. For example, the Time
dimension in the ASOsamp.Sample database includes the hierarchies MTD, QTD, and YTD, as
shown in Figure 152.
909
Figure 152
Stored
Dynamic
The two types of hierarchies have different advantages and restrictions. A dimension may contain
both types of hierarchies. To use multiple hierarchies in a dimension (even if they are all stored
hierarchies), you must enable multiple hierarchies for that dimension.
To enable multiple hierarchies for a dimension, tag the dimension member as multiple
hierarchies enabled using a tool:
Tool
Topic
Location
Administration Services
MaxL
import database
When you tag a dimension member as multiple hierarchies enabled, it is automatically tagged
label only.
If you do not tag the dimension as multiple hierarchies enabled, Essbase automatically tags the
dimension as a stored hierarchy (except the dimension tagged as Accounts, which is
automatically tagged as a dynamic hierarchy).
Note: The first hierarchy in a multiple hierarchies enabled dimension must be a stored hierarchy.
Stored Hierarchies
Members of stored hierarchies are aggregated according to the outline structure. Because
aggregate storage databases are optimized for aggregation, the aggregation of data values for
stored hierarchies is very fast. To allow this fast aggregation, members of stored hierarchies have
the following restrictions:
l
910
Stored hierarchies can have the no-consolidation (~) operator (only underneath label only
members) or the addition (+) operator.
Stored hierarchies have restrictions on label only members. See Table 186 on page 900.
In Figure 153 on page 913, the All Merchandise hierarchy and the High End Merchandise
hierarchy are stored hierarchies. The All Merchandise member and the High End Merchandise
member are the tops of the hierarchies and are both tagged as top of a stored hierarchy.
To specify a stored hierarchy, tag the top member of the hierarchy as top of a stored hierarchy
using a tool:
Tool
Topic
Location
Administration Services
MaxL
import database
The dimension tagged as accounts is automatically considered a dynamic hierarchy. You cannot
specify the accounts dimension as a stored hierarchy.
Dynamic Hierarchies
To evaluate a dynamic hierarchy, Essbase calculates, rather than aggregates, the members and
formulas. The order in which members and formulas are evaluated is defined by the solve order
property. See Calculation Order on page 971.
At the time of retrieval, Essbase calculates the required member combinations and calculates
any required outline member formulas. Because dynamic hierarchies are calculated, the data
retrieval time may be longer than for data retrieved from stored hierarchies. However, when you
design your database, dynamic hierarchies provide the following advantages:
l
911
To specify a dynamic hierarchy, tag the top member of the hierarchy as top of a dynamic
hierarchy using a tool:
Tool
Topic
Location
Administration Services
MaxL
import database
Note: If a member has the no-consolidation operator (~) on all its children, the member must
Alternate Hierarchies
An alternate hierarchy may be modeled in either of the following ways:
l
As an attribute dimension, which uses attributes to classify members logically within the
dimension (for example, a Product dimension can have attributes such as Size and Flavor).
See Chapter 10, Working with Attributes.
Note: If you use an attribute dimension to create an alternate hierarchy, you can create a
crosstab report query of members in the attribute dimension with members in the
base dimension. For example, a crosstab report of product sales information could
show size attributes (such as small and large) as column headings and products as
row headings. If you use shared members to create an alternate hierarchy, you cannot
create an equivalent crosstab report query of the shared members with the nonshared
members in the primary hierarchy.
l
912
As a hierarchy of shared members. The alternate hierarchy has shared members that refer
to nonshared members of previous hierarchies in the outline. The shared members roll up
according to a different hierarchy from the nonshared members to which they refer. Shared
members on dynamic hierarchies can have formulas. See Understanding Shared Members
on page 149. Table 192 shows the hierarchies for the ASOsamp.Sample database. The
Products dimension is shown in Figure 153 on page 913.
Table 192
Example Hierarchies and Alternate Hierarchies for the Product Dimension of ASOsamp.Sample
Product
Hierarchy
Flat Panel
HDTV
Figure 153
Aggregate Storage Outline Displaying the Alternate Hierarchy High End Merchandise on the Product Dimension
The following restrictions apply when creating alternate hierarchies in aggregate storage outlines:
l
The nonshared instance of the member must occur in the outline before any shared instances
of the member. For example, in Figure 153, the member HDTV occurs in the All
Merchandise hierarchy before it occurs as a shared member in the alternate hierarchy of
High End Merchandise.
The first hierarchy in a dimension where multiple hierarchies are enabled cannot contain a
shared member.
Stored hierarchy dimensions cannot have shared members. Stored hierarchies within a
multiple hierarchies dimension can have shared members.
To ensure that values are not double-counted, a stored hierarchy cannot contain multiple
copies of the same shared member. For example, a stored hierarchy cannot contain a shared
member and any of its ancestors. In Figure 153 on page 913, you cannot add the shared
member Televisions as a child of High End Merchandise, because doing so would make
Televisions a sibling of its children, shared members Flat Panel and HDTV, causing
the values of Flat Panel and HDTV to be added twice.
913
Nonshared instances of a member must be in the same dimension as the shared member
(same for block storage outlines).
A stored hierarchy cannot contain a nonshared instance and a shared instance of the same
member.
A stored hierarchy can contain a shared instance of a dynamic hierarchy member only if the
dynamic hierarchy member is a level 0 member without a formula.
Note: In an aggregate storage database, a shared member automatically shares any attributes
that are associated with its nonshared member. This also applies to an implied shared
member (for example, a member that has only one child). See Understanding Implied
Sharing on page 152. You can prevent implied sharing by setting the Never Share
property; see Determining How Members Store Data Values on page 147. This behavior
of shared members and attributes in aggregate storage databases is different from the
behavior in block storage databases.
Attribute Dimensions
This topic provides information on the differences between aggregate storage and block storage
databases with regard to attribute dimensions. To use the information in this topic, you should
be familiar with attribute dimension concepts for block storage databases. See Chapter 10,
Working with Attributes.
The following information applies to attribute dimensions when used on aggregate storage
databases:
l
Only the addition (+) consolidation operator is available for attribute dimensions.
For a given attribute dimension, all associations must be with one level of the base dimension.
For example, in the ASOsamp.Sample database, associations for the Store Manager attribute
dimension are with level 0 of the Stores dimension. The following restrictions apply to
attribute associations:
m
Level 0: You can associate attributes with any level 0 member of a dynamic or stored
hierarchy that does not have a formula.
Non-level 0: You can associate attributes only to upper level members in the primary
stored hierarchy.
Attribute dimensions do not have hierarchy types. You cannot specify an attribute dimension
as a dynamic or stored hierarchy. Essbase treats attribute dimensions as stored alternate
hierarchies of the base dimension. For example, in the ASOsamp.Sample database, Essbase treats
the Store Manager attribute dimension as if the Store Manager dimension were a stored alternate
hierarchy of the Stores dimension.
When using query tracking, Essbase considers queries on attribute dimension data and may
include attribute dimension members in aggregate view selections. See Selecting Views Based
on Usage on page 980 and Calculating Aggregate Storage Databases on page 969.
914
Note: Queries on attribute members that are associated with non-level 0 members return values
for descendants of the non-level 0 member. This behavior of queries on attribute members
in aggregate storage databases is different from the behavior in block storage databases.
Query involves any member of the base dimension and members from
multiple attribute dimensions.
Query involves any child member of the base dimension member (or
dimension member that is tagged as label-only) and members from
one attribute dimension.
In the outline displayed in Figure 154 on page 916, RealDimension is the sum of all its
descendents (it is not tagged as label-only). If a query involves one or more members from a
single attribute dimension (for example, AttributeDimension1), crossed with the base
dimension member (RealDimension), Essbase can build aggregate cells for the data, potentially
improving query performance.
The following queries, however, are always calculated at the time of retrieval:
l
Any query requesting data for members from an attribute dimension (for example
AttributeDimension1) and any of the children of RealDimension is calculated dynamically
at retrieval time based on the level 0 input data or on data from aggregations.
Any query requesting data from multiple attribute dimensions (for example
AttributeDimension1 and AttributeDimension2) and a base member dimension (for
example RealDimension) is calculated dynamically at retrieval time based on level 0 input
data.
915
Figure 154
Minimize the number of hierarchies. (For example, each additional stored hierarchy slows
down view selection and potentially increases the size of the aggregated data).
If a hierarchy is a small subset of the first hierarchy, consider making the small hierarchy a
dynamic hierarchy. Considerations include how often the hierarchy data is queried and the
query performance impact when it is dynamically queried at the time of retrieval.
The performance of attributes is the same as for members on a stored hierarchy.
The higher the association level of an attribute to the base member, the faster the retrieval
query. (See also, Design Considerations for Attribute Queries on page 915).
916
For the purposes of member numbering, attribute dimensions are treated as alternate hierarchies
of their base dimensions.
In general, the formula to determine the number of bits required for any member in a dimension
can be expressed as:
#_bits_members_parent + log(x)
The top member of a dimension or hierarchy usually uses 0 bits. However, when one or more
top generations consist of label-only members, the label-only members do not receive member
numbers (because they are not considered stored members). Therefore, if there are x members
in the first non-label-only generation, those members use log(x) bits. The rest of the children
below them are numbered normally.
Similarly, if a dimension or hierarchy is dynamic, only the level 0 members that are stored or
shared receive member numbers. The number of bits required for those members is log(x),
where x is the number of level 0 members that are stored or shared (that is, the number of level
0 members that are not formula members).
If, however, any alternate hierarchies have stored (non-shared) level 0 members, each member
of every hierarchy in the dimension (including associated attribute dimensions) uses an extra
log(x) bit, where x is the total number of hierarchies and associated attribute dimensions for this
base dimension.
The following example uses the Products dimension in the ASOsamp.Sample database:
The Products dimension has two hierarchies: All Merchandise and High End Merchandise,
which is an alternate hierarchy. High End Merchandise has one stored level 0 member: Stored
Member. The Products dimension does not have any associated attribute dimensions.
Members All Merchandise and High End Merchandise use log(2) = 1 bit.
917
Note: If the alternate hierarchy High End Merchandise did not have any stored level 0 members,
the top members of each hierarchy (and associated attribute dimensions) would each use
0 bits.
The calculation of the number of bits required by each level 0 children:
All Merchandise = 1 bit
Personal Electronics, Home Entertainment, Other = 1 + log(3) = 3 bits
Digital Cameras/Camcorders, Handhelds/PDAs, Portable Audio = 3 + log(3) = 5
Children of Digital Cameras/Camcorders = 5 + log(3) = 7
Children of Handhelds/PDAs = 5 + log(3) = 7
Children of Portable Audio = 5 + log(2) = 6
Televisions, Home Audio/Video = 3 + log(2) = 4
Children of Televisions = 4 + log(5) = 7
Children of Home Audio/Video = 4 + log(4) = 6
Computers and Peripherals = 3 + log(1) = 3 **
Systems, Displays, CD/DVD drives = 3 + log(3) = 5
Children of Systems = 5 + log(2) = 6
High End Merchandise = 1 bit
Flat Panel, HDTV, Stored Member = 1 + log(3) = 3 bits
Member Computers and Peripherals has the same number of bits (3) as its parent Other.
The maximum bits used by any level 0 children in the Products dimension is 7 (Children of
Digital Cameras and Children of Televisions). Therefore, Products uses 7 bits, which is less than
the dimension size limit of 64 bits.
If the dimension size exceeds 64 bits:
l
Essbase logs messages similar to the following messages in the application log:
Member
Member
Member
Member
Member
918
If possible, delete some siblings of any of the members referenced in the messages. Reducing
the number of siblings by a power of two saves one bit. For instance, assume that
level0member, which contributes 5 bits to the member number, has 18 siblings, including
itself. Reducing the number of siblings to 16 or fewer saves one bit because log(16) = 4.
Similarly, reducing the number of siblings to 8 or fewer saves two bits.
Reclassify some siblings of members referenced in the messages. For example, move half of
level0members 18 siblings to another parent that doesnt have as many children. Alternately,
create a new parent as a sibling of level1parent and move half of level1parents children
under the new member. This approach saves one bit.
Combine some intermediate levels. For instance, move level0member, and all of its siblings,
to be children of level2parent and then remove level1parent. This approach is more involved
but it can save many bits.
In the Aggregate Storage Statistics area, the number of levels and bits used in each dimension
is displayed.
919
To view the expected level 0 size of the database for each dimension when hypothetically
tagged as compression, and to choose a compression dimension:
See Selecting a Compression Dimension for Aggregate Storage in the Oracle Essbase
Administration Services Online Help.
l
l
l
l
In Administration Services and in MaxL, you can view detailed compression and query statistics.
You can view the number of stored level 0 members, which affects retrieval performance; the
average bundle fill and average value length, which affect compression; and the level 0 size.
Topic
Location
Administration Services
MaxL
The following sections describe each of the compression and query related statistics.
920
Verifying Outlines
Aggregate storage outline files have the same file extension (.otl) as block storage database
outline files and are stored in an equivalent directory structure. When you save an outline,
Essbase verifies it for errors. You can also verify the accuracy of an outline before you save it.
Some block storage database features do not apply to aggregate storage databases, and the
verification process considers the rules for aggregate storage databases. See Chapter 60,
Comparison of Aggregate and Block Storage.
921
Outline Paging
Aggregate storage database outlines are pageable. This feature may significantly reduce memory
usage for very large database outlines. For aggregate storage databases, Essbase preloads part of
the database outline into memory. Then, during data retrieval, Essbase pages other parts of the
outline into memory as required.
When you create an aggregate storage database, the outline is created in a pageable format. When
you use the Aggregate Storage Outline Conversion Wizard to convert an existing block storage
outline to aggregate storage, the outline is automatically converted to a pageable format.
Paging an outline into memory enables Essbase to handle very large outlines (for example, 10
million or more members) but potentially increases data retrieval time.
Note: Aggregate storage databases that have pageable outlines contain memory pages, and
therefore their outline files may be larger than binary block storage database outline files.
The amount of memory required for each member (and aliases for each member)
Table 194 shows the amount of addressable memory available for Essbase on supported 32-bit
operating systems:
Table 194
Operating System
Addressable Memory
3 GB
Requires a setting in the boot.ini file
AIX
3.25 GB
Up to 13 (256 MB) segments. Requires setting the LDR_CNTRL environment variable to:
0xD0000000@DSA
HP-UX
2.9 GB
Requires using the following command to set the addressable memory for the Essbase server process, ESSSVR:
chatr +q3p enable ESSSVR
Redhat Linux
Solaris
Essbase uses about 40 MB of memory on startup. In addition, the various caches require the
following memory allocations:
922
Therefore, the initial memory footprint for Essbase is about 90 MB. In addition, memory must
be allocated to process incoming query requests. Typical memory to reserve for this purpose is
about 300 MB. The total memory allocated for Essbase is therefore 390 MB.
On a Windows system with 1.85 GB of addressable memory, the amount available to build and
load the outline is about 1.46 GB (1.85 GB - 390 MB = 1.46 GB).
The maximum outline size depends on whether it is built using a dimension build or from an
outline already loaded into Essbase.
923
Assuming 1.46 GB of available memory, the maximum size of an outline that can be loaded is
one with 14 million members (1.46 GB / 105 bytes).
The 14 million members are the sum of two outlines that are loaded during restructuring. For
example, if an existing outline has 5 million members, the new outline can have a maximum of
9 million members. In an incremental dimension build, it is recommended to build the smaller
dimensions first and the larger ones last to allow for a maximum outline size.
in the outline file is marked as deleted but the record remains in the outline file.
Compacting the outline file does not remove the records of deleted members.
Topic
Location
Administration Services
MaxL
alter database
Essbase provides a native calculation language (the Calc language, or Calc) to write formulas
on block storage outlines. To write formulas for aggregate storage outlines, the MDX
(Multidimensional Expressions) language is required.
Apply formulas directly to members in the database outline. For block storage databases,
formulas can be placed in a calculation script. For aggregate storage databases, you cannot
place formulas in a calculation script.
The current chapter concentrates on using MDX to write formulas on aggregate storage
databases. For information about using MDX to write queries, see Chapter 36, Writing MDX
Queries. For information about writing formulas for block storage outlines, see Chapter 23,
924
Developing Formulas for Block Storage Databases. Also see the MDX section of the Oracle
Essbase Technical Reference.
Calculates a value
A numeric value expression is different from a set expression. A set expression is used on query
axes and describes members and member combinations. A numeric value expression specifies
a value.
A numeric value expression is used in queries to build calculated members, which are logical
members created for analytical purposes in the WITH section of the query, but which do not
exist in the outline.
The following query defines a calculated member and uses a numeric value expression to provide
a value for it:
WITH MEMBER
[Measures].[Prod Count]
AS
'Count (
Crossjoin (
{[Units]},
{[Products].children}
)
)', SOLVE_ORDER=1
SELECT
{[Geography].children}
ON COLUMNS,
{
Crossjoin (
{[Units]},
{[Products].children}
),
([Measures].[Prod Count], [Products])
}
ON ROWS
FROM
ASOsamp.Sample
In the sample query, the WITH clause defines a calculated member, Product Count, in the
Measures dimension, as follows:
WITH MEMBER
[Measures].[Prod Count]
925
The numeric value expression follows the WITH clause and is enclosed in single quotation
marks. In the sample query, the numeric value expression is specified as follows:
'Count (
Crossjoin (
{[Units]},
{[Products].children}
)
)'
The SOLVE_ORDER property specifies the order in which members and formulas are evaluated.
See Calculation Order on page 971.
Note: For an explanation of the syntax rules used to build the numeric value expression in the
example, see the documentation in the Oracle Essbase Technical Reference for the Count,
CrossJoin, and Children functions.
A numeric value expression also can be used as an MDX formula to calculate the value of an
existing outline member.
Therefore, rather than creating the example query, you can create an outline member on the
Measures dimension called Prod Count that is calculated in the outline in the same way that the
hypothetical Prod Count was calculated in the sample query.
Create a member.
Assuming that you created the example Prod Count member, you would use the following
formula, which is the equivalent of the numeric value expression used to create the calculated
member in the example query:
Count(Crossjoin ( {[Units]}, {[Products].children}))
When you retrieve data from the aggregate storage database, the formula is used to calculate
the member value.
You can use substitution variables within formulas. For example, you could define a
substitution variable named EstimatedPercent and provide different percentages as
substitution variable values. See Using Substitution Variables on page 120.
Before applying formulas to members in the outline, you can write MDX queries that contain
calculated members. When you can write an MDX query that returns the calculated member
results that you want, you are ready to apply the logic of the numeric value expression to an
outline member and validate and test the expression. See Chapter 36, Writing MDX
Queries. For syntax information about MDX, see the Oracle Essbase Technical Reference.
926
database members with MDX formulas are dynamically calculated. The dynamically
calculated members have a value of #MISSING until they are queried.
Enclose member names in brackets ([]) if they meet any of the following conditions:
m
Start with a number or contains spaces; for example, [100]. Brackets are recommended
for all member names, for clarity and code readability.
Are the same as an operator or function name. See the Oracle Essbase Technical
Reference for a list of operators and functions.
Include a nonalphanumeric character; for example, a hyphen (-), an asterisk (*), or a
slash (/).
Note: In formulas, member names starting with $ or & must be enclosed in quotation marks
as well as brackets. For example, $testmember would be expressed in the formula
as ["$testmember"]/100
l
Use the IIF function to write conditional tests with a single else condition. The syntax for
the IIF function does not require an ELSEIF keyword to identify the else condition nor an
ENDIF keyword to terminate the statement. You can nest IIF functions to create a more
complex formula.
Use the CASE, WHEN, THEN construct to write conditional tests with multiple conditions.
Be certain that tuples are specified correctly. A tuple is a collection of members with the
restriction that no two members can be from the same dimension. Enclose tuples in
parentheses; for example, (Actual, Sales).
Be certain that sets are specified correctly. A set is an ordered collection of one or more
tuples. When a set has multiple tuples, the following rule applies: In each tuple of the set,
members must represent the same dimensions as do the members of other tuples of the set.
Additionally, the dimensions must be represented in the same order. In other words, all
tuples of the set must have the same dimensionality.
See Rules for Specifying Sets on page 580.
Enclose sets in braces, for example:
{ [Year].[Qtr1], [Year].[Qtr2], [Year].[Qtr3], [Year].[Qtr4] }
927
You use Formula Editor to create formulas. Formula Editor is a tab in the Member Properties
dialog box in Outline Editor. Formulas are plain text. You can type the formulas directly into
the formula text area, use a predefined formula template, or you can create a formula in the text
editor of your choice and paste it into Formula Editor.
You can also include formulas in a dimension build data source. See Setting Field Type
Information on page 285.
To create a formula:
See Creating Formulas for Aggregate Storage Databases in the Oracle Essbase Administration
Services Online Help.
928
Displaying Formulas
To display a formula, use tool:
Tool
Topic
Location
Administration Services
MaxL
query database
ESSCMD
GETMBRCALC
The following sections discuss and give examples of how to write a variety of formulas for
members in aggregate storage outlines.
The formula in Avg Units/Transaction divides the number of units by the number of transactions
to arrive at the average number of units per transaction.
In aggregate storage outlines, members cannot be tagged as expense items. Therefore, functions
in Calc, such as @VAR and @VARPER, which determine the difference between two members
by considering expense tags, are not relevant in aggregate storage outlines.
The MDX subtraction operator can be used to calculate the difference between two members.
For example, the following formula can be applied to a new member, called Price Diff, in
ASOsamp.Sample, to calculate the difference between the price paid and the original price:
[Price Paid]-[Original Price]
Transactions/
(Transactions,Years,Months,[Transaction Type],[Payment Type],
Promotions,Age,[Income Level],Products,Stores,Geography)
The formula specifies a member (Transactions) divided by a tuple (Transactions, Years, ...). The
formula lists a top member from every dimension to account for all Transaction data in the
cube; that is, not Transaction data for the Curr Year member but Transaction data for all
members of the Years dimension, not Transaction data for months in the first two quarters but
Transaction for all months, and so on. In this way, the value of % of Total represents the
percentage of the Measures total that are produced by Transactions.
Use the CASE, WHEN, THEN construct to create formulas with multiple tests and else
conditions.
The Filter function returns the tuples of the input set that meet the criteria of the specified search
condition. For example, to establish a baseline (100) for all products, you can add a Baseline
member and create a formula for it, as follows:
Count(Filter(Descendants([PersonalElectronics],
[Products].Levels(0)),[Qtr1] > 100.00))
930
2. A Filter function, when used with IsUDA (as shown in the following syntax), cycles through
each member of the Market dimension and returns a value for each member that has the
Major Market UDA:
Filter([Market].Members, IsUda([Market].CurrentMember, "Major Market"))
3. The Sum function adds the values returned by the Filter function; for the Major Market
example, the following formula is produced:
Sum (Filter([Market].Members, IsUda([Market].CurrentMember, "Major Market")))
Create the block storage database in a separate application from the one in which the
aggregate storage database is located.
Typically, the block storage database contains a subset of the dimensions in the aggregate
storage database.
Create a transparent partition based on where you want the data to be stored. Make the
block storage database the target and the aggregate storage database the source.
See Chapter 15, Designing Partitioned Applications.
Note: You may want to partition on the time dimension if data for some time periods is
stored in the aggregate storage database and data for other time periods is stored in
the block storage database. For example, if you have actual data for January through
March, which is stored in an aggregate storage database, and you want to budget for
the last nine months of the year using write-back members in a block storage database.
Users query and write-back to the block storage database. Queries are processed by the block
storage database or transparently by the aggregate storage database.
931
To create an aggregate storage and block storage write-back partition use a tool:
Tool
Topic
Location
Administration Services
Creating Partitions
create database
MaxL
create partition
Transparent Partition Used for Analyzing Variance Between Forecast and Actual Data
The following procedure is based on the aggregate storage sample database (ASOsamp.Sample),
and uses the Administration Services Aggregate Storage Partition Wizard (see the Oracle Essbase
Administration Services Online Help).
Select the ASOsamp.Sample database, which contains the actual data for the current year and for
previous years.
932
Figure 156
Create a block storage database containing the following subset of dimensions from ASOsamp.Sample:
Measures, Years, Time, Products, Stores, and Geography.
Edit the Years dimension to add the following members to the block storage database outline:
l
A member called Next Year, which will contain the forecast data.
A member called Forecast Variance. Add a formula to this member to calculate the
variance between actual and forecast data.
Figure 157 Block Storage Database Outline Showing Years Dimension Members for Calculating Variance Between Actual and
Forecast Data
These formulas are expressions written in MDX that are copied from the aggregate storage
database. MDX formula expressions cannot be interpreted in block storage databases.
Link the databases with a transparent partition on the Years dimension, with the block storage database
(forecast data) as the target and the aggregate storage database (actual data) as the source.
Do not include the write-back members (Forecast and Variance) in the partitioned area.
933
Note: When using the Administration Services Aggregate Storage Partition wizard, this step
934
62
In This Chapter
Introduction............................................................................................... 935
Understanding Date-Time Dimensions................................................................. 936
Understanding Linked Attributes ....................................................................... 937
Designing and Creating an Outline for Date-Time Analysis .......................................... 939
Modifying or Deleting Date-Time Dimensions ......................................................... 942
Loading Data Mapped to Dates ........................................................................ 943
Analyzing Time-Based Data ............................................................................. 944
The information in this chapter applies only to aggregate storage databases and is not relevant
to block storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Introduction
Most data analysis includes a time (history) perspective. Aggregate storage applications provide
built-in time-based functionality through time dimensions and date-time dimensions.
Aggregate storage time dimensions are similar to block storage time dimensions. They enable
tagging the accounts dimension for such time balance calculations as first, last, average, and todate values. Time dimensions are easily modifiable.
Aggregate storage date-time dimensions enable the first, last, and average time balance support.
In addition, Administration Services provides the powerful Create Date-Time Dimension wizard
for quick date-time dimension setup based on special calendars, plus linked attribute dimension
setup enabling crosstab reporting of time-related data. Date-time dimensions have a rigid
structure and are not easily modified after they are created.
The remainder of this chapter discusses date-time dimensions and the linked attribute
dimensions that can be associated with them. For information about time balance calculations
in aggregate storage outlines, see Performing Time Balance and Flow Metrics Calculations in
Aggregate Storage Accounts Dimensions on page 985.
935
The dimension member at the top of the hierarchy shows the comment:
/* TI-HIER,TP[3,1,4,5]!TI-MBR,TSPAN[112008,12312009]! */.
The TI-MBR,TSPAN[date1, date2] information enclosed between exclamation points (!) defines
the time range covered by the dimension; in this case two years, Jan. 1, 2008Dec. 31, 2009.
Positioned in front of the time span, the array TI-HIER,TP[3,1,4,5] describes the hierarchy. The
first number in the array, 3, indicates that the hierarchy contains three time periods. The
remaining numbers in the array indicate what time periods are included, based on the following
possible levels:
l
1Year
2Semester
3Trimester
4Quarter
5Month
6Period
7Week
8Day
Array TI-HIER,TP[3,1,4,5] indicates that the array contains three time periods: year, quarter,
and month.
Using the same time span TI-MBR,TSPAN syntax, each member comments field defines the
time range that it covers; for example, member Quarter 1 of Gregorian Year 2008 covers Jan.
936
1, 2008Mar. 31, 2008, and member Quarter 2 of Gregorian Year 2008 covers Apr. 1, 2008
Jun. 30, 2008.
937
Figure 159
Linked attributes enable you to compare sales of the first month of a quarter against sales of the
second and third months of a quarter in a simple crosstab analysis, as shown:
Linked attribute dimensions reflect two time components, which are easier to understand if we
use the default names; for example, Quarter by Year. Members of the Quarter by Year
dimension are associated with quarter time-depth members such as Quarter 1 of Gregorian
Year 2008 in Figure 159 on page 938. The first time component, Quarter, is called the
association level, because it indicates the date-time dimension members to which the attributes
are associated.
938
The second time component in this example, Year, is called the attachment level. The
attachment level indicates a member level in the associated date-time dimension. Each member
of the linked attribute dimension contains a number that indicates a relationship between the
association level and the attachment level. Quarter by Year: 1 is the first attribute member
Quarter by Year: 2 is the second member, and so on.
The date-time dimension members associated with linked attribute Quarter by Year: 1 are the
first quarters of their respective years. All date-time dimension members with the attribute
Month by Quarter: 1 are the first months of their respective quarters. Thus linked attributes
enable analysis of information based on a common periodic relationship such as first, second,
and third.
(Optional) Attribute dimensions associated with day-level members. These are standard
Boolean or text attributes based on specific dates or days of the week. You can use these
attributes to include or exclude day-level information. For example, the wizard enables
defining the following types of situations:
m
The Administration Services Create Date-Time Dimension wizard builds all members for the
calendars and time ranges specified.
What time period must the database model? You must provide the start and end dates.
939
What time-period granularity should the database reflect in its outline? Does business
analysis drill down to the week level, or can weeks be omitted because reporting is by month
or a higher level? Are any business measures analyzed and reported down to the day level?
Are semester or trimester breakdowns required?
Would analysis of data within time relationships be valuable? For example, within a business
calendar containing quarters, would the ability to see trends for each closing quarter be
useful, such as whether sales increase toward the close of each?
The Create Date-Time Dimension wizard is a powerful tool with many options. Consider some
practice runs to better understand the dimensions it builds. See also the topics for each page of
this wizard in Oracle Essbase Administration Services Online Help.
members. This can cause the create date-time dimension procedure to fail unless the
outline is set to allow duplicate member names. If the outline is not set to allow duplicate
member names, you must avoid duplicates.
Depending on the calendar template and chosen time depths, you may need to define year,
month, or period characteristics (semantic rules) such as period starting or ending dates, week
count, or how months or weeks are grouped within their parent members. These characteristics
affect the rules by which members are built and named. For some calendars, availability of year,
period, or month semantic rules is dependent on other year, period, or month options selected.
See Create Date-Time Dimension WizardSelect Calendar Hierarchy Panel in Oracle Essbase
Administration Services Online Help.
The Create Date-Time Dimension wizard provides templates for the following calendar types:
940
Gregorian
The Gregorian calendar is the standard 12-month calendar, January 1December 31. Time
depths are year, semester, trimester, quarter, month, week, and day.
Fiscal
Fiscal calendar definitions are based on company financial reporting requirements and can start
on any date. Weeks In fiscal calendars have seven days. The 12-month reporting period includes
two months of four weeks and one month of five weeks, in a repeated three-month quarterly
pattern, (4-4-5, 4-5-4, or 5-4-4 weeks). If the year has 53 weeks, one month can have an extra
week.
The week definition determines how to divide the calendar year into weeks. You can adjust the
week definition to make a 52 week or 53 week year. Time depths are year, semester, trimester,
quarter, month, week, and day.
Retail
The retail calendar, from the National Retail Federation, is modeled to analyze week-over-week
data across years. It has a 4-5-4 quarter pattern with leap weeks every five to six years. The starting
date differs from year to year but always falls in early February. When comparing year over year,
standard practice is to omit the first week of a 53-week year to normalize for the extra week while
the years keep the same holidays. Available time depths are year, semester, quarter, month, week,
and day.
Manufacturing
The manufacturing calendar defines a 13-period year, made up of seven-day weeks.
Manufacturing periods are divided into three quarters of three periods each and one quarter of
four periods. All periods have four weeks, except for 53-week years, in which one period has five
weeks.
When you define the 13 periods, you specify which quarter has the extra period. If the year has
53 weeks, you must specify which period will have the extra week. If you specify that the year
starts on a specific date, you must indicate whether the year has 52 weeks or 53. If the year has
52 weeks, you may need to specify both 52-week and 53-week options, to pare the weeks first
down to 53, then pare them down to 52. Available time depths are year, semester, quarter, period,
week, and day.
ISO 8601
The ISO 8601 calendar contains seven-day weeks. The year can start before or after January 1
and is modeled to start on a day such that the first week of the ISO calendar contains the first
Thursday of January. The first day of the week is Monday. Year, week, and day time depths are
required for the ISO calendar, with no additional time-depth options.
941
Note: If you edit the TI-HIER and TI-MBR,TSPAN sections in member comments, you must
ensure that the correct members exist throughout the hierarchy, and you must edit
dependent ranges for ancestors or descendants. For example, if you change the span of a
given month, you must also change the span of the quarter.
If you delete a date-time dimension, also delete all associated attribute dimensions. Linked
attributes have meaning only when they are whole; that is, all members exist and be associated
in the correct sequence. An outline is invalid if you disassociate a linked attribute from only a
few members.
Be aware of the verification rules summarized in the following sections.
The hierarchy is balanced; all level 0 members are of the same generation.
Member comment fields for each member contain the following information in the leftmost part of the comment. (Details are described in Understanding Date-Time
Dimensions on page 936.)
m
942
The member comment field for the top dimension member includes contains the TIHIER, TP[ ] specification that contains an array that describes the hierarchy structure.
The member comment field for each member including the top dimension member
contains the TI-MBR, TSPAN[ ] specification that includes the date range for the
member, with starting date preceding ending date.
Along a generation, date ranges should be contiguous and should increase in ascending
order. For example, along the month generation, the date range for each month member
must have a starting date that logically follows from the ending date of the previous period.
There must be no time gaps, and the span of the parent member must equal the total time
span of its children.
Each linked attribute dimension has two levels only, the parent level and the children
attribute members.
Linked attribute member names are sequential numbers, starting with 1.
If attribute dimensions exist, all combinations of attachment and association levels for the
date-time dimension must exist. For example, if the date-time dimension includes year,
semester, and month time depths, if you create linked attribute dimensions you must create
Month by Year, Month by Semester, and Semester by Year.
Data can be loaded from any day-level load file, as long as the data file date format is
supported.
If you set the data load to Add to existing cells, data can be loaded from a day-level load
file to a less granular level in the hierarchy; for example to week or month level 0 cells.
Table 195 lists the date format strings you can use when you define the date field in the data load
rules file:
Table 195
Example
mon dd yyyy
Jan 15 2006
Mon dd yyyy
January 15 2006
mm/dd/yy
01/15/06
mm/dd/yyyy
01/15/2006
yy.mm.dd
06.01.06
dd/mm/yy
15/01/06
dd.mm.yy
15.01.06
dd-mm-yy
150106
dd Mon yy
15 January 06
943
Example
dd mon yy
15 Jan 06
Mon dd yy
January 15 06
mon dd yy
Jan 15 06
mm-dd-yy
011506
yy/mm/dd
06/01/15
yymmdd
060115
dd Mon yyyy
15 January 2006
dd mon yyyy
15 Jan 2006
yyyy-mm-dd
20060115
yyyy/mm/dd
2006/01/15
Long Name
Short Name
1/8/06 (m/d/yy)
Note: Using extra white space not included in the internal format strings returns an error.
Trailing characters after the date format has been satisfied are ignored. If you erroneously
use a date string of 06/20/2006 with date format mm/dd/yy, the trailing 06 is ignored and
the date is interpreted as June 20, 2020. Long Name format is not verified for a day-ofweek match to the given date.
Working on the free-form grid. With a date-time member on the grid selected, using
Member Selection shows Date-Time as a dimension type and lists the members of that
dimension. The Period and Range filters enable you to select and display information using
linked attributes.
Using Query Designer.
m
944
Using the POV toolbar, you can select a linked attribute, drag it to the free-form grid,
and execute the query.
For additional information, see Oracle Smart View for Office User's Guide.
Function
Description
DateDiff
DatePart
DateRoll
To the given date, rolls (adds or subtracts) a number of specific time intervals, returning another date.
DateToMember
FormatDate
GetFirstDate
GetLastDate
Today
ToDateEx
945
946
63
In This Chapter
Introduction............................................................................................... 947
Preparing Aggregate Storage Databases .............................................................. 949
Calculating Aggregate Storage Databases............................................................. 969
Retrieving Aggregate Storage Data ..................................................................... 989
The information in this chapter applies only to aggregate storage databases and is not relevant
to block storage databases. Also see Chapter 60, Comparison of Aggregate and Block Storage.
Introduction
The most common processes for working with database information include maintaining the
outline, loading data values to the database, calculating values, and retrieving database
information. Performing these tasks with aggregate storage databases is different from
performing them with block storage databases.
Examples in this chapter refer to the outline in Figure 160.
947
Figure 160
The simplified aggregate storage outline in Figure 160 is not completely expanded. A plus sign
(+) node at the left of a member name indicates that the member has children that are not
displayed.
948
The topics in this section describe dimension build and data load process differences between
aggregate storage and block storage databases. You should be familiar with data load, dimension
build, and rules file concepts and procedures.
For information about using data sources to change outlines and to load data values, see
Chapter 17, Understanding Data Loading and Dimension Building and Chapter 20,
Performing and Debugging Data Loads or Dimension Builds.
For information on the maximum size of a buildable aggregate storage outline, see Outline
Paging Limits on page 922.
Aggregate storage dimension build changes to the outline can result in all aggregate views or all
data values being cleared from the database when the dimension build is finished. Aggregate
Storage Database Restructuring on page 1027 describes the results of outline changes.
If you use multiple data sources to build dimensions, you can save processing time by performing
an incremental dimension build. Incremental dimension builds enable you to defer restructuring
until all data sources have been processed. For information about incremental dimension build,
see Performing Deferred-Restructure Dimension Builds on page 307.
Differences between outline characteristics of block storage outlines and aggregate storage
outlines affect data sources and rules files. For example, defining a dimension as sparse or dense
is not relevant to aggregate storage outlines.
949
l
l
Rules files for building aggregate storage outlines must define only outline properties and field
types that apply to aggregate storage outlines. See Table 186, Outline Differences Between
Aggregate Storage and Block Storage, on page 900.
After converting a block storage outline to aggregate storage, update the rules files by associating
them to the aggregate storage version of the outline. See Associating an Outline with an Editor
in the Oracle Essbase Administration Services Online Help.
Generation
Level
Parent-child references
Dimension Build Rules File Options That Do Not Apply to Aggregate Storage
Databases
950
Dimension Build Rules File Options That Do Not Apply to Aggregate Storage
Databases
Dynamic Calc
Currency name
Currency category
Code
Description
Express as a percentage of the current total in a consolidation (applies only to members of a dynamic hierarchy)
Multiply by the current total in a consolidation (applies only to members of a dynamic hierarchy)
Add to the current total in a consolidation (applies only to members of a dynamic hierarchy)
Subtract from the current total in a consolidation (applies only to members of a dynamic hierarchy)
Divide by the current total in a consolidation (applies only to members of a dynamic hierarchy)
Exclude from the consolidation (applies only to members of a dynamic hierarchy or members beneath Label Only members in a
stored hierarchy)
Essbase does not use the value of the member in any consolidation in any dimension except attribute dimensions
951
Code
Description
Set member as top of a stored hierarchy (applies to dimension member or generation 2 member)
Set member as top of a dynamic hierarchy (applies to dimension member or generation 2 member)
Set dimension member as multiple hierarchies enabled (applies to dimension member only)
Currency name and currency category field types are not supported for aggregate storage
outlines.
In aggregate storage outlines, formulas must be specified in the same format as MDX numeric
value expressions. See Developing Formulas on Aggregate Storage Outlines on page 924.
alternate hierarchies in aggregate storage outlines. See Table 189, Data Load Differences
Between Aggregate Storage and Block Storage, on page 903.
Caution!
Export
Multiple export operations can run at the same time because export is a read-only operation.
Export operations can run at the same time as build aggregations and backup, both of which
952
are exclusive operations; however, export is not compatible with any other exclusive
operation.
l
Build aggregations
is running, the order in which the new exclusive operations execute after the send
operation completes is random; the order is not based on the sequence in which the
new exclusive operations were attempted. For example, if a send operation is running
and an exclusive operation of a different type is attempted, the new exclusive
operation waits for the send operation to finish before proceeding. If, in the
meantime, more send operations are attempted by other users, those send operations
might be executed before the other exclusive operation, even though they were
attempted afterward. Therefore, the exclusive operation might wait indefinitely as
long as there is at least one send operation waiting to be executed.
l
Merge slices
Queries are allowed to run concurrently with all exclusive operations. However, if an operation
adds, changes, or removes any data in the database, the following sequence takes place at the
end of the operation, when the changes are made visible to queries:
1. Any new queries are temporarily blocked from starting (the queries wait).
2. Existing queries finish running.
3. Data changes from the exclusive operation are committed to the database.
4. Queries that are waiting proceed.
Queries are never rejected or canceled because of an operation that changes data on an aggregate
storage cube.
953
l
l
l
l
l
l
l
l
l
l
l
l
l
l
For general information about loading data, see Chapter 20, Performing and Debugging Data
Loads or Dimension Builds.
Aggregate storage databases facilitate analysis of very large dimensions containing up to a million
or more members. To efficiently support loading data values into such large databases, Essbase:
Allows the processing of multiple data sources through temporary aggregate storage data
load buffers
Allows you to control the percentage of resources a data load buffer uses
Allows an aggregate storage database to contain multiple slices of data (a query to the
database accesses each slice, collecting all of the data cells)
Provides an incremental data load process that completes in a length of time that is
proportional to the size of the incremental data
Topic
Location
Administration Services
MaxL
alter database
import data
ESSCMD
IMPORT
LOADDB
954
Note: If values have been calculated and stored through an aggregation, Essbase automatically
updates higher-level stored values when data values are changed. No additional
calculation step is necessary. The existence and size of an aggregation can affect the time
it takes to perform a data load. See Aggregations on page 976.
You cannot export data when loading data into a database.
subtracting values is specified for the entire set of data sources when loading the data
buffer contents to the database.
While the data load buffer exists in memory, you cannot build aggregations or merge slices,
because these operations are resource-intensive. You can, however, load data to other data load
buffers, and perform queries and other operations on the database. There might be a brief wait
for queries, until the full data set is committed to the database and aggregations are created.
The data load buffer exists in memory until the buffer contents are committed to the database
or the application is restarted, at which time the buffer is destroyed. Even if the commit operation
fails, the buffer is destroyed and the data is not loaded into the database. (You can manually
destroy a data load buffer by using the alter database MaxL statement. See the Oracle Essbase
Technical Reference.)
Note: Stopping the application before committing the buffer contents destroys the buffer. In
this situation, after restarting the application, you must initialize a new buffer and load
the data to it.
Prepare the data load buffer, where data values are sorted and accumulated by using the alter
database MaxL statement to initialize an aggregate storage data load buffer. For example:
alter database ASOsamp.Sample
initialize load_buffer with buffer_id 1;
955
Load data from your data sources into the data load buffer using the import database MaxL statement.
Use multiple statements to load data from multiple data sources. You can include any combination of
data sources, such as .xls files, text files, and SQL relational sources. Specify a rules file if the data
source requires one.
The following example loads three data sources, one of which uses a rules file, into the same
data load buffer:
import database ASOsamp.Sample data
from server data_file 'file_1.txt'
to load_buffer with buffer_id 1
on error abort;
import database ASOsamp.Sample data
from server data_file 'file_2'
using server rules_file rule
to load_buffer with buffer_id 1;
on error abort;
import database ASOsamp.Sample data
from server excel data_file 'file_3.xls'
to load_buffer with buffer_id 1
on error abort;
To load data into multiple load buffers simultaneously, see Performing Multiple Data Loads
in Parallel on page 958.
Use the import database MaxL statement to commit the data load buffer contents to the database. For
example:
import database ASOsamp.Sample data
from load_buffer with buffer_id 1;
To commit the contents of multiple data load buffers into the database with one MaxL
statement, see Performing Multiple Data Loads in Parallel on page 958.
The following incremental data load example provides optimal performance when new data
values do not intersect with existing values:
1. Create a single data load buffer using the ignore_missing_values and ignore_zero_values
properties. For example:
alter database ASOsamp.Sample
initialize load_buffer with buffer_id 1
property ignore_missing_values, ignore_zero_values;
If the database must be available for send data requests while the database is being updated,
initialize the data load buffer with the resource_usage grammar set for 80%. For example:
alter database ASOsamp.Sample
initialize load_buffer with buffer_id 1
resource_usage 0.8 property
ignore_missing_values, ignore_zero_values;
956
3. Commit the contents of the data load buffer to the database by creating a slice and adding
values. For example:
import database ASOsamp.Sample data
from load_buffer with buffer_id 1
add values create slice;
default size of 1.0 will cause send operations to fail because of insufficient data load buffer
resources.
To set the amount of resources the buffer is allowed to use, use the alter database MaxL statement
with the resource_usage grammar.
For example, to set the resource_usage to 50% of the total cache, use this statement:
alter database ASOsamp.Sample
initialize load_buffer with buffer_id 1
resource_usage .5;
If you plan to run concurrent send operations, use the ASOLOADBUFFERWAIT configuration
setting and the alter database MaxL statement with the wait_for_resources grammar.
ASOLOADBUFFERWAIT applies to the creation of aggregate storage data load buffers with the
wait_for_resources option, and applies to allocations, custom calculations, and lock and send
operations.
957
In Administration Services Console, you can set options to ignore missing values and zero values,
and to aggregate duplicate cells by using the value of the last cell loaded, on the Data Load dialog
box. See Data Load Dialog Box in the Oracle Essbase Administration Services Online Help.
Note: When using data load buffers with the aggregate_use_last grammar, data loads are
958
Note: When using Administration Services Console to load data into an aggregate storage
Simultaneously, in another MaxL Shell session, load data into a buffer with an ID of 2:
alter database ASOsamp.Sample
initialize load_buffer with buffer_id 2 resource_usage 0.5;
import database ASOsamp.Sample data
from data_file "dataload2.txt"
to load_buffer with buffer_id 2
on error abort;
When the data is fully loaded into the data load buffers, use one MaxL statement to commit the
contents of both buffers into the database by using a comma-separated list of buffer IDs:
For example, this statement loads the contents of buffers 1 and 2:
import database ASOsamp.Sample data
from load_buffer with buffer_id 1, 2;
Note: When loading SQL data into aggregate storage databases, you can use up to eight rules
files to load data in parallel. This functionality is different than the process described
above. When preforming multiple SQL data loads in parallel, you use one import
database MaxL statement with the using multiple rules_file grammar. Essbase initializes
multiple temporary aggregate storage data load buffers (one for each rules file) and
commits the contents of all buffers into the database in one operation. See the Oracle
Essbase SQL Interface Guide.
This statement returns the following information about each existing data load buffer:
Table 199
Field
Description
buffer_id
959
Field
Description
internal
A Boolean that specifies whether the data load buffer was created internally by Essbase (TRUE) or by a user (FALSE).
active
A Boolean that specifies whether the data load buffer is currently in use by a data load operation.
resource_usage
The percentage (a number between .01 and 1.0 inclusive) of the aggregate storage cache that the data load buffer
is allowed to use.
aggregation
method
One of the methods used to combine multiple values for the same cell within the buffer:
l
AGGREGATE_SUM: Add values when the buffer contains multiple values for the same cell.
AGGREGATE_USE_LAST: Combine duplicate cells by using the value of the cell that was loaded last into the load
buffer.
ignore_missings
A Boolean that specifies whether to ignore #MI values in the incoming data stream.
ignore_zeros
A Boolean that specifies whether to ignore zeros in the incoming data stream.
Note: If you use override values when creating a slice, #MISSING values are replaced with zeros.
Using this option is significantly slower than using the add values or subtract values
options.
In Administration Services Console, you can set an option to create a slice on the Data Load
dialog box. See Data Load Dialog Box in the Oracle Essbase Administration Services Online
Help.
960
Automatically Merging Incremental Data Slices During a Data Load to an Aggregate Storage Database
Manually Merging Incremental Data Slices
Automatically Merging Incremental Data Slices During a Data Load to an Aggregate Storage
Database
Using the AUTOMERGE and AUTOMERGEMAXSLICENUMBER configuration settings, you
can specify whether Essbase automatically merges incremental data slices during a data load to
an aggregate storage database.
AUTOMERGE configuration setting options:
l
NEVERSpecifies to never automatically merge incremental data slices during a data load
to an aggregate storage database. To manually merge incremental data slices, use the alter
database MaxL statement with the merge grammar. See Manually Merging Incremental
Data Slices on page 961.
SELECTIVESpecifies to activate the incremental data slice auto-merge process when the
number of incremental data slices specified in the AUTOMERGEMAXSLICENUMBER
configuration setting is exceeded. If the number of incremental data slices in the data load
does not exceed the value of AUTOMERGEMAXSLICENUMBER, the auto-merge process
is not activated.
961
If you cleared data from a region using the logical clear region operation, which results in a value
of zero for the cells you cleared, you can elect to remove zero value cells during the merge
operation. See Clearing Data from Specific Regions of Aggregate Storage Databases on page
965.
To perform merging operations, use the alter database MaxL statement with the merge grammar.
For example, to merge all incremental data slices into the main database slice, use this statement:
alter database ASOsamp.Sample
merge all data;
To merge all incremental data slices into the main database slice and remove zero value cells,
use this statement:
alter database ASOsamp.Sample
merge all data remove_zero_cells;
To merge all incremental data slices into a single data slice, use this statement:
alter database ASOsamp.Sample
merge incremental data;
In Administration Services Console, you can merge data slices. See Merging Incremental Data
Slices (Aggregate Storage Databases) in the Oracle Essbase Administration Services Online
Help.
Note: Before you copy an aggregate storage application, you must merge all incremental data
slices into the main database slice. Data in unmerged incremental data slices is not copied.
See Manually Merging Incremental Data Slices on page 961.
962
Note: To use the override grammar, create a data load buffer with the ignore_missing_values
property for optimal performance. Additionally, you must ensure that there are not any
conflicts between the static and volatile data sets (for example, there should not be a value
in each data set for the same cell).
To replace the contents of a database or the incremental data slices in a database, use the import
database MaxL statement with the override grammar.
For example, to replace the contents of a database, use this statement:
import database ASOsamp.Sample data
from load_buffer with buffer_id 1
override all data;
To replace the contents of all incremental data slices with a new slice, use this statement:
import database ASOsamp.Sample data
from load_buffer with buffer_id 1
override incremental data;
Note: If the override replacement fails, Essbase continues to serve the old data set.
In Administration Services Console, you can set the option to replace the contents of the database
or data slices in the Data Load dialog box. See Replacing Database or Data Slice Contents
(Aggregate Storage Database) in the Oracle Essbase Administration Services Online Help.
963
In cases where databases are larger than 2 GB, you can reduce disk space utilization by setting
the maximum file size of the default tablespace to no more than 2 GB. See Working with
Tablespaces on page 1024.
To set the maximum file size of the default tablespace, use a tool:
Tool
Topic
Location
Administration Services
Managing Tablespaces
MaxL
alter tablespace
Essbase ignores records that specify upper-level members and, at the end of the data load, displays
the number of skipped records.
For example, the following record would be skipped because member Mid West is a level 1
member:
Jan, Curr Year, Digital Cameras, Mid West, Original Price, 121301
Sorting data sources is unnecessary because Essbase Server reads and sorts records internally
before committing values to the database.
964
For block storage data loads, through the rules file, you choose for each data source whether to
overwrite existing values, add values in the data source to existing values, or subtract them from
existing values.
For aggregate storage data loads using the aggregate storage data load buffer, you make this
choice for all data load sources that are gathered into the data load buffer before they are loaded
to the database.
To use a rules file that was defined for a block storage outline with an aggregate storage outline,
first associate the rules file with the aggregate storage outline. See Associating an Outline with
an Editor in the Oracle Essbase Administration Services Online Help.
You can selectively clear data or clear all data from an aggregate storage database.
Also see Clearing Aggregations on page 984.
Physical
The input cells in the specified region are physically removed from the aggregate storage
database, as illustrated in Figure 161.
Figure 161
965
If there are multiple data slices in the database, the physical clear region operation
automatically merges all data slices into the main data slice. After data for the specified region
is cleared, Essbase materializes all aggregate views that were present in the main data slice
before the clear region operation took place.
The process for physically clearing data completes in a length of time proportional to the
size of the input data, not to the size of the data being cleared. Therefore, you might use this
method only when removing large slices of data.
To physically clear data, use the alter database MaxL statement with the clear data in
region grammar and the physical keyword:
alter database appname.dbname clear data in region 'MDX set expression' physical;
l
Logical
The input cells in the specified region are written to a new data slice with negative,
compensating values that result in a value of zero for the cells you want to clear, as illustrated
in Figure 162.
Figure 162
The logical clear region operation automatically merges only the data slice with zero values
into the main data slice; other data slices in the database are not merged. After data for the
specified region is cleared, Essbase materializes aggregate views only in the new data slice.
The process for logically clearing data completes in a length of time that is proportional to
the size of the data being cleared. Because compensating cells are created, this option
increases the size of the database.
To logically clear data, use the alter database MaxL statement with the clear data in
region grammar but without the physical keyword:
alter database appname.dbname clear data in region 'MDX set expression';
Queries to the logically cleared region return zero values instead of #MISSING values. You
may need to update formulas that rely on #MISSING values for empty cells.
To remove cells with a value of zero, use the alter database MaxL statement with the
merge grammar and the remove_zero_cells keyword. See the Oracle Essbase Technical
Reference.
966
Note: Oracle does not recommend performing a second logical clear region operation on
the same region, because the second operation does not clear the compensating cells
created in the first operation and does not create new compensating cells.
In specifying the region to be cleared, follow these guidelines:
l
{(Jan, Budget)} is a valid symmetrical region that clears all Budget data for Jan.
{(Jan, Forecast1),(Feb, Forecast2)} is an invalid region because it consists of two
asymmetrical regions (Jan, Forecast1 and Feb, Forecast2).
Individual members in any dimension in the region specification must be stored members.
(Physically clearing data only) Members in the region can be upper-level members in
alternate hierarchies.
For example, you can specify High End Merchandise, which is the same as specifying Flat
Panel, HDTV, Digital Recorders, and Notebooks (the shared, level 0 children of High End
Merchandise):
967
To specify members in alternate hierarchies when logically clearing data, use the
Descendants MDX function.
Note: When the region contains upper-level members from alternate hierarchies, you may
The MDX set expression must be enclosed with single quotation marks.
For example, to clear all January data for Forecast1 and Forecast2 scenarios, use this statement:
alter database ASOsamp.Sample clear data in region 'CrossJoin({Jan},{Forecast1,
Forecast2})';
During the clear region operation, you cannot perform operations that update the database
(such as loading data, merging data slices, or clearing data from another region), nor export
data. You can query the database; however, the query results are based on the data set before the
clear region operation.
The clear data in region grammar cannot clear data from the entire database. See Clearing All
Data from an Aggregate Storage Database on page 968.
968
combined into one operation in Administration Services, Oracle recommends that you
separate dimension build operations from data load operations, because some dimension
builds clear data, which could lead to data loss. See Building Dimensions in Aggregate
Storage Databases on page 949.
Aggregate storage database values are calculated through the outline structure and MDX
formulas. When a data load is complete, all the information needed to calculate an aggregate
storage database is available. When a retrieval request is made, Essbase Server calculates the
needed values by consolidating the values loaded for level 0 members and calculating formulas.
Values calculated for retrievals are not stored.
To improve retrieval performance, Essbase can aggregate values and store them ahead of time.
However, aggregating and storing all values can be a lengthy process that requires disk space for
storage. Essbase provides an intelligent aggregation process that balances time and storage
resources. See Aggregating an Aggregate Storage Database on page 974.
To prepare an aggregate storage database for retrieval, you create the outline and load the level 0
values. Then you calculate the database by aggregating, and storing additional values, with the
remaining values to be calculated when retrieved.
Note: If a database needs calculation scripts to handle special calculations and data
dependencies, consider altering the database design or making it a block storage database.
969
See Table 187, Calculation Differences Between Aggregate Storage and Block Storage, on page
902.
(~) operator.
For more complex operations, you can provide MDX formulas on members of dynamic
hierarchies. MDX formulas are written in the same format as MDX numeric value expressions.
See Developing Formulas on Aggregate Storage Outlines on page 924.
Dynamic Calc and Dynamic Calc and Store member storage properties
970
Calculation Order
Subtopics
l
l
Aggregate storage calculation order and block storage calculation order differ. For aggregate
storage databases, Essbase calculates data in the following order:
1. Aggregates members of stored hierarchies and attribute dimensions. The order in which
members and dimensions are aggregated is optimized internally and changes according to
the nature of the database outline and the existing aggregations. Because the aggregation is
additive, the order in which Essbase aggregates the dimensions and members does not affect
the results.
Because the internal aggregation order for an aggregate storage database is not predictable,
any inherent rounding errors are also not predictable. These rounding errors are expected
behavior in computer calculation and are extremely small in relation to the data values
concerned.
2. Calculates dynamic hierarchy dimension members and formulas. The order in which
members and formulas are evaluated is defined by the solve order property, which you can
set for each member or dimension. Calculation order may affect calculation results.
property at the member level or at the dimension level. Members without formulas that
do not have a specified solve order inherit the solve order of their dimension. Members
with formulas that do not have a specified solve order have a solve order of zero.
Topic
Location
Administration
Services
MaxL
The value of the solve order property determines the priority with which Essbase calculates the
formulas. The formulas on the members that have a specified solve order are calculated in order
971
from the lowest solve order to the highest. (See Example Using the Solve Order Property on
page 972). You can specify a solve order between 0 and 127. The default is 0.
You can specify the solve order at the member level or at the dimension level. Essbase uses the
following information to define calculation precedence:
1. Member solve order
2. Dimension solve order (members without formulas for which you do not specify a member
solve order inherit the solve order of their dimension. Members with formulas for which
you do not specify a member solve order have a solve order of zero.)
If multiple members have the same solve order, the members are evaluated in the reverse
order in which their dimensions occur in the database outline. The member that occurs later
in the outline takes precedence.
The tie situation calculation order is different for calculated members defined in an MDX
query for block storage databases. See the Oracle Essbase Technical Reference.
Note: When a member formula is dependant on the value of another member, the member
with the formula must have a higher solve order than the member or members on
which it depends. For example, in the ASOsamp.Sample database outline in
Figure 164 on page 973, Avg Units/Transaction depends on the value of Units and
of Transactions. Avg Units/Transaction must have a higher solve order than Units
and Transactions.
972
Results from Spreadsheet Query of ASOsamp.Sample database Showing the Variance Between Two Ratios (C12)
Figure 164 shows the database outline for these members and the formulas applied to the
Variance and Avg Units/Transaction members.
Figure 164
When calculating the variance of the average units per transaction (cell C12 in Figure 163 on
page 972), the result could be the variance between the two ratios, or the result could be the ratio
of the two variances. The result depends on whether Essbase gives precedence to the formula on
Variance or the formula on Avg Units/Transaction.
The value of the solve order property, which is attached to the members in the database outline,
determines the priority with which Essbase evaluates the formulas. The formula on the member
that has the higher solve order takes precedence.
In the example, if the Variance member has a higher solve order than the Avg Units/Transaction
member, then the formula on the Variance member takes precedence and the result is the
variance between two ratios. This is the case in the ASOsamp.Sample database, because the solve
order of the Variance member is 20 and the solve order of the Avg Units/Transaction member
is 10. The formula on Variance takes precedence, because the Variance member has the higher
solve order. The result for cell C12 of the query in Figure 163 is the variance between the two
ratios, as shown in Table 200:
Table 200
Using the Solve Order Property to Specify the Variance Between Two Ratios
Member
Solve
Order
Formula
Variance
20
Avg Units/
Transaction
10
Units/Transactions
Alternatively, if you change the ASOsamp.Sample database, and you give the Avg Units/
Transaction member a higher solve order than the Variance member, then the formula on the
Avg Units/Transaction member takes precedence, and the result is the ratio of two variances, as
shown in Table 201 and in Figure 165:
973
Table 201
Using the Solve Order Property to Specify the Ratio of Two Variances
Member
Solve
Order
Formula
Variance
10
Avg Units/
Transaction
20
Units/Transactions
Figure 165
Results from Spreadsheet Query of ASOsamp.Sample Database Showing the Ratio of Two Variances (C12)
Aggregate storage databases require no separate calculation step after data values are loaded into
the level 0 cells of the outline. From any point in the database, users can retrieve and view values
that are aggregated dynamically, for the current retrieval only. Aggregate storage databases are
smaller than block storage databases, enabling quick retrieval of data values.
As databases grow, retrievals must process more data values to satisfy the calculation needs of
the queries. For faster retrieval, Essbase enables you to precalculate data values and store those
values in aggregations. If a database size nears one million aggregate cells, you should strongly
consider performing an aggregation. Depending on database usage and the usage environment,
you can achieve performance benefits by precalculating smaller databases as well. You can use
either Administration Services Console or MaxL to calculate an aggregate storage database.
974
Aggregate Cells
Aggregate Views
Aggregations
Aggregation Scripts
The following topics describe terms that are integral to an explanation of aggregate storage
database calculation.
Aggregate Cells
Cells for level 0 intersections across dimensions, without formulas, are called input cells. Data
values can be loaded to them. Higher-level cells involving members of the accounts dimension
or dynamic hierarchies are always calculated at retrieval. All other higher-level intersections
across dimensions are aggregate cells. For example, for the outline in Figure 160 on page 948,
Price Paid > Curr Year > 1st Half > Portable Audio > CO is an aggregate cell; Original Price >
Curr Year > Jan > Camcorders > CO is another aggregate cell. Values for aggregate cells must
be rolled up from lower-level values.
Aggregate cell values are calculated for each request, or they can be precalculated and stored on
disk.
Aggregate Views
When Essbase defines which aggregate cells to precalculate and store, it works with aggregate
views. An aggregate view is a collection of aggregate cells. The collection is based on the levels of
the members within each dimension.
For example, consider one aggregate view for the outline in Figure 160 on page 948. This
aggregate view includes aggregate cells for the following dimension levels:
l
975
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
Original Price,
and so on...
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Curr
Prev
Prev
Prev
Prev
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Year,
Qtr1,
Qtr1,
Qtr1,
Qtr1,
Qtr2,
Qtr2,
Qtr2,
Qtr2,
Qtr3,
Qtr3,
Qtr3,
Qtr3,
Qtr4,
Qtr4,
Qtr4,
Qtr4,
Qtr1,
Qtr1,
Qtr1,
Qtr1,
Personal Electronics,
Personal Electronics,
Home Entertainment,
Home Entertainment,
Personal Electronics,
Personal Electronics,
Home Entertainment,
Home Entertainment,
Personal Electronics,
Personal Electronics,
Home Entertainment,
Home Entertainment,
Personal Electronics,
Personal Electronics,
Home Entertainment,
Home Entertainment,
Personal Electronics,
Personal Electronics,
Home Entertainment,
Home Entertainment,
CO
KS
CO
KS
CO
KS
CO
KS
CO
KS
CO
KS
CO
KS
CO
KS
CO
KS
CO
KS
Aggregations
Aggregations are consolidations, based on outline hierarchy, of level 0 data values. An aggregation
contains one or more aggregate views. Essbase provides an intelligent aggregation process that
selects aggregate views to be rolled up, aggregates them, and then stores the values for the cells
in the selected views. If an aggregation includes aggregate cells dependent on level 0 values that
are changed through a data load, the higher-level values are automatically updated at the end of
the data load process.
The term aggregation is used for the aggregation process and the set of values stored as a result
of the process.
Aggregation Scripts
Each aggregation script is a file that defines a particular selection of aggregate views to be
materialized. The Administration Services Aggregation Design Wizard enables you to create
aggregation scripts and store them in the database directory as text files with the .csc extension.
See Working with Aggregation Scripts on page 982.
976
During the aggregate view selection phase, Essbase analyzes how calculating and storing various
combinations of aggregate views might affect average query response time. As input to the
analysis, you can define physical storage and performance requirements. You can also track data
usage and provide the information to the analysis process. See Selecting Views Based on Usage
on page 980.
Based on their usefulness and resource requirements, Essbase creates a list of aggregate views.
Included with each view in the list is storage and performance information that applies when
that aggregate view plus all other aggregate views listed above it are stored. You can choose to
aggregate the listed views, select and aggregate a subset of the listed views, or rerun the selection
process with different input criteria. You can also add to an aggregation the materialization of
new views that are based on new selection criteria. See Fine-Tuning Aggregate View Selection
on page 978.
Whether or not you materialize the selection, you can save the selection of aggregate views as an
aggregation script. Aggregation scripts provide flexibility and can save time because they enable
you to bypass the selection process if the same selection is needed again. See Working with
Aggregation Scripts on page 982.
After the selection process is finished, the selected aggregate views are calculated when you
materialize the selected aggregate views into an aggregation.
The following process is recommended for defining and materializing aggregations:
1. After the outline is created or changed, load data values.
2. Perform the default aggregation.
Optional: Specify a storage stopping point.
3. Materialize the suggested aggregate views and save the default selection in an aggregation
script.
4. Run the types of queries for which the aggregation is designed.
5. If query time or aggregation time is too long, consider fine-tuning the aggregation. See
Fine-Tuning Aggregate View Selection on page 978.
6. Optional: Save the aggregation selection as an aggregation script.
See Working with Aggregation Scripts on page 982.
Topic
Location
Administration Services
MaxL
977
Note: Aggregation Design Wizard enables running aggregation processes in the background.
When you run an Administration Services process in the background, you can continue
to use Administration Services Console for other activities simultaneously as the
background process is running.
Also see Optimizing Aggregation Performance on page 983.
Improving retrieval performance can increase disk storage costs and the time it takes to
materialize the aggregation.
Tracking queries may result in a set of proposed aggregate views that provide better
performance for some queries than for others. Selecting proposed aggregate views can
considerably improve performance time of some queries with others experiencing little
improvementbut never worseas long as query type and frequency are close to the type
and frequency of queries performed during the tracking period.
Optimizing aggregations may require an iterative, fine-tuning process.
To estimate the size of aggregate views, you can use the ASOSAMPLESIZEPERCENT
configuration setting in essbase.cfg to specify the number of sample cells Essbase uses. The
sample size is specified as a percentage of input-level data. The default, and minimum, sample
size is 1 million (1,000,000) cells. See the Oracle Essbase Technical Reference.
Essbase provides information to help you select and store the right balance of aggregate views
for your database. Weigh this information against what you know about your database retrieval
requirements and environment. Use the following information to help you select aggregate views
for an aggregation:
l
978
When the aggregation selection is initiated, you specify a maximum storage stopping
value. Aggregate views are selected until the specified storage limit is reached or there
are no more views to select.
In Administration Services, the number you specify is the amount of storage in MB; in
MaxL, the number is a factor times the size of the level 0 stored values. See the Oracle
Essbase Administration Services Online Help and the Oracle Essbase Technical Reference.
m
After each analysis of the database, Essbase displays information about the level 0 input
cell view followed by a list of suggested aggregate views. Displayed by each aggregate
view is a storage number that includes that aggregate view and all other aggregate views
it depends on. You can consider this storage number as you select the aggregate views
to be included in the aggregation.
Tracked usage
Before running an aggregate view selection, you can turn on query tracking to determine
which data is retrieved most often. After some period of database activity, you can have
Essbase include the usage statistics in the aggregation analysis process. See Selecting Views
Based on Usage on page 980.
Aggregation time
The time it takes to perform an aggregation after the selection process completes increases
for each aggregate view materialized. To determine actual aggregation time, you must
perform the aggregation.
979
7. Materialize the selected aggregate views and, if desired, save the selection in an aggregation
script.
8. Working with aggregation scripts and various selection criteria, repeat the process until you
think you have the optimum selection of aggregate views for your situation.
Note: To optimize aggregations for different database retrieval situations, such as for generating
reports or user queries, you may need to repeat the tuning process, creating an aggregation
script for each situation. See Working with Aggregation Scripts on page 982.
Topic
Location
Administration Services
MaxL
alter database
Query tracking holds query usage information in memory. Performing any of the following
operations clears query usage information.
l
Query tracking remains on until you turn it off, stop the application, or change the outline.
Property
Effect
Default
On primary hierarchies, Essbase considers all levels. It does not aggregate on secondary hierarchies
unless alternative roll-ups are enabled.
Considers all levels of the hierarchy as potential candidates for aggregation. This is the default for primary
hierarchies, but not for secondary hierarchies.
Do not aggregate
Does not aggregate along this hierarchy. All views selected by Essbase are at the input level.
Applies only to secondary hierarchies. Essbase considers only the bottom level of this hierarchy for
aggregation.
Applies only to primary hierarchies. Considers only top level of this hierarchy for aggregation.
Note: The bottom level of an attribute dimension consists of the zero-level attribute members.
When a secondary hierarchy is formed using shared members, the bottom level comprises
the immediate parents of the shared members.
Essbase considers only views that satisfy the selected view selection properties.
You should be familiar with the dominant query patterns of databases before changing default
properties; preventing selection of certain views will make queries to those views slower while
improving the speed of other queries. Similarly, enabling Consider All Levels on a secondary
hierarchy may speed queries to that hierarchy while making other queries slower.
Topic
Location
Administration Services
MaxL
Query Hints
Query hints tell Essbase what types of queries likely will occur. For example, to indicate queries
at the bottom level of the time dimension, you can specify one member at the bottom level of
time, such as January. This tells Essbase that any member at the bottom level of time likely will
be queried. Essbase gives members indicated in query hints priority when selecting views,
optimizing common queries.
If no member is specified for a dimension, it means that any member of that dimension may be
used in a query. For example, using a query hint of (Sales, 100, East) on Sample.Basic means
981
that profit margin measures for level 1 products at level 1 markets is a common type of query,
regardless of Year and Scenario dimensions, which were omitted.
Usage-based view selection overrides query hints. See Selecting Views Based on Usage on page
980. User-defined view selection overrides query hints if there is a conflict between the two. See
Understanding User-Defined View Selection on page 980.
Asterisks (*) indicate that no member is selected for a dimension.
Hint
Use Case
(Jan, *, *, *, *,)
(Qtr1, *, *, *, Cola)
Queries often include members both at the bottom level of product and the quarterly level of time.
Analysis at the state level of Market tends to stay at the Quarterly level or below.
Numerous hints can exist in the same outline. Any view that fits at least one hint is given more
weight than views that fit none.
Query Hints cannot contain dynamic, label-only, or shared members.
Topic
Location
Administration Services
Query Hints
Each aggregation script represents a specific aggregate view selection against a database.
Aggregation scripts can save you time. For example, after loading new data values you need not
perform another aggregate view selection. You can speed the aggregation process by using the
selection stored in an aggregation script to materialize the aggregation.
Aggregation scripts also give you flexibility. You can use them to save aggregate view selections
optimized for different retrieval situations; for example, you can use one script to optimize
retrievals in month-end reporting and another for daily retrieval requirements.
Aggregation scripts for a database become invalid when the selection it contains is invalid for
the database. Create aggregation scripts when you create aggregations. Do not manually modify
aggregation script files, which may cause unpredictable results. For information about when you
must create aggregations and aggregation scripts, see Replacing Aggregations on page 984.
982
Topic
Location
Administration Services
MaxL
Aggregation scripts are stored in the database directory as text files with the .csc extension and
are valid as long as the dimension level structure in the outline has not changed. For information
about when aggregation selections are invalid, see Replacing Aggregations on page 984. To
avoid the potential clutter of invalid aggregation script files, use the Aggregation Design Wizard
or manually delete aggregation scripts when they are no longer useful.
Topic
Location
Administration Services
Note: When Aggregation Design Wizard displays the list of existing aggregation scripts, it lists
all files with the .csc extension in the database directory. Only valid aggregation script
I/O-bound, such as for databases too large to fit in memory. Because threads must share
aggregate storage cache, the cache size must be sufficiently large to support the number of threads
defined. Otherwise, increasing the number of threads could degrade aggregation performance
time.
Note: For small databases, the performance of building aggregate views in Essbase 9.3.1 and
later versions may be slower than Essbase versions earlier than 9.3.1. However, Essbase
9.3.1 should perform better for databases larger than a few hundred million cells,
especially on computers with more than two processors and where the CALCPARALLEL
configuration setting has been chosen appropriately.
See the Oracle Essbase Technical Reference.
Clearing Aggregations
At times you might want to manually clear aggregations from the disk; for example, to make the
disk space available for disk-intensive operations. Clearing aggregations clears all data, except
level 0 values, from the database, releasing the disk area for other use. After aggregations are
cleared, queries calculate retrieved values dynamically from level 0 values.
For information about when Essbase Server automatically clears aggregated data, see Database
restructure in Table 186, Outline Differences Between Aggregate Storage and Block Storage,
on page 900.
Topic
Location
Administration Services
MaxL
alter database
Replacing Aggregations
You can replace an aggregation by clearing the existing aggregation and materializing a different
selection of aggregate views. You can perform a new aggregate view selection and materialization
process, or you can run an aggregation script. Consider replacing the aggregation in the following
situations:
l
984
aggregation when performance degradation is noticeable or when the database size increases
to about 150% of its original size.
l
You must replace an aggregation and associated aggregation scripts after the number of levels
in a dimension has been changed or one or more dimensions have been added or removed from
the outline. See Performing Database Aggregations on page 976 and Working with
Aggregation Scripts on page 982.
The topics in this section explain how to perform time balance and flow metrics calculations on
aggregate storage databases.
Consider a stored measure such as Headcount in a human-resources application. Within a YearQuarter-Months hierarchy, Headcount data is loaded at the month level.
985
The desired yearly or quarterly Headcount value is not the sum of its months; rather, it should
be the last recorded value within a time period.
Tagging Headcount as TB Last with SKIPMISSING means that, for Year 2005, its value is the
last nonempty value of the headcount for its months. If Dec has a nonmissing Headcount value,
then that value will be returned; otherwise, the Nov value will be checked and returned if
nonmissing.
If a formula-bearing member has a time balance tag, the formula is executed only for level 0
Time members, and the Time dimension is aggregated according to the time balance tag.
The time balance tags provide a built-in calculation along the Time dimension. To perform other
time-based calculations using formulas, such as period-to-date and rolling averages, you can
create a dimension called TimeView and write all time-based formulas on that dimension. Doing
so enables you to use Time Balance calculation functionality without losing the ability to perform
other time-based calculations.
Inventory Calculation
Sales
Additions
Inventory
Jan
50
Feb
46
Mar
43
Apr
41
...
986
You would use an MDX formula on the Beginning Inventory member in order to calculate its
value. Without flow metrics, to obtain each months beginning inventory, the calculator engine
would have to reiterate the MDX formula exponentially.
Inventory = SUM(MemberRange(Jan:Time.CurrentMember), (Additions - Sales)) + Beg_Inventory
To optimize the illustrated example, assign the Inventory member the formula (Addition
Sales), and tag the member as Flow.
987
988
The topics in this section describe how Essbase retrieves data from aggregate storage databases.
Also see Table 190, Query Differences Between Aggregate Storage and Block Storage, on page
903.
MDX Queries
Report Writer which is run through Administration Services Console or the export data
using report_file MaxL statement
Note: Commands that support block-storage-only features (for example, the <SPARSE Report
Writer command) cannot be used with aggregate storage databases. MDX queries fully
support aggregate storage features.
989
990
64
Performing Custom
Calculations and Allocations on
Aggregate Storage Databases
In This Chapter
Performing Custom Calculations and Allocations on Aggregate Storage Databases .............. 991
Custom Calculations on Aggregate Storage Databases .............................................. 992
Allocations on Aggregate Storage Databases ......................................................... 997
Understanding Data Load Buffers for Custom Calculations and Allocations ..................... 1020
Understanding Offset Handling for Custom Calculations and Allocations ........................ 1021
Understanding Credit and Debit Processing for Custom Calculations and Allocations.......... 1022
Chapter 30, Reviewing Examples of Calculation Scripts for Block Storage Databases
For more information about APIs and configuration settings discussed in this chapter, see the
Oracle Essbase API Reference and the Oracle Essbase Technical Reference, respectively.
991
See Understanding Data Load Buffers for Custom Calculations and Allocations on page
1020.
l
Offset handling
See Understanding Offset Handling for Custom Calculations and Allocations on page
1021.
Custom calculations extend the analytical capabilities of Essbase by enabling the execution of
recurring calculations on aggregate storage databases.
You can write custom calculations for aggregate storage databases that update target level 0 cells.
Custom calculation scripts are expressed in MDX.
Using custom calculations, you can do basic math on account balances in a general ledger and
write the results to targeted level 0 members of an Essbase aggregate storage database. You can
perform calculations on account balances or on fixed amounts and can be scheduled to repeat
every accounting period.
Custom calculations on aggregate storage databases can be useful when the database is used for
general ledger reporting, where double-entry accounting is in effect. Debit items, such as assets
and expenses, must balance with credit items, such as equity and revenue.
Use the following workflow to create and execute custom calculations:
l
992
Select an area of the database where the calculation will be executed. You provide the area
at execution time using the target and POV (point of view) parameters.
If you use debit and credit processing, select the debit and credit members in the outline to
write the positive and negative values. You provide these parameters at execution time.
See Understanding Credit and Debit Processing for Custom Calculations and Allocations
on page 1022.
l
If you use offsetting entries, select the area where offsetting entries should be made. You
provide this parameter at execution time using an MDX tuple. If an offset is not specified
or is empty, the offset calculation is not performed.
Note: In general ledger bookkeeping, an offsetting entry is a counterbalancing measure on
the opposite side of the ledger; for example, a $100 credit in January may have a $100
offset added to the debit side of the ledger, so the ledger can be balanced in preparation
for an upcoming expense of that amount.
See Understanding Offset Handling for Custom Calculations and Allocations on page
1021.
l
Criteria
Description
POV
A symmetric region in the database that describes the context in which custom calculations are performed.
Attribute members cannot be used for this argument.
Calculation script
Target
A tuple argument expressed in MDX that defines the region in the database where calculation results are written.
This argument is combined with left side of each formula and the offset to determine where the results and
offset values are written.
Attribute members cannot be used for this argument.
(Optional) Offset
The location in the database where an offsetting value for each source amount is written.
Attribute members cannot be used for this argument.
In double-entry accounting, balancing journal entries for one transaction. Both are MDX member expressions.
The debit member indicates a member to which positive result values are written, and the credit member
indicates a member to which negative result values are written.
Attribute members cannot be used for this argument.
Source region
An MDX set expression specifying the region of the cube referred to by the formulas in the script.
993
The tuple is an MDX specification of one or more members where no two members can be from
the same dimension. The tuple must be on the left side of the equation and is the primary factor
in determining where results of the custom calculation are written.
Only member names are allowed in the tuple expression. The use of member functions is not
supported for custom calculation scripts.
Note: The secondary factor determining the target for results is the target parameter, and the
third factor is the POV parameter. You specify the second and third parameters at
calculation execution time, rather than as part of the calculation script.
The numeric_value_expression is a simple MDX numeric value expression, such as a number or
an arithmetic operation. The expression must be on the right side of the equation. Only
arithmetic operators are permitted. An error is returned if non arithmetic operators (such as
AND, OR, or IF statements) are used.
Member names can be used in the numeric value expression, but the use of member functions
is not supported for custom calculation scripts.
Attribute members cannot be used on the left side of the equation in a custom calculation script.
You must also define the source region, which serves as a performance hint for Essbase. Essbase
pre-fetches the data specified in the source region, and uses that to perform the calculation
specified in the script.
For an example of a custom calculation script, and more information about defining the source
region, see Sample Use Case for Custom Calculations on page 995.
994
Account, in which Account 5740 is a rent expense account and SQFT is a statistical account
used to record square footage for each department.
Scenario, in which the Actual member is where data is posted, and the Allocation member
is where allocations and custom calculations are stored. The Scenario member is a parent
that aggregates the child members Actual and Allocation.
The POV is an MDX set expression indicating where the custom calculation should be executed.
It is specified as follows:
CrossJoin( { ( [Company], [101], [Jan], [Scenario] ) },
Descendants( Geography, Geography.Levels(0)) )
The DebitMember is an MDX member expression indicating a debit member to which positive
result values should be written. It is specified as [BeginningBalance_Debit].
The CreditMember is an MDX member expression indicating a credit member to which negative
and offsetting result values should be written. It is specified as
[BeginningBalance_Credit].
Note: The offset is written to the debit member in the case that the sum of all result values is
negative.
The offset is an MDX tuple expression indicating where offsetting entries should be made. It is
specified as ([Account_NA], [Project_NA]).
The offset expression is combined with Target and POV to determine the location where
offsetting entries are made. If dimensions overlap, the order for resolving the offset location is
the offset, the target, and the POV, in that order.
The target is an MDX tuple expression indicating where to write the results of the custom
calculation. It is specified as(Allocation).
The target expression is combined with POV, and the left side of each line in the custom
calculation script, to determine the location where results are written. If dimensions overlap,
the order for resolving the target location is the left side of the equations, the target, and the
POV, in that order. In this example, results are written to the Allocation member, because the
target overrides the Scenario member specified in the POV.
995
The calculation script is executed in the context of the current POV combination.
Note: Each formula (line in the calculation script) is executed simultaneously, rather than
sequentially. Therefore, you cannot use the result of one formula in a subsequent formula.
To define the source region, examine the custom calculation script and determine which
members are referenced on the right sides of equations. At a minimum, the source region should
include all members from the right sides of the assignment statements in the custom calculation
script.
Define the source region as a single MDX set. If the members on the right sides of the equations
are from more than one dimension, you can use CrossJoin to create the set from two sets.
CrossJoin only accepts two sets, so you may have to use nested CrossJoins.
The source region for the above custom calculation script is:
Crossjoin(
{[AccountB], [AccountD]},
Crossjoin(
{[Proj1], [Proj2]}, {[2007]}
)
)
It is not necessary to include any members in the source region that are not assigned in the script.
For example, if you added to the source region an [AccountC], which is not used in the script,
then it would be ignored, and could cause a slight detriment to performance.
It is not necessary to account for numbers in the source region. For example, the following
assignment in a custom calculation script requires nothing to be added to source region:
([Bud Var]):=10.
996
997
Table 204
Criteria
Description
See
POV
Range
Amount
Basis
When combined with the range, defines the location of basis values
that determine how the amount is allocated
Method for calculating the basis across the basis time span:
Combine
Split
Target
When combined with the range, defines the region in the database
where allocation values are written
998
Criteria
Description
See
Rounding method
A specific location
To a power of 10
(Optional) Offset
Round to location
Understanding Regions
Essbase uses various regions in the database when performing allocations. Each region consists
of at least one member from each dimension defined in the region.
Table 205
Region
Name
Region Definition
Description
Source
The region containing the locations to which allocated values are written.
Target
999
Region
Name
Region Definition
Description
Basis
The region containing the basis values that are used to determine how the source
amount is allocated.
Basis might override part of the POV.
Offset
The region containing the locations to which offset values are written.
MDX tuple expression (where no two members can be from the same dimension)
Constant
For more information about how to express allocation parameter values, see the Oracle Essbase
API Reference.
Project1,CostCenter1
Project1,CostCenter2
Project2,CostCenter1
Project2,CostCenter2
Project3,CostCenter1
Project3,CostCenter2
The allocation is repeated six times by successively setting the allocation context to each
combination.
Values considered as the basis for the allocation are dependent on the POV combination. See
Setting the Basis on page 1004.
Note: If time periods are specified in the POV, you cannot use the amount time span and the
target time span options. See Setting the Amount on page 1002 and Setting the Target
on page 1005, respectively.
CostCtr2
Project1
Project2
Project3
As illustrated in Table 207, if the excluded range is set to the member combination of
(Project2,CostCtr2), Essbase does not write the allocation spread amount to that cell. Therefore,
the sum of allocated values (5) is less than the amount (6). The value of the excluded cell after
the allocation process is either #MISSING or zero.
1001
Table 207
CostCtr2
Project1
Project2
Project3
The range and excluded range can consist of only level 0 members.
For example:
(Acc_1000 + Acc_2000)/2
AccA + AcctB
Balance * 1.1
l
Tuple:
m
The tuple must use one member from every dimension that is not specified in the POV.
For example:
(Balance,Cost_Center_00,Project_00)
(Balance,Cost_Center_00,Actual)
l
Constant:
m
For example:
100
1002
(Optional) Amount context provides additional context, or specificity, for the amount. The
amount context, which can consist of upper-level or level 0 members, can be expressed as
a tuple. By specifying the amount context, you can include a member from a dimension that
is not specified in the POV.
When using amount context, these requirements apply to the amount and the amount
context:
The parameters cannot refer to members in the same dimensions.
Together, the parameters must use members from every dimension not specified in the
POV.
(Optional) Amount time span specifies one or more time periods to be considered for the
amount. The amount value is aggregated over the specified time periods, and the aggregated
amount value is allocated. Time periods must be level 0 members in a Time dimension.
When amount is specified using an arithmetic expression, and amount time span is used,
amount time span takes precedence over any formulas in the amount or any formula
members used in the amount. For example, assume that the amount is specified as Dept_A/
Dept_B and amount time span is set to Jan, Feb, Mar, and Apr for each department, as
shown in Table 208. The amount to be allocated for the POV is calculated by dividing the
amount time span value for Dept_A (10) by the amount time span value for Dept_B (20),
which is 0.5.
Table 208
Dept_A
Dept_B
Jan
Feb
Mar
Apr
Total
10
20
(Optional) Zero amount options specifies how to treat the amount if the value is zero or
#MISSING. You can choose to allocate zero values (the default), skip to the next nonzero
or non-#MISSING amount value, or cancel the entire allocation operation.
You can use amount context and amount time span to achieve the same result, as shown in
following example. The amount is the value of Dept_A, but amount time span is used to focus
only on the months of Jan, Feb, Mar, and Apr for Dept_A. As shown in Table 209, the aggregated
value of the members included in the amount time span (10) is the amount value that is allocated
across the cells in the range.
1003
Table 209
Dept_A
Jan
Feb
Mar
Apr
Total
10
You can achieve the same amount value by specifying amount as an arithmetic expression of
Jan + Feb + Mar + Apr and setting the amount context as Dept_A, as shown in Table 210:
Table 210
Amount Context
Jan
Feb
Mar
Apr
Total
Dept_A
10
(Optional) Basis time span specifies one or more time periods to be considered for the basis.
Time periods must be level 0 members in a Time dimension.
(Required if basis time span is set) Basis time span option specifies how the basis is calculated
across the time periods specified by the basis time span. You can choose to use the basis
value for each time period individually (split) or use the sum of the basis values across the
time periods specified by the basis time span (combine).
m
If basis time span specifies multiple time periods and the target time span specifies one
time period or is empty, you must set the basis time span option to combine. Essbase
ignores the target time span option.
If basis time span and target time span specifies multiple time periods, and you set the
basis time span option to split, the periods specified by basis time span and target time
span must be identical. Essbase ignores the target time span option.
See Understanding Settings for Basis and Target Time Span on page 1009.
l
Zero basis options specifies how to treat a zero basis value. You can choose to skip to the next
nonzero or non-#MISSING amount value or cancel the entire allocation operation. Essbase
processes the zero basis options setting based on the allocation method. See Setting the
Allocation Method on page 1005.
1004
(Optional) Negative basis options specifies how to treat a negative basis value. The options
available for the negative basis options depend on the allocation method used. See Setting
the Allocation Method on page 1005.
Note: The basis is ignored when using the spread allocation method and you have not set any
(Optional) Target time span specifies one or more time periods to be considered for the
target. Time periods must be level 0 members in a Time dimension.
(Required if target time span is set) Target time span option specifies the method for allocating
values across the time periods specified in target time span. You can choose to divide the
amount value or repeat the amount value across the specified time periods.
m
If basis time span specifies multiple time periods, and the target time span specifies one
time period or is empty, you must set the basis time span option to combine. Essbase
ignores the target time span option.
If basis time span and target time span specifies multiple time periods, and you set the
basis time span option to split, the periods specified by the basis time span and target
time span must be identical. Essbase ignores the target time span option.
See Understanding Settings for Basis and Target Time Span on page 1009.
#MISSING, Essbase either leaves the target cell as #MISSING, or, if the target cell already
has a value, overwrites the existing value with zero.
1005
A negative number, Essbase uses the negative basis options setting. You can choose to
use the negative basis value (the default), skip to the next amount value (no data is
allocated for the current amount value, and Essbase skips to the next POV combination),
or cancel the entire operation.
The following examples illustrate the share allocation method. In both examples, the amount
to allocate is 10.
In Table 211, assume that the amount (10) represents the rent expense for a building, and
the basis represents the head count of each department in the range. Essbase uses the basis
values for departments with non-#MISSING head count (Dept_A through Dept_D) to
calculate the allocation share amounts, which is the rent allocation.
The rent allocation for Dept_A is the basis value of Dept_A (3), divided by the sum of valid
basis values across the range (3 + 2 = 5), multiplied by the amount (10): 3/5 * 10 = 6. For
Dept_D, the rent allocation is 2/5 * 10 = 4. The total of the target cells in the range equals
10.
Table 211
Members in Range
Dept_A
Dept_C
Dept_D
Dept_B
In Table 212, assume that all basis values are to be considered in calculating the share
allocation amounts. The allocation for Mbr1 is the basis value of Mbr1 (3), divided by the
sum of valid basis values across the range (3 + -1 + 2 = 4), multiplied by the amount (10):
3/4 * 10 = 7.5. For Mbr3, the allocation is -1/4 * 10 = -2.5; for Mbr4, the allocation is 2/4
*10 = 5. The total of the target cells in the range equals 10.
Table 212
Members in Range
Basis
Target
Mbr1
7.5
Mbr2
#MISSING
Mbr3
-1
-2.5
Mbr4
5.0
The spread method allocates the amount evenly across the range (alloc_spread_amt).
The number used to divide the amount and, therefore, the number of target cells where the
allocation spread amount is to be written, is based on the number of valid basis values in
the range (#_valid_basis_values). The algorithm for calculating the allocation spread
amount:
1006
alloc_spread_amt = amount/#_valid_basis_values
When using the spread allocation method, you can use the optional spread skip options
parameter to skip all basis values in the range that are zero, #MISSING, or negative. You can
specify multiple options.
Basis values and Essbase action:
m
#MISSING, Essbase either leaves the target cell as #MISSING; or, if the target cell already
has a value, Essbase overwrites the existing value with zeros.
If spread skip options is set to skip #MISSING, no data is allocated.
A negative number, Essbase uses the negative basis options setting (which takes
precedence over the spread skip options setting of skip negative). You can choose one
of the following actions:
o
Skip to the next amount value (no data is allocated for the current amount value)
Treat the negative number as $MISSING (no value is allocated to the target cell)
Treat the negative number as a zero (zero is allocated to the target cell)
If all basis values have been skipped (which would make the denominator in the allocation
zero), Essbase uses the zero basis options setting. See Setting the Basis on page 1004.
The following examples illustrate the spread allocation method. In both examples, the
amount to allocate is 10.
In Table 213, assume that the spread skip options parameter is not specified. Therefore,
Essbase considers all four basis members in the range. Essbase divides the amount (10), by
the number of valid basis members in the range (4), and spreads that value (2.5) to each
target cell in the range: 10/4 = 2.5.
Table 213
Members in Range
Basis
Target
Mbr1
2.5
Mbr2
#MISSING
2.5
Mbr3
2.5
Mbr4
-6
2.5
In Table 214, assume that the spread skip options parameter is set to ignore #MISSING and
negative numbers. Therefore, Essbase considers only the two basis members with positive
values (Mbr1 and Mbr3). Essbase divides the amount (10), by the number of valid basis
1007
members in the range (2), and spreads that value (5) to the Mbr1 and Mbr3 target cells: 10/2
= 5.
Table 214
Spread Allocation Method Example: Skip #MISSING and Negative Basis Values
Members in Range
Basis
Target
Mbr1
Mbr2
#MISSING
Mbr3
Mbr4
-6
(Required if rounding allocated values) Round digits specifies the number of decimal places
to which allocated values are rounded. You can choose to round to the nearest integer (the
default), to a specified number of decimal places, or to a power of 10.
Round digits must be a number from -100 to 100 and can be expressed as an integer, an
MDX numeric value expression, or a tuple.
Using an MDX numeric value expression is helpful when the setting for round digits is based
on the currency of the allocated value. For example, assume that the database contains a
dimension named Currency, which is part of the POV, and an associated attribute dimension
named NumCurrencyDigits, which specifies how to round allocated values based on the
currency of the allocated values. You can express round digits as:
Currency.currentMember.NumCurrencyDigits
Note: If, for the rounding method, you choose not to round allocated values, the round
(Required if rounding method is set to a specific location) Round to location specifies a cell
to which to add the total rounding error. Expressed as a tuple, the cell must be in the range
and have the same dimensionality as the range. Round to location can consist of only level
0 members.
1008
Note: If, for the rounding method, you choose an option other than to round to a specific
Balancing Allocations
(Optional) debitMember and creditMember can consist only of level 0 members.
The debit member and the credit member must be two different members from the same
dimension.
debitMember and creditMember work the same for allocations and custom calculations. See
Understanding Credit and Debit Processing for Custom Calculations and Allocations on page
1022.
The number of members that are specified for the basis time span and target time span affect
how Essbase treats the basis time span option and target time span option, respectively, as
summarized in Table 215. In situations where the basis or target time span is empty or set to a
single time period, Essbase ignores any setting that you might have set for the respective basis
or target time span option. In situations where one or both of the basis or target time spans are
set to multiple time periods, Essbase requires a particular setting for the respective basis or target
time span option.
1009
Table 215
Summary: Basis and Target Time Span, and Basis and Time Span Option
Basis Time
Span
Target Time
Span
Basis Time
Span Option
Target
Time Span
Option
See
Empty or
single
member
Empty or
single
member
Ignored
Ignored
Empty or
single
member
Multiple
members
Ignored
Divide or
repeat
Multiple
members
Empty or
single
member
Combine
Ignored
Multiple
members
Multiple
members
Split
Ignored
Multiple
members
Multiple
members
Combine
Divide or
repeat
Basis
1Basis
2Total
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
11
The setting for target time span option determines how the allocation is calculated.
l
Repeat the allocated amount across the specified target time span periods:
1010
212
In this scenario, Essbase performs the allocation for a single period and copies the allocated
amount value to all members in the target time span.
The algorithm Essbase uses:
alloc_amt = (basis_mbr_value/basis_total_range) * amount
As shown in Table 217, for Dec 07,Dept_1, the member basis value (1) is divided by the total
basis across the range (21), and the result (0.04762) is multiplied by amount (1000): (1/21)
* 1000 = 47.62. Essbase copies 47.62 into the cells for Jan 08, Feb 08, Mar 08, and Apr 08.
Essbase continues to perform allocations for Dec 07 for each department. For each target
time span, the sum of the allocated values across the range equals the amount (1000).
Table 217
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
47.62
95.24
142.86
190.48
238.10
285.71
1000
Jan 08
47.62
95.24
142.86
190.48
238.10
285.71
1000
Feb 08
47.62
95.24
142.86
190.48
238.10
285.71
1000
Mar 08
47.62
95.24
142.86
190.48
238.10
285.71
1000
Apr 08
47.62
95.24
142.86
190.48
238.10
285.71
1000
50001
1Total
allocated values
The total allocated amount is the original amount value (1000) multiplied by the number
of target time span members (5): 1000 * 5 = 5000.
l
Divide the allocated amount across the specified target time span periods
In this scenario, Essbase performs the allocation for one period and evenly divides the
allocated amount across all members in the target time span.
The algorithm Essbase uses:
alloc_amt = ((basis_mbr_value/basis_total_range) * amount)/#_target_time_span_periods
As shown in Table 218, for Dec 07,Dept_1, Essbase performs the same calculation as
described for the repeat target time span option scenario to arrive at 47.62. However, this
amount is evenly divided across all five target time span periods for Dept_1; therefore, 9.52
is written in each target cell: 47.62/5 = 9.52. Essbase continues to perform allocations for
each department. For each target time span, the sum of the allocated values across the range
equals (200).
1011
Table 218
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
9.52
19.05
28.57
38.10
47.62
57.14
200
Jan 08
9.52
19.05
28.57
38.10
47.62
57.14
200
Feb 08
9.52
19.05
28.57
38.10
47.62
57.14
200
Mar 08
9.52
19.05
28.57
38.10
47.62
57.14
200
Apr 08
9.52
19.05
28.57
38.10
47.62
57.14
200
10001
1Total
allocated values
The total allocated values across the range is the original amount value (1000): 200 * 5 =
1000.
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
Jan 08
Feb 08
Mar 08
Apr 08
10
Total
151
20
25
12
35
40
1Basis
2Total
for each range member summed across the basis time span periods
basis for the range
The allocation is calculated using the basis time span setting of combine, which uses the sum of
the basis values across the basis time span periods.
1012
1472
As shown in Table 220, the allocated value for each department is written to one target location,
because the target time span is not set to multiple periods. For the allocated amount for Dept_1,
the sum of the basis time span (15) is divided by the total basis for the range (147), and the result
(0.10204) is multiplied by amount (1000): (15/147) * 1000 = 102.04. Essbase continues to
perform allocations for each department in the range.
Table 220
Target
1Total
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
102.04
136.05
170.07
81.63
238.10
272.11
10001
allocated values
The total allocated values across the range is the original amount value (1000).
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
211
Jan 08
27
Feb 08
33
Mar 08
39
Apr 08
10
45
1652
1Total
2Total
The allocation is calculated using the basis time span setting of split, which uses the basis value
for each time period individually.
1013
As shown in Table 222, for Dec 07,Dept_1, the member basis value (1) is divided by the total
basis for the range (165), and the result (0.00606) is multiplied by amount (1000): (1/165) *
1000 = 6.06. Essbase continues to perform allocations for each time period for each department.
Table 222
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
6.06
12.12
18.18
24.24
30.30
36.36
127.27
Jan 08
12.12
18.18
24.24
30.30
36.36
42.42
163.64
Feb 08
18.18
24.24
30.30
36.36
42.42
48.48
200.00
Mar 08
24.24
30.30
36.36
42.42
48.48
54.55
236.36
Apr 08
30.30
36.36
42.42
48.48
54.55
60.61
272.73
10001
1Total
allocated values
The total allocated values across the range is the original amount value (1000).
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
Jan 08
Feb 08
1014
Range
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Mar 08
Total
101
14
18
15
26
30
1Basis
2Total
1132
for each range member summed across the basis time span periods
basis for the range
The setting for target time span option determines how the allocation is calculated.
l
Repeat the allocated amount across the specified target time periods:
In this scenario, Essbase performs the allocation for a single period and copies the allocated
amount value to all members in the target time span.
The algorithm Essbase uses for each range member:
alloc_amt = (sum_across_basis_time_span/basis_total_range) * amount
As shown in Table 224, for Dec 07,Dept_1, the basis for Dept_1 (10) is divided by the total
basis for the range (113), and the result (0.0885) is multiplied by amount (1000): (10/113)
* 1000 = 88.50. Essbase copies 88.50 into the cells for Jan 08, Feb 08, Mar 08, and Apr 08.
Essbase continues to perform allocations for Dec 07 for each department. For each target
time span, the sum of the allocated values across the range equals the amount (1000).
Table 224
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
88.50
123.89
159.29
132.74
230.09
265.49
1000
Jan 08
88.50
123.89
159.29
132.74
230.09
265.49
1000
Feb 08
88.50
123.89
159.29
132.74
230.09
265.49
1000
Mar 08
88.50
123.89
159.29
132.74
230.09
265.49
1000
Apr 08
88.50
123.89
159.29
132.74
230.09
265.49
1000
50001
1Total
allocated values
The total allocated values is the original amount value (1000) multiplied by the number of
target time span members (5): 1000 * 5 = 5000.
l
Divide the allocated amount across the specified target time periods:
In this scenario, Essbase performs the allocation for a single period and evenly divides the
allocated amount across all members in the target time span.
The algorithm Essbase uses:
alloc_amt = ((basis_time_span/basis_total_range) * amount)/#_target_time_span_periods
1015
As shown in Table 225, Essbase performs the same calculation as described for the repeat
target time span option scenario to arrive at 88.50. However, this amount is evenly divided
across all five target time span periods for Dept_1; therefore, 17.70 is written in each target
cell: 88.50/5 = 17.70. Essbase continues to perform allocations for each department. For each
target time span, the sum of the allocated values across the range equals (200).
Table 225
Total
Dept_1
Dept_2
Dept_3
Dept_4
Dept_5
Dept_6
Dec 07
17.70
24.78
31.86
26.55
46.02
53.10
200
Jan 08
17.70
24.78
31.86
26.55
46.02
53.10
200
Feb 08
17.70
24.78
31.86
26.55
46.02
53.10
200
Mar 08
17.70
24.78
31.86
26.55
46.02
53.10
200
Apr 08
17.70
24.78
31.86
26.55
46.02
53.10
200
10001
1Total
allocated values
The total allocated values across the range is the original amount value (1000): 200 * 5 =
1000.
Criteria
Definition
POV
Dept_A, Dept_B
Amount
Dept_A = 1000
Dept_B = 2000
Basis
Target
1016
Criteria
Definition
Range
CostCenter1
CostCenter2
CostCenter3
CostCenter4
Dept_A
Dept_B
Each POV combination has its own set of basis values that are used in calculating the allocation:
the head count for each cost center in the range and the total Jan 2008 head count, as shown in
Table 227:
Table 227
POV
CostCenter1
CostCenter2
CostCenter3
CostCenter4
Dept_A
11
Dept_B
10
15
For each POV, Essbase divides the head count of each cost center (the basis value of each
member) by the total head count of the range (the basis value of the range), and then multiplies
that value by the total rental amount for each department (amount). For example, for
Dept_A,CostCenter1, the member basis value (1) is divided by the basis of the range (11), and
the result (0.09090909) is multiplied by amount (1000): (1/11) * 1000 = 90.90909. For
Dept_B,CostCenter1, the allocated amount is 666.6667: (5/15) * 2000 = 666.6667. Table 228
shows the allocated share amount for each cost center:
Table 228
Amount Value
POV
CostCenter1
CostCenter2
CostCenter3
CostCenter4
Dept_A
90.90909
181.8182
272.7273
454.5455
1000
Dept_B
666.6667
1333.333
2000
1017
The objective of this sample use case is to use the share allocation method to proportionally
redistribute the total monthly rent expense across departments, based on the square footage
each department occupies.
Consider an outline with the following dimensions:
l
Company: Contains multiple ledgers. The rent expense allocations take place in the Vision
US ledger.
Department: Contains the following members:
m
100, which stores the total monthly rent expense, of $100,000, for Vision US. This
amount is proportionally allocated to the children of department 999.
999, which is the parent of the following departments:
o
SQFT, which is a statistical account used to record square footage for each department
You can accomplish the rent expense allocation in several ways, each with the same result. Two
scenarios are presented. For each scenario, assume that the following parameters are defined as
follows:
l
101
102
103
Basis: The square footage of each range member for the period of activity (which is monthly).
SQFT,PeriodActivity
1018
Zero basis option: If the basis value is zero, cancel the allocation operation.
Basis time span option: (Default) Split, use the basis value for each time period individually.
Rounding method: Round allocation values to the nearest 1,000 and add the total rounding
error to department 101.
POV: Consists of one member, Vision US, from the Company dimension.
Because only one member from one dimension is specified, the POV does not change and,
therefore, the allocation is performed only once.
Amount: The source value of the allocation is from the following cross-dimensional
member:
5740,100,Beginning Balance
Because only one member from each dimension is specified, the POV does not change and,
therefore, the allocation is performed only once.
l
Amount: The source value of the allocation is from the following cross-dimensional
member:
100,Beginning Balance
Target: Not set. Because the combination of POV, target, debit member/credit member, and
range uses members from all dimensions, the target can be empty.
Offset: Write the offset entry to department 100.
1019
Scenario 3: User 1 posts revenue and User 2 runs the allocation concurrently.
The allocation results are based on the updated or prior revenue values, depending on which
user operation started first.
Oracle does not recommend running these operations concurrently when using formula
members in the amount or the basis.
Also, assume that an MDX formula is used to calculate the year-to-date revenue for the
allocation. The complexity of the formula can affect the result:
l
Scenario 4: The year-to-date revenue formula involves members from one dimension and
uses only the following arithmetic expressions: +, -, /, and *.
The allocation results are based entirely on either the updated or prior revenue values.
Oracle recommends using simple MDX formulas, as described in scenario 4.
Scenario 5: The year-to-date revenue formula is more complicated than the formula in
scenario 4.
It is possible that some of the allocation results are based on the updated revenue values and
some are based on the prior revenue values.
1020
If you want to perform allocations and custom calculations concurrently with data loads and
postings, set the resource usage for the data load buffers that you create for data loads and
postings to a maximum of 0.8 (80%). The lower you set the resource usage setting, the greater
the number of allocations and custom calculations that can run concurrently with data loads
and postings. You can also configure the amount of time Essbase waits for resources to become
available in order to process load buffer operations.
To configure data load buffers, use the alter database MaxL statement with the initialize
load_buffer grammar and ASOLOADBUFFERWAIT configuration setting.
:=
:=
:=
:=
7;
-4;
0;
10;
Therefore, if an offset is required, it must also be 13. Assume that an offset is written to a member
called Offset_Member.
Debit
mbr1
7
mbr2
mbr3
0
mbr4
10
mbr_offset
Total
17
Credit
4
13
17
When an offset is used, credit and debit processing is reversed. The following calculation
sequence occurs when an offset is used with credit and debit processing:
1. For the given POV, get the sum of results written by the calculation script (in this case, 13).
2. If the sum is positive, write it to the credit member in the target database.
1021
3. If the sum is negative, change it to a positive and write it to the debit member in the target
database.
1022
65
In This Chapter
Aggregate Storage Security ........................................................................... 1023
Managing Storage for Aggregate Storage Applications............................................. 1024
Managing the Aggregate Storage Cache............................................................. 1025
Improving Performance When Building Aggregate Views on Aggregate Storage Databases .... 1026
Aggregate Storage Database Restructuring ......................................................... 1027
Exporting Aggregate Storage Databases............................................................. 1033
Calculating the Number of Stored Dimension Levels in an Aggregate Storage Outline ......... 1034
The information in this chapter applies only to aggregate storage databases and is not relevant
to block storage databases.
Also see:
l
1023
For aggregate storage applications, Tablespace Manager controls data retrieval and storage, using
tablespace definitions to manage data storage and work areas on the disk.
defaultContains database data structure and database values (After data is loaded, the
metadataContains information about file locations, files, and objects contained in the
database
l
Note: You can modify or delete file locations used to store information within a tablespace if
1024
Based on the maximum size specified for files, Essbase writes multiple files; for example,
ess00001.dat, ess00002.dat, and so on. If you back up database files to other media, do
not set a maximum tablespace file size greater than the size that the media can handle.
Defining Tablespaces
You define tablespace definitions for each aggregate storage application.
Topic
Location
Administration Services
Managing Tablespaces
MaxL
alter tablespace
memory.
You can view the current aggregate cache memory allocation and the maximum aggregate cache
size setting. Changing the setting may optimize memory use. The default maximum cache size,
32 MB, is the minimum setting size. You can use the size of input-level data to determine when
to increase the maximum size for the cache. Administration Services and MaxL display the size
of input-level data as the aggregate storage database property: Size of level 0 values.
A 32 MB cache setting supports a database with approximately 2 GB of input-level data. If the
input-level data size is greater than 2 GB by some factor, the aggregate storage cache can be
increased by the square root of the factor. For example, if the input-level data size is 3 GB
(2 GB * 1.5), multiply the aggregate storage cache size of 32 MB by the square root of 1.5, and
set the aggregate cache size to the result: 39.04 MB.
For aggregation materialization performance, consider the number of threads set for parallel
calculation. The aggregation materialization process uses multiple threads that divide the
aggregate storage cache. Increasing the number of threads specified in the CALCPARALLEL
configuration setting for aggregate storage applications or databases may require an increase in
aggregate storage cache size. See the CALCPARALLEL configuration setting in the Oracle Essbase
Technical Reference.
1025
Note: Setting the number of threads higher than the number of processors may improve
Topic
Location
Administration Services
MaxL
query application
alter application
Note: A changed aggregate storage cache setting becomes effective when the application is
restarted.
This message sometimes occurs when an aggregate storage database is larger than a few hundred
million input cells.
To improve the performance of building aggregates, take the following steps.
1. Increase the size of the aggregate storage cache to at least 512 MB or 20% of the input data
size, whichever is smaller. (If the cache setting is already greater than this amount, proceed
to the next step.) You can use Administration Services Console or the following MaxL
command:
alter application appname set cache_size xMB
Gradually increase the n value until the message disappears and optimal aggregation
performance is reached. For a database that contains:
l
1026
Clear the aggregate views; then reselect and rebuild them. If the message still appears,
increase the setting and try again.
Performance of building aggregate views may not improve until the message no longer
occurs. When the message no longer occurs and performance no longer improves, stop
increasing the setting.
Note: If you increase the ASOSAMPLESIZEPERCENT setting too high, performance will
start to degrade again. The optimal setting for a database larger than 1 billion cells
will probably be less than 3%. For more information on
ASOSAMPLESIZEPERCENT, see the Oracle Essbase Technical Reference.
Database restructures may be forced by some aggregate storage database outline changes,
including changes to hierarchies. A hierarchy comprises a top member and its descendants.
l
A dynamic hierarchy includes only one stored level. The Accounts dimension is a dynamic
hierarchy.
An attribute dimension is one hierarchy. The generation 1 member is the top member of
the hierarchy.
If a standard dimension is not tagged as multiple hierarchies enabled, it is one hierarchy.
The generation 1 member is the top member of the hierarchy.
If a standard dimension is tagged as multiple hierarchies enabled, it contains multiple
hierarchies. The generation 2 members are the top members of the hierarchies. For example,
the Products dimension in ASOsamp.Sample contains two hierarchies. The top members
are the generation 2 members All Merchandise and High End Merchandise.
1027
User-Outline Changes
Add, delete, or move a standard dimension
Essbase-Restructure
Level
Clears data and aggregate
views, and performs full
outline restructure
Very high
Very high
See:
m
Performance Impact
Storage requirement is up
to three times the size of the
database file (.dat file).
User must select the
aggregate views and rerun
the database aggregation.
1028
High
Storage requirement is up
to three times the size of the
database file (.dat file).
User-Outline Changes
Essbase-Restructure
Level
Performance Impact
Low
Very low
Storage requirement is up
to three times the size of the
affected views. Such
aggregate views normally
exist only if you used query
tracking to select views
based on usage. See
Selecting Views Based on
Usage on page 980.
Very low
Add a child branch as the last child branch of an existing parent without
crossing a power of 2 boundary and without changing the number of levels
in the hierarchy.
Examples:
l
Renames a member
Changes a formula
Changes an alias
1029
User-Outline Changes
On nonattribute dimensions with stored level 0 members:
Add a child that crosses a power of 2 boundary as the last child of a parent.
For example, if a parent member has three children and you add a fourth
and fifth child, the fifth child crosses the power of 2 boundary. See
Example: Addition of Child Members on page 1032.
Essbase-Restructure
Level
Clears aggregate views,
and performs full outline
restructure
Performance Impact
Very high
For scenarios in which adding a child branch as the last child branch of
an existing parent that crosses a power of 2 boundary or changing the
number of levels in the hierarchy, which triggers a full outline restructure,
see Example: Addition of Child Branches on page 1032.
Outline-Change Examples
Subtopics
l
l
l
l
l
This sections contains examples of the more complicated outline changes described in Table 229,
Aggregate Storage Restructuring Levels, on page 1028.
Adding the child member All to Ratios does not change the number of stored levels in the
Measures dimension. Saving the outline triggers a light restructure.
1030
Adding a child member does not change the number of levels (two) in the hierarchy. Adding a
seventh or eighth child member at the end is allowed; however, adding a ninth child member
crosses the power of 2 boundary (see Example: Addition of Child Members on page 1032),
requiring a full outline restructure.
1031
However, adding a child member under Computers and Peripherals increases the number of
children under Computers and Peripherals from three to four. Adding a fourth child, which
must be added after the existing members, does not cross the boundary of 2 or 4. The child must
be added after existing members. When the outline is saved, Essbase performs a light restructure.
1032
Adding a child branch with three child members crosses the power of 2 boundary and may
require that Essbase perform a full outline restructure. However, if Systems already had three
members, the power of 2 boundary would be four and, at most, four children can be added to
Other Peripherals without triggering a full outline restructure.
To create backups
The default location for export files is ARBORPATH/app/. You can specify an alternate location;
see the Oracle Essbase Administration Services Online Help or the Oracle Essbase Technical
Reference.
Aggregate storage database exports have limits:
l
To avoid creating export files larger than 2 GB, Essbase may create multiple export files that
include a number suffix in the name, as follows: _1, _2, and so on. For example, if the first file
name is /home/exportfile.txt, the next file is /home/exportfile_1.txt.
To improve performance, you can export data in parallel.
Topic
Location
Administration Services
Exporting Databases
MaxL
export data
1033
To determine the factor for each dimension, use the following guidelines:
l
For stored dimensions, for an initial dimension factor, count the nonlabel-only levels.
m
If a stored dimension has attribute dimensions, count the levels in each attribute
dimension, and add that number to the dimension factor. Then, if all level 0 members
of the dimension have an attribute from a specific attribute dimension, subtract 1 for
each attribute dimension in which this occurs.
If a stored dimension has additional stored hierarchies, count the number of nonlabelonly levels in each stored hierarchy, and add the count to the dimension factor. Do not
count a level if it comprises only shared members.
Dynamic hierarchies in a stored dimension do not affect the dimension factor.
In Administration Services Console, right-click a database, select Edit, and then Properties.
On the Statistics tab, under Aggregate storage statistics, each non-attribute dimension in
the outline is listed, showing the number of stored levels (which is the dimension level factor)
in each dimension. For example:
Dimension [Products] has [6] levels, bits used 7
1034
Part XI
Appendixes
In Appendixes:
l
l
l
l
l
l
l
l
l
Limits
Setting Up Sample Applications
Troubleshooting Essbase Errors
Estimating Disk and Memory Requirements
Using ESSCMD
Naming Conventions for Essbase
Differences in Security-Related Operations in Different Security Models
Essbase 32-Bit and 64-Bit Compatibility
Essbase Features No Longer Supported or Deprecated in Previous Releases
1035
1036
Limits
A
In This Appendix
Artifact
Limits
Alias name
Application name
Application description
1037
Artifact
l
Limits
l
Database description
Dimension name
Directory path
For example:
EPM_ORACLE_HOME/products/Essbase/
EssbaseServer/bin
Environment variable name
1038
1024 bytes
Artifact
Limits
Filter name
Group name
LRO URL
Member name
20 levels
320 bytes
256 bytes
320 bytes
256 bytes
1024
80
-32768 to 32767
Trigger name
UDA
User name
1039
Artifact
Limits
20
64
Artifact
Limits
65535 (including all stored hierarchies, dynamic hierarchies, and any attribute dimensions based
on the dimension)
4,294,967,295 MB
264
The limit is based on the number of cells that Essbase processes in the query, which is the product
of the member count across all dimensions, not on the number of cells contained in the output
report.
You might encounter this limit when using a client interface (such as Oracle Hyperion Financial
Reporting) that suppresses missing data in order to generate a relatively small report compared
to the size of the query.
32
8
For information about how Essbase uses export threads, see the data export MaxL command for
block storage database and the EXPORTTHREADS configuration setting in the Oracle Essbase
Technical Reference.
1040
Artifact
Limits
255
When working with an aggregation storage database outline, dimensions that you delete count
toward the total number of dimensions because Essbase does not reclaim the ID of deleted
dimensions. Therefore, if you create and then delete dimensions, the maximum number of
dimensions is reduced by the number of deleted dimensions.
Artifact
Limits
The product of the stored member count of sparse dimensions cannot exceed the following values:
Longer member names, which can occur if using multibyte characters, decrease the number of
members that are allowed.
32
1024
For information about how Essbase uses export threads, see the data export MaxL command for
aggregate storage database and the EXPORTTHREADS configuration setting in the Oracle Essbase
Technical Reference.
255
1041
Table 234
Artifact
Limits
255
256
65536
Artifact
Limits
Formula size
65534 bytes
30,000
Exceeding this limit results in an error.
64 KB
64 KB
1042
B
In This Appendix
Introduction............................................................................................. 1043
Loading Data into Sample Databases ............................................................... 1044
Providing User Access to Sample Applications ..................................................... 1044
Preparing the Aggregate Storage Sample Application.............................................. 1045
Preparing the Partitioning Sample Applications..................................................... 1045
Introduction
The Essbase Server installation includes sample applications that are designed to familiarize you
with Essbase features. Each application contains one or more databases and each database has
an associated data load file, as described in Table 236:
Table 236
Application
Database
Sample
Basic
Calcdat.txt
Interntl
Currcalc.txt
Xchgrate
Rates.txt
Basic
Data.txt
Company
Calccomp.txt
East
Calceast.txt
Basic
Calcdat.txt
Sample
dataload.txt1
Demo
See the Oracle Essbase Technical Reference and documentation for Report Writer.
Samppart
Demonstrates Essbase Partitioning features. See Chapter 15, Designing Partitioned Applications.
Sampeast
Demonstrates Essbase Partitioning features. See Chapter 15, Designing Partitioned Applications.
Sample_U
Contains a Unicode-mode version of the Basic database in the Sample application, which includes alias
tables in English and four other character sets. Characters in this application are encoded in UTF-8.
ASOsamp
Demonstrates aggregate storage features.
1The
ASOsamp.Sample database must be loaded using the dataload.rul rules file. The other samples do not require a rules file.
1043
other user name. See Creating the Partition User on page 1046.
From Enterprise View or a custom view, navigate to the appropriate Essbase Server, application, and
database.
For Data Source, click Find Data File. In the Essbase Server tab, navigate to the correct
data source. For Files of Type, ensure that Data files (*.txt) is selected.
For Rules File, if the data source requires a rules file, click Find Rule File. In the Essbase
Server tab, navigate to the rule file. For Files of Type, ensure that Rules file (*.rul) is
selected.
Note: The ASOsamp database must be loaded using the dataload.rul file. The other
1044
From Enterprise View, find the appropriate Essbase Server and application.
For example, if you want all users to have at least Write access to all databases in the
application (meaning that all users can update data values), select Write.
Click Apply.
The selected application is ready for use. If you want to provide access to another application,
repeat the procedure.
For instructions on loading data to aggregate storage databases, see the Oracle Essbase
Administration Services Online Help.
Precalculate aggregations on the database to improve retrieval times, using one of these methods:
l
SamppartCompany
SampeastEast
The Partitioning applications and databases include partition definitions stored in .ddb files.
The .ddb files define the map between member combinations in the target database, Company,
and the source database, East.
For the Partitioning applications to work in your environment, you may need to create a user
named partitionuser (see Creating the Partition User on page 1046), or change the embedded
user names in the .ddb files (see Changing Embedded User Names in Sample Partition
Definitions on page 1046).
Note: Do not make changes to user name information directly in the .ddb files.
To create partitionuser:
1
In Enterprise View, navigate to the Administration Server's node and select the appropriate Essbase
Administration Server name.
For Create user on Essbase Administration Server, enter partitionuser for User name.
Click OK.
To change the user name in the Samppart.Company and Sampeast.East .ddb files:
1
In Enterprise View, expand the Applications node and select the Samppart application.
1046
Expand the Partitions node, select Source Databases, and then double-click:
servername:Sampeast:East [transparent]
For Data Source and Data Target, select a user name from User list.
and the Data Target groups, you do not need to repeat this process to change the user
name in the Sampeast.East .ddb file.
1047
1048
In This Appendix
Understanding Fatal Error Handling .................................................................. 1049
Recovering from Dense Restructure Failures ........................................................ 1050
Recovering from Sparse Restructure Failure......................................................... 1050
Synchronizing Member Names in Report Scripts and Database Outlines ........................ 1050
Handling Essbase Server Problems When Running Multiple Reports ............................. 1051
References.............................................................................................. 1051
The kernel cannot perform an operation that is necessary to ensure data integrity (for
example, disk space is insufficient).
The kernel encounters a condition that can lead to data corruption.
When the kernel encounters a fatal error, it shuts down and restarts, attempting to reinitialize
itself and proceed with database recovery. When recovery begins, Essbase displays an error
message similar to this one:
1080022 Reinitializing the Essbase Kernel for database dbname due to a fatal error...
This message is followed by other informational messages related to database recovery, such as
this one:
1080028 Performing transaction recovery for database dbname during fatal error
processing.
When you see such messages, the kernel has shut down and is attempting to restart. Check the
Essbase Server log and determine whether Essbase issued a fatal error message just before it
generated the reinitialization messages. See Using Essbase Server and Application Logs on
page 736.
If the kernel did encounter a fatal error, you must usually restart any operation that was active
at the time of the fatal error. If the operation was a calculation or a data load, you may be able
to continue where the operation left off; check the Essbase Server log to see how far Essbase
1049
processed the operation. When in doubt, restart the operation. See What to Expect if a Server
Interruption Occurs on page 789.
If the kernel did not encounter a fatal error, contact your software providers technical support
to determine what caused the kernel to shut down and restart.
See Contents of the Essbase Server Log on page 727 for descriptions of the contents of the
Essbase Server log. See Essbase Server and Application Log Message Categories on page 734
for information about identifying the component where the error occurred.
Delete the temporary files, to free disk space and to avoid conflicts during the next database restructure.
To recover from a failure during step 1, step 3, or step 4 of Dense Restructures on page
842:
Review the disk directory and determine how far restructuring has progressed.
If all but step 4 is complete, rename the temporary files to the correct file names.
1050
References
Chapters related to partitions, currency conversion, and data load have basic troubleshooting
information in the relevant chapters.
For information about restoring from backups, see the Oracle Hyperion Enterprise Performance
Management System Backup and Recovery Guide.
For information about specific error messages, see Oracle Essbase Error Message Reference.
For information about error and exception logs, see Using Essbase Logs on page 726.
1051
1052
D
In This Appendix
Introduction............................................................................................. 1053
Understanding How Essbase Stores Data ........................................................... 1053
Determining Disk Space Requirements .............................................................. 1054
Determining Memory Requirements.................................................................. 1067
Introduction
This appendix uses a worksheet approach to help you keep track of the many components that
you calculate. If you are using a printed version of this book, you can photocopy the worksheets.
Otherwise, you can simulate the worksheets on your own paper. Labels, such as DA and MA,
help you keep track of the various calculated disk and memory component values.
An Essbase database comprises many components. In addition to an outline file and data file,
Essbase uses several types of files and memory structures to manage data storage, calculation,
and retrieval operations.
Table 237 describes the major components to consider when you estimate the disk and memory
requirements of a database. Yes means the type of storage indicated is relevant, No means
that it is not.
Table 237
Storage Unit
Description
Disk
Memory
Outline
A structure that defines all elements of a database. The number of members in an outline determines
the outline size.
Yes
Yes
1053
Storage Unit
Description
Disk
Memory
Data files
Files in which Essbase stores data values in data blocks in data files.
Yes
Yes
Named essxxxxx.pag, where xxxxx is a number. Essbase increments the number, starting with
ess00001.pag, on each disk volume. Memory is also affected, because Essbase copies the files
into memory.
Data blocks
Subdivisions of a data file. Each block is a multidimensional array that represents all cells of all
dense dimensions relative to a particular intersection of sparse dimensions.
Yes
Yes
Index files
Files that Essbase uses to retrieve data blocks from data files. Named essxxxxx.ind, where
xxxxx is a number. Essbase increments the number, starting with ess00001.ind, on each disk
volume.
Yes
Yes
Index pages
Subdivisions of an index file. Contain index entries that point to data blocks. The size of index pages
is fixed at 8 KB.
Yes
Yes
Index cache
A buffer in memory that holds index pages. Essbase allocates memory to the index cache at startup
of the database.
No
Yes
A buffer in memory that holds data files. When direct I/O is used, Essbase allocates memory to the
data file cache during data load, calculation, and retrieval operations, as needed. Not used with
buffered I/O.
No
Yes
Data cache
A buffer in memory that holds data blocks. Essbase allocates memory to the data cache during
data load, calculation, and retrieval operations, as needed.
No
Yes
Calculator cache
A buffer in memory that Essbase uses to create and track data blocks during calculation operations.
No
Yes
Calculate the factors identified in Calculating the Factors to Be Used in Sizing Disk Requirements on
page 1055.
See Estimating Disk Space Requirements for One Database on page 1059.
See Estimating the Total Essbase Server Disk Space Requirement on page 1066.
Note: The database sizing calculations in this chapter assume an ideal scenario with an optimum
database design and unlimited disk space. The space required is difficult to determine
precisely because most multidimensional applications are sparse.
1054
Label
DA
DB
DC
DD
Value
To determine the potential number of data blocks, assume that data values exist for all
combinations of stored members.
Using Table 239 as a worksheet, list each sparse dimension and its number of stored members. If more
than seven sparse dimensions exist, list the dimensions elsewhere and include all sparse dimensions
in the calculation.
Shared members
Dynamic Calc members (Dynamic Calc And Store members are stored members)
Table 239
1055
Multiply the number of stored members of the first sparse dimension (line a.) by the number of stored
members of the second sparse dimension (line b.) by the number of stored members of the third sparse
dimension (line c.), and so on:
a * b * c * d * e * f * g (and so on)
= potential number of blocks
Write the resulting value to the cell labeled DA in Table 238 on page 1055.
Example
The Sample.Basic database contains the following sparse dimensions:
l
Estimate a database density factor that represents the percentage of sparse dimension stored-member
combinations that have values.
1056
Write the number of actual blocks to the cell labeled DB in Table 238 on page 1055.
Example
The following three examples show different levels of sparsity and assume 100,000,000 potential
data blocks:
l
Using Table 240 on page 1058 as a worksheet, enter each dense dimension and its number of stored
members. If more than seven dense dimensions exist , list the dimensions elsewhere, and include all
dense dimensions in the calculation.
Shared members
Dynamic Calc members (Dynamic Calc and Store members are stored members)
1057
Table 240
Multiply the number of stored members of the first dense dimension (line a) by the number of stored
members of the second dense dimension (line b) by the number of stored members of the third dense
dimension (line c), and so on, to determine the total number of cells in a block:
a * b * c * d * e * f * g (and so on)
= the total number of cells
Multiply the resulting number of cells by 8 bytes to determine the expanded block size:
(Total number of cells) * 8 bytes per cell
= expanded block size
Write the resulting value to the cell labeled DC in Table 238 on page 1055.
Example
The Sample.Basic database contains the following dense dimensions:
l
Perform the following calculations to determine the potential size of a data block in Sample.Basic:
12 * 8 * 2 = 192 data cells
192 data cells
* 8 bytes
= 1,536 bytes (potential data block size)
1058
If you are not using compression, or if you have enabled RLE compression, skip this calculation
and proceed to Stored Data Files on page 1060.
Note: Due to sparsity also existing in the block, actual (compressed) block density varies widely
from block to block. The calculations in this discussion are only for estimation purposes.
If the database is loaded, you can see the size of an expanded data block on the Statistics
tab of the Database Properties dialog box of Administration Services. Use the value that
is displayed for Block Density.
If you want to estimate block density prior to loading data, estimate the ratio of existing
data values to potential data values.
Write the resulting block size to the cell labeled DD in Table 238 on page 1055.
Example
Assume an expanded block size of 1,536 bytes and a block density of 25% (.25):
1,536 bytes
* .25
= 384 bytes (compressed block size)
Database Name:
Database Component
Size
DE
DF
DG
1059
Database Name:
Database Component
Size
DH
DI
DE + DF + DG + DH
Linked Reporting Objects Considerations on page 1065, if needed
DJ
Repeat this exercise for each database on the server. After estimating disk space for all databases
on the server, proceed to Estimating the Total Essbase Server Disk Space Requirement on page
1066.
In some situations Essbase chooses what it considers the best method at the block level.
Size of expanded data block (value DC from Table 238 on page 1055)
Write the result in cell labeled DE in Table 241 on page 1059. Proceed to Index Files on page
1062.
For example, if there are 1000 blocks, the average expanded block size is 2000 bytes, and 30%
of cells are #MISSING, the result is:
1000 * (72 + 2000 * (1/64 + 0.7) )
= 1000 * 1503
= 1,503,000 bytes (approximately)
Write the result in cell labeled DE in Table 241 on page 1059. Proceed to Index Files on page
1062.
Index-Value Compression
To estimate database size when the compression option is Index-value, use the formula:
Number of blocks * (72 bytes
+ (1.5 * database density * expanded data block size)
Write the result in cell labeled DE in Table 241 on page 1059. Proceed to Index Files on page
1062.
RLE Compression
To estimate database size when the compression option is RLE, use the formula for calculating
Bitmap Compression.
When the compression method is RLE, Essbase automatically uses the bitmap or Index-value
method for a block if it determines that better compression can be gained. Estimating using the
bitmap calculation estimates the maximum size.
Write the result in cell labeled DE in Table 241 on page 1059. Proceed to Index Files on page
1062.
1061
zlib Compression
To estimate database size when the compression option is zlib, use the formula for calculating
Bitmap Compression.
Determining the size of a data block when zlib compression is used is difficult. Individual blocks
could be larger or smaller than if compressed using other compression types. Calculating using
the bitmap compression formula at least provides an approximation to use for this exercise.
Write the result in cell labeled DE in Table 241 on page 1059. Proceed to Index Files on page
1062.
Index Files
The calculation for the space required to store the index files (essxxxxx.ind) uses the following
factors:
l
The minimum size for the index is 8,216,576 bytes (8 MB). To calculate the size of a database
index, including all index files, perform the following calculation:
number of existing blocks * 112 bytes = the size of database index
In the cell labeled DF in Table 241 on page 1059, write whichever is the larger number: the results
of the calculation or 8,216,576.
Example
Assume a database with 15,000,000 blocks.
15,000,000 blocks
* 112
= 1,680,000,000 bytes
Note: If the database is already loaded, select the Storage tab on the Database Properties window
Fragmentation Allowance
If you are using bitmap or RLE compression, some fragmentation occurs, the amount of which
is based on individual database and operating system configurations and cannot be precisely
predicted.
As a rough estimate, calculate 20% of the compressed database size (value DE from Table 241
on page 1059) and write the result to the cell labeled DG in the same table.
Example
Calculating fragmentation allowance assuming a compressed database size of 5,769,000,000
bytes:
1062
5,769,000,000 bytes
* .2
= 1,153,800,000 bytes
Outline
The space required by an outline can have two components.
l
The main area of the outline is a component of both disk and memory space requirements
and is calculated using the following factors:
m
The attribute association area of an outline is a component only of disk space and is
calculated using the following factors:
m
Estimate the main area of the outline by multiplying the number of members by a name-length factor
between 350 and 450 bytes.
If the database includes few aliases or very short aliases and short member names, use a
smaller number within this range. If you know that the member names or aliases are very
long, use a larger number within this range.
Because the name-length factor is an estimated average, the following formula provides only
a rough estimate of the main area of the outline:
number of members
* name-length factor
Note: See Appendix A, Limits, for the maximum sizes for member names and aliases.
For memory space requirements calculated later in this chapter, use the size of the main area
of the outline.
For disk space requirements, if the outline includes attribute dimensions, calculate the size of the
attribute association area for the database. Calculate the size of this area for each base dimension.
Multiply the number of members of the base dimension by the sum of the count of members of all
attribute dimensions associated with the base dimension, and then divide by 8:
(number of base-dimension members * sum of count of attribute-dimension members)/8 =
size of attribute association area for a base dimension
Note: Within the count of members, do not include Label Only members and shared
members.
Sum the attribute association areas of each dimension to determine the total attribute association area
for the outline.
1063
For the total disk space required for the outline, add together the main outline area and the attribute
association area:
main area of outline + total attribute association area
Write the result of this calculation to the cell labeled DH in Table 241 on page 1059.
Example
Assume the outline has the following characteristics:
l
26,000 members
A base dimension Product (23,000 membersexcluding Label Only members and shared
members) with two attribute dimensions associated with itOunces (20 members) and
Pkg Type (50 members)
A base dimension Market (2,500 membersexcluding Label Only members and shared
members) with one associated attribute dimension, Population (12 members)
* 26,000 members
= 10,400,000 bytes
= 201,250 bytes
= 3,750 bytes
3. Sum these areas for the total attribute association area for the database:
201,250 bytes + 3,750 bytes = 205,000 bytes
4. For a total estimate of outline disk space, add the main area of the outline and the total
attribute association area:
10,400,000 bytes
requirement)
+ 205,000 bytes
Note: Do not use this procedure to calculate outline memory space requirements. Use the
Work Areas
Three processes create temporary work areas on the disk:
l
For recovery purposes, Essbase maintains a data recovery area on the disk. The size of this
area increases until the database is restructured.
During restructuring, Essbase uses a restructuring work area on the disk.
1064
During upgrade from prior releases of Essbase, for recovery purposes, Essbase creates a copy
of the database in a migration work area.
To create these temporary work areas, Essbase may require disk space equal to the size of the
entire database. Restructuring and migration need additional work space the size of the outline.
Because none of these activities occur simultaneously, a single allocation can represent all three
requirements.
To calculate the size of a work area used for restructuring, migration, and recovery, calculate the
sum of the sizes of the following database components from Table 241 on page 1059:
l
Use the following formula to calculate the size of the work area:
work area = size of compressed data files
+ size of index files
+ fragmentation allowance
+ outline size
Write the result of this calculation to the cell labeled DI in Table 241 on page 1059.
The size of the object. Because Essbase copies files used as LROs to the server, you must
know the combined size of all files you are using as LROs.
Note: You can set a limit on the size of a linked object, if the linked object is a file (as opposed
The size of the LRO catalog, where the Essbase Kernel stores information about LROs. Cell
notes and URLs are also stored in the catalog. A catalog entry is stored as an index page. For
every catalog entry, Essbase uses 8 KB.
Estimate the size of the objects. If a limit is set, multiply the number of LROs by that limit. Otherwise,
sum the size of all anticipated LROs.
Size the LRO catalog. Multiply the total number of LROs by 8,192 bytes.
Add together the two areas and write the result of this calculation to the cell labeled DJ in Table 241
on page 1059.
1065
Example
Assume the database uses 1,500 LROs, which comprise the following:
l
See also Block Storage Database Limits on page 1041 for Linked Reporting Objects
considerations.
In the worksheet in Table 242, list the names and disk space requirements that you calculated for each
database.
Sum the database requirements and write the total in bytes in the cell labeled DL.
In the cell labeled DM, write the disk space requirement for the software installed on the server; for
example, 209,715,200 bytes.
For the total server disk space requirement in bytes, sum the values in cells DL and DM. Write this value
in the cell labeled DN.
Convert the total in cell DN to MB by dividing the value by 1,048,576 bytes. Write this value in the cell
labeled DO.
Table 242
List of Databases1
a.
1066
Size
List of Databases1
Size
b.
c.
d.
e.
f.
g.
Sum of database disk sizes:
DL:
a + b + c + d + e + f + g
Size in bytes for Essbase server software
DM:
DN:
DL + DM
Total Essbase Server disk requirement in megabytes (MB):
DO:
DN / 1,048,576 bytes
1See
Calculate the factors identified in Factors to Be Used in Sizing Memory Requirements on page
1068.
See Estimating the Total Essbase Server Disk Space Requirement on page 1066.
1067
Value
MI:
MJ:
MK:
The calculations in this chapter do not account for the following factors that have complex
implications on how much memory is used and are not included in the discussion:
l
Cache memory locking. Whether ache memory locking is enabled affects how the operating
system and Essbase manage memory. See Deciding Whether to Use Cache Memory
Locking on page 824.
Different operation types and their associated cache allocations. Data load, data retrieval,
and calculation operations set aside memory for the data file, data, and calculation caches,
plus some overhead associated with the caches.
The sizes of the retrieval buffer and the retrieval sort buffer. See Changing Buffer Size on
page 889 for a discussion of the significance of the size of the retrieval buffer and the retrieval
sort buffer.
Database workload; for example, the complexity of a calculation script or the number and
complexity of data queries.
The number of data blocks defined using the CALCLOCKBLOCK setting in the
essbase.cfg file in combination with the SET LOCKBLOCK setting, which specifies which
CALCLOCKBLOCK setting to use.
The number of Dynamic Calc members in the outline, including members of attribute
dimensions.
Synchronization points
Use of triggers
MDX implications
1068
Essbase code and static data (10 MB). This number may vary, depending on the operating
system.
(Optional) JVM (2 to 4 MB), which is used for custom-defined functions. This value depends
on the operating system.
Multiply the number of applications that will be running simultaneously on the server by the
startup requirement and write the resulting value in the cell labeled ML in Table 246 on page
1078.
Database Name:
Size (MB)
Memory Requirements:
Startup requirements per database:
Database outline
MA:
MB:
MC:
MD:
1069
Database Name:
Size (MB)
ME:
See Estimating Additional Memory Requirements for Data Retrievals on page 1073.
Memory used for calculations
MF:
MG:
MA + MB + MC +MD + ME + MF
Total database memory requirement in megabytes (MB):
MG / 1,048,576 bytes
Write the name of this database and the total memory required in Table 246 on page 1078, which is a worksheet for
determining the memory requirement for all databases on the server (there are placeholders for seven databasesa
through g).
Repeat this exercise for each database on the server. After estimating the memory required for
all databases on the server, proceed to Estimating the Total Essbase Server Disk Space
Requirement on page 1066.
To calculate the outline memory requirement, multiply the number of members by a namelength factor of 300 bytes-400 bytes and write the result in the cell labeled MA in Table 244 on
page 1069.
If the database includes few aliases or very short aliases and short member names, use a smaller
number in the 300 byte-400 byte range. If you know that the names or aliases are very long, use
a larger number within this range.
Because the name-length factor is an estimated average, the following formula provides only a
rough estimate of the main area of the outline:
memory size of outline
= number of members
* name-length factor
Note: See Appendix A, Limits, for the maximum sizes for member names and aliases.
1070
MH:
Example
Assuming that the outline has 26,000 members and a median name-length, use the following
calculation to estimate the outline size used in memory:
26,000 members
* 350 bytes per member
= 9,100,000 bytes
Index Cache
At startup, Essbase sets aside memory for the index cache, the size of which can be user-specified.
To determine the size of the index cache, see Sizing Caches on page 824 and write the size in
the cell labeled MB in Table 244 on page 1069.
Cache-Related Overhead
Essbase uses additional memory while it works with the caches.
The calculation for this cache-related overhead uses the following factors:
l
The number of server threads (value MJ from Table 243 on page 1068)
Sum the index cache overhead plus the additional cache overhead.
cache-related overhead
= index cache-related overhead
+ additional cache overhead
Write the result to the cell labeled MC in Table 244 on page 1069.
1071
To determine the cell count of a logical block, multiply all members of each dense dimension
(including Dynamic Calc and Dynamic Calc and Store members but excluding Label Only
and shared members):
Using Table 245 as a worksheet, enter each dense dimension and its number of members, excluding
Label Only and shared members. If there are more than seven dense dimensions, list the dimensions
elsewhere and include all dense dimensions in the calculation.
Table 245
Number of Members
a.
b.
c.
d.
e.
f.
g.
Multiply the number of members of the first dense dimension (line a.) by the number of members of
the second dense dimension (line b.) by the number of members of the third dense dimension (line c.),
and so on, to determine the total number of cells in a logical block:
a * b * c * d * e * f * g = total number of cells
Write the result to the cell labeled MI in Table 243 on page 1068.
Example
Excluding Label Only and shared members, the dense dimensions in Sample.Basic contain 17
(Year), 14 (Measures), and 4 (Scenario) members. The calculation for the cell count of a logical
block in Sample.Basic:
17 * 14 * 4 = 952 cells
The number of cells in a logical block (value MI in Table 243 on page 1068)
The number of threads on the server (value MJ in Table 243 on page 1068)
1072
Number of threads
* ((Number of members in the outline * 26 bytes)
+ (Logical block cell count * 36 bytes))
Write the result in the cell labeled MD in Table 244 on page 1069.
Example
Assuming 20 threads for the Sample.Basic database, the startup area in memory required for
data structures is calculated:
20 threads
* ((79 members * 26 bytes) + (952 cells * 36 bytes))
= 726,520 bytes 726,520 bytes
/ 1,048,576 bytes = .7 MB
The maximum simultaneous queries that will occur are being processed.
1073
In the example where 20 threads are available at startup, the maximum amount of memory is
used for queries when at least 20 queries have been processed and the maximum number of
simultaneous queries are in process.
Calculating the Maximum Additional Memory Required
Calculate the maximum possible use of memory for query processing by totaling the memory used by
queries that will be run simultaneously, and add the memory acquired by threads that are now waiting
for queries.
Use the following variables when you calculate the formula in Estimating the Maximum Memory
Usage for a Query Before and After Processing:
l
Turn the dynamic calculator cache off by setting the essbase.cfg setting DYNCALCACHEMAXSIZE
to 0 (zero). Turning off the dynamic calculator cache enables measurement of memory still held by a
1074
thread by ensuring that, after the query is complete, the memory used for blocks during dynamic
calculations is released by the ESSSVR process to the operating system.
Using memory monitoring tools for the operating system, note the memory used by Essbase Server before
processing the query. Use the value associated with the ESSSVR process.
Using memory monitoring tools for the operating system, note the peak memory usage of Essbase Server
while the query is processed. This value is associated with the ESSSVR process.
Using memory monitoring tools for the operating system, after the query is completed, note the memory
usage of Essbase. This value is associated with the ESSSVR process.
Additional memory used after Essbase has finished processing the query
(AdditionalMemAfterP):
AdditionalMemAfterP = MemAfterP - MemBeforeP
When you have completed the above calculations for all the relevant queries, compare all results to
determine the following two values:
l
Insert the two values from step 7 into the formula in the following statement.
The additional memory required for data retrievals will not exceed the following:
Max#ConcQueries
* MAXAdditionalMemDuringP
+ (Total#Threads - Max#ConcQueries)
* MAXAdditionalMemAfterP
Write the result of this calculation, in bytes, to the cell labeled ME in Table 244 on page
1069.
Because this calculation method assumes that all of the concurrent queries are maximum-sized
queries, the result may exceed your actual requirement. It is difficult to estimate the actual types
of queries that will be run concurrently.
1075
To adjust the memory used during queries, you can set values for the retrieval buffer and the
retrieval sort buffer. See Setting the Retrieval Buffer Size on page 889 and Setting the Retrieval
Sort Buffer Size on page 890.
If sorting is involved in the query, the size of the retrieval sort buffer (20,480 bytes)
The size of the buffer that holds formatting information (140 KB, which rounds up to
144,000 bytes)
Report Writer factors:
m
The memory used for dynamically calculated values, which is based on the following
numbers:
m
The size of the data cache. See Sizing the Data Cache on page 827.
If direct I/O is used, the size of the data file cache. See Sizing the Data File Cache on page
826.
Report Writer factors the number of:
m
You can then use the following two calculations for the memory needed for retrievals:
l
1076
Summarize the calculations and write the result, in bytes, to the cell labeled ME in Table 244 on
page 1069.
Example
To estimate the maximum memory needed for concurrent queries, assume the following values
for this example:
l
The buffer and work area values apply for each retrieval:
m
Data file cache size: zero. Direct I/O is not used in the example.
The number of selected members is generalized across all queries to be 10,000 members.
The approximate memory requirement equals the following:
10000 members * 40 bytes/member = 400,000 bytes
1077
If you cannot perform a test with a calculation script, you can calculate a very rough estimate
for the operational requirement of a calculation by adding the following values:
The size of the calculator cache.
The size of the memory area used by the blocks set aside by the SET LOCKBLOCK command.
To calculate the memory requirement in bytes, multiply the specified number of data
blocks by the logical size of the data blocks.
For the logical block size, multiply the number of cells (value MI in Table 243 on page
1068) by 8 bytes per cell.
For the total calculation requirement, summarize the memory needed for all calculations that
will be run simultaneously and write that total to the cell labeled MF in Table 244 on page
1069.
Note: The size and complexity of the calculation scripts affect the memory required. The effects
Component
ML:
MH:
b.
MH:
c.
MH:
d.
MH:
e.
MH:
1078
Component
f.
MH:
g.
MH:
MN:
MO:
In the cell labeled ML, record the total startup memory requirement for applications, as described in
Estimating Startup Memory Requirements for Applications on page 1069.
List the largest set of databases that will run concurrently on the server. In the Memory Required column,
for the MH value for each database, note the memory requirement estimated in the database
requirements worksheet, Table 244 on page 1069.
Determine the operating system memory requirement, and write the value in megabytes to the cell
labeled MN in Table 246.
Total all values and write the result in the cell labeled MO.
Compare the value in MN with the total available random-access memory (RAM) on the server.
Note: In addition, consider memory requirements for client software, such as Administration
Services, that may be installed on the Essbase Server computer. See the Oracle Enterprise
Performance Management System Installation and Configuration Guide.
If cache memory locking is enabled, the total memory requirement should not exceed two-thirds
of available RAM; otherwise, system performance can be severely degraded. If cache memory
locking is disabled, the total memory requirement should not exceed available RAM.
If insufficient memory is available, you can redefine the cache settings and recalculate the
memory requirements. This process can be iterative. See Fine-Tuning Cache Settings on page
836. In some cases, you may need to purchase additional RAM.
1079
1080
Using ESSCMD
E
In This Appendix
Also see:
l
Oracle Essbase Administration Services Online Help for information about MaxL Script Editor
Understanding ESSCMD
With ESSCMD, you can execute Essbase Server operations at the command line, in either
interactive or batch mode.
Interactive mode means entering commands at the ESSCMD command line and receiving
prompts where necessary. Interactive mode is convenient for short operations that require few
commands, checking for information on the fly, and error checking.
Batch processing mode is used for automating routine Essbase Server maintenance and diagnostic
tasks. You can write a script or batch file and run it from the command line. Batch processing
mode is convenient if you frequently use a particular series of commands, or if a task requires
many commands.
1081
Quotation Marks
Quotation marks (" ") enclose character parameters and responses to commands.
l
In interactive ESSCMD, using quotes is optional. Use quotes when a parameter has an
embedded space; for example:
CALC "Calc All;"
In an ESSCMD script file, always enclose all character parameters and responses to
commands in quotation marks; for example:
LOGIN "Localhost" "user1" "Password";
In interactive ESSCMD, pressing the Enter key signals ESSCMD that the command is
complete. The statement terminator is optional.
In an ESSCMD script file, you should use the terminator, even though it is optional, if a
command has many parameters. Doing so is especially important to signal the end of the
parameter list if some parameters are optional.
If you omit some optional parameters and do not use a semicolon to end the list, ESSCMD looks
for the remaining values in the next command in the file, leading to unpredictable results.
The SETAPPSTATE and SETDBSTATE commands, defined in the Oracle Essbase Technical
Reference, are examples of commands that you should terminate with a semicolon to prevent
confusion in processing.
Note: All syntax examples in this chapter use quotation marks and semicolon terminators.
Referencing Files
Some commands require that you precede artifact or file names with a numeric parameter, from
1 to 4, that tells Essbase where to look for the artifact or file. The parameter directs ESSCMD to
look for files in other applications, databases, or systems.
1082
Table 247 lists each value for the numeric parameter (Number), the file location to which it
applies, and the information that ESSCMD requests when you use each parameter setting.
appname is the application name and dbname is the database name.
Table 247
Number
File
File
Fully qualified path to the file, unless file is in the current ESSCMD directory
SQL table
For example, the LOADDATA command can load a data file that resides on the client or Essbase
Server. The command requires the numeric parameter to tell Essbase where to look for the data
file. This example causes ESSCMD to prompt for the fully qualified path name of the file to load:
LOADDATA 3
File extensions are usually optional in interactive and batch processing modes, except when using
commands that require a numeric parameter that indicates the location of files:
l
If you use file option 3 (File), you must enter the file extension in both interactive and batch
processing modes.
If the artifact is in the directory from which you started ESSCMD, you need not enter a path.
Considering Case-Sensitivity
The Essbase Server creates application and database names exactly as the user specifies. Case is
not changed for any platform.
For backward compatibility, the Essbase Server searches for existing application and database
names using the exact case first. However, if it cannot find the file, Essbase Server searches all
possible case combinations to find the existing application and database names.
Essbase does not allow you to create application and database names that differ only in case. For
example, Essbase displays an error message if application mYdATA exists and you try to create
an application MyData.
You can choose to make member names case-sensitive.
1083
Getting Help
For descriptions and syntax for individual ESSCMD commands, see the Oracle Essbase Technical
Reference.
Essbase
where n is the value of the active login instance. Each subsequent, successful login increments
this value by one. When ESSCMD starts, the instance number is zero (0).
Note: Use the SETLOGIN command to toggle between active login instances. Use the
At the ESSCMD prompt, log on to the server with the LOGIN command.
When you connect from the Essbase Server window, the server name depends on your
network setup. For example, the name could be aspen.
You can enter any valid ESSCMD command. For a complete listing of commands, see the Oracle
Essbase Technical Reference.
Note: To load an application into memory and select a database on the Essbase server, use the
SELECT command to select a database from an application that resides on the server.
The ESSCMD prompt is displayed:
aspen:appname:dbname:userName[1]->
appname is the name of the application. dbname is the name of the database to which you are
connected.
Entering Commands
Choose either of the following methods to enter commands in interactive mode:
l
If you enter only SELECT and press Enter, ESSCMD prompts you for the first parameter,
the application name (appname). After you enter the application name and press Enter,
ESSCMD prompts you for the database name (dbname).
l
1085
Whichever method you use, the interactive prompt now reflects the application and database
names. For example, the following prompt tells you that the Sample application and Basic
database are selected:
aspen:Sample:Basic:User[1]->
In this case, you can enter other commands without the application or database name parameters
that it normally requires.
Canceling Operations
While ESSCMD is running, you can cancel an asynchronous operation, such as a calculation,
export, or restructure operation, by pressing and holding the Esc key until ESSCMD responds.
Caution!
A script file contains ESSCMD commands. You can run a script file from the operating system
command line or from within an operating system batch file, and the script file is processed
by ESSCMD. By default, an ESSCMD script file has a .scr file extension. You can use a
different extension.
A batch file is an operating system file that calls multiple ESSCMD scripts and can also include
operating system commands. You can use a batch file to run multiple sessions of ESSCMD.
You can run a batch file on Essbase Server from the operating system prompt; the file is
processed by the operating system. On Windows, batch files have .bat file extensions.
Note: On UNIX, a batch or script file is written as a shell script. A shell script usually has the file
extension .sh (Bourne or Korn shell) or .csh (C shell).
When you run a script or batch file, ESSCMD executes the commands in sequence until it reaches
the end of the file.
Some commands may be changed in new releases of Essbase. Changes might affect existing
scripts. To ensure that your scripts work correctly in the current release, see the Oracle Essbase
1086
New Features and the Essbase Readme for information about changed or deleted commands and
change your scripts if needed.
Enter ESSCMD commands in any editor that saves data in ASCII text.
Save the file with the .scr ESSCMD script file extension.
For example, the following script file, test.scr, was created in Notepad:
LOGIN "localhost" "User1" "password";
SELECT "Sample" "Basic";
GETDBSTATE
EXIT;
When run from the operating system command line, this script logs User1 into the Essbase
localhost server, selects the Sample application and Basic database, gets database statistics, and
quits the ESSCMD session.
For example, enter the following if the script file is in the current directory:
ESSCMD TEST.SCR
If the script file is not in the current directory, include the path.
For example:
ESSCMD C:\WORK\SCRIPTS\TEST.SCR (an absolute path on Windows)
or
ESSCMD..\SCRIPTS\TEST.SCR (a relative path on Windows)
1087
IFERROR checks the previously executed command for a nonzero return status (failure to
execute). If the status is not zero, processing skips all subsequent commands and jumps to
a user-specified point in the file, where it resumes. The script file can branch to an errorhandling routine or the end of the file.
RESETSTATUS reverts all saved status values to 0 (zero) in preparation for more status
checking.
GOTO forces unconditional branching to a user-specified point in the file, whether or not
an error occurred.
In this load.scr example file, if the LOADDATA command does not execute successfully,
ESSCMD branches to the end of the file to avoid attempting to calculate and run a report script
on the empty database:
LOGIN "localhost" "User1" "password" "Sample" "Basic";
LOADDATA 2 "calcdat";
IFERROR "Error";
CALC "Calc All;";
IFERROR "Error";
RUNREPT 2 "Myreport";
IFERROR "Error";
[possible other commands]
EXIT;
:Error
Note: You can use the OUTPUT command to log errors to a text file.
For the syntax and usage of ESSCMD error commands, see the Oracle Essbase Technical
Reference.
1088
Prevents other users from logging on and making changes to the database
Reenables logins
Exits ESSCMD
Prevents other users from logging on and making changes to the database
Reenables logins
Exits ESSCMD
1089
Exits ESSCMD
1090
:Error
Echo There was a problem running the script
1091
1092
F
In This Appendix
Use no more than 8 bytes when naming non-Unicode-mode applications and databases.
Use no more than 30 characters when naming Unicode-mode applications and databases.
Character
Description
asterisk
[]
brackets
colon
semicolon
comma
equal sign
>
greater-than sign
<
less-than sign
1093
Character
Description
period
plus sign
question mark
"
forward slash
backslash
vertical bars
tabs
For aggregate storage databases, do not use the following words as application or database
names:
DEFAULT
LOG
METADATA
REPLAY
TEMP
Application and database names are not case-sensitive. However, on case-sensitive file systems,
the application or database name is created exactly as you enter it. Therefore, when creating,
renaming, or copying applications and databases on case-sensitive file systems, Essbase ensures
that the same application or database name but with different case usage cannot be used. For
example, if you create an application name with all uppercase letters (NEWAPP), you cannot
then create an application with the same name but with mixed-case letters (Newapp). Also, when
manually copying application and database files from one computer to another and then creating
an application or database, you must use the same case for the application and database directory
names on both computers.
1094
Even when case-sensitivity is enabled, in an aggregate storage outline for which duplicate
member names is enabled, do not use matching names with only case differences for a
dimension name. For example, do not name two dimensions Product and product.
Do not use quotation marks (" "), brackets ([ ]), or tabs in dimension, member, or alias
names.
At the beginning of dimension or member names, do not use the characters listed in
Table 249:
Table 249
Character
Description
at sign
backslash
{}
brace
comma
equal sign
<
()
parentheses
period
plus sign
'
underscore
vertical bar
Do not place spaces at the beginning or end of names. Essbase ignores such spaces.
Names of other dimensions and members (unless the member is shared), and generation
names, level names, and aliases in the database
1095
1096
TO
TOLOCALRATE
TRAILMISSING
TRAILSUM
UMINUS
UPPER
VARORXMBR
XMBRONLY
$$$UNIVERSE$$$
#MISSING
#MI
History
Year
Season
Period
Quarter
Month
Week
Day
Sum
Count
Min
Max
Avg
If the outline is tagged as a duplicate member outline, you can use the default names to name
other base or attribute members.
See Changing the Member Names of the Attribute Calculations Dimension on page 176.
1097
1098
Character
Description
&
ampersand
asterisk
at sign
backslash
{}
braces
colon
comma
exclamation point
equal sign
>
<
()
parentheses
percent sign
period
plus sign
semicolon
slash
tilde
In calculation scripts and formulas, you must enclose these member names, which are also
Essbase keywords, in quotation marks (" ") for block storage databases, and in brackets ([ ]) for
aggregate storage databases:
BEGIN
DOUBLE
ELSE
END
FUNCTION
GLOBAL
IF
MACRO
MEMBER
RANGE
RETURN
STRING
THEN
True
False
Sum
Count
Min
Max
Avg
See Naming Conventions for Attribute Calculations Dimension Member Names on page
1097.
1099
1100
Differences in Security-Related
Operations in Different Security
Models
EPM System security mode: Most of the security responsibilities are moved from Essbase
to Shared Services. Security information stored in the Shared Services native directory
include: users and groups information, roles assignment for users and groups, application
information, and more. User authentication for users in external providers (such as LDAP,
MSAD, and OID) is done through the providers. Security information in the
essbase.sec file is kept to a minimum.
Fusion security mode: Fusion JPS security is responsible for user and group management,
as well as role management for users and groups. User authentication for users in external
providers (such as LDAP, MSAD, and OID) is done through the providers. There is no
security information stored in essbase.sec. Application and database information is still
stored in essbase.sec.
Table 251 explains the how security-related operations are handled in each security mode.
Table 251
Request
Fusion Security
Create user
Create group
Delete user
Delete group
Rename user
Rename group
1101
Request
Fusion Security
Set password
Migrate to Shared
Services mode
Create application
Create database
Reregister application
Delete application
Delete database
Set user
Display user/group
1102
Request
Fusion Security
Display filter
1103
1104
H
In This Appendix
Essbase 32-Bit and 64-Bit Client and Server Compatibility ....................................... 1105
Essbase API Compatibility on 32-Bit and 64-Bit Platforms........................................ 1106
Server
32-bit, 64-bit
32-bit, 64-bit
64-bit
32-bit, 64-bit
32-bit, 64-bit
64-bit
32-bit, 64-bit
64-bit
32-bit, 64-bit
64-bit
32-bit, 64-bit
64-bit
1105
Client programs developed for 32-bit platforms using the Essbase C API or Visual Basic API
can run on 32-bit platforms and connect to either 32-bit or 64-bit Essbase Server.
Precompiled client programs developed using the 32-bit Essbase Visual Basic API can run
on 64-bit Windows platforms connecting to 64-bit Essbase Server, as long as the 32-bit
runtime environment is set up as according to the documented instructions.
Client programs developed for 64-bit platforms using the Essbase C API:
m
Can run on 64-bit platforms and connect to 32-bit or 64-bit Essbase Servers
Caution!
Client programs developed for 64-bit platforms do not require the #pragma
directive to set the byte alignment.
You cannot develop a client program for 64-bit Windows using the Essbase Visual Basic
API.
The following table summarizes the compatibility of client programs developed with Essbase
APIs:
Client Development: Platform with API Version
32-bit
32-bit, 64-bit
32-bit Windows
32-bit, 64-bit
64-bit Windows
64-bit
32-bit, 64-bit
32-bit, 64-bit
64-bit
32-bit, 64-bit
64-bit
1106
64-bit
I
In This Appendix
Not supportedIn the release in which a feature is not supported, the functionality is either
completely removed from the product or, if not completely removed, is no longer supported.
DeprecatedIn the release in which a feature is deprecated, the feature is still fully functional
(unless limitations are specified) and supported. Typically, a deprecated feature will no
longer be supported in the next release.
Caution!
This topic lists the Essbase features, by release, that were no longer supported or deprecated.
Essbase 11.1.2.4
For information about features that are no longer supported or are deprecated in this release,
see the 11.1.2.4 Oracle Essbase Readme.
1107
Essbase 11.1.2.3.503
Not supported calculation command: SET FORCEPARALLELCALC.
Consider using FIXPARALLEL instead.
Essbase 11.1.2.3.500
Not supported configuration settings:
l
VLBREPORT
XOLAPENABLEHEURISTICS
Essbase 11.1.2.3
Not supported features:
l
Data Mining
PRELOADALIASNAMESPACE
PRELOADMEMBERNAMESPACE
Essbase 11.1.2.2.100
Not supported functionality:
l
Essbase 11.1.2.2.000
Not supported configuration settings:
l
HSSREGNAME
INSTANCENAME
1108
Essbase 11.1.2.1
Deprecated configuration settings:
l
HSSREGNAME
INSTANCENAME
Essbase 11.1.1.4
Not supported feature: Reference cubes
Not supported Visual Basic API functions:
l
EsbPartitionOpenDefFile
EsbPartitionReadDefFile
EsbPartitionWriteDefFile
CssSyncLevel
CssRefreshLevel
SharedServicesRefreshInterval
sync user
sync group
sync all_users_groups
For the alter group MaxL statement: all sync with all application
1109
For the create user MaxL statement: with protocol MODULE-STRING identified by AUTHPARAMETERS
For the display user system MaxL statement:
m
all migr_modified_access
EssGetMigrModifiedAccessUsers
EssGetNewSSNativeEssbaseUsers
EssReassignIdentity
EssResyncSSSecurity
EssSyncGroupWithApp
EssSyncUser
EssSyncUserWithApp
EssSyncUsersandGroupsWithApps
Essbase 9.3.3
Not supported functionality:
l
CssSyncLevel
CssRefreshLevel
SharedServicesRefreshInterval
sync user
sync group
sync all_users_groups
For the alter group MaxL statement: all sync with all application
1110
For the create user MaxL statement: with protocol MODULE-STRING identified by AUTHPARAMETERS
For the display user system MaxL statement:
m
all migr_modified_access
EssGetMigrModifiedAccessUsers
EssGetNewSSNativeEssbaseUsers
EssReassignIdentity
EssResyncSSSecurity
EssSyncGroupWithApp
EssSyncUser
EssSyncUserWithApp
EssSyncUsersandGroupsWithApps
1111
1112